@codeyam/codeyam-cli 0.1.16 → 0.1.18

package/analyzer-template/.build-info.json

@@ -1,10 +1,10 @@
 {
-  "buildTimestamp": "2026-03-19T01:18:46.592Z",
-  "buildTime": 1773883126592,
-  "gitCommit": "27da20c7d41586bf9567c2e2ac63312ba9fb9057",
+  "buildTimestamp": "2026-03-19T21:52:47.836Z",
+  "buildTime": 1773957167836,
+  "gitCommit": "40b059fe8e0f00686186b501bf7ad39e8cdbc22c",
   "nodeVersion": "v20.20.1",
   "contentHash": "b046e014847d5b02d10d6795839ccd0d5117627cbd0be413260824610596a63d",
-  "buildNumber": 1104,
-  "semanticVersion": "0.1.1104",
-  "version": "0.1.1104 (2026-03-19T01:18+b046e01)"
+  "buildNumber": 1110,
+  "semanticVersion": "0.1.1110",
+  "version": "0.1.1110 (2026-03-19T21:52+b046e01)"
 }

package/analyzer-template/log.txt

@@ -1,7 +1,7 @@
 
-[3/19/2026, 1:18:46 AM] > codeyam-combo@1.0.0 mergeDependencies
-[3/19/2026, 1:18:46 AM] > node ./scripts/mergePackageJsonFiles.cjs
+[3/19/2026, 9:52:47 PM] > codeyam-combo@1.0.0 mergeDependencies
+[3/19/2026, 9:52:47 PM] > node ./scripts/mergePackageJsonFiles.cjs
 
 
-[3/19/2026, 1:18:46 AM] Merged dependencies into root package.json
+[3/19/2026, 9:52:47 PM] Merged dependencies into root package.json
 

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

@@ -1449,6 +1449,7 @@ function printStep12(root, feature) {
     checkbox('If `hasErrors` is true, fix them and re-capture affected scenarios');
     checkbox('Run `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1"]}\'` with all page paths and image URLs');
     checkbox('Fix or remove any broken images before continuing');
+    checkbox('Recapture stale scenarios: `codeyam editor recapture-stale`');
     checkbox('Run `codeyam editor audit` to verify completeness of scenarios and tests');
     checkbox('Do not proceed until all checks pass');
     stopGate(12);
@@ -2122,6 +2123,7 @@ function printStep14(root, feature) {
     console.log('Commit all changes for this feature.');
     console.log();
     console.log(chalk.bold('Checklist:'));
+    checkbox('Ensure all screenshots are fresh: `codeyam editor recapture-stale`');
     checkbox(`Hide the results panel: \`codeyam editor hide-results\``);
     checkbox(`Git commit using the journal description: \`codeyam editor commit '{"message":"feat: <title>\\n\\n<journal description>"}'\``);
     console.log(chalk.dim('    The commit message body MUST match the journal description exactly'));
@@ -2709,6 +2711,53 @@ async function handleRegister(jsonArg) {
         process.exit(1);
     }
 }
+// ─── Glossary-add subcommand ──────────────────────────────────────────
+/**
+ * `codeyam editor glossary-add '{"name":"...", "filePath":"...", "description":"..."}'`
+ *
+ * Safely adds/updates entries in .codeyam/glossary.json via the CLI,
+ * avoiding hand-editing that breaks on unicode characters.
+ */
+async function handleGlossaryAdd(jsonArg) {
+    if (!jsonArg) {
+        console.error(chalk.red('Error: JSON argument required.'));
+        console.error(chalk.dim('  Usage: codeyam editor glossary-add \'{"name":"DrinkCard","filePath":"app/components/DrinkCard.tsx","description":"Displays a drink item"}\''));
+        console.error(chalk.dim('  For large payloads: codeyam editor glossary-add @.codeyam/tmp/entry.json'));
+        process.exit(1);
+    }
+    const parsed = parseRegisterArg(jsonArg);
+    if (parsed.error) {
+        console.error(chalk.red(`Error: ${parsed.error}`));
+        process.exit(1);
+    }
+    // Normalize to array
+    const items = Array.isArray(parsed.body) ? parsed.body : [parsed.body];
+    // Read existing glossary
+    const root = getProjectRoot();
+    const glossaryPath = path.join(root, '.codeyam', 'glossary.json');
+    let existing = [];
+    try {
+        const raw = JSON.parse(fs.readFileSync(glossaryPath, 'utf8'));
+        existing = sanitizeGlossaryEntries(raw);
+    }
+    catch {
+        // Glossary doesn't exist yet or can't be parsed — start fresh
+    }
+    // Merge
+    const { validateGlossaryEntry, mergeGlossaryEntries } = await import('../utils/glossaryAdd.js');
+    const result = mergeGlossaryEntries(existing, items);
+    // Report validation errors
+    for (const err of result.errors) {
+        console.error(chalk.red(`Error at index ${err.index}: ${err.message}`));
+    }
+    if (result.added === 0 && result.updated === 0 && result.errors.length > 0) {
+        process.exit(1);
+    }
+    // Write back with utf8 encoding to safely handle unicode
+    fs.mkdirSync(path.dirname(glossaryPath), { recursive: true });
+    fs.writeFileSync(glossaryPath, JSON.stringify(result.entries, null, 2), 'utf8');
+    console.log(`added=${result.added} updated=${result.updated} total=${result.entries.length}`);
+}
 // ─── Dependents subcommand ────────────────────────────────────────────
 /**
  * `codeyam editor dependents <EntityName>`
@@ -2904,6 +2953,7 @@ function handleChange(feature) {
     checkbox(`Navigate to key pages to verify changes: \`codeyam editor preview '{"path":"/your-route","dimension":"${dim}"}'\``);
     printDimensionGuidance(dim, dimNames);
     checkbox('Run `codeyam editor scenario-coverage` — all affected scenarios must be fresh');
+    checkbox('Recapture stale scenarios: `codeyam editor recapture-stale`');
     checkbox('Run `codeyam editor audit` — all checks must pass');
     checkbox(`Check for client-side errors: \`codeyam editor client-errors\``);
     console.log(chalk.dim('    If `hasContent=false`, the preview is blank — fix the code before proceeding.'));
@@ -3041,8 +3091,18 @@ function printAuditGateFailures(data) {
     }
     if (s.missingFromGlossary > 0)
         issues.push(`${s.missingFromGlossary} file(s) with scenarios not in glossary`);
-    if (s.incompleteEntities > 0)
-        issues.push(`${s.incompleteEntities} entity/entities need import analysis`);
+    if (s.incompleteEntities > 0) {
+        const preCount = s.preExistingIncompleteEntities || 0;
+        if (preCount > 0 && preCount === s.incompleteEntities) {
+            issues.push(`${s.incompleteEntities} entity/entities need import analysis (pre-existing — not caused by your current changes, but must be fixed before proceeding)`);
+        }
+        else if (preCount > 0) {
+            issues.push(`${s.incompleteEntities} entity/entities need import analysis (${preCount} pre-existing — not from your changes)`);
+        }
+        else {
+            issues.push(`${s.incompleteEntities} entity/entities need import analysis`);
+        }
+    }
     if (s.miscategorizedScenarios > 0)
         issues.push(`${s.miscategorizedScenarios} component(s) using page URLs instead of isolation routes`);
     if (s.scenariosNeedingRecapture > 0)
@@ -3129,11 +3189,18 @@ async function handleAudit() {
         }
         console.log(chalk.bold('Components (scenarios):'));
         for (const c of components) {
-            const icon = c.status === 'ok' ? chalk.green('✓') : chalk.red('✗');
+            const icon = c.status === 'ok'
+                ? chalk.green('✓')
+                : c.status === 'needs_recapture'
+                    ? chalk.yellow('↻')
+                    : chalk.red('✗');
             let detail;
             if (c.status === 'has_errors') {
                 detail = chalk.red(` — ${c.scenarioCount} scenario${c.scenarioCount !== 1 ? 's' : ''} but has client errors`);
             }
+            else if (c.status === 'needs_recapture') {
+                detail = chalk.yellow(` — ${c.scenarioCount} scenario${c.scenarioCount !== 1 ? 's' : ''}, needs recapture`);
+            }
             else if (c.status === 'ok') {
                 detail = chalk.dim(` (${c.scenarioCount} scenario${c.scenarioCount !== 1 ? 's' : ''})`);
             }
@@ -3142,7 +3209,7 @@ async function handleAudit() {
             }
             // Show file path for failing components always, for OK only when name is ambiguous
             const isDuplicate = (componentNameCounts.get(c.name) || 0) > 1;
-            const showPath = c.status !== 'ok' || isDuplicate;
+            const showPath = (c.status !== 'ok' && c.status !== 'needs_recapture') || isDuplicate;
             const pathSuffix = showPath && c.filePath ? chalk.dim(` (${c.filePath})`) : '';
             console.log(`  ${icon} ${c.name}${pathSuffix}${detail}`);
             if (c.clientErrors && c.clientErrors.length > 0) {
@@ -3256,7 +3323,7 @@ async function handleAudit() {
                 : `${s.status.status}`;
             console.log(`  ${chalk.red('✗')} ${s.scenarioName} ${chalk.dim(`(${s.entityName} — ${reason})`)}`);
         }
-        console.log(chalk.yellow('    Re-register these scenarios to capture updated screenshots.'));
+        console.log(chalk.yellow('    Run: codeyam editor recapture-stale'));
         console.log();
     }
     // Duplicate glossary names (warning, not a failure)
@@ -3328,6 +3395,109 @@ async function handleAudit() {
         console.log(chalk.yellow('Warning: Could not build import graph. Run `codeyam editor analyze-imports` manually.'));
     }
 }
+// ─── Recapture-stale subcommand ────────────────────────────────────────
+/**
+ * `codeyam editor recapture-stale`
+ *
+ * Identifies all scenarios whose entity (or dependency) has changed but
+ * whose screenshot hasn't been recaptured this session, then recaptures
+ * them in batch.
+ */
+async function handleRecaptureStale() {
+    const port = getServerPort();
+    const url = `http://localhost:${port}/api/editor-recapture-stale`;
+    console.log();
+    console.log(chalk.bold.cyan('━━━ Recapture Stale Scenarios ━━━'));
+    console.log();
+    let res;
+    try {
+        res = await fetch(url, { method: 'POST' });
+    }
+    catch (err) {
+        console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
+        console.error(chalk.dim(`  ${err.message}`));
+        process.exit(1);
+    }
+    if (!res.ok) {
+        const body = await res.json().catch(() => null);
+        console.error(chalk.red(`Error: Recapture endpoint returned ${res.status}`));
+        if (body?.error)
+            console.error(chalk.red(`  ${body.error}`));
+        process.exit(1);
+    }
+    // Handle JSON response (early returns like "no changes" / "all up to date")
+    const contentType = res.headers.get('content-type') || '';
+    if (contentType.includes('application/json')) {
+        const data = await res.json();
+        if (data.note) {
+            console.log(chalk.dim(data.note));
+        }
+        else if (data.total === 0) {
+            console.log(chalk.green('All scenarios are up to date.'));
+        }
+        console.log();
+        return;
+    }
+    // Stream NDJSON progress events
+    let total = 0;
+    let recapturedCount = 0;
+    let failedCount = 0;
+    const reader = res.body?.getReader();
+    if (!reader) {
+        console.error(chalk.red('Error: No response body'));
+        process.exit(1);
+    }
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || ''; // Keep incomplete last line in buffer
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                const event = JSON.parse(line);
+                switch (event.type) {
+                    case 'start':
+                        total = event.total;
+                        console.log(`Found ${total} stale scenario(s). Recapturing...\n`);
+                        break;
+                    case 'capturing':
+                        process.stdout.write(chalk.dim(`  … ${event.name}`));
+                        break;
+                    case 'success':
+                        // Clear the "capturing" line and print success
+                        process.stdout.write('\r\x1b[K');
+                        console.log(`  ${chalk.green('✓')} ${event.name}`);
+                        recapturedCount++;
+                        break;
+                    case 'failure':
+                        process.stdout.write('\r\x1b[K');
+                        console.log(`  ${chalk.red('✗')} ${event.name} — ${chalk.dim(event.error)}`);
+                        failedCount++;
+                        break;
+                    case 'done':
+                        // Final summary
+                        console.log();
+                        const color = failedCount > 0 ? chalk.yellow : chalk.green;
+                        console.log(color(`Recaptured ${recapturedCount}/${total} scenario(s).`));
+                        console.log();
+                        break;
+                }
+            }
+            catch {
+                // Skip unparseable lines
+            }
+        }
+    }
+    if (failedCount > 0) {
+        process.exit(1);
+    }
+}
 // ─── Scenarios subcommand ─────────────────────────────────────────────
 async function handleScenarios() {
     const port = getServerPort();
@@ -3938,8 +4108,8 @@ const editorCommand = {
     describe: 'Editor mode guided workflow',
     builder: (yargs) => {
         const stepDescription = IS_INTERNAL_BUILD
-            ? 'Step number (1-16) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, scenario-coverage, change, sync, debug, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors)'
-            : 'Step number (1-16) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, scenario-coverage, change, sync, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors)';
+            ? 'Step number (1-16) or subcommand (template, register, isolate, analyze-imports, 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)'
+            : 'Step number (1-16) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors)';
         let builder = yargs
             .positional('step', {
             type: 'string',
@@ -4032,6 +4202,11 @@ const editorCommand = {
             await handleRegister(argv.json || '');
             return;
         }
+        // Subcommand: codeyam editor glossary-add '{"name":"...", ...}'
+        if (argv.step === 'glossary-add') {
+            await handleGlossaryAdd(argv.json || '');
+            return;
+        }
         // Subcommand: codeyam editor analyze-imports
         if (argv.step === 'analyze-imports') {
             await handleAnalyzeImports();
@@ -4057,6 +4232,11 @@ const editorCommand = {
             await handleScenarioCoverage();
             return;
         }
+        // Subcommand: codeyam editor recapture-stale
+        if (argv.step === 'recapture-stale') {
+            await handleRecaptureStale();
+            return;
+        }
         // Subcommand: codeyam editor change <feature>
         if (argv.step === 'change') {
             handleChange(argv.json || '');