Marketplace-CLI Relationship

V2 introduces a clear separation between marketplaces (opinionated) and CLI (generic). Marketplaces transform genomes; the CLI executes them.

Architecture

┌─────────────────┐
│   V2Genome      │  User defines business-level packages/apps
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Marketplace    │  Transforms V2Genome → StandardizedGenome
│  Adapter        │  - Loads recipe books
│  transformGenome│  - Expands packages → modules
└────────┬────────┘  - Resolves dependencies
         │           - Creates lock file
         ▼
┌─────────────────┐
│ StandardizedGenome│  Unified format for CLI
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│      CLI        │  Executes StandardizedGenome
│  Orchestrator   │  - Framework bootstrap
└─────────────────┘  - Module execution

Marketplace Responsibilities

1. Load Recipe Books

Recipe books map business packages → technical modules:

{
  "packages": {
    "auth": {
      "providers": {
        "default": {
          "modules": [
            { "id": "capabilities/auth", "targetPackage": "auth" }
          ]
        }
      }
    }
  }
}

2. Transform Genome

Marketplace adapter's transformGenome() method:

Expands packages into modules using recipe book
Resolves dependencies using prerequisites
Generates lock file for reproducible builds
Returns StandardizedGenome ready for CLI execution

async transformGenome(genome: V2Genome, options, context) {
  // 1. Load recipe books
  const recipeBooks = await this.loadRecipeBooks(genome);
  
  // 2. Use CompositionEngine to resolve
  const handler = new context.V2GenomeHandler(
    context.marketplaceAdapters,
    context.logger,
    context.projectRoot
  );
  
  // 3. Resolve to lock file
  const lockFile = await handler.resolveGenome(genome, context.projectRoot);
  
  // 4. Convert to StandardizedGenome
  return handler.convertLockFileToResolvedGenome(
    lockFile,
    genome,
    context.genomeFilePath
  );
}

3. Provide Path Defaults

Marketplaces provide default path values:

async resolvePathDefaults(context) {
  return {
    'apps.web.root': 'apps/web/',
    'apps.web.src': 'apps/web/src/',
    'packages.auth.root': 'packages/auth/',
    // ...
  };
}

CLI Responsibilities

1. Load Marketplaces

CLI loads marketplaces specified in V2Genome:

const marketplaces = genome.marketplaces;
for (const [name, config] of Object.entries(marketplaces)) {
  const adapter = await loadMarketplaceAdapter(name, config);
  marketplaceAdapters.set(name, adapter);
}

2. Call transformGenome()

CLI calls marketplace adapter's transformGenome():

const standardizedGenome = await marketplaceAdapter.transformGenome(
  genome,
  options,
  {
    marketplaceAdapters,
    logger,
    projectRoot,
    V2GenomeHandler,
    CompositionEngine
  }
);

3. Execute StandardizedGenome

CLI executes the standardized genome:

Path mapping generation
Framework bootstrap
Module execution

Key Principles

1. CLI is Generic

The CLI does not know about:

Package → Module mappings (handled by recipe books)
Framework detection (handled by metadata)
Path resolution (handled by path keys)

Result: CLI works with any marketplace structure.

2. Marketplaces are Opinionated

Marketplaces define:

Which modules are available
How packages map to modules
What paths are available
Framework compatibility

Result: Different marketplaces can have different opinions.

3. StandardizedGenome is the Contract

Both CLI and marketplaces agree on StandardizedGenome:

interface StandardizedGenome {
  project: { name, structure, ... };
  modules: Module[];
  metadata: { moduleIndex, executionPlan, ... };
  // Optional: V2 structure preserved
  packages?: Record<string, PackageConfig>;
  apps?: Record<string, AppConfig>;
}

Result: CLI can execute any StandardizedGenome, regardless of source.

Example Flow

1. User Creates V2Genome

{
  packages: { auth: {} },
  apps: { web: { framework: 'nextjs', packages: ['auth'] } }
}

2. Marketplace Transforms

// Marketplace loads recipe book
recipeBook.packages.auth → capabilities/auth module
 
// Marketplace expands
packages.auth → capabilities/auth → packages/auth/
 
// Marketplace resolves
apps.web.framework → capabilities/nextjs → apps/web/
 
// Marketplace creates lock file
{
  executionPlan: ['capabilities/nextjs', 'capabilities/auth'],
  modules: [...]
}

3. CLI Executes

// CLI receives StandardizedGenome
{
  modules: [
    { id: 'capabilities/nextjs', ... },
    { id: 'capabilities/auth', ... }
  ],
  metadata: {
    executionPlan: ['capabilities/nextjs', 'capabilities/auth']
  }
}
 
// CLI executes
1. Bootstrap: capabilities/nextjs → apps/web/
2. Execute: capabilities/auth → packages/auth/

Benefits

Separation of Concerns: Marketplaces handle business logic, CLI handles execution
Flexibility: Different marketplaces can have different structures
Reusability: CLI works with any marketplace
Type Safety: StandardizedGenome provides consistent interface

Marketplace Adapter Interface - Complete interface reference
Recipe Books - Package → Module mapping
V2Genome Structure - V2Genome format

Monorepo-Only Architecture Execution Flow