@codeyam/codeyam-cli 0.1.14 → 0.1.16

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

@@ -1,10 +1,10 @@
 {
-  "buildTimestamp": "2026-03-18T14:58:22.078Z",
-  "buildTime": 1773845902078,
-  "gitCommit": "4dda2c78ef15ac678fb9a0e8f4d270c514f30f81",
+  "buildTimestamp": "2026-03-19T01:18:46.592Z",
+  "buildTime": 1773883126592,
+  "gitCommit": "27da20c7d41586bf9567c2e2ac63312ba9fb9057",
   "nodeVersion": "v20.20.1",
   "contentHash": "b046e014847d5b02d10d6795839ccd0d5117627cbd0be413260824610596a63d",
-  "buildNumber": 1092,
-  "semanticVersion": "0.1.1092",
-  "version": "0.1.1092 (2026-03-18T14:58+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, 2:58:21 PM] > codeyam-combo@1.0.0 mergeDependencies
-[3/18/2026, 2:58:21 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, 2:58:22 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

@@ -205,6 +205,8 @@ function checkbox(text) {
  * Prints seed-based scenarios, mock-based fallback, @ file prefix, externalApis, url requirement, and error checking.
  */
 function printAppScenarioInstructions(pageName, route) {
+    const root = process.cwd();
+    const hasSeedAdapter = !!detectSeedAdapter(root);
     checkbox('Check existing scenarios: `codeyam editor scenarios`');
     console.log(chalk.dim('    Review existing scenarios — reuse and update their data rather than'));
     console.log(chalk.dim('    creating duplicates. Re-register with the same name to update a scenario.'));
@@ -230,10 +232,18 @@ function printAppScenarioInstructions(pageName, route) {
     console.log(chalk.yellow('    Required fields: "type":"application", "url" (real route), "pageFilePath" (source file)'));
     console.log(chalk.yellow('    Do NOT include "componentName" — that would make it a component scenario'));
     console.log();
-    checkbox('Choose the right data approach for scenarios:');
-    console.log(chalk.dim('    With seed adapter: add "seed":{...} to populate the database for each state'));
-    console.log(chalk.dim('    Without seed adapter: add "mockData":{"routes":{"/api/...":{"body":[...]}}} to mock API responses'));
-    console.log(chalk.dim('    For external APIs (Stripe, weather, etc.): add "externalApis":{"GET https://...":{"body":[...],"status":200}}'));
+    if (hasSeedAdapter) {
+        checkbox(chalk.bold.red('REQUIRED: Every app scenario MUST include "seed" data — without it the page will be empty!'));
+        console.log(chalk.yellow('    A seed adapter exists — you MUST include "seed":{...} in every app scenario registration.'));
+        console.log(chalk.yellow('    An app scenario without seed data will render an empty page (no database rows = nothing to show).'));
+        console.log(chalk.dim('    "seed" maps table names to arrays of rows: "seed":{"user":[{"id":1,"name":"Alice"}],"article":[...]}'));
+        console.log(chalk.dim('    For external APIs: also add "externalApis":{"GET https://...":{"body":[...],"status":200}}'));
+    }
+    else {
+        checkbox('Include data in every app scenario — without it the page will be empty:');
+        console.log(chalk.dim('    Use "mockData":{"routes":{"/api/...":{"body":[...]}}} to mock API responses'));
+        console.log(chalk.dim('    For external APIs: add "externalApis":{"GET https://...":{"body":[...],"status":200}}'));
+    }
     checkbox('For large seed/mock data, write JSON to a temp file and use @ prefix:');
     console.log(chalk.dim('    Write JSON to .codeyam/tmp/scenario.json then register with:'));
     console.log(chalk.dim('    codeyam editor register @.codeyam/tmp/scenario.json'));
@@ -320,7 +330,7 @@ function printComponentCaptureInstructions() {
     console.log(chalk.dim('       The route defines a `scenarios` object mapping scenario names to props,'));
     console.log(chalk.dim('       reads `?s=ScenarioName` from the URL, and renders the component with those props.'));
     console.log(chalk.dim('       Wrap the component in a capture container with id="codeyam-capture":'));
-    console.log(chalk.dim('       <div id="codeyam-capture" style={{ display:"inline-block", padding:"20px" }}>'));
+    console.log(chalk.dim('       <div id="codeyam-capture" style={{ display:"inline-block" }}>'));
     console.log(chalk.dim('         <div style={{ width:"100%", maxWidth:"..." }}> ← match the app\'s container width'));
     console.log(chalk.dim('       e.g. card in a 3-col grid → maxWidth:"24rem", full-width component → omit maxWidth'));
     console.log(chalk.dim('       The screenshot captures just this wrapper, so the component fills the image.'));
@@ -800,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 ─────────────────────────────────────────────────────
@@ -2651,6 +2662,13 @@ async function handleRegister(jsonArg) {
             if (data.captureError)
                 parts.push(chalk.yellow(`captureError="${data.captureError}"`));
             console.log(prefix + parts.join(' '));
+            // Warn when application scenario is missing seed data
+            if (data.missingSeedWarning) {
+                console.log(chalk.red.bold('WARNING: No seed data in this application scenario!'));
+                console.log(chalk.yellow('  This scenario has type "application" but no "seed" data was provided.'));
+                console.log(chalk.yellow('  The page will render with an empty database — nothing will be visible.'));
+                console.log(chalk.yellow('  Re-register with "seed":{...} containing the database rows this page needs.'));
+            }
             // Surface client errors prominently so they can't be missed
             if (data.clientErrors && data.clientErrors.length > 0) {
                 console.log(chalk.red.bold(`⚠ WARNING: ${data.clientErrors.length} client error${data.clientErrors.length !== 1 ? 's' : ''} detected during capture:`));
@@ -2658,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) {
@@ -2971,24 +2997,56 @@ 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.miscategorizedScenarios > 0)
         issues.push(`${s.miscategorizedScenarios} component(s) using page URLs instead of isolation routes`);
+    if (s.scenariosNeedingRecapture > 0)
+        issues.push(`${s.scenariosNeedingRecapture} scenario(s) need recapture (dependency tree changed)`);
     if (issues.length > 0) {
         console.error(chalk.yellow('\nAudit failures:'));
         for (const issue of issues) {
@@ -3064,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('✗');
@@ -3077,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}`));
@@ -3179,6 +3246,32 @@ async function handleAudit() {
         console.log(chalk.yellow('    or re-register with an isolation URL.'));
         console.log();
     }
+    // Scenarios needing recapture (entity or dependency tree changed)
+    const scenariosNeedingRecapture = data.scenariosNeedingRecapture || [];
+    if (scenariosNeedingRecapture.length > 0) {
+        console.log(chalk.bold('Scenarios needing recapture (dependency tree changed):'));
+        for (const s of scenariosNeedingRecapture) {
+            const reason = s.status.status === 'impacted' && s.status.impactedBy?.length
+                ? `impacted by: ${s.status.impactedBy.map((d) => `${d.name} [${d.changeType}]`).join(', ')}`
+                : `${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();
+    }
+    // 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) {
@@ -3214,6 +3307,9 @@ async function handleAudit() {
         if (summary.miscategorizedScenarios > 0) {
             parts.push(`${summary.miscategorizedScenarios} component${summary.miscategorizedScenarios !== 1 ? 's' : ''} using page URLs instead of isolation routes`);
         }
+        if (summary.scenariosNeedingRecapture > 0) {
+            parts.push(`${summary.scenariosNeedingRecapture} scenario${summary.scenariosNeedingRecapture !== 1 ? 's' : ''} need recapture`);
+        }
         console.log(chalk.red.bold('Audit failed: ') + parts.join(', '));
     }
     console.log();