Project Plan: MECA Initiative - Phase III

❦

Project Objective

Welcome to Phase III, team. This is the capstone phase where we bring everything together. The foundational workbench and the core engine are built; now, we build the "flywheel" that makes the entire system powerful and intelligent. The objective is to implement the complete, end-to-end workflow for an agent: discovering available operations, executing complex changes, and promoting a finished experiment to production. When this phase is complete, MECA will be fully operational for its primary use case.

Key Deliverables

1. The Full MPI System: A dynamic system that allows the meca CLI to discover and execute operations defined in any component's .meta.ts file.
2. A Composed "Smart" Operation: A real-world example of a high-level operation, web:integrateExperiment, that composes multiple smaller operations to modify both dependencies and code.
3. The Graduation Pipeline: The final meca promote command, which validates an experiment, moves it to the production packages workspace, and prepares it for consumption.

Acceptance Criteria for Phase III

• The meca list mpi <ComponentName> command successfully reads a .meta.ts file and lists its exported operations.
• The generic meca run <component> <operation> --params '{...}' command can dynamically execute an MPI handler.
• The web:integrateExperiment operation correctly adds a dependency to the sandbox/web app's package.json AND adds the component's import and JSX to pages/index.tsx.
• The meca promote <ComponentName> command successfully moves a package from sandbox/ to packages/ and, crucially, deletes the .meta.ts file from the promoted version.

Task 1: Implement the MPI System (Discovery and Execution)

This is the heart of the framework's dynamic nature.

• Step 1.1: MPI Discovery (list mpi).

  • In meca-cli, create the new command list mpi <componentName>.
  • The handler logic will need to:
    1. Locate the component package in the sandbox.
    2. Find its .meta.ts file.
    3. For this initial version, we can use a simple ts-morph script to parse the file and find the names of the top-level exports, logging them to the console. This proves the discovery mechanism.

• Step 1.2: The AstContext.

  • In meca-core, we need to define the context object that will be passed to every MPI handler. Create a new ast-context.ts file.
  • The AstContext class will be a sandboxed environment. It should be initialized with the target SourceFile (from ts-morph) and provide access to our existing helpers (like addImport).

• Step 1.3: MPI Execution (ctx.run).

  • This is the most complex part. We need a way to dynamically run these operations. Modify the TxContext from Phase II.
  • Add a new operation type: { type: 'RUN_MPI', componentName: string, opName: string, params: any }.
  • When commit encounters this operation, it must:
    1. Dynamically import() the target component's .meta.ts file.
    2. Access the exported object and find the handler for opName.
    3. Create an AstContext for the component's main .tsx file.
    4. Call the handler(astContext, params).
    5. After the handler completes, save the modified SourceFile from the AstContext.

Task 2: Implement a Composed "Smart" Operation

Let's build a high-value, real-world operation to prove the power of composition.

• Step 2.1: Create a new package packages/meca-web-ops to house web-specific, reusable operations.

• Step 2.2: In this new package, define the integrateExperiment MPI operation. The handler function will be a sequence of steps managed by the TxContext:

  // In a new meca-web-ops package...
  // The handler for the 'integrateExperiment' operation
  async function handler(ctx, params: { experimentName: string }) {
    // 1. Modify package.json (a file system operation)
    await ctx.modifyJsonFile('sandbox/web/package.json', (json) => {
      json.dependencies[params.experimentName] = "workspace:*";
    });
  
    // 2. Modify the main page (an AST operation)
    await ctx.modifyAstFile('sandbox/web/pages/index.tsx', (sourceFile) => {
      // Use the helper from Phase II
      addImport(sourceFile, { moduleSpecifier: params.experimentName, ... });
      // Use another helper to find the main JSX return and add the component
      insertJsxChild(sourceFile, ...);
    });
  }
  

  Note: This will require adding new capabilities to TxContext like modifyJsonFile and modifyAstFile.

• Step 2.3: Wire up the generic meca run command in the CLI to execute these MPIs. meca run web integrateExperiment --params '{ "experimentName": "my-timeline" }'.

Task 3: Implement the Graduation Pipeline

This task completes the component lifecycle.

• Step 3.1: In meca-cli, create the meca promote <componentName> command.

• Step 3.2: The handler for this command will orchestrate a multi-step transaction using project.transaction():

  1. Validation (Placeholder): For now, the transaction will simply log "Running validation checks..." to the console. We can stub out calls to linting and testing here to be implemented later. If a stubbed check "fails," the transaction should halt.
  2. File Transfer: Stage a COPY_DIRECTORY operation to copy the entire component package from sandbox/ to packages/.
  3. MPI Stripping: Stage a DELETE_FILE operation that targets the .meta.ts file in the destination directory (packages/<componentName>/src/...). This is the most critical step of the promotion.

Task 4: Final End-to-End Verification

This is the final exam for the entire MECA framework.

• Step 4.1: Execute the full workflow from the command line:

  1. pnpm exec meca create:experiment cool-new-feature
  2. pnpm exec meca list mpi cool-new-feature (Verify it has a default empty export)
  3. pnpm exec meca run web integrateExperiment --params '{ "experimentName": "cool-new-feature" }'
  4. Verify the changes in sandbox/web/package.json and sandbox/web/pages/index.tsx.
  5. pnpm exec meca promote cool-new-feature
  6. Verify that packages/cool-new-feature exists and that cool-new-feature.meta.ts is gone from the packages version.

• Step 4.2: Upon successful verification, we can celebrate. The core vision of the MECA framework will have been realized.