@codeyam/codeyam-cli 0.1.15 → 0.1.16

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

@@ -1,10 +1,10 @@
 {
-  "buildTimestamp": "2026-03-18T20:56:41.501Z",
-  "buildTime": 1773867401501,
-  "gitCommit": "3328e60080cd05630588c6f1b139c2caffcb164a",
+  "buildTimestamp": "2026-03-19T01:18:46.592Z",
+  "buildTime": 1773883126592,
+  "gitCommit": "27da20c7d41586bf9567c2e2ac63312ba9fb9057",
   "nodeVersion": "v20.20.1",
   "contentHash": "b046e014847d5b02d10d6795839ccd0d5117627cbd0be413260824610596a63d",
-  "buildNumber": 1100,
-  "semanticVersion": "0.1.1100",
-  "version": "0.1.1100 (2026-03-18T20:56+b046e01)"
+  "buildNumber": 1104,
+  "semanticVersion": "0.1.1104",
+  "version": "0.1.1104 (2026-03-19T01:18+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, 1:18:46 AM] > codeyam-combo@1.0.0 mergeDependencies
+[3/19/2026, 1:18:46 AM] > node ./scripts/mergePackageJsonFiles.cjs
 
 
-[3/18/2026, 8:56:41 PM] Merged dependencies into root package.json
+[3/19/2026, 1:18:46 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) {
@@ -2988,18 +2997,48 @@ 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)
@@ -3083,6 +3122,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 +3140,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 +3259,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) {