@codeyam/codeyam-cli 0.1.20 → 0.1.21

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

@@ -21,6 +21,7 @@ import { validateSeedData, detectSeedAdapter, validateSeedKeysAgainstPrisma, } f
 import { deleteScenarioViaCli } from "../utils/editorDeleteScenario.js";
 import { buildEditorApiRequest, callEditorApi, EDITOR_API_SUBCOMMANDS, } from "../utils/editorApi.js";
 import { parseRegisterArg } from "../utils/parseRegisterArg.js";
+import { classifyRegistrationResult } from "../utils/registerScenarioResult.js";
 import { sanitizeGlossaryEntries } from "../utils/editorLoaderHelpers.js";
 import { readMigrationState, writeMigrationState, advanceToNextPage, completePage, getMigrationResumeInfo, } from "../utils/editorMigration.js";
 const __filename = fileURLToPath(import.meta.url);
@@ -210,6 +211,34 @@ function checkbox(text) {
     const highlighted = text.replace(/`([^`]+)`/g, (_m, code) => chalk.cyan(code));
     console.log(`  ${chalk.dim('[ ]')} ${highlighted}`);
 }
+/**
+ * Instructions for creating/updating .codeyam/data-structure.json.
+ * Only prints creation instructions if the file doesn't exist yet.
+ * If it exists, reminds Claude to update it if data models changed.
+ */
+function printDataStructureInstructions() {
+    const root = getProjectRoot();
+    const dsPath = path.join(root, '.codeyam', 'data-structure.json');
+    const exists = fs.existsSync(dsPath);
+    if (!exists) {
+        console.log(chalk.bold('Create the data structure config:'));
+        checkbox('Create `.codeyam/data-structure.json` describing all data sources');
+        console.log(chalk.dim("  This file tells the editor what data the app uses and how it's stored."));
+        console.log(chalk.dim('  The file is a JSON array. Each entry describes one data source:'));
+        console.log(chalk.dim('  { "name": "Drink", "description": "...", "category": "datastore", "order": 1,'));
+        console.log(chalk.dim('    "fields": [{ "name": "id", "type": "number", "isId": true, "required": true }, ...] }'));
+        console.log();
+        console.log(chalk.dim('  category: "datastore" for persisted data (DB, localStorage)'));
+        console.log(chalk.dim('           "mock-api" for mocked external API responses'));
+        console.log(chalk.dim('  order: 1 = primary data store, 2 = secondary, etc.'));
+        console.log(chalk.dim('  Do NOT include types only used as component props.'));
+    }
+    else {
+        checkbox('If this feature changes data models, update `.codeyam/data-structure.json`');
+        console.log(chalk.dim('  Add new tables, update fields, or change descriptions to match.'));
+    }
+    console.log();
+}
 /**
  * Shared app scenario registration instructions used by editor Step 8 and migration Steps 1/6.
  * Prints seed-based scenarios, mock-based fallback, @ file prefix, externalApis, url requirement, and error checking.
@@ -978,6 +1007,7 @@ function printStep2(root, feature) {
         console.log(chalk.dim('  Key: import { prisma } from "@/app/lib/prisma" in API routes.'));
         console.log(chalk.dim('  Key: Seed scripts must use the adapter pattern (see prisma/seed.ts).'));
         console.log();
+        printDataStructureInstructions();
     }
     else {
         console.log(chalk.bold('Prepare the database for this feature:'));
@@ -992,6 +1022,7 @@ function printStep2(root, feature) {
         console.log(chalk.dim('    This switches the active scenario, runs the seed adapter, and refreshes the preview.'));
         console.log(chalk.dim('    If no existing scenario fits, use the default seed: npm run db:seed'));
         console.log();
+        printDataStructureInstructions();
     }
     stopGate(2);
 }
@@ -1326,7 +1357,10 @@ function printStep9(root, feature) {
     console.log();
     checkbox('Run `codeyam editor audit` to verify all components have scenarios and all functions/hooks have tests');
     console.log(chalk.red.bold('    The audit is a HARD GATE — step 10 will refuse to run until the audit passes.'));
-    console.log(chalk.dim('    When audit passes, the import graph is built automatically for change tracking.'));
+    console.log(chalk.dim('    The audit auto-fixes incomplete entities by running targeted analysis on just the affected files.'));
+    console.log(chalk.dim('    If the audit reports issues (including pre-existing ones), fix ALL of them — do not skip.'));
+    console.log(chalk.dim('    Re-run `codeyam editor audit` until all checks pass. Do NOT run `codeyam editor analyze-imports`'));
+    console.log(chalk.dim('    — the audit runs targeted analysis automatically and is much faster.'));
     console.log();
     stopGate(9);
 }
@@ -2362,25 +2396,54 @@ async function handleAnalyzeImports(options = {}) {
         // Non-fatal — scenario file paths just won't be included
     }
     const progress = new ProgressReporter();
-    // Run data-structure-only analysis for all entities (glossary + pages)
-    // Don't pass entityNames — entities may not exist yet (fresh clone).
-    // The analyzer will discover and create them from file paths.
-    progress.start('Running import analysis for all entities...');
+    // Filter to only files that actually need analysis — avoids re-analyzing
+    // ~120 files when only 2 are incomplete.
+    let targetFilePaths = filePaths;
     try {
-        await runAnalysisForEntities({
-            projectRoot: root,
-            filePaths,
-            progress,
-            onlyDataStructure: true,
-        });
+        const { getDatabase } = await import('../../../packages/database/index.js');
+        const db = getDatabase();
+        const { requireBranchAndProject: rbp } = await import('../utils/database.js');
+        const { project } = await rbp(JSON.parse(fs.readFileSync(path.join(root, '.codeyam', 'config.json'), 'utf8')).projectSlug);
+        const { filterToIncompleteFilePaths } = await import('../utils/editorAudit.js');
+        const incomplete = await filterToIncompleteFilePaths(db, project.id, filePaths);
+        if (incomplete.length < filePaths.length && incomplete.length > 0) {
+            if (!options.silent) {
+                console.log(chalk.dim(`Skipping ${filePaths.length - incomplete.length} already-analyzed files, analyzing ${incomplete.length} remaining...`));
+            }
+            targetFilePaths = incomplete;
+        }
+        else if (incomplete.length === 0) {
+            if (!options.silent) {
+                console.log(chalk.green('All entities already have analyses — nothing to do.'));
+            }
+            // Still need to run the import graph + backfill below
+            targetFilePaths = [];
+        }
     }
-    catch (err) {
-        progress.fail('Analysis failed');
-        const msg = err instanceof Error ? err.message : String(err);
-        console.error(chalk.red(`Error: ${msg}`));
-        process.exit(1);
+    catch {
+        // Non-fatal — fall back to analyzing all files
+    }
+    // Run data-structure-only analysis for entities that need it.
+    // Don't pass entityNames — entities may not exist yet (fresh clone).
+    // The analyzer will discover and create them from file paths.
+    if (targetFilePaths.length > 0) {
+        progress.start(`Running import analysis for ${targetFilePaths.length} entit${targetFilePaths.length !== 1 ? 'ies' : 'y'}...`);
+        try {
+            await runAnalysisForEntities({
+                projectRoot: root,
+                filePaths: targetFilePaths,
+                progress,
+                onlyDataStructure: true,
+            });
+        }
+        catch (err) {
+            progress.fail('Analysis failed');
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(chalk.red(`Error: ${msg}`));
+            process.exit(1);
+        }
+        progress.succeed('Analysis complete');
     }
-    progress.succeed('Analysis complete');
     // Load entities WITH metadata from database
     progress.start('Loading entity metadata...');
     await initializeEnvironment();
@@ -2736,6 +2799,8 @@ async function handleRegister(jsonArg) {
     const isBatch = items.length > 1;
     let succeeded = 0;
     let failed = 0;
+    let warnings = 0;
+    const issues = [];
     const screenshotEntries = [];
     for (let i = 0; i < items.length; i++) {
         const body = items[i];
@@ -2805,11 +2870,14 @@ async function handleRegister(jsonArg) {
                 }
                 console.log(chalk.yellow('  Fix the issue and re-register this scenario.'));
             }
+            const resultIssues = classifyRegistrationResult(res.ok, res.status, data, String(body.name || `item ${i + 1}`));
             if (!res.ok) {
                 console.error(chalk.dim(JSON.stringify(data, null, 2)));
                 failed++;
             }
             else {
+                if (resultIssues.length > 0)
+                    warnings++;
                 succeeded++;
                 // Collect screenshot paths for duplicate detection
                 if (data.screenshotCaptured &&
@@ -2822,6 +2890,10 @@ async function handleRegister(jsonArg) {
                     });
                 }
             }
+            // Collect issues from this registration
+            for (const issue of resultIssues) {
+                issues.push(`"${issue.scenarioName}": ${issue.message}`);
+            }
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
@@ -2859,9 +2931,22 @@ async function handleRegister(jsonArg) {
         }
     }
     if (isBatch) {
-        console.log(chalk.dim(`\nBatch complete: ${succeeded}/${items.length} succeeded`));
+        console.log('');
+        if (failed > 0 || warnings > 0) {
+            console.log(chalk.red.bold(`ERROR: ${failed} failed, ${warnings} with warnings out of ${items.length} scenarios`));
+            console.log('');
+            console.log(chalk.red.bold('Issues that MUST be fixed:'));
+            for (const issue of issues) {
+                console.log(chalk.red(`  ✗ ${issue}`));
+            }
+            console.log('');
+            console.log(chalk.red('Do NOT skip these errors. Fix each issue and re-register the affected scenarios.'));
+        }
+        else {
+            console.log(chalk.green(`✓ Batch complete: ${succeeded}/${items.length} succeeded with no issues`));
+        }
     }
-    if (failed > 0) {
+    if (failed > 0 || warnings > 0) {
         process.exit(1);
     }
 }
@@ -3176,17 +3261,15 @@ async function checkAuditGate() {
         return true; // Server unreachable — don't block
     if (data.summary?.allPassing === true)
         return true;
-    // If incomplete entities / unassociated scenarios are the only issue,
-    // auto-fix with analyze-imports + entity SHA backfill (once)
-    const { isAutoRemediable } = await import('../utils/editorAudit.js');
-    if (isAutoRemediable(data.summary, false)) {
-        try {
-            await handleAnalyzeImports({ silent: true });
-        }
-        catch {
-            // Fall through to backfill attempt
-        }
-        // Backfill entity_sha on scenarios registered before entities existed
+    // Lightweight auto-fix: backfill entity_sha (DB-only, fast).
+    // Never run handleAnalyzeImports here — it takes minutes on large projects.
+    const { isOnlyIncompleteEntities, isOnlyPreExistingIncomplete } = await import('../utils/editorAudit.js');
+    // If the only failures are pre-existing incomplete entities (not caused by
+    // this session), don't block — the audit text already calls these "non-blocking".
+    if (isOnlyPreExistingIncomplete(data.summary, data.incompleteEntities)) {
+        return true;
+    }
+    if (isOnlyIncompleteEntities(data.summary)) {
         try {
             const entities = await loadEntities({});
             if (entities && entities.length > 0) {
@@ -3204,7 +3287,7 @@ async function checkAuditGate() {
         catch {
             // Fall through
         }
-        // Re-check after fix
+        // Re-check after backfill
         const retry = await fetchAuditResult();
         if (retry?.summary?.allPassing === true)
             return true;
@@ -3228,6 +3311,8 @@ function printAuditGateFailures(data) {
         const missing = (data.components || []).filter((c) => c.status === 'missing');
         for (const c of missing) {
             issues.push(`    → ${c.name}${c.filePath ? ` (${c.filePath})` : ''}`);
+            if (c.hint)
+                issues.push(`      Fix: ${c.hint}`);
         }
     }
     if (s.componentsWithErrors > 0) {
@@ -3241,7 +3326,15 @@ function printAuditGateFailures(data) {
         issues.push(`${s.functionsMissing} function(s) missing test files`);
         const missing = (data.functions || []).filter((f) => f.status === 'missing');
         for (const f of missing) {
-            issues.push(`    → ${f.name}${f.filePath ? ` (${f.filePath})` : ''}`);
+            if (f.testFile) {
+                issues.push(`    → ${f.name} — test file missing: ${f.testFile}`);
+            }
+            else {
+                issues.push(`    → ${f.name} (${f.filePath}) — no testFile in glossary`);
+                if (f.suggestedTestFile) {
+                    issues.push(`      Fix: Create ${f.suggestedTestFile} or add "testFile": "${f.suggestedTestFile}" to .codeyam/glossary.json`);
+                }
+            }
         }
     }
     if (s.functionsFailing > 0) {
@@ -3330,22 +3423,16 @@ async function handleAudit() {
         console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
         process.exit(1);
     }
-    // Auto-fix incomplete entities and unassociated scenarios — but only once.
-    // If analyze-imports + entity SHA sync runs and issues persist, report clearly
-    // instead of retrying. The analysis may have errors (e.g., stale entity
-    // references from refactoring) that can't be fixed by re-running.
+    // Lightweight auto-fix: backfill entity_sha on scenarios that were
+    // registered before entity records existed. This is fast (DB-only).
+    // We do NOT run handleAnalyzeImports here — it scans all files and takes
+    // minutes on large projects. Users should run it separately if needed.
     const incompleteBeforeFix = data.incompleteEntities || [];
     const unassociatedBeforeFix = data.unassociatedScenarios || [];
     let autoRemediationFailed = false;
     if (incompleteBeforeFix.length > 0 || unassociatedBeforeFix.length > 0) {
         const issueCount = incompleteBeforeFix.length + unassociatedBeforeFix.length;
-        console.log(chalk.dim(`Auto-fixing ${issueCount} entity association issue${issueCount !== 1 ? 's' : ''}...`));
-        try {
-            await handleAnalyzeImports({ silent: true });
-        }
-        catch {
-            // Fall through — the audit will still report them
-        }
+        console.log(chalk.dim(`Backfilling ${issueCount} entity association issue${issueCount !== 1 ? 's' : ''}...`));
         // Backfill entity_sha on scenarios that were registered before entities existed
         try {
             const entities = await loadEntities({});
@@ -3364,13 +3451,13 @@ async function handleAudit() {
         catch {
             // Fall through — re-fetch will show remaining issues
         }
-        // Re-fetch audit results after the fix
+        // Re-fetch audit results after the backfill
         data = await fetchAuditResult();
         if (!data) {
-            console.error(chalk.red('Error: Could not reach the CodeYam server after auto-fix.'));
+            console.error(chalk.red('Error: Could not reach the CodeYam server after backfill.'));
             process.exit(1);
         }
-        // If issues persist after auto-fix, flag it so we show clear guidance
+        // If issues persist after backfill, flag it so we show clear guidance
         const incompleteAfterFix = data.incompleteEntities || [];
         const unassociatedAfterFix = data.unassociatedScenarios || [];
         if (incompleteAfterFix.length > 0 || unassociatedAfterFix.length > 0) {
@@ -3407,6 +3494,9 @@ async function handleAudit() {
             }
             else {
                 detail = chalk.red(' — no scenarios registered');
+                if (c.hint) {
+                    detail += `\n      ${chalk.yellow('Fix: ' + c.hint)}`;
+                }
             }
             // Show file path for failing components always, for OK only when name is ambiguous
             const isDuplicate = (componentNameCounts.get(c.name) || 0) > 1;
@@ -3450,9 +3540,16 @@ async function handleAudit() {
                     break;
                 case 'missing':
                 default:
-                    detail = f.testFile
-                        ? chalk.red(` — test file missing: ${f.testFile}`)
-                        : chalk.red(' — no test file specified');
+                    if (f.testFile) {
+                        detail = chalk.red(` — test file missing: ${f.testFile}`);
+                    }
+                    else {
+                        detail = chalk.red(` — no test file specified in glossary`);
+                        detail += chalk.dim(` (source: ${f.filePath})`);
+                        if (f.suggestedTestFile) {
+                            detail += `\n      ${chalk.yellow(`Fix: Either create ${f.suggestedTestFile} or add "testFile": "${f.suggestedTestFile}" to this entry in .codeyam/glossary.json`)}`;
+                        }
+                    }
                     break;
             }
             console.log(`  ${icon} ${f.name}${detail}`);
@@ -3469,19 +3566,48 @@ async function handleAudit() {
         console.log(chalk.yellow('    Add these to .codeyam/glossary.json and run `codeyam editor analyze-imports`'));
         console.log();
     }
-    // Incomplete entities (scenarios without analyses)
-    const incompleteEntities = data.incompleteEntities || [];
+    // Incomplete entities (scenarios without analyses) — auto-fix by running
+    // targeted analysis on just the affected files (fast: 2 files vs 117+).
+    let incompleteEntities = data.incompleteEntities || [];
     if (incompleteEntities.length > 0) {
-        console.log(chalk.bold('Incomplete entities (need import analysis):'));
-        for (const e of incompleteEntities) {
-            console.log(`  ${chalk.red('✗')} ${e.name} — ${e.scenarioCount} scenario${e.scenarioCount !== 1 ? 's' : ''} but entity not analyzed`);
+        const { getIncompleteEntityFilePaths } = await import('../utils/editorAudit.js');
+        try {
+            const { getDatabase } = await import('../../../packages/database/index.js');
+            const db = getDatabase();
+            const filePaths = await getIncompleteEntityFilePaths(db, incompleteEntities);
+            if (filePaths.length > 0) {
+                console.log(chalk.dim(`Running targeted import analysis for ${filePaths.length} incomplete entit${filePaths.length !== 1 ? 'ies' : 'y'}...`));
+                const root = getProjectRoot();
+                try {
+                    const { runAnalysisForEntities } = await import('../utils/analysisRunner.js');
+                    await runAnalysisForEntities({
+                        projectRoot: root,
+                        filePaths,
+                        progress: new ProgressReporter(),
+                        onlyDataStructure: true,
+                    });
+                    // Re-fetch audit results after targeted fix
+                    const refreshed = await fetchAuditResult();
+                    if (refreshed) {
+                        data = refreshed;
+                        incompleteEntities = data.incompleteEntities || [];
+                    }
+                }
+                catch {
+                    // Fall through — report remaining incomplete entities below
+                }
+            }
         }
-        if (autoRemediationFailed) {
-            console.log(chalk.yellow('    analyze-imports ran automatically but could not resolve these.'));
-            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to see the full error output.'));
+        catch {
+            // DB not available — fall through to reporting
         }
-        else {
-            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to analyze these entities.'));
+    }
+    if (incompleteEntities.length > 0) {
+        const { formatIncompleteEntityGuidance } = await import('../utils/editorAudit.js');
+        console.log(chalk.bold('Incomplete entities (need import analysis):'));
+        for (const e of incompleteEntities) {
+            const guidance = formatIncompleteEntityGuidance(e);
+            console.log(`  ${chalk.red('✗')} ${guidance}`);
         }
         console.log();
     }