@codeyam/codeyam-cli 0.1.15 → 0.1.17

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

@@ -1,10 +1,10 @@
 {
-  "buildTimestamp": "2026-03-18T20:56:41.501Z",
-  "buildTime": 1773867401501,
-  "gitCommit": "3328e60080cd05630588c6f1b139c2caffcb164a",
+  "buildTimestamp": "2026-03-19T11:57:18.299Z",
+  "buildTime": 1773921438299,
+  "gitCommit": "471e1bd5c0e64ab79e5aae1965797f9cc293303d",
   "nodeVersion": "v20.20.1",
   "contentHash": "b046e014847d5b02d10d6795839ccd0d5117627cbd0be413260824610596a63d",
-  "buildNumber": 1100,
-  "semanticVersion": "0.1.1100",
-  "version": "0.1.1100 (2026-03-18T20:56+b046e01)"
+  "buildNumber": 1105,
+  "semanticVersion": "0.1.1105",
+  "version": "0.1.1105 (2026-03-19T11:57+b046e01)"
 }

package/analyzer-template/log.txt

@@ -1,7 +1,7 @@
 
-[3/18/2026, 8:56:41 PM] > codeyam-combo@1.0.0 mergeDependencies
-[3/18/2026, 8:56:41 PM] > node ./scripts/mergePackageJsonFiles.cjs
+[3/19/2026, 11:57:18 AM] > codeyam-combo@1.0.0 mergeDependencies
+[3/19/2026, 11:57:18 AM] > node ./scripts/mergePackageJsonFiles.cjs
 
 
-[3/18/2026, 8:56:41 PM] Merged dependencies into root package.json
+[3/19/2026, 11:57:18 AM] Merged dependencies into root package.json
 

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

@@ -810,6 +810,7 @@ function printCycleOverview(root, state) {
         console.log(chalk.green('Start now: ') + chalk.bold('codeyam editor 1'));
         console.log(chalk.dim('  If the user already described what they want, pass it: codeyam editor 1 --prompt "their message"'));
     }
+    console.log(chalk.dim('If stuck on CLI commands, scenarios, or debugging, read: .codeyam/docs/editor-reference.md'));
     console.log();
 }
 // ─── Step 1: Plan ─────────────────────────────────────────────────────
@@ -2675,6 +2676,14 @@ async function handleRegister(jsonArg) {
                     console.log(chalk.red(`  → ${err}`));
                 }
                 console.log(chalk.yellow('  The screenshot may show an error screen instead of the actual component.'));
+                // Provide actionable debugging hints for HTTP/API errors
+                const hasApiResponseError = data.clientErrors.some((e) => e.includes('API response error:'));
+                const hasHttpError = data.clientErrors.some((e) => e.includes('HTTP error:'));
+                if (hasHttpError || hasApiResponseError) {
+                    console.log(chalk.yellow('  To debug: look at the "API response error" lines above — they show the exact API endpoint'));
+                    console.log(chalk.yellow('  that failed and what the server returned. Then check the scenario seed data to ensure'));
+                    console.log(chalk.yellow('  all IDs referenced in the URL exist in the seed, and that the route is correct.'));
+                }
                 console.log(chalk.yellow('  Fix the issue and re-register this scenario.'));
             }
             if (!res.ok) {
@@ -2700,6 +2709,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>`
@@ -2988,22 +3044,62 @@ function printAuditGateFailures(data) {
     if (!s)
         return;
     const issues = [];
-    if (s.componentsMissing > 0)
+    if (s.componentsMissing > 0) {
         issues.push(`${s.componentsMissing} component(s) missing scenarios`);
-    if (s.componentsWithErrors > 0)
+        const missing = (data.components || []).filter((c) => c.status === 'missing');
+        for (const c of missing) {
+            issues.push(`    → ${c.name}${c.filePath ? ` (${c.filePath})` : ''}`);
+        }
+    }
+    if (s.componentsWithErrors > 0) {
         issues.push(`${s.componentsWithErrors} component(s) with client errors (browser API or runtime errors in captured scenarios)`);
-    if (s.functionsMissing > 0)
+        const withErrors = (data.components || []).filter((c) => c.status === 'has_errors');
+        for (const c of withErrors) {
+            issues.push(`    → ${c.name}${c.filePath ? ` (${c.filePath})` : ''}`);
+        }
+    }
+    if (s.functionsMissing > 0) {
         issues.push(`${s.functionsMissing} function(s) missing test files`);
-    if (s.functionsFailing > 0)
+        const missing = (data.functions || []).filter((f) => f.status === 'missing');
+        for (const f of missing) {
+            issues.push(`    → ${f.name}${f.filePath ? ` (${f.filePath})` : ''}`);
+        }
+    }
+    if (s.functionsFailing > 0) {
         issues.push(`${s.functionsFailing} function(s) with failing tests`);
-    if (s.functionsRunnerError > 0)
+        const failing = (data.functions || []).filter((f) => f.status === 'failing');
+        for (const f of failing) {
+            issues.push(`    → ${f.name}${f.testFile ? ` (${f.testFile})` : ''}`);
+        }
+    }
+    if (s.functionsRunnerError > 0) {
         issues.push(`${s.functionsRunnerError} function(s) with test runner errors (the runner crashed — not a test failure)`);
-    if (s.functionsNameMismatch > 0)
+        const runnerErrors = (data.functions || []).filter((f) => f.status === 'runner_error');
+        for (const f of runnerErrors) {
+            issues.push(`    → ${f.name}${f.testFile ? ` (${f.testFile})` : ''}`);
+        }
+    }
+    if (s.functionsNameMismatch > 0) {
         issues.push(`${s.functionsNameMismatch} function(s) with test name mismatch`);
+        const mismatch = (data.functions || []).filter((f) => f.status === 'name_mismatch');
+        for (const f of mismatch) {
+            issues.push(`    → ${f.name}${f.testFile ? ` (${f.testFile})` : ''}`);
+        }
+    }
     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)
@@ -3083,6 +3179,11 @@ async function handleAudit() {
     console.log();
     // Components
     if (components.length > 0) {
+        // Build name frequency map for disambiguation
+        const componentNameCounts = new Map();
+        for (const c of components) {
+            componentNameCounts.set(c.name, (componentNameCounts.get(c.name) || 0) + 1);
+        }
         console.log(chalk.bold('Components (scenarios):'));
         for (const c of components) {
             const icon = c.status === 'ok' ? chalk.green('✓') : chalk.red('✗');
@@ -3096,7 +3197,11 @@ async function handleAudit() {
             else {
                 detail = chalk.red(' — no scenarios registered');
             }
-            console.log(`  ${icon} ${c.name}${detail}`);
+            // 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 pathSuffix = showPath && c.filePath ? chalk.dim(` (${c.filePath})`) : '';
+            console.log(`  ${icon} ${c.name}${pathSuffix}${detail}`);
             if (c.clientErrors && c.clientErrors.length > 0) {
                 for (const err of c.clientErrors.slice(0, 3)) {
                     console.log(chalk.red(`      → ${err}`));
@@ -3211,6 +3316,19 @@ async function handleAudit() {
         console.log(chalk.yellow('    Re-register these scenarios to capture updated screenshots.'));
         console.log();
     }
+    // Duplicate glossary names (warning, not a failure)
+    const duplicateNames = data.duplicateNames || [];
+    if (duplicateNames.length > 0) {
+        console.log(chalk.bold('Duplicate names in glossary (confusing for audit):'));
+        for (const dn of duplicateNames) {
+            console.log(`  ${chalk.yellow('⚠')} "${dn.name}" appears ${dn.filePaths.length} times:`);
+            for (const fp of dn.filePaths) {
+                console.log(`      ${fp}`);
+            }
+        }
+        console.log(chalk.yellow('    Fix: remove duplicate entries or rename them to be unique in .codeyam/glossary.json'));
+        console.log();
+    }
     // Summary
     const allOk = summary.allPassing;
     if (allOk) {
@@ -3971,6 +4089,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();