@codeyam/codeyam-cli 0.1.0-staging.323686 → 0.1.0-staging.415103

package/codeyam-cli/src/commands/editor.js

@@ -0,0 +1,696 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const STEP_LABELS = {
+    1: 'Plan',
+    2: 'Prototype',
+    3: 'Confirm',
+    4: 'Deconstruct',
+    5: 'Glossary',
+    6: 'Analyze',
+    7: 'App Scenarios',
+    8: 'User Scenarios',
+    9: 'Verify',
+    10: 'Review',
+};
+/**
+ * Append a JSONL log entry to .codeyam/logs/editor-log.jsonl
+ */
+function logEvent(root, event, data) {
+    try {
+        const logsDir = path.join(root, '.codeyam', 'logs');
+        fs.mkdirSync(logsDir, { recursive: true });
+        const logPath = path.join(logsDir, 'editor-log.jsonl');
+        const entry = JSON.stringify({
+            ts: new Date().toISOString(),
+            event,
+            ...data,
+        });
+        fs.appendFileSync(logPath, entry + '\n', 'utf8');
+    }
+    catch {
+        // Logging is best-effort
+    }
+}
+/**
+ * Get the project root (where .codeyam/ lives) or cwd.
+ */
+function getProjectRoot() {
+    return process.env.CODEYAM_ROOT_PATH || process.cwd();
+}
+/**
+ * Path to the editor step state file.
+ */
+function getStatePath(root) {
+    return path.join(root, '.codeyam', 'editor-step.json');
+}
+/**
+ * Read the current editor state, or null if none.
+ */
+function readState(root) {
+    const statePath = getStatePath(root);
+    try {
+        const content = fs.readFileSync(statePath, 'utf8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write the editor state.
+ */
+function writeState(root, state) {
+    const statePath = getStatePath(root);
+    const dir = path.dirname(statePath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2), 'utf8');
+}
+/**
+ * Clear the editor state (for starting a new feature).
+ */
+function clearState(root) {
+    const statePath = getStatePath(root);
+    try {
+        fs.unlinkSync(statePath);
+    }
+    catch {
+        // File doesn't exist, that's fine
+    }
+}
+/**
+ * Check if a project has been scaffolded (package.json exists).
+ */
+function hasProject(root) {
+    return fs.existsSync(path.join(root, 'package.json'));
+}
+/**
+ * Get the CodeYam server port from env or default.
+ */
+function getServerPort() {
+    return process.env.CODEYAM_PORT || '3111';
+}
+/**
+ * Print a checklist item.
+ * Inline backtick-wrapped text is highlighted in cyan for visibility.
+ */
+function checkbox(text) {
+    // Highlight `backtick-wrapped` segments in cyan
+    const highlighted = text.replace(/`([^`]+)`/g, (_m, code) => chalk.cyan(code));
+    console.log(`  ${chalk.dim('[ ]')} ${highlighted}`);
+}
+/**
+ * Print a section header.
+ */
+function stepHeader(step, title, feature) {
+    console.log();
+    console.log(chalk.bold.cyan(`━━━ Step ${step}: ${title} ━━━`));
+    if (feature) {
+        console.log(chalk.dim(`Feature: "${feature}"`));
+    }
+    console.log();
+}
+/**
+ * Print a colored progress tracker showing all 10 steps.
+ * Steps before `current` are green ✓, `current` is bold cyan →, future steps are dim ○.
+ */
+function printProgressTracker(current) {
+    console.log();
+    console.log(chalk.dim('┌─────────────────────────────────────┐'));
+    for (let i = 1; i <= 10; i++) {
+        const label = STEP_LABELS[i];
+        const num = i < 10 ? ` ${i}` : `${i}`;
+        const content = `${num}. ${label.padEnd(28)}`;
+        if (i < current) {
+            console.log(chalk.dim('  │') + chalk.green(`  ✓  ${content}`) + chalk.dim('│'));
+        }
+        else if (i === current) {
+            console.log(chalk.dim('  │') + chalk.bold.cyan(`  →  ${content}`) + chalk.dim('│'));
+        }
+        else {
+            console.log(chalk.dim(`  │  ○  ${content}│`));
+        }
+    }
+    console.log(chalk.dim('  └─────────────────────────────────────┘'));
+}
+/**
+ * Print a hard STOP gate directing to the next command.
+ *
+ * Options:
+ * - confirm: true  → step requires user confirmation before proceeding (steps 1, 3, 9)
+ */
+function stopGate(current, opts) {
+    console.log();
+    console.log(chalk.bold.red('━━━ STOP ━━━'));
+    console.log();
+    console.log(chalk.red('Complete ALL checklist items above before proceeding.'));
+    console.log(chalk.red('Do NOT skip ahead. Do NOT combine steps.'));
+    if (opts?.confirm) {
+        console.log();
+        console.log(chalk.yellow('Wait for user confirmation before moving on.'));
+    }
+    console.log();
+    console.log(chalk.bold.yellow('Present the following progress tracker to the user (copy it verbatim):'));
+    printProgressTracker(current);
+    console.log();
+    console.log(chalk.yellow('For the CURRENT step (→), show each checklist item with ✓ (done) or ✗ (skipped + reason).'));
+    console.log(chalk.yellow('If any items are ✗, explain why and ask if the user wants to address them.'));
+    console.log();
+    if (current < 10) {
+        console.log(chalk.green('When done, run: ') +
+            chalk.bold(`codeyam editor ${current + 1}`));
+    }
+    else {
+        console.log(chalk.green('Feature complete! Run: ') +
+            chalk.bold('codeyam editor 1') +
+            chalk.green(' to start the next feature'));
+    }
+    console.log();
+}
+// ─── Setup (no args, no project) ──────────────────────────────────────
+function printSetup(root) {
+    const port = getServerPort();
+    logEvent(root, 'setup');
+    console.log();
+    console.log(chalk.bold.cyan('━━━ Editor Mode: Project Setup ━━━'));
+    console.log();
+    console.log("No project detected. Let's scaffold one.");
+    console.log();
+    // Resolve the project template directory (works in both src/ and dist/)
+    const templateDir = path.join(__dirname, '..', '..', 'templates', 'nextjs-prisma-sqlite');
+    const hasTemplate = fs.existsSync(templateDir);
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Read `.codeyam/editor-mode-context.md` for session state');
+    checkbox('Ask the user what they want to build');
+    if (hasTemplate) {
+        checkbox('Copy the project template and install dependencies');
+        console.log();
+        console.log(chalk.dim('  Copy template (Next.js + Prisma 7 + SQLite, pre-configured):'));
+        console.log(chalk.dim(`  cp -r ${templateDir}/* .`));
+        console.log(chalk.dim(`  cp ${templateDir}/.env ${templateDir}/.gitignore .`));
+        console.log(chalk.dim('  npm install'));
+        console.log();
+        checkbox('Define your data models in `prisma/schema.prisma`');
+        console.log(chalk.dim("  Replace the placeholder Todo model with your app's models"));
+        console.log();
+        checkbox('Push schema and seed the database');
+        console.log(chalk.dim('  npm run db:push'));
+        console.log(chalk.dim('  # Edit prisma/seed.ts with your seed data, then:'));
+        console.log(chalk.dim('  npm run db:seed'));
+        console.log();
+        console.log(chalk.dim('  See PRISMA_SETUP.md for Prisma patterns and important warnings.'));
+        console.log(chalk.dim('  Key: import { prisma } from "@/app/lib/prisma" in API routes.'));
+        console.log(chalk.dim('  Key: Seed scripts must use the adapter pattern (see prisma/seed.ts).'));
+    }
+    else {
+        checkbox('Scaffold the project (Next.js recommended) using temp-dir-rsync pattern');
+        console.log();
+        console.log(chalk.dim('  Scaffolding pattern (avoids .claude/ conflicts):'));
+        console.log(chalk.dim('  SCAFFOLD_DIR="/tmp/codeyam-scaffold-$$" && mkdir -p "$SCAFFOLD_DIR"'));
+        console.log(chalk.dim('  npx create-next-app@latest "$SCAFFOLD_DIR" --typescript --tailwind --eslint \\'));
+        console.log(chalk.dim('    --app --no-src-dir --no-import-alias --no-react-compiler --turbopack'));
+        console.log(chalk.dim('  rsync -a --exclude=\'.git\' "$SCAFFOLD_DIR/" . && rm -rf "$SCAFFOLD_DIR"'));
+        console.log();
+        checkbox('Set up Prisma + SQLite database');
+        console.log(chalk.dim('  npm install prisma @prisma/client @prisma/adapter-better-sqlite3 better-sqlite3'));
+        console.log(chalk.dim('  npm install -D @types/better-sqlite3'));
+        console.log(chalk.dim('  npx prisma init --datasource-provider sqlite'));
+        console.log(chalk.dim('  # Define schema, then: npx prisma db push'));
+    }
+    console.log();
+    checkbox('Run `codeyam init --force --keep-server` to detect the project and configure it');
+    console.log(chalk.dim('  This auto-detects webapps and configures the start command for analysis'));
+    console.log();
+    checkbox('Verify `.codeyam/config.json` has `startCommand` in the webapp entry');
+    console.log(chalk.dim('  Should look like: "startCommand": { "command": "sh", "args": ["-c", "npm run dev -- --port $PORT"] }'));
+    console.log(chalk.dim('  If missing, add it manually. $PORT is replaced at runtime by the analyzer.'));
+    console.log();
+    checkbox(`Notify CodeYam: \`curl -s -X POST http://localhost:${port}/api/editor-refresh\``);
+    checkbox('Verify the preview loads in the browser');
+    console.log();
+    console.log(chalk.bold.red('━━━ STOP ━━━'));
+    console.log();
+    console.log(chalk.red('Complete ALL checklist items above. Do NOT start building features yet.'));
+    console.log();
+    console.log(chalk.bold.yellow('Present a completion checklist to the user:'));
+    console.log(chalk.yellow('Show each setup checklist item with ✓ (done) or ✗ (skipped + reason).'));
+    console.log(chalk.yellow('If any items are ✗, explain why and ask if the user wants to address them.'));
+    console.log();
+    console.log(chalk.green('When setup is complete, run: ') +
+        chalk.bold('codeyam editor 1') +
+        chalk.green(' to start your first feature'));
+    console.log();
+}
+// ─── Cycle overview (no args, has project) ────────────────────────────
+function printCycleOverview(root, state) {
+    logEvent(root, 'overview', state ? { feature: state.feature, step: state.step } : {});
+    console.log();
+    console.log(chalk.bold.cyan('━━━ Editor Mode: Feature Cycle ━━━'));
+    console.log();
+    if (state) {
+        console.log(chalk.yellow(`Current: Step ${state.step} (${state.label}) — "${state.feature}"`));
+        console.log();
+        console.log(chalk.green('Continue with: ') +
+            chalk.bold(`codeyam editor ${state.step}`));
+        console.log(chalk.dim('Or run ') +
+            chalk.bold('codeyam editor 1') +
+            chalk.dim(' to start a new feature'));
+    }
+    else {
+        console.log('Each feature follows 10 steps. You MUST run each command in order:');
+        console.log();
+        console.log(`  ${chalk.bold.yellow(' 1')} ${chalk.bold('Plan')}            — Plan the feature, confirm with user`);
+        console.log(`  ${chalk.bold.yellow(' 2')} ${chalk.bold('Prototype')}       — Build a working prototype fast`);
+        console.log(`  ${chalk.bold.yellow(' 3')} ${chalk.bold('Confirm')}         — Confirm prototype with user`);
+        console.log(`  ${chalk.bold.yellow(' 4')} ${chalk.bold('Deconstruct')}     — TDD extraction into small functions`);
+        console.log(`  ${chalk.bold.yellow(' 5')} ${chalk.bold('Glossary')}        — Record functions in glossary`);
+        console.log(`  ${chalk.bold.yellow(' 6')} ${chalk.bold('Analyze')}         — Analyze and verify components`);
+        console.log(`  ${chalk.bold.yellow(' 7')} ${chalk.bold('App Scenarios')}   — Create app-level scenarios`);
+        console.log(`  ${chalk.bold.yellow(' 8')} ${chalk.bold('User Scenarios')}  — Create user-persona scenarios`);
+        console.log(`  ${chalk.bold.yellow(' 9')} ${chalk.bold('Verify')}          — Review screenshots, check for errors`);
+        console.log(`  ${chalk.bold.yellow('10')} ${chalk.bold('Review')}          — Present summary, get approval`);
+        console.log();
+        console.log(chalk.green('Start now: ') + chalk.bold('codeyam editor 1'));
+    }
+    console.log();
+}
+// ─── Step 1: Plan ─────────────────────────────────────────────────────
+function printStep1(root) {
+    clearState(root);
+    logEvent(root, 'step', { step: 1, label: 'Plan' });
+    stepHeader(1, 'Plan');
+    console.log('Plan the feature before writing ANY code.');
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Read `.codeyam/glossary.json` for reusable functions/components');
+    checkbox('Ask the user what they want to build');
+    checkbox('Identify the data model (what API routes will return)');
+    checkbox('Identify the components needed (reuse from glossary where possible)');
+    checkbox('Identify demo/seed data for the prototype');
+    checkbox('Present the plan and wait for user confirmation');
+    console.log();
+    console.log(chalk.dim('Do NOT write any code during this step. Plan only.'));
+    console.log();
+    console.log(chalk.bold.red('━━━ STOP ━━━'));
+    console.log();
+    console.log(chalk.red('Complete ALL checklist items above before proceeding.'));
+    console.log(chalk.red('Do NOT skip ahead. Do NOT combine steps.'));
+    console.log();
+    console.log(chalk.yellow('Wait for user confirmation before moving on.'));
+    console.log();
+    console.log(chalk.bold.yellow('Present the following progress tracker to the user (copy it verbatim):'));
+    printProgressTracker(1);
+    console.log();
+    console.log(chalk.yellow('For the CURRENT step (→), show each checklist item with ✓ (done) or ✗ (skipped + reason).'));
+    console.log(chalk.yellow('If any items are ✗, explain why and ask if the user wants to address them.'));
+    console.log();
+    console.log(chalk.green('When done, run: ') +
+        chalk.bold('codeyam editor 2 --feature "Feature Name"'));
+    console.log(chalk.dim('  Replace "Feature Name" with a short title for what you just described.'));
+    console.log();
+}
+// ─── Step 2: Prototype ────────────────────────────────────────────────
+function printStep2(root, feature) {
+    const port = getServerPort();
+    writeState(root, {
+        feature,
+        step: 2,
+        label: STEP_LABELS[2],
+        startedAt: new Date().toISOString(),
+    });
+    logEvent(root, 'step', { step: 2, label: 'Prototype', feature });
+    stepHeader(2, 'Prototype', feature);
+    console.log('Build fast with real data. Prioritize speed over quality.');
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Create/update API routes (real database reads via Prisma)');
+    checkbox('Seed the database with demo data');
+    checkbox('Build the page/feature UI components');
+    checkbox('Verify the dev server shows the changes');
+    console.log();
+    console.log(chalk.bold('Verify the dev server:'));
+    console.log(chalk.dim(`  # Get dev server URL: curl -s http://localhost:${port}/api/editor-dev-server`));
+    console.log(chalk.dim('  # Check page loads: curl -s -o /dev/null -w "%{http_code}" http://localhost:<dev-port>'));
+    console.log(chalk.dim('  # Check API routes: curl -s http://localhost:<dev-port>/api/your-route'));
+    console.log();
+    console.log(chalk.dim('Do NOT create scenarios or run codeyam analyze. Do NOT refactor.'));
+    stopGate(2);
+}
+// ─── Step 3: Confirm ──────────────────────────────────────────────────
+function printStep3(root, feature) {
+    writeState(root, {
+        feature,
+        step: 3,
+        label: STEP_LABELS[3],
+        startedAt: new Date().toISOString(),
+    });
+    logEvent(root, 'step', { step: 3, label: 'Confirm', feature });
+    stepHeader(3, 'Confirm', feature);
+    console.log('Summarize what was built and get user confirmation.');
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Summarize what was built (routes, components, data)');
+    checkbox('Show the user the current state of the prototype');
+    console.log();
+    console.log(chalk.bold('Present a selection menu to the user (use AskUserQuestion):'));
+    console.log(chalk.green('    "Yes, this looks right!"') +
+        chalk.dim(' — proceed to step 4'));
+    console.log(chalk.yellow('    "I\'d like some changes"') +
+        chalk.dim(' — user describes changes, you make them, then re-present'));
+    console.log();
+    console.log(chalk.dim('Do NOT refactor or create scenarios until the user approves the prototype.'));
+    stopGate(3, { confirm: true });
+}
+// ─── Step 4: Deconstruct ──────────────────────────────────────────────
+function printStep4(root, feature) {
+    writeState(root, {
+        feature,
+        step: 4,
+        label: STEP_LABELS[4],
+        startedAt: new Date().toISOString(),
+    });
+    logEvent(root, 'step', { step: 4, label: 'Deconstruct', feature });
+    stepHeader(4, 'Deconstruct', feature);
+    console.log('TDD extraction: write failing tests first, then extract.');
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Read `.codeyam/glossary.json` — reuse existing functions/components where they fit');
+    checkbox('Review the prototype code for extractable logic');
+    checkbox('Extract reusable components (each should accept props, render independently)');
+    checkbox('Extract utility functions (pure functions where possible)');
+    checkbox('Each component should be small enough to analyze independently');
+    console.log();
+    console.log(chalk.bold('Testing — CRITICAL:'));
+    console.log(chalk.yellow('  Every extracted library function MUST have a dedicated test file'));
+    console.log(chalk.yellow('  with thorough coverage. `codeyam analyze` only captures screenshots'));
+    console.log(chalk.yellow('  for visual components — it does NOT test library functions.'));
+    console.log(chalk.yellow('  Your tests ARE the only test coverage for these functions.'));
+    console.log();
+    checkbox('For each extracted function: write MULTIPLE failing tests FIRST, then extract to make them pass');
+    console.log(chalk.dim('    Cover: typical inputs, edge cases, empty/null inputs, error conditions'));
+    console.log(chalk.dim('    Aim for 3-8 test cases per function depending on complexity'));
+    checkbox('Place test files next to source: `app/lib/drinks.ts` → `app/lib/drinks.test.ts`');
+    checkbox('Run all tests and verify they pass before proceeding');
+    console.log();
+    console.log(chalk.dim('Reuse glossary functions when they fit naturally — but do NOT overload an existing'));
+    console.log(chalk.dim('function to handle too many situations. Extract a new one if the use case diverges.'));
+    console.log();
+    console.log(chalk.dim('Do NOT create scenarios. Write failing tests first, then extract. TDD only.'));
+    stopGate(4);
+}
+// ─── Step 5: Glossary ─────────────────────────────────────────────────
+function printStep5(root, feature) {
+    writeState(root, {
+        feature,
+        step: 5,
+        label: STEP_LABELS[5],
+        startedAt: new Date().toISOString(),
+    });
+    logEvent(root, 'step', { step: 5, label: 'Glossary', feature });
+    stepHeader(5, 'Glossary', feature);
+    console.log('Record all new functions/components in `.codeyam/glossary.json`.');
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox("Read `.codeyam/glossary.json` (create if it doesn't exist)");
+    checkbox('Add an entry for each new function/component extracted in step 4');
+    checkbox('Each entry should have: name, filePath, description, parameters, returnType, tags, feature');
+    checkbox('For each function with a test file from step 4, set `testFile` to the relative path');
+    console.log();
+    console.log(chalk.bold('Entry format:'));
+    console.log(chalk.dim('  { "name": "calculateTotal", "filePath": "app/utils/pricing.ts",'));
+    console.log(chalk.dim('    "description": "Calculates total price including tax and discounts",'));
+    console.log(chalk.dim('    "parameters": [{ "name": "items", "type": "CartItem[]" }],'));
+    console.log(chalk.dim('    "returnType": "number", "tags": ["pricing"],'));
+    console.log(chalk.dim('    "testFile": "app/utils/pricing.test.ts",'));
+    console.log(chalk.dim(`    "feature": "${feature}", "createdAt": "..." }`));
+    console.log();
+    console.log(chalk.dim('Do NOT write application code or create scenarios. Update the glossary only.'));
+    stopGate(5);
+}
+// ─── Step 6: Analyze ──────────────────────────────────────────────────
+function printStep6(root, feature) {
+    writeState(root, {
+        feature,
+        step: 6,
+        label: STEP_LABELS[6],
+        startedAt: new Date().toISOString(),
+    });
+    logEvent(root, 'step', { step: 6, label: 'Analyze', feature });
+    stepHeader(6, 'Analyze and Verify', feature);
+    console.log('Verify both visual components (via `codeyam analyze`) and library functions (via tests).');
+    console.log();
+    console.log(chalk.bold('Visual Components — `codeyam analyze`:'));
+    checkbox('List all files with new/modified visual components from step 4');
+    checkbox('Run ONE `codeyam analyze --noOpen` command with all component files');
+    console.log(chalk.dim('    Example: codeyam analyze --noOpen app/components/DrinkCard.tsx app/components/StarRating.tsx'));
+    console.log(chalk.dim('    This discovers and analyzes all entities in all listed files in one pass'));
+    console.log(chalk.dim('    Use --entity to filter specific entities: --entity DrinkCard --entity StarRating'));
+    checkbox('Wait for the analyze command to complete');
+    checkbox('Check results — if any failed, read the log and fix the source code');
+    console.log(chalk.dim('    Log location: /tmp/codeyam/local-dev/<project-slug>/codeyam/log.txt'));
+    checkbox('Re-run `codeyam analyze` on fixed files until all pass');
+    console.log();
+    console.log(chalk.bold('Library Functions — run tests:'));
+    console.log(chalk.dim('  `codeyam analyze` does NOT test library functions. The tests'));
+    console.log(chalk.dim('  you wrote in step 4 are the only coverage for these functions.'));
+    checkbox('Run ALL test files created in step 4');
+    console.log(chalk.dim('    Example: npx vitest run app/lib/drinks.test.ts'));
+    checkbox('Verify every test passes');
+    checkbox('If any test fails, fix the source code and re-run');
+    console.log();
+    console.log(chalk.dim('Do not proceed until both visual analyses and library tests pass.'));
+    stopGate(6);
+}
+// ─── Step 7: App Scenarios ────────────────────────────────────────────
+function printStep7(root, feature) {
+    const port = getServerPort();
+    writeState(root, {
+        feature,
+        step: 7,
+        label: STEP_LABELS[7],
+        startedAt: new Date().toISOString(),
+    });
+    logEvent(root, 'step', { step: 7, label: 'App Scenarios', feature });
+    stepHeader(7, 'App Scenarios', feature);
+    console.log('Create app-level scenarios representing different data states.');
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Create scenarios for key data states (empty, loaded, error)');
+    console.log(chalk.dim('    Each scenario provides data across ALL API routes for that state'));
+    checkbox('Register each scenario (auto-captures screenshot):');
+    console.log(chalk.dim(`    curl -s -X POST http://localhost:${port}/api/editor-register-scenario \\`));
+    console.log(chalk.dim(`      -H 'Content-Type: application/json' \\`));
+    console.log(chalk.dim(`      -d '{"name":"...","description":"...","mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
+    checkbox('Create a journal entry for the feature:');
+    console.log(chalk.dim(`    curl -s -X POST http://localhost:${port}/api/editor-journal-entry \\`));
+    console.log(chalk.dim(`      -H 'Content-Type: application/json' \\`));
+    console.log(chalk.dim(`      -d '{"title":"...","type":"feature","description":"...","scenarios":["..."]}'`));
+    console.log();
+    console.log(chalk.dim('Do NOT modify application code. Create and register app-level scenarios only.'));
+    stopGate(7);
+}
+// ─── Step 8: User Scenarios ───────────────────────────────────────────
+function printStep8(root, feature) {
+    const port = getServerPort();
+    writeState(root, {
+        feature,
+        step: 8,
+        label: STEP_LABELS[8],
+        startedAt: new Date().toISOString(),
+    });
+    logEvent(root, 'step', { step: 8, label: 'User Scenarios', feature });
+    stepHeader(8, 'User Scenarios', feature);
+    console.log('Create per-persona scenarios if the app has users. Skip to step 9 if no users.');
+    console.log();
+    console.log(chalk.bold('If the app has users:'));
+    checkbox('Create scenarios for each user persona (admin, regular user, new user)');
+    console.log(chalk.dim('    Each persona scenario provides data across ALL API routes for that user type'));
+    checkbox('Register each persona scenario (auto-captures screenshot):');
+    console.log(chalk.dim(`    curl -s -X POST http://localhost:${port}/api/editor-register-scenario \\`));
+    console.log(chalk.dim(`      -H 'Content-Type: application/json' \\`));
+    console.log(chalk.dim(`      -d '{"name":"...","description":"...","mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
+    console.log();
+    console.log(chalk.bold('If the app has NO users:'));
+    console.log(chalk.dim('  Skip this step and proceed to step 9 (Verify).'));
+    console.log();
+    console.log(chalk.dim('Do NOT modify application code. Create user-persona scenarios only (or skip if no users).'));
+    stopGate(8);
+}
+// ─── Step 9: Verify ──────────────────────────────────────────────────
+function printStep9(root, feature) {
+    const port = getServerPort();
+    writeState(root, {
+        feature,
+        step: 9,
+        label: STEP_LABELS[9],
+        startedAt: new Date().toISOString(),
+    });
+    logEvent(root, 'step', { step: 9, label: 'Verify', feature });
+    stepHeader(9, 'Verify', feature);
+    console.log('Verify entity screenshots, editor scenarios, and library tests. After ANY code fix, re-analyze affected files.');
+    console.log();
+    console.log(chalk.bold('Entity screenshots (Data tab) — verify via API:'));
+    checkbox(`Check entity status: \`curl -s http://localhost:${port}/api/editor-entity-status\``);
+    checkbox('Review `summary.missingScreenshots` — each listed entity needs `codeyam analyze --noOpen <file>`');
+    checkbox('Open the Data tab and review each entity screenshot for visual correctness');
+    checkbox('If any screenshot looks wrong, fix the component code');
+    console.log(chalk.yellow('    IMPORTANT: After fixing ANY visual component, re-run `codeyam analyze --noOpen <file>`'));
+    console.log(chalk.yellow('    to update the entity screenshot. Re-capturing an editor scenario is NOT sufficient.'));
+    console.log();
+    console.log(chalk.bold('Editor scenarios (App tab) — visual + error check:'));
+    checkbox(`Refresh the preview: \`curl -s -X POST http://localhost:${port}/api/editor-refresh\``);
+    checkbox('Click through each app-level and user-persona scenario in the preview');
+    checkbox('Check for visual correctness and client-side errors (Console tab)');
+    console.log(chalk.dim('    Look for: React errors, failed fetches, undefined references, hydration mismatches'));
+    checkbox('If any errors found, fix the source code and re-test');
+    console.log(chalk.yellow('    After fixing code that affects visual components, also re-run `codeyam analyze --noOpen <file>`'));
+    console.log();
+    console.log(chalk.bold('Library functions — test check:'));
+    checkbox('Re-run all test files from step 4 to confirm they still pass');
+    console.log(chalk.dim('    Example: npx vitest run app/lib/drinks.test.ts'));
+    checkbox('If any test fails, fix the source code and re-run');
+    console.log();
+    console.log(chalk.dim('Do NOT add new features. Fix issues only. All entity screenshots, scenarios, and tests must be clean.'));
+    stopGate(9);
+}
+// ─── Step 10: Review ──────────────────────────────────────────────────
+function printStep10(root, feature) {
+    const port = getServerPort();
+    writeState(root, {
+        feature,
+        step: 10,
+        label: STEP_LABELS[10],
+        startedAt: new Date().toISOString(),
+    });
+    logEvent(root, 'step', { step: 10, label: 'Review', feature });
+    stepHeader(10, 'Review', feature);
+    console.log('Present a full summary, verify screenshots, then let the user save or revise.');
+    console.log();
+    console.log(chalk.bold('Phase 1 — Summary:'));
+    checkbox('Summarize the feature that was built');
+    checkbox('List all components and functions created');
+    checkbox('List glossary entries added in step 5');
+    checkbox('List all scenarios (app-level and user-persona)');
+    checkbox('Report analysis status (completed/in-progress from step 6)');
+    checkbox('Report verification status from step 9 (all clean?)');
+    checkbox(`Refresh the preview: \`curl -s -X POST http://localhost:${port}/api/dev-mode-refresh\``);
+    console.log();
+    console.log(chalk.bold('Phase 2 — Screenshot & error verification:'));
+    console.log(chalk.yellow('  CRITICAL: Verify screenshots AND check for client-side errors.'));
+    console.log();
+    console.log(chalk.bold('  Entity screenshots:'));
+    checkbox(`Check entity status: \`curl -s http://localhost:${port}/api/editor-entity-status\``);
+    checkbox('Review `summary.missingScreenshots` — each listed entity needs `codeyam analyze --noOpen <file>`');
+    checkbox('For each component created in this feature, confirm it has a screenshot in the Data tab');
+    console.log();
+    console.log(chalk.bold('  Client-side errors:'));
+    checkbox(`Check for errors: \`curl -s http://localhost:${port}/api/editor-client-errors\``);
+    checkbox('If `hasErrors` is true, list the errors and fix them in the source code');
+    checkbox('After fixing, re-capture affected scenarios to clear the errors');
+    console.log();
+    checkbox('Do NOT proceed until all components have screenshots AND client errors are resolved');
+    console.log();
+    checkbox('Present the summary (with screenshot and error status) to the user');
+    console.log();
+    console.log(chalk.bold('Phase 3 — Present a selection menu to the user (use AskUserQuestion):'));
+    console.log(chalk.green('    "Save & commit"') +
+        chalk.dim(' — git commit all changes and record in journal'));
+    console.log(chalk.yellow('    "I\'d like to make some changes"') +
+        chalk.dim(' — describe changes, then re-verify'));
+    console.log();
+    console.log(chalk.bold('If the user chooses "Save & commit":'));
+    checkbox(`Git commit all changes: \`curl -s -X POST http://localhost:${port}/api/editor-commit -H 'Content-Type: application/json' -d '{"message":"feat: <feature name>"}'\``);
+    checkbox(`Update journal entry with commit SHA: \`curl -s -X PATCH http://localhost:${port}/api/editor-journal-update -H 'Content-Type: application/json' -d '{"time":"<journal entry time>","commitSha":"<sha>","commitMessage":"feat: <feature name>"}'\``);
+    console.log(chalk.green('  Then run: ') +
+        chalk.bold('codeyam editor 1') +
+        chalk.green(' to start the next feature'));
+    console.log();
+    console.log(chalk.bold('If the user chooses "Make changes":'));
+    checkbox('Ask what changes the user wants');
+    checkbox('Make the requested changes');
+    checkbox(`Update the journal entry description: \`curl -s -X PATCH http://localhost:${port}/api/editor-journal-update -H 'Content-Type: application/json' -d '{"time":"<journal entry time>","description":"<updated description>"}'\``);
+    console.log(chalk.yellow('  Then run: ') +
+        chalk.bold('codeyam editor 9') +
+        chalk.yellow(' to re-verify, which flows back to step 10'));
+    console.log();
+    console.log(chalk.dim('Do NOT skip the screenshot verification or user menu. Complete all phases in order.'));
+    stopGate(10, { confirm: true });
+}
+// ─── Command definition ───────────────────────────────────────────────
+const editorCommand = {
+    command: 'editor [step]',
+    describe: 'Editor mode guided workflow',
+    builder: (yargs) => {
+        return yargs
+            .positional('step', {
+            type: 'number',
+            describe: 'Step number (1-10)',
+            choices: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+        })
+            .option('feature', {
+            type: 'string',
+            describe: 'Feature name (required for step 2)',
+        });
+    },
+    handler: (argv) => {
+        const root = getProjectRoot();
+        if (argv.step == null) {
+            // No step specified: setup or overview
+            if (!hasProject(root)) {
+                printSetup(root);
+            }
+            else {
+                const state = readState(root);
+                printCycleOverview(root, state);
+            }
+            return;
+        }
+        const state = readState(root);
+        switch (argv.step) {
+            case 1:
+                printStep1(root);
+                break;
+            case 2: {
+                const feature = argv.feature || state?.feature;
+                if (!feature) {
+                    console.error(chalk.red('Error: --feature "Feature Name" is required for step 2.'));
+                    console.error(chalk.dim('  Usage: codeyam editor 2 --feature "Drink Rating System"'));
+                    process.exit(1);
+                }
+                printStep2(root, feature);
+                break;
+            }
+            case 3:
+            case 4:
+            case 5:
+            case 6:
+            case 7:
+            case 8:
+            case 9:
+            case 10: {
+                const feature = argv.feature || state?.feature;
+                if (!feature) {
+                    console.error(chalk.red('Error: No feature in progress. Run codeyam editor 1 first.'));
+                    process.exit(1);
+                }
+                const stepFns = {
+                    3: printStep3,
+                    4: printStep4,
+                    5: printStep5,
+                    6: printStep6,
+                    7: printStep7,
+                    8: printStep8,
+                    9: printStep9,
+                    10: printStep10,
+                };
+                stepFns[argv.step](root, feature);
+                break;
+            }
+        }
+    },
+};
+export default editorCommand;
+//# sourceMappingURL=editor.js.map