Framework Bootstrap

Framework bootstrap is the process of initializing application frameworks (Next.js, Expo, Hono, etc.) before regular module execution. This ensures the correct project structure exists before any modules try to create files.

Overview

When you create a project with a framework (e.g., Next.js for web apps), the CLI:

Detects framework modules from your genome
Executes framework bootstrap in the correct app directory
Runs framework CLI commands (e.g., create-next-app)
Filters framework modules from regular execution (they only run once)

Execution Flow

┌─────────────────────────────────────┐
│ 1. Path Mapping Generation          │
│    - Generate all path keys         │
│    - Available even for non-existent│
│      apps (using default patterns)  │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│ 2. Framework Bootstrap              │
│    - Identify framework modules      │
│    - Create VFS with app directory  │
│      as root (e.g., apps/web)       │
│    - Execute framework CLI commands │
│    - Framework modules execute HERE │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│ 3. Regular Module Execution         │
│    - Framework modules filtered out │
│    - Regular modules execute         │
│    - All paths correctly resolved   │
└─────────────────────────────────────┘

Framework Module Detection

Framework modules are identified using metadata, not hardcoded patterns:

// Metadata-based detection (fully dynamic)
const isFramework = 
  metadata?.category === 'framework' || 
  metadata?.category === 'foundation' ||
  (metadata?.type && String(metadata.type).toLowerCase() === 'framework');

This means:

✅ Works with any marketplace structure
✅ No hardcoded paths or patterns
✅ Fully marketplace-agnostic

Path Resolution During Bootstrap

Critical: During framework bootstrap, the VFS root IS the app directory (e.g., apps/web).

This means paths must resolve relative to the VFS root:

// During bootstrap
if (plan.appType && key === `apps.${plan.appType}.root`) {
  paths[key] = './'; // VFS root IS the app directory
}

Why? This prevents creating nested directories like apps/web/apps/web/.

Example

When bootstrapping Next.js for a web app:

VFS Root: /project/apps/web
Path Resolution: paths.apps.web.root → ./ (not apps/web/)
File Creation: next.config.js → /project/apps/web/next.config.js ✅

Working Directory

Framework CLI commands (e.g., create-next-app) must run in the correct directory:

// VFS is created with app directory as root
const vfs = new VirtualFileSystem(
  `framework-${frameworkId}`,
  plan.targetPath // e.g., /project/apps/web
);
 
// Commands use VFS root as working directory
const workingDir = vfs.getProjectRoot(); // /project/apps/web
execSync('npx create-next-app@latest .', { cwd: workingDir });

Framework Modules Execute Once

Framework modules are filtered out from regular module execution:

// In orchestrator-agent.ts
const regularModules = resolvedGenome.modules.filter(
  mod => !isFrameworkModule(mod, resolvedGenome)
);
 
// Framework modules only execute during bootstrap
// Regular modules execute after bootstrap

This ensures:

✅ Framework setup happens first
✅ Framework modules don't execute twice
✅ Correct execution order

Package Manager Detection

During dependency installation, the CLI detects the package manager from:

Genome monorepo config (highest priority)
Generated project's package.json (checks packageManager field)
Lock files in project root (pnpm-lock.yaml, yarn.lock, etc.)
Default: pnpm (supports workspace:* protocol)

Important: Corepack is bypassed to prevent checking parent directories (CLI's package.json).

Framework Blueprints

Framework blueprints should NOT create config files that framework CLIs already create:

// ❌ DON'T create these (framework CLI handles them)
// - next.config.js (create-next-app creates this)
// - tsconfig.json (create-next-app creates this)
// - app.json (create-expo-app creates this)
 
// ✅ DO create framework-specific enhancements
// - Custom middleware
// - Additional config overrides
// - Framework-specific utilities

Troubleshooting

Framework commands run in wrong directory

Symptom: create-next-app runs in project root instead of apps/web

Solution: Verify VFS is created with correct targetPath:

const vfs = new VirtualFileSystem(blueprintId, plan.targetPath);
// plan.targetPath should be absolute path to app directory

Nested app directories created

Symptom: Files created at apps/web/apps/web/ instead of apps/web/

Solution: Ensure paths resolve to ./ during bootstrap:

if (plan.appType && key === `apps.${plan.appType}.root`) {
  paths[key] = './'; // Relative to VFS root
}

Framework modules execute twice

Symptom: Framework setup runs during bootstrap AND regular execution

Solution: Verify framework modules are filtered:

const regularModules = resolvedGenome.modules.filter(
  mod => !isFrameworkModule(mod, resolvedGenome)
);

CLI Architecture - Overall CLI architecture
Marketplace Adapter Interface - How marketplaces work
Path Resolution - Path resolution strategy

Overview Overview