Project Plan: MECA Initiative - Phase I

❦

Project Objective

The primary objective of Phase I is to establish the foundational infrastructure for the MECA framework within the existing monorepo. This involves creating the core packages, implementing a basic project discovery mechanism, and building a simple, read-only CLI command to validate the entire toolchain. By the end of this phase, we will have a stable "workbench" upon which all future development will be built.

Key Deliverables

1. Workspace Scaffolding: A new meca workspace within the monorepo, housing the core, cli, and ops packages.
2. The Project Abstraction: A foundational Project class in meca-core capable of discovering pnpm workspaces and the packages within them.
3. The "Hello, World" CLI: A working meca ws list command that successfully uses meca-core to display a list of all packages in the project.

Acceptance Criteria for Phase I

• The packages/meca-core, packages/meca-cli, and packages/meca-ops directories and their initial files exist.
• Running pnpm install from the project root completes successfully, linking the new workspace packages.
• The meca command is executable from the project root via pnpm exec meca.
• Running pnpm exec meca ws list outputs a list of all package directory paths found in the sandbox/* and packages/* workspaces.

Task 1: Workspace and Package Scaffolding

This task involves creating the directory structure and configuration files for the MECA framework itself.

• Step 1.1: Create the parent directory for the framework packages at the project root: packages/.

• Step 1.2: Create the three core package directories within it:

  • packages/meca-core
  • packages/meca-cli
  • packages/meca-ops

• Step 1.3: Create initial package.json files for each new package.

  • For packages/meca-core/package.json:

    {
      "name": "@meca/core",
      "version": "0.1.0",
      "main": "dist/index.js",
      "types": "dist/index.d.ts",
      "scripts": {
        "build": "tsc"
      }
    }
    

  • For packages/meca-cli/package.json:

    {
      "name": "@meca/cli",
      "version": "0.1.0",
      "bin": {
        "meca": "dist/index.js"
      },
      "scripts": {
        "build": "tsc"
      },
      "dependencies": {
        "@meca/core": "workspace:*"
      }
    }
    

  • For packages/meca-ops/package.json:

    {
      "name": "@meca/ops",
      "version": "0.1.0",
      "main": "dist/index.js",
      "types": "dist/index.d.ts",
      "scripts": {
        "build": "tsc"
      }
    }
    

• Step 1.4: Create a basic tsconfig.json for each new package. This configuration can be used for all three:

  {
    "compilerOptions": {
      "target": "es2020",
      "module": "commonjs",
      "strict": true,
      "esModuleInterop": true,
      "skipLibCheck": true,
      "forceConsistentCasingInFileNames": true,
      "outDir": "./dist",
      "declaration": true
    },
    "include": ["src/**/*"]
  }
  

• Step 1.5: Ensure the root pnpm-workspace.yaml includes the new directory:

  packages:
    - 'sandbox/*'
    - 'packages/*'
  

• Step 1.6: Install root-level development dependencies by running this command from the project root:

  pnpm add -wD typescript ts-node @types/node
  

Task 2: Implement the Project Abstraction

This task involves writing the initial code for meca-core to discover packages.

• Step 2.1: Install necessary dependencies for meca-core:

  pnpm add glob yaml @types/glob @types/yaml -F @meca/core
  

• Step 2.2: Create and populate the initial Project class in packages/meca-core/src/index.ts:

  import { glob } from 'glob';
  import * as fs from 'fs/promises';
  import * as path from 'path';
  import * as YAML from 'yaml';
  
  export class Project {
    private constructor(readonly rootPath: string, readonly packagePaths: string[]) {}
  
    public static async load(projectRoot: string): Promise<Project> {
      const workspaceConfigPath = path.join(projectRoot, 'pnpm-workspace.yaml');
      const fileContent = await fs.readFile(workspaceConfigPath, 'utf8');
      const config = YAML.parse(fileContent);
      const patterns: string[] = config.packages || [];
  
      const packagePaths: string[] = [];
      for (const pattern of patterns) {
        const found = await glob(pattern, { cwd: projectRoot, absolute: true, onlyDirectories: true });
        packagePaths.push(...found);
      }
  
      return new Project(projectRoot, packagePaths);
    }
  
    public listPackagePaths(): string[] {
      return this.packagePaths;
    }
  }
  

Task 3: Build the "Hello, World" CLI

This task connects the core logic to an executable command.

• Step 3.1: Install the CLI helper library for meca-cli:

  pnpm add commander -F @meca/cli
  

• Step 3.2: Create and populate the CLI entry point at packages/meca-cli/src/index.ts:

  #!/usr/bin/env node
  import { Command } from 'commander';
  import { Project } from '@meca/core';
  
  const program = new Command();
  
  program
    .command('ws:list')
    .description('List all discovered packages in the workspace')
    .action(async () => {
      try {
        console.log('Discovering project structure...');
        const project = await Project.load(process.cwd());
        const packagePaths = project.listPackagePaths();
  
        if (packagePaths.length === 0) {
          console.log('No packages found. Check your pnpm-workspace.yaml.');
          return;
        }
  
        console.log('\nFound packages:');
        packagePaths.forEach(p => console.log(`- ${p}`));
  
      } catch (error) {
        console.error('An error occurred:', error);
        process.exit(1);
      }
    });
  
  program.parse(process.argv);
  

Task 4: Final Verification

This final task ensures all pieces work together as expected.

• Step 4.1: From the project root, run pnpm install to link all local dependencies correctly.
• Step 4.2: Build the new TypeScript packages: pnpm --filter "@meca/*" build.
• Step 4.3: Execute the CLI command: pnpm exec meca ws list.
• Step 4.4: Verify that the output lists the directory paths for all packages in your sandbox and packages directories, confirming the successful completion of Phase I.