@codeyam/codeyam-cli 0.1.22 → 0.1.24

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

@@ -13,6 +13,7 @@ import { installClaudeCodeSkills } from "../utils/install-skills.js";
 import { setupClaudeCodeSettings } from "../utils/setupClaudeCodeSettings.js";
 import { ensureAnalyzerFinalized, } from "../utils/analyzerFinalization.js";
 import { APP_FORMATS, TECH_STACKS } from "../data/techStacks.js";
+import { DESIGN_SYSTEMS } from "../data/designSystems.js";
 import { getProjectRoot as getStateProjectRoot } from "../state.js";
 import initCommand from "./init.js";
 import { scanScenarioFiles, syncScenarioFilesToDatabase, backfillScenarioMetadata, migrateScenarioFormats, } from "../utils/scenariosManifest.js";
@@ -714,11 +715,17 @@ function printSetup(root) {
     console.log();
     // ── Design System ────────────────────────────────────────────────
     console.log(chalk.bold('Design System (ask FIRST):'));
-    console.log(chalk.dim('  Ask: "Do you have a design system, brand guidelines, or style preferences you\'d like me to follow?"'));
+    console.log(chalk.dim('  Ask: "What visual style do you want? Pick a built-in design system or bring your own."'));
     console.log(chalk.dim('  Use AskUserQuestion with these EXACT option labels:'));
-    console.log(chalk.yellow('    Option 1 label: "Yes, I\'ll paste my design system"'));
+    console.log();
+    for (const ds of DESIGN_SYSTEMS) {
+        console.log(chalk.yellow(`    Option label: "${ds.name}"`) +
+            chalk.dim(` — ${ds.description}`));
+        console.log(chalk.dim(`       → Run: codeyam editor design-system ${ds.id}`));
+    }
+    console.log(chalk.yellow('    Option label: "I\'ll paste my own design system"'));
     console.log(chalk.dim('       → Wait for paste, save to .codeyam/design-system.md, confirm with brief summary'));
-    console.log(chalk.yellow('    Option 2 label: "No, use sensible defaults"'));
+    console.log(chalk.yellow('    Option label: "Skip — use sensible defaults"'));
     console.log(chalk.dim('       → Skip'));
     console.log();
     console.log(chalk.bold('Checklist:'));
@@ -1132,14 +1139,13 @@ function printStep4(root, feature) {
     console.log('Verify everything works before presenting the prototype.');
     console.log();
     console.log(chalk.bold('Verify the dev server:'));
-    console.log(chalk.dim(`  # Get dev server URL: codeyam 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(chalk.dim('  # Verify pages and API routes load:'));
+    console.log(chalk.dim(`  codeyam editor verify-routes '{"paths":["/your-page"],"apiRoutes":["/api/your-route"]}'`));
     console.log();
     console.log(chalk.bold('Verify before proceeding:'));
     console.log(chalk.yellow('  Verify everything works before presenting the prototype to the user.'));
-    checkbox('Verify the page loads: curl the dev server URL and confirm HTTP 200 (not an error page)');
-    checkbox('Verify API routes return valid JSON: curl each route and confirm no error responses');
+    checkbox('Verify page and API routes: `codeyam editor verify-routes \'{"paths":["/"],"apiRoutes":["/api/your-route"]}\'`');
+    console.log(chalk.dim('    Include ALL page paths you built and ALL API routes they depend on.'));
     checkbox('Check for broken images: `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1","url2"]}\'`');
     console.log(chalk.dim('    Pass ALL page paths and ALL image URLs you used in seed data / API responses.'));
     console.log(chalk.dim('    Client-rendered pages need imageUrls — the HTML shell has no images to scan.'));
@@ -1182,7 +1188,7 @@ function printStep5(root, feature) {
     console.log();
     console.log(chalk.bold('Before presenting — verify everything works:'));
     checkbox(`Refresh the preview: \`codeyam editor preview '{"dimension":"${dim}"}'\` — check the \`preview\` field for \`healthy: false\``);
-    checkbox('Verify API routes return valid data (curl each route)');
+    checkbox('Verify routes: `codeyam editor verify-routes \'{"paths":["/"],"apiRoutes":["/api/your-route"]}\'`');
     console.log();
     console.log(chalk.bold.red('  Verify EVERY image loads (this is the #1 source of broken prototypes):'));
     checkbox('Run `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1","url2"]}\'`');
@@ -1978,7 +1984,7 @@ function printMigrateStep8(root) {
     printComponentCaptureInstructions();
     console.log();
     console.log(chalk.bold('Verify:'));
-    checkbox('Run `codeyam editor analyze-imports` to populate import graph');
+    checkbox('Run `codeyam editor analyze-imports` to populate import graph (or `codeyam editor analyze-imports path/to/file.tsx ...` for specific files)');
     checkbox('Run library function tests: `npx jest --testPathPattern="<relevant>" --maxWorkers=2`');
     checkbox('Run `codeyam editor audit` to check completeness');
     checkbox('Check for client errors: `codeyam editor client-errors`');
@@ -2356,10 +2362,14 @@ async function handleAnalyzeImports(options = {}) {
         glossaryEntries = sanitizeGlossaryEntries(parsed);
     }
     catch {
+        if (options.silent)
+            return;
         console.error(chalk.red('Error: Could not parse .codeyam/glossary.json.'));
         process.exit(1);
     }
     if (glossaryEntries.length === 0) {
+        if (options.silent)
+            return;
         console.error(chalk.red('Error: glossary.json is empty.'));
         process.exit(1);
     }
@@ -2428,6 +2438,15 @@ async function handleAnalyzeImports(options = {}) {
     catch {
         // Non-fatal — fall back to analyzing all files
     }
+    // If specific file paths were requested, scope analysis to only those files.
+    // The full filePaths set is still used for the import graph below.
+    if (options.filePaths && options.filePaths.length > 0) {
+        const requested = new Set(options.filePaths);
+        targetFilePaths = targetFilePaths.filter((fp) => requested.has(fp));
+        if (targetFilePaths.length === 0 && !options.silent) {
+            console.log(chalk.dim('Requested file(s) already analyzed or not in glossary — skipping analysis.'));
+        }
+    }
     // Run data-structure-only analysis for entities that need it.
     // Don't pass entityNames — entities may not exist yet (fresh clone).
     // The analyzer will discover and create them from file paths.
@@ -2444,6 +2463,10 @@ async function handleAnalyzeImports(options = {}) {
         catch (err) {
             progress.fail('Analysis failed');
             const msg = err instanceof Error ? err.message : String(err);
+            if (options.silent) {
+                // Internal caller — don't kill the process, let the caller handle it
+                return;
+            }
             console.error(chalk.red(`Error: ${msg}`));
             process.exit(1);
         }
@@ -2499,18 +2522,10 @@ async function handleAnalyzeImports(options = {}) {
                     }
                 }
             }
-            else if (targetFilePaths.length > 0) {
-                // Couldn't parse specific entity names — mark all target files
-                // that we attempted to analyze as potentially failed
-                for (const fp of targetFilePaths) {
-                    const entry = glossary.find((e) => e.filePath === fp);
-                    updatedFailures[fp] = {
-                        entityName: entry?.name || path.basename(fp, path.extname(fp)),
-                        error: `Automated analysis failed — see .codeyam/analysis-errors.txt`,
-                        failedAt: now,
-                    };
-                }
-            }
+            // When we can't parse specific entity names from the error, DON'T mark
+            // all target files as failed. The error may be non-fatal (e.g., a cache
+            // miss logged as "CodeYam Error") and blanket-marking every file as
+            // permanently failed blocks future audits from resolving them.
             writeAnalysisFailures(root, updatedFailures);
         }
         catch {
@@ -2709,6 +2724,24 @@ async function handleDelete(scenarioId) {
  * Creates isolation route directories and the layout guard file.
  * This avoids brace-expansion permission prompts in the embedded terminal.
  */
+function handleDesignSystem(designSystemId) {
+    const root = process.cwd();
+    const ds = DESIGN_SYSTEMS.find((d) => d.id === designSystemId);
+    if (!ds) {
+        console.error(chalk.red(`Error: Unknown design system "${designSystemId}". Valid options: ${DESIGN_SYSTEMS.map((d) => d.id).join(', ')}`));
+        process.exit(1);
+    }
+    const srcPath = path.join(__dirname, '..', '..', 'templates', 'design-systems', ds.fileName);
+    if (!fs.existsSync(srcPath)) {
+        console.error(chalk.red(`Error: Design system file not found: ${srcPath}`));
+        process.exit(1);
+    }
+    const destDir = path.join(root, '.codeyam');
+    fs.mkdirSync(destDir, { recursive: true });
+    const destPath = path.join(destDir, 'design-system.md');
+    fs.copyFileSync(srcPath, destPath);
+    console.log(chalk.green(`Installed "${ds.name}" design system → .codeyam/design-system.md`));
+}
 function handleIsolate(componentNames) {
     const root = process.cwd();
     if (componentNames.length === 0) {
@@ -2848,6 +2881,34 @@ function formatApiSubcommandResult(subcommand, data) {
             }
             return parts.join(' ');
         }
+        case 'verify-routes': {
+            const lines = [];
+            lines.push(chalk.bold.yellow('━━━ Route Verification ━━━'));
+            for (const [route, info] of Object.entries(data.routes || {})) {
+                const r = info;
+                if (r.ok) {
+                    lines.push(chalk.green(`  ✓ ${route} — HTTP ${r.status}`));
+                }
+                else {
+                    lines.push(chalk.red(`  ✗ ${route} — ${r.error || `HTTP ${r.status}`}`));
+                }
+            }
+            for (const [route, info] of Object.entries(data.apiRoutes || {})) {
+                const r = info;
+                if (r.ok && r.isJSON) {
+                    lines.push(chalk.green(`  ✓ ${route} — HTTP ${r.status}, valid JSON`));
+                }
+                else if (r.ok) {
+                    lines.push(chalk.yellow(`  ⚠ ${route} — HTTP ${r.status}, not valid JSON`));
+                }
+                else {
+                    lines.push(chalk.red(`  ✗ ${route} — ${r.error || `HTTP ${r.status}`}`));
+                }
+            }
+            lines.push('');
+            lines.push(data.ok ? chalk.green(data.summary) : chalk.red(data.summary));
+            return lines.join('\n');
+        }
         default:
             return null; // journal-list, show/hide-results: keep full JSON
     }
@@ -3454,7 +3515,15 @@ function printAuditGateFailures(data) {
         for (const m of missingGlossary) {
             issues.push(`    → ${m.name} (${m.filePath})`);
         }
-        issues.push(`      Fix: Run \`codeyam editor analyze-imports\` to add these files to the glossary`);
+        const missingPaths = missingGlossary
+            .map((m) => m.filePath)
+            .filter(Boolean);
+        if (missingPaths.length > 0) {
+            issues.push(`      Fix: Run \`codeyam editor analyze-imports ${missingPaths.join(' ')}\``);
+        }
+        else {
+            issues.push(`      Fix: Run \`codeyam editor analyze-imports\` to add these files to the glossary`);
+        }
     }
     if (s.incompleteEntities > 0) {
         // Check for persistent analysis failures
@@ -3498,8 +3567,16 @@ function printAuditGateFailures(data) {
         }
     }
     if (s.unassociatedScenarios > 0) {
-        issues.push(`${s.unassociatedScenarios} component(s) have scenarios with no entity link — run \`codeyam editor analyze-imports\` then re-run audit`);
         const unassociated = data.unassociatedScenarios || [];
+        const unassocPaths = unassociated
+            .map((u) => u.filePath)
+            .filter(Boolean);
+        if (unassocPaths.length > 0) {
+            issues.push(`${s.unassociatedScenarios} component(s) have scenarios with no entity link — run \`codeyam editor analyze-imports ${unassocPaths.join(' ')}\` then re-run audit`);
+        }
+        else {
+            issues.push(`${s.unassociatedScenarios} component(s) have scenarios with no entity link — run \`codeyam editor analyze-imports\` then re-run audit`);
+        }
         for (const u of unassociated) {
             issues.push(`    → ${u.name} (${u.filePath}) — ${u.scenarioCount} scenario${u.scenarioCount !== 1 ? 's' : ''}`);
         }
@@ -3554,16 +3631,16 @@ function printAuditGateFailures(data) {
  * which glossary components have registered scenarios and which functions
  * have test files. Exits with code 1 if anything is missing.
  */
-async function handleAudit() {
+async function handleAudit(options) {
     let data = await fetchAuditResult();
     if (!data) {
         console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
         process.exit(1);
     }
-    // Lightweight auto-fix: backfill entity_sha on scenarios that were
-    // registered before entity records existed. This is fast (DB-only).
-    // Import analysis is NOT triggered here — it scans all files and takes
-    // minutes on large projects. Users should run it separately if needed.
+    // Two-phase auto-fix for entity associations:
+    // Phase 1: DB-only backfill — fast, matches existing entities to scenarios.
+    // Phase 2: If backfill fails, targeted analyze-imports for only the
+    // specific unresolved files (1-3 files, not the full glossary scan).
     const incompleteBeforeFix = data.incompleteEntities || [];
     const unassociatedBeforeFix = data.unassociatedScenarios || [];
     let autoRemediationFailed = false;
@@ -3595,14 +3672,58 @@ async function handleAudit() {
             console.error(chalk.red('Error: Could not reach the CodeYam server after backfill.'));
             process.exit(1);
         }
-        // If issues persist after backfill, flag it so we show clear guidance
+        // If issues persist after DB-only backfill, run targeted analyze-imports
+        // for ONLY the specific files that need entities. This is fast (1-3 files)
+        // unlike full analyze-imports which scans all glossary entries.
+        const incompleteAfterBackfill = data.incompleteEntities || [];
+        const unassociatedAfterBackfill = data.unassociatedScenarios || [];
+        if (incompleteAfterBackfill.length > 0 ||
+            unassociatedAfterBackfill.length > 0) {
+            const { determineTargetedAnalysisPaths } = await import('../utils/editorAudit.js');
+            const targetPaths = determineTargetedAnalysisPaths({
+                unassociatedScenarios: unassociatedAfterBackfill,
+                incompleteEntities: incompleteAfterBackfill,
+            });
+            if (targetPaths.length > 0) {
+                console.log(chalk.dim(`Running targeted analysis for ${targetPaths.length} file${targetPaths.length !== 1 ? 's' : ''}...`));
+                try {
+                    await handleAnalyzeImports({
+                        silent: true,
+                        filePaths: targetPaths,
+                    });
+                    // Retry backfill after analysis created entities
+                    const entities = await loadEntities({});
+                    if (entities && entities.length > 0) {
+                        const { getDatabase: getDb } = await import('../../../packages/database/index.js');
+                        const freshDb = getDb();
+                        await backfillEntityShaOnScenarios(freshDb, entities.map((e) => ({
+                            sha: e.sha,
+                            name: e.name,
+                            filePath: e.filePath || '',
+                            isDefaultExport: e.metadata?.notExported === false &&
+                                e.metadata?.namedExport === false,
+                        })));
+                    }
+                    // Re-fetch audit results after targeted analysis
+                    data = await fetchAuditResult({ skipTests: true });
+                    if (!data) {
+                        console.error(chalk.red('Error: Could not reach the CodeYam server after analysis.'));
+                        process.exit(1);
+                    }
+                }
+                catch {
+                    // Targeted analysis failed — fall through to show remaining issues
+                }
+            }
+        }
+        // Check if issues persist after all remediation attempts
         const incompleteAfterFix = data.incompleteEntities || [];
         const unassociatedAfterFix = data.unassociatedScenarios || [];
         if (incompleteAfterFix.length > 0 || unassociatedAfterFix.length > 0) {
             autoRemediationFailed = true;
         }
     }
-    const { components, functions, summary } = data;
+    let { components, functions, summary } = data;
     console.log();
     console.log(chalk.bold.cyan('━━━ Editor Audit ━━━'));
     console.log();
@@ -3701,7 +3822,15 @@ async function handleAudit() {
         for (const m of missingFromGlossary) {
             console.log(`  ${chalk.red('✗')} ${m.name} ${chalk.dim(`(${m.filePath})`)} — ${m.scenarioCount} scenario${m.scenarioCount !== 1 ? 's' : ''} but not in glossary`);
         }
-        console.log(chalk.yellow('    Add these to .codeyam/glossary.json and run `codeyam editor analyze-imports`'));
+        const mgPaths = missingFromGlossary
+            .map((m) => m.filePath)
+            .filter(Boolean);
+        if (mgPaths.length > 0) {
+            console.log(chalk.yellow(`    Add these to .codeyam/glossary.json and run \`codeyam editor analyze-imports ${mgPaths.join(' ')}\``));
+        }
+        else {
+            console.log(chalk.yellow('    Add these to .codeyam/glossary.json and run `codeyam editor analyze-imports`'));
+        }
         console.log();
     }
     // Incomplete entities (scenarios without analyses) — report with guidance.
@@ -3756,12 +3885,18 @@ async function handleAudit() {
                 console.log(chalk.dim(`      … and ${u.scenarioNames.length - 3} more`));
             }
         }
+        const uaPaths = unassociatedScenarios
+            .map((u) => u.filePath)
+            .filter(Boolean);
+        const uaCmd = uaPaths.length > 0
+            ? `codeyam editor analyze-imports ${uaPaths.join(' ')}`
+            : 'codeyam editor analyze-imports';
         if (autoRemediationFailed) {
             console.log(chalk.yellow('    analyze-imports ran automatically but could not resolve these.'));
-            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to see the full error output.'));
+            console.log(chalk.yellow(`    Run \`${uaCmd}\` to see the full error output.`));
         }
         else {
-            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to create entity records, then re-run audit to backfill.'));
+            console.log(chalk.yellow(`    Run \`${uaCmd}\` to create entity records, then re-run audit to backfill.`));
         }
         const unassocErrorReportPath = path.join(getProjectRoot(), '.codeyam', 'analysis-errors.txt');
         if (fs.existsSync(unassocErrorReportPath)) {
@@ -3794,7 +3929,26 @@ async function handleAudit() {
                 : `${s.status.status}`;
             console.log(`  ${chalk.red('✗')} ${s.scenarioName} ${chalk.dim(`(${s.entityName} — ${reason})`)}`);
         }
-        console.log(chalk.yellow('    Run: codeyam editor recapture-stale'));
+        if (options?.fix) {
+            // --fix: auto-recapture stale scenarios instead of just reporting them
+            const { shouldAutoRecapture } = await import('../utils/editorAudit.js');
+            if (shouldAutoRecapture({ fix: true, scenariosNeedingRecapture })) {
+                console.log(chalk.cyan('    --fix: auto-recapturing stale scenarios...'));
+                console.log();
+                await handleRecaptureStale();
+                // Re-fetch audit results so the summary and exit code reflect
+                // the post-fix state, not the pre-fix state.
+                const refreshed = await fetchAuditResult({ skipTests: true });
+                if (refreshed) {
+                    data = refreshed;
+                    ({ components, functions, summary } = data);
+                }
+            }
+        }
+        else {
+            console.log(chalk.yellow('    Run: codeyam editor recapture-stale'));
+            console.log(chalk.dim('    Or: codeyam editor audit --fix (to auto-recapture)'));
+        }
         console.log();
     }
     // Duplicate glossary names (warning, not a failure)
@@ -4764,8 +4918,8 @@ const editorCommand = {
     describe: 'Editor mode guided workflow',
     builder: (yargs) => {
         const stepDescription = IS_INTERNAL_BUILD
-            ? 'Step number (1-18) or subcommand (template, register, isolate, analyze-imports, manual-entity, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, debug, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors, task-ontrack)'
-            : 'Step number (1-18) or subcommand (template, register, isolate, analyze-imports, manual-entity, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors, task-ontrack)';
+            ? 'Step number (1-18) or subcommand (template, register, isolate, analyze-imports, manual-entity, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, debug, design-system, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors, task-ontrack)'
+            : 'Step number (1-18) or subcommand (template, register, isolate, analyze-imports, manual-entity, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, design-system, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors, task-ontrack)';
         let builder = yargs
             .positional('step', {
             type: 'string',
@@ -4796,6 +4950,11 @@ const editorCommand = {
             alias: 'p',
             describe: 'Port to run the web server on',
             default: 3111,
+        })
+            .option('fix', {
+            type: 'boolean',
+            describe: 'For audit: also recapture stale scenarios after displaying results',
+            default: false,
         });
         if (IS_INTERNAL_BUILD) {
             builder = builder
@@ -4923,9 +5082,11 @@ const editorCommand = {
             fs.writeFileSync(trackingPath, JSON.stringify({ step: state.step, taskCreated: true }, null, 2), 'utf8');
             return;
         }
-        // Subcommand: codeyam editor analyze-imports
+        // Subcommand: codeyam editor analyze-imports [file1.tsx file2.tsx ...]
         if (argv.step === 'analyze-imports') {
-            await handleAnalyzeImports();
+            const { parseAnalyzeImportsArgs } = await import('./editorAnalyzeImportsArgs.js');
+            const requestedPaths = parseAnalyzeImportsArgs(argv.json, argv._);
+            await handleAnalyzeImports(requestedPaths.length > 0 ? { filePaths: requestedPaths } : {});
             return;
         }
         // Subcommand: codeyam editor manual-entity <JSON|@file>
@@ -4938,9 +5099,9 @@ const editorCommand = {
             await handleDependents(argv.json || '');
             return;
         }
-        // Subcommand: codeyam editor audit
+        // Subcommand: codeyam editor audit [--fix]
         if (argv.step === 'audit') {
-            await handleAudit();
+            await handleAudit({ fix: argv.fix || false });
             return;
         }
         // Subcommand: codeyam editor scenarios
@@ -4973,6 +5134,11 @@ const editorCommand = {
             await handleValidateSeed(argv.json || '');
             return;
         }
+        // Subcommand: codeyam editor design-system <id>
+        if (argv.step === 'design-system') {
+            handleDesignSystem(argv.json || '');
+            return;
+        }
         // Subcommand: codeyam editor delete <scenarioId>
         if (argv.step === 'delete') {
             await handleDelete(argv.json || '');