@codeyam/codeyam-cli 0.1.0-staging.30dc541 → 0.1.0-staging.346f50f

package/codeyam-cli/src/utils/designSystemShowcase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"designSystemShowcase.js","sourceRoot":"","sources":["../../../../src/utils/designSystemShowcase.ts"],"names":[],"mappings":"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"}

package/codeyam-cli/src/utils/devServerState.js

@@ -68,4 +68,36 @@ export function computeDevServerTransition(current, response) {
     // Unknown status — no changes
     return { ...current, shouldAutoStart: false };
 }
+// ─── Server Error Auto-Restart Logic ────────────────────────────────
+/** Max consecutive auto-restarts before requiring manual intervention. */
+export const MAX_AUTO_RESTARTS = 2;
+/** Minimum interval (ms) between auto-restart attempts. */
+export const AUTO_RESTART_COOLDOWN_MS = 30000;
+/**
+ * Decide whether to auto-restart the dev server after an error page
+ * is shown in the preview iframe. Pure function for testability.
+ *
+ * Prevents restart loops by enforcing:
+ * - A 30-second cooldown between auto-restarts
+ * - A maximum of 2 consecutive auto-restarts (reset when server comes up)
+ * - No restart if the server is already starting
+ */
+export function shouldAutoRestartOnError(state, isStarting, now) {
+    if (isStarting) {
+        return { shouldRestart: false, nextState: state };
+    }
+    if (now - state.lastAutoRestartAt < AUTO_RESTART_COOLDOWN_MS) {
+        return { shouldRestart: false, nextState: state };
+    }
+    if (state.autoRestartCount >= MAX_AUTO_RESTARTS) {
+        return { shouldRestart: false, nextState: state };
+    }
+    return {
+        shouldRestart: true,
+        nextState: {
+            lastAutoRestartAt: now,
+            autoRestartCount: state.autoRestartCount + 1,
+        },
+    };
+}
 //# sourceMappingURL=devServerState.js.map

package/codeyam-cli/src/utils/devServerState.js.map

@@ -1 +1 @@
-{"version":3,"file":"devServerState.js","sourceRoot":"","sources":["../../../../src/utils/devServerState.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuBH;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAAuB,EACvB,QAA8B;IAE9B,IAAI,QAAQ,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;QAChC,OAAO;YACL,GAAG,EAAE,IAAI;YACT,QAAQ,EAAE,IAAI;YACd,UAAU,EAAE,KAAK;YACjB,KAAK,EAAE,QAAQ,CAAC,YAAY,IAAI,oBAAoB;YACpD,cAAc,EAAE,OAAO,CAAC,cAAc;YACtC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;YAC9C,eAAe,EAAE,KAAK;SACvB,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,GAAG,EAAE,CAAC;QACjB,OAAO;YACL,GAAG,EAAE,QAAQ,CAAC,GAAG;YACjB,QAAQ,EAAE,QAAQ,CAAC,QAAQ,IAAI,IAAI;YACnC,UAAU,EAAE,KAAK;YACjB,KAAK,EAAE,IAAI;YACX,cAAc,EAAE,IAAI;YACpB,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;YAC9C,eAAe,EAAE,KAAK;SACvB,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACnC,OAAO;YACL,GAAG,OAAO;YACV,UAAU,EAAE,IAAI;YAChB,KAAK,EAAE,IAAI;YACX,cAAc,EAAE,IAAI;YACpB,eAAe,EAAE,KAAK;SACvB,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAClC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;YAChB,kDAAkD;YAClD,OAAO;gBACL,GAAG,OAAO;gBACV,GAAG,EAAE,IAAI;gBACT,UAAU,EAAE,KAAK;gBACjB,eAAe,EAAE,KAAK;aACvB,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC;YAChC,wDAAwD;YACxD,OAAO;gBACL,GAAG,OAAO;gBACV,kBAAkB,EAAE,IAAI;gBACxB,eAAe,EAAE,IAAI;aACtB,CAAC;QACJ,CAAC;QAED,4CAA4C;QAC5C,OAAO;YACL,GAAG,OAAO;YACV,UAAU,EAAE,KAAK;YACjB,eAAe,EAAE,KAAK;SACvB,CAAC;IACJ,CAAC;IAED,8BAA8B;IAC9B,OAAO,EAAE,GAAG,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC;AAChD,CAAC"}
+{"version":3,"file":"devServerState.js","sourceRoot":"","sources":["../../../../src/utils/devServerState.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuBH;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAAuB,EACvB,QAA8B;IAE9B,IAAI,QAAQ,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;QAChC,OAAO;YACL,GAAG,EAAE,IAAI;YACT,QAAQ,EAAE,IAAI;YACd,UAAU,EAAE,KAAK;YACjB,KAAK,EAAE,QAAQ,CAAC,YAAY,IAAI,oBAAoB;YACpD,cAAc,EAAE,OAAO,CAAC,cAAc;YACtC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;YAC9C,eAAe,EAAE,KAAK;SACvB,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,GAAG,EAAE,CAAC;QACjB,OAAO;YACL,GAAG,EAAE,QAAQ,CAAC,GAAG;YACjB,QAAQ,EAAE,QAAQ,CAAC,QAAQ,IAAI,IAAI;YACnC,UAAU,EAAE,KAAK;YACjB,KAAK,EAAE,IAAI;YACX,cAAc,EAAE,IAAI;YACpB,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;YAC9C,eAAe,EAAE,KAAK;SACvB,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACnC,OAAO;YACL,GAAG,OAAO;YACV,UAAU,EAAE,IAAI;YAChB,KAAK,EAAE,IAAI;YACX,cAAc,EAAE,IAAI;YACpB,eAAe,EAAE,KAAK;SACvB,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAClC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;YAChB,kDAAkD;YAClD,OAAO;gBACL,GAAG,OAAO;gBACV,GAAG,EAAE,IAAI;gBACT,UAAU,EAAE,KAAK;gBACjB,eAAe,EAAE,KAAK;aACvB,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC;YAChC,wDAAwD;YACxD,OAAO;gBACL,GAAG,OAAO;gBACV,kBAAkB,EAAE,IAAI;gBACxB,eAAe,EAAE,IAAI;aACtB,CAAC;QACJ,CAAC;QAED,4CAA4C;QAC5C,OAAO;YACL,GAAG,OAAO;YACV,UAAU,EAAE,KAAK;YACjB,eAAe,EAAE,KAAK;SACvB,CAAC;IACJ,CAAC;IAED,8BAA8B;IAC9B,OAAO,EAAE,GAAG,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC;AAChD,CAAC;AAED,uEAAuE;AAEvE,0EAA0E;AAC1E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AACnC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAM,CAAC;AAY/C;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAA8B,EAC9B,UAAmB,EACnB,GAAW;IAEX,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACpD,CAAC;IACD,IAAI,GAAG,GAAG,KAAK,CAAC,iBAAiB,GAAG,wBAAwB,EAAE,CAAC;QAC7D,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACpD,CAAC;IACD,IAAI,KAAK,CAAC,gBAAgB,IAAI,iBAAiB,EAAE,CAAC;QAChD,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACpD,CAAC;IAED,OAAO;QACL,aAAa,EAAE,IAAI;QACnB,SAAS,EAAE;YACT,iBAAiB,EAAE,GAAG;YACtB,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,GAAG,CAAC;SAC7C;KACF,CAAC;AACJ,CAAC"}

package/codeyam-cli/src/utils/editorApi.js

@@ -53,6 +53,22 @@ const SUBCOMMAND_MAP = {
         method: 'GET',
         endpoint: '/api/editor-client-errors',
     }),
+    'verify-routes': (jsonArg) => {
+        if (!jsonArg) {
+            throw new Error('JSON argument is required for verify-routes. Example: \'{"paths":["/library"],"apiRoutes":["/api/users"]}\'');
+        }
+        const body = JSON.parse(jsonArg);
+        const hasPaths = Array.isArray(body.paths) && body.paths.length > 0;
+        const hasApiRoutes = Array.isArray(body.apiRoutes) && body.apiRoutes.length > 0;
+        if (!hasPaths && !hasApiRoutes) {
+            throw new Error('verify-routes requires at least one entry in "paths" or "apiRoutes"');
+        }
+        return {
+            method: 'POST',
+            endpoint: '/api/editor-verify-routes',
+            body,
+        };
+    },
 };
 export function buildEditorApiRequest(subcommand, jsonArg) {
     const builder = SUBCOMMAND_MAP[subcommand];

package/codeyam-cli/src/utils/editorApi.js.map

@@ -1 +1 @@
-{"version":3,"file":"editorApi.js","sourceRoot":"","sources":["../../../../src/utils/editorApi.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"editorApi.js","sourceRoot":"","sources":["../../../../src/utils/editorApi.ts"],"names":[],"mappings":"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"}

package/codeyam-cli/src/utils/editorAudit.js

@@ -4,17 +4,34 @@
  * Cross-references glossary entries against registered scenarios (components)
  * and test files (functions) to detect gaps Claude may have missed.
  */
-import { isIsolationUrl, } from "./entityChangeStatus.js";
+import { isIsolationUrl, scenarioEntityName, } from "./entityChangeStatus.js";
 // ─── Logic ───────────────────────────────────────────────────────────
 const COMPONENT_RETURN_PATTERNS = ['JSX', 'React', 'Element', 'ReactNode'];
+/** File names that indicate page/route files — these are visual components
+ * verified via screenshots, not functions that need unit tests. */
+const PAGE_FILE_NAMES = new Set([
+    'page.tsx',
+    'page.ts',
+    'index.tsx',
+    'index.ts',
+]);
 /**
- * Returns true when the entry's returnType indicates a React component
- * (contains "JSX", "React", "Element", or "ReactNode").
+ * Returns true when the entry represents a visual component (needs scenarios,
+ * not unit tests). Matches on returnType containing JSX/React patterns, OR
+ * on file path patterns for page/route files.
  */
 export function isComponent(entry) {
-    if (!entry.returnType)
-        return false;
-    return COMPONENT_RETURN_PATTERNS.some((pat) => entry.returnType.includes(pat));
+    if (entry.returnType &&
+        COMPONENT_RETURN_PATTERNS.some((pat) => entry.returnType.includes(pat))) {
+        return true;
+    }
+    // Page/route files are visual components — verified via app scenarios, not tests
+    if (entry.filePath) {
+        const fileName = entry.filePath.split('/').pop() || '';
+        if (PAGE_FILE_NAMES.has(fileName))
+            return true;
+    }
+    return false;
 }
 /**
  * Split glossary entries into components (JSX-returning) and functions (everything else).
@@ -40,7 +57,7 @@ export function classifyGlossaryEntries(entries) {
  * @param scenarioCounts - Map of component_name → number of registered scenarios
  * @param testFileExistence - Map of testFile path → whether the file exists on disk
  */
-export function computeAudit({ components, functions, scenarioCounts, testFileExistence, testResults, clientErrors, totalScenarioCounts, entityChangeStatus, }) {
+export function computeAudit({ components, functions, scenarioCounts, testFileExistence, testResults, clientErrors, totalScenarioCounts, entityChangeStatus, analysisFailedEntities, testCaseCounts, }) {
     const componentResults = components.map((c) => {
         const count = scenarioCounts[c.name] || 0;
         const totalCount = totalScenarioCounts?.[c.name] || 0;
@@ -48,7 +65,10 @@ export function computeAudit({ components, functions, scenarioCounts, testFileEx
         const errors = clientErrors?.[c.name];
         const hasErrors = count > 0 && errors && errors.length > 0;
         let status;
-        if (count === 0) {
+        if (analysisFailedEntities?.has(c.name)) {
+            status = 'analysis_failed';
+        }
+        else if (count === 0) {
             // Entities with existing scenarios from prior sessions don't need
             // new scenarios — they need recapture. This applies to both "edited"
             // and "impacted" entities: an edited page may not have been re-registered
@@ -66,12 +86,33 @@ export function computeAudit({ components, functions, scenarioCounts, testFileEx
         else {
             status = 'ok';
         }
+        // Generate actionable hint for missing or needs_recapture components
+        let hint;
+        if (status === 'missing') {
+            const fileName = c.filePath.split('/').pop() || '';
+            if (fileName === 'layout.tsx' || fileName === 'layout.ts') {
+                hint = `This is a layout file — register an app-level scenario with pageFilePath instead of componentName: codeyam editor register '{"name":"${c.name} - Default","pageFilePath":"${c.filePath}","url":"/<route>","dimensions":["Desktop"]}'`;
+            }
+            else if (fileName === 'page.tsx' || fileName === 'page.ts') {
+                hint = `This is a page file — register an app-level scenario with pageFilePath: codeyam editor register '{"name":"${c.name} - Default","pageFilePath":"${c.filePath}","url":"/<route>","dimensions":["Desktop"]}'`;
+            }
+            else {
+                hint = `Register a component scenario via an isolation route: codeyam editor isolate ${c.name} then codeyam editor register '{"name":"${c.name} - Default","componentName":"${c.name}","url":"/isolated-components/${c.name}?s=Default","dimensions":["Desktop"]}'`;
+            }
+        }
+        else if (status === 'needs_recapture') {
+            hint = `This component's code or dependencies changed — recapture existing scenarios to update screenshots: codeyam editor recapture ${c.name}`;
+        }
+        else if (status === 'analysis_failed') {
+            hint = `Analysis failed for this component (likely timed out due to complex dependencies). The component has partial data but may be missing some dependency schemas. Try re-analyzing: codeyam editor analyze-imports`;
+        }
         return {
             name: c.name,
             filePath: c.filePath,
             scenarioCount: status === 'needs_recapture' ? totalCount : count,
             status,
             ...(hasErrors ? { clientErrors: errors } : {}),
+            ...(hint ? { hint } : {}),
         };
     });
     const functionResults = functions.map((f) => {
@@ -79,12 +120,17 @@ export function computeAudit({ components, functions, scenarioCounts, testFileEx
             ? (testFileExistence[f.testFile] ?? false)
             : false;
         if (!exists) {
+            // Suggest conventional test file path when testFile isn't in the glossary
+            const suggestedTestFile = !f.testFile
+                ? f.filePath.replace(/\.tsx?$/, '.test.ts')
+                : undefined;
             return {
                 name: f.name,
                 filePath: f.filePath,
                 testFile: f.testFile,
                 testFileExists: false,
                 status: 'missing',
+                ...(suggestedTestFile ? { suggestedTestFile } : {}),
             };
         }
         // If we have test results for this file, use them for deeper status
@@ -112,6 +158,14 @@ export function computeAudit({ components, functions, scenarioCounts, testFileEx
         else {
             status = 'ok';
         }
+        // Generate actionable hint for non-ok functions
+        let hint;
+        if (status === 'name_mismatch') {
+            hint = `Tests pass but won't show in the CodeYam UI. Add a top-level describe("${f.name}", ...) block in ${f.testFile}`;
+        }
+        else if (status === 'runner_error' && tr.errorMessage) {
+            hint = `Test runner crashed (not a test failure): ${tr.errorMessage}`;
+        }
         return {
             name: f.name,
             filePath: f.filePath,
@@ -121,17 +175,23 @@ export function computeAudit({ components, functions, scenarioCounts, testFileEx
             testsVisibleInUi: tr.hasEntityNameDescribe,
             status,
             ...(tr.errorMessage ? { errorMessage: tr.errorMessage } : {}),
+            ...(hint ? { hint } : {}),
+            ...(testCaseCounts?.[f.name] !== undefined
+                ? { testCaseCount: testCaseCounts[f.name] }
+                : {}),
         };
     });
-    const componentsOk = componentResults.filter((c) => c.status === 'ok' || c.status === 'needs_recapture').length;
+    const componentsOk = componentResults.filter((c) => c.status === 'ok').length;
     const componentsWithErrors = componentResults.filter((c) => c.status === 'has_errors').length;
     const componentsMissing = componentResults.filter((c) => c.status === 'missing').length;
     const componentsNeedingRecapture = componentResults.filter((c) => c.status === 'needs_recapture').length;
+    const componentsAnalysisFailed = componentResults.filter((c) => c.status === 'analysis_failed').length;
     const functionsOk = functionResults.filter((f) => f.status === 'ok').length;
     const functionsFailing = functionResults.filter((f) => f.status === 'failing').length;
     const functionsRunnerError = functionResults.filter((f) => f.status === 'runner_error').length;
     const functionsNameMismatch = functionResults.filter((f) => f.status === 'name_mismatch').length;
     const functionsMissing = functionResults.filter((f) => f.status === 'missing').length;
+    const functionsThinCoverage = functionResults.filter((f) => f.status === 'ok' && f.testCaseCount !== undefined && f.testCaseCount < 3).length;
     return {
         components: componentResults,
         functions: functionResults,
@@ -141,14 +201,17 @@ export function computeAudit({ components, functions, scenarioCounts, testFileEx
             componentsMissing,
             componentsWithErrors,
             componentsNeedingRecapture,
+            componentsAnalysisFailed,
             totalFunctions: functionResults.length,
             functionsOk,
             functionsMissing,
             functionsFailing,
             functionsRunnerError,
             functionsNameMismatch,
+            functionsThinCoverage,
             allPassing: componentsMissing === 0 &&
                 componentsWithErrors === 0 &&
+                componentsAnalysisFailed === 0 &&
                 functionsFailing === 0 &&
                 functionsRunnerError === 0 &&
                 functionsNameMismatch === 0 &&
@@ -157,32 +220,167 @@ export function computeAudit({ components, functions, scenarioCounts, testFileEx
     };
 }
 /**
- * Returns true when the audit failure can be auto-fixed by running
- * analyze-imports: incomplete entities are the only issue AND we haven't
- * already tried (to prevent infinite retry loops when analysis has errors).
+ * Returns true when the audit failure can be auto-fixed inline.
+ *
+ * Always returns false — full analyze-imports takes minutes on large projects
+ * and must never run as part of the audit. The audit only does lightweight
+ * entity SHA backfill. Users should run `codeyam editor analyze-imports`
+ * separately if incomplete entities persist.
  */
-export function isAutoRemediable(summary, alreadyAttempted) {
-    if (alreadyAttempted)
-        return false;
-    if (!summary.incompleteEntities || summary.incompleteEntities === 0)
-        return false;
-    return isOnlyIncompleteEntities(summary);
+export function isAutoRemediable(_summary, _alreadyAttempted) {
+    return false;
+}
+/**
+ * Determine whether the audit should auto-recapture stale scenarios.
+ * Returns true when the `--fix` flag is set AND there are stale scenarios.
+ */
+export function shouldAutoRecapture(params) {
+    return params.fix && params.scenariosNeedingRecapture.length > 0;
+}
+/**
+ * Extract unique file paths that need targeted analysis from audit results.
+ *
+ * After a DB-only backfill attempt fails, these are the files that need
+ * `analyze-imports` to create entity records. Unlike full analyze-imports
+ * (which scans ALL glossary + page files), this returns only the specific
+ * files that have unresolved associations — typically 1-3 files.
+ */
+export function determineTargetedAnalysisPaths(auditData) {
+    const paths = new Set();
+    for (const u of auditData.unassociatedScenarios) {
+        if (u.filePath)
+            paths.add(u.filePath);
+    }
+    for (const e of auditData.incompleteEntities) {
+        if (e.filePath)
+            paths.add(e.filePath);
+    }
+    return [...paths];
 }
 /**
- * Returns true when incompleteEntities is the ONLY audit failure —
- * all other failure counts are zero. Used to decide whether auto-running
- * analyze-imports can fix the audit without manual intervention.
+ * Generate clear, actionable guidance for an incomplete entity.
+ *
+ * Tells Claude exactly what's wrong, whether it's pre-existing, and
+ * the exact command to fix it — no guessing required.
+ */
+export function formatIncompleteEntityGuidance(entity) {
+    const parts = [];
+    if (entity.preExisting) {
+        parts.push(`${entity.name}: ${entity.scenarioCount} scenario(s) without import graph (pre-existing issue, not from this session).`);
+        parts.push(`This is non-blocking — the entity had scenarios before this session but analyze-imports was never run for it.`);
+    }
+    else {
+        parts.push(`${entity.name}: ${entity.scenarioCount} scenario(s) without import graph — analyze-imports has not been run for this entity.`);
+        parts.push(`The entity has scenarios registered but its import graph is not built, so the editor cannot track its dependencies.`);
+    }
+    parts.push(`Fix: Run \`codeyam editor analyze-imports\` to build the import graph for all entities.`);
+    return parts.join(' ');
+}
+/**
+ * Generate step-by-step manual analysis instructions for an entity
+ * whose automated analysis has persistently failed.
+ *
+ * Used by the audit when analysis-failures.json contains the entity.
+ * Tells Claude exactly how to read the source, gather imports/types,
+ * and run `codeyam editor manual-entity` to unblock the audit.
+ */
+export function formatManualAnalysisGuidance(entity) {
+    const lines = [];
+    lines.push(`${entity.name}: ${entity.scenarioCount} scenario(s) — automated analysis failed`);
+    lines.push(`Error: ${entity.error}`);
+    lines.push('');
+    lines.push('MANUAL ANALYSIS REQUIRED — follow these steps:');
+    lines.push(`1. Read ${entity.filePath}`);
+    lines.push('2. Identify which glossary entities it imports (check .codeyam/glossary.json)');
+    lines.push('3. Determine entity type: "visual" if it returns JSX, "library" otherwise');
+    lines.push('4. Identify the type structure:');
+    lines.push('   - For components: props interface and hook return types');
+    lines.push('   - For functions: parameter types and return type');
+    lines.push(`5. Write the JSON to .codeyam/tmp/manual-entity.json then run: codeyam editor manual-entity @.codeyam/tmp/manual-entity.json`);
+    return lines.join('\n');
+}
+/**
+ * Resolve incomplete entity SHAs to their source file paths.
+ *
+ * Used by the audit to run targeted analysis on just the files that need it,
+ * instead of scanning all 117+ project files. Returns deduplicated file paths.
+ */
+export async function getIncompleteEntityFilePaths(db, incompleteEntities) {
+    if (incompleteEntities.length === 0)
+        return [];
+    const shas = incompleteEntities.map((e) => e.entitySha);
+    const rows = await db
+        .selectFrom('entities')
+        .select('file_path')
+        .where('sha', 'in', shas)
+        .execute();
+    const paths = new Set();
+    for (const row of rows) {
+        if (row.file_path)
+            paths.add(row.file_path);
+    }
+    return [...paths];
+}
+/**
+ * Returns true when the only audit failures are auto-fixable entity issues
+ * (incompleteEntities and/or unassociatedScenarios) — all other failure
+ * counts are zero. Used to decide whether auto-running analyze-imports +
+ * entity SHA sync can fix the audit without manual intervention.
  */
 export function isOnlyIncompleteEntities(summary) {
     return ((summary.componentsMissing ?? 0) === 0 &&
         (summary.componentsWithErrors ?? 0) === 0 &&
         (summary.functionsFailing ?? 0) === 0 &&
+        (summary.functionsRunnerError ?? 0) === 0 &&
         (summary.functionsNameMismatch ?? 0) === 0 &&
         (summary.functionsMissing ?? 0) === 0 &&
         (summary.missingFromGlossary ?? 0) === 0 &&
         (summary.miscategorizedScenarios ?? 0) === 0 &&
         (summary.scenariosNeedingRecapture ?? 0) === 0);
 }
+/**
+ * Returns true when the only audit failures are incomplete entities that ALL
+ * existed before the current session. Used by the step gate to avoid blocking
+ * progress on pre-existing issues the user didn't cause.
+ *
+ * Requires both the summary (to confirm no other failure types) and the
+ * incompleteEntities array (to verify every entry is pre-existing).
+ */
+export function isOnlyPreExistingIncomplete(summary, incompleteEntities) {
+    // Must have at least one incomplete entity to be relevant
+    if (!incompleteEntities || incompleteEntities.length === 0)
+        return false;
+    // All other failure types must be zero
+    if (!isOnlyIncompleteEntities(summary))
+        return false;
+    // Every incomplete entity must be pre-existing
+    return incompleteEntities.every((e) => e.preExisting);
+}
+/**
+ * Filter a list of file paths to only those that need analysis.
+ *
+ * A file is excluded if ANY entity at that file path has an analysis
+ * record (direct or inherited from a sibling version with the same
+ * name+filePath). Everything else passes through.
+ *
+ * Used by handleAnalyzeImports to avoid re-analyzing ~120 files when
+ * only a few need it.
+ */
+export async function filterToIncompleteFilePaths(db, _projectId, allFilePaths) {
+    if (allFilePaths.length === 0)
+        return [];
+    // Single query: find all file paths that have at least one entity
+    // with an analysis record. These are already analyzed and can be skipped.
+    const analyzedRows = await db
+        .selectFrom('entities')
+        .innerJoin('analyses', 'analyses.entity_sha', 'entities.sha')
+        .select('entities.file_path')
+        .where('entities.file_path', 'in', allFilePaths)
+        .groupBy('entities.file_path')
+        .execute();
+    const analyzedFilePaths = new Set(analyzedRows.map((r) => r.file_path));
+    return allFilePaths.filter((fp) => !analyzedFilePaths.has(fp));
+}
 /**
  * Ensures the two audit filters — glossary scoping and scenario-count scoping —
  * are consistent. When entityChangeStatus is empty/undefined (meaning the glossary
@@ -298,7 +496,7 @@ export async function queryIncompleteEntities(db, projectId, featureStartedAt) {
         const name = entityNameMap.get(sha);
         const filePath = entityFilePathMap.get(sha);
         if (!name)
-            return true; // No entity record — keep as incomplete
+            return false; // No entity record (phantom SHA) — skip, not fixable by analysis
         const key = `${name}::${filePath}`;
         return !keysWithInheritedAnalyses.has(key);
     });
@@ -466,6 +664,72 @@ export async function queryPageScenarioCounts(db, projectId, featureStartedAt) {
     }
     return counts;
 }
+// ─── Unassociated Scenarios ───────────────────────────────────────────
+/**
+ * Find scenarios with NULL entity_sha that have a file path
+ * (component_path or page_file_path). These scenarios were registered
+ * before entity records existed in the DB — typically because a subagent
+ * registered scenarios without running analyze-imports first.
+ *
+ * Fix: run `codeyam editor analyze-imports` to create entity records,
+ * then entity_sha backfill will associate them automatically.
+ *
+ * Optionally scoped to the current feature session via featureStartedAt.
+ */
+export async function queryUnassociatedScenarios(db, projectId, featureStartedAt) {
+    let query = db
+        .selectFrom('editor_scenarios')
+        .select(['component_name', 'component_path', 'page_file_path', 'name'])
+        .where('project_id', '=', projectId)
+        .where('entity_sha', 'is', null)
+        .where((eb) => eb.or([
+        eb('component_path', 'is not', null),
+        eb('page_file_path', 'is not', null),
+    ]));
+    if (featureStartedAt) {
+        const sqliteTimestamp = featureStartedAt
+            .replace('T', ' ')
+            .replace(/\.\d{3}Z$/, '');
+        query = query.where((eb) => eb.or([
+            eb('created_at', '>=', sqliteTimestamp),
+            eb('updated_at', '>=', sqliteTimestamp),
+        ]));
+    }
+    const rows = await query.execute();
+    if (rows.length === 0)
+        return [];
+    // Group by file path (component_path or page_file_path)
+    const groups = new Map();
+    for (const row of rows) {
+        const r = row;
+        const filePath = r.component_path || r.page_file_path;
+        const existing = groups.get(filePath);
+        if (existing) {
+            existing.scenarioNames.push(r.name);
+        }
+        else {
+            // Derive a display name: use component_name if available,
+            // otherwise extract from file path (e.g., "src/lib/LibraryApp.tsx" → "LibraryApp")
+            const displayName = r.component_name ||
+                filePath
+                    .split('/')
+                    .pop()
+                    ?.replace(/\.\w+$/, '') ||
+                filePath;
+            groups.set(filePath, {
+                name: displayName,
+                filePath,
+                scenarioNames: [r.name],
+            });
+        }
+    }
+    return [...groups.values()].map((g) => ({
+        name: g.name,
+        filePath: g.filePath,
+        scenarioCount: g.scenarioNames.length,
+        scenarioNames: g.scenarioNames,
+    }));
+}
 // ─── Duplicate Name Detection ─────────────────────────────────────────
 /**
  * Detect glossary entries that share the same `name`.
@@ -515,6 +779,10 @@ export function identifyScenariosNeedingRecapture(params) {
         const changeStatus = entityChangeStatus[scenario.entityName];
         if (!changeStatus)
             continue;
+        // "new" entities need initial scenario creation, not recapture.
+        // Only "edited" and "impacted" entities have stale screenshots.
+        if (changeStatus.status === 'new')
+            continue;
         result.push({
             scenarioName: scenario.name,
             entityName: scenario.entityName,
@@ -523,4 +791,59 @@ export function identifyScenariosNeedingRecapture(params) {
     }
     return result;
 }
+// ─── Client Error Aggregation ─────────────────────────────────────────
+/**
+ * Aggregate client errors by component name using scenario metadata.
+ *
+ * Given a map of scenario ID → { scenarioName, errors } and a list of
+ * scenario metadata (with componentName from the DB), group errors by
+ * the component they belong to.
+ *
+ * For component scenarios: use the `componentName` field directly.
+ * For app-level scenarios (no componentName): derive the entity name
+ * using `scenarioEntityName()` — the same canonical function used by
+ * recapture detection and entity change status. This ensures the keys
+ * match what `computeAudit` checks against glossary entry names.
+ *
+ * This replaces the fragile "parse component name from scenario name"
+ * approach which fails for app-level scenarios like "Full Page with Library".
+ */
+export function aggregateClientErrorsByComponent(clientErrors, scenarioMetadata) {
+    const result = {};
+    // Build a lookup from scenario name → component/entity name.
+    // Uses scenarioEntityName() for consistency with the rest of the system
+    // (recapture detection, entity change status, journal filtering).
+    const scenarioToComponent = new Map();
+    for (const meta of scenarioMetadata) {
+        const entityName = scenarioEntityName({
+            componentName: meta.componentName,
+            pageFilePath: meta.pageFilePath,
+            url: meta.url,
+        });
+        if (entityName) {
+            scenarioToComponent.set(meta.name, entityName);
+        }
+    }
+    for (const [, data] of Object.entries(clientErrors)) {
+        if (data.errors.length === 0)
+            continue;
+        // First try: look up via scenario metadata (authoritative)
+        let componentName = scenarioToComponent.get(data.scenarioName);
+        // Fallback: parse from scenario name convention "ComponentName - Variant"
+        if (!componentName) {
+            const dashIndex = data.scenarioName.indexOf(' - ');
+            componentName =
+                dashIndex >= 0
+                    ? data.scenarioName.slice(0, dashIndex)
+                    : data.scenarioName;
+        }
+        if (componentName) {
+            if (!result[componentName]) {
+                result[componentName] = [];
+            }
+            result[componentName].push(...data.errors);
+        }
+    }
+    return result;
+}
 //# sourceMappingURL=editorAudit.js.map