@codeyam/codeyam-cli 0.1.28 → 0.1.30

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

@@ -227,6 +227,143 @@ function getTechStackContext(root) {
                 : 'FEATURE_PATTERNS.md',
     };
 }
+/**
+ * Returns a pre-populated tech stack for a given template ID.
+ * Written to .codeyam/config.json during `codeyam editor template`.
+ */
+function getTechStackForTemplate(templateId) {
+    switch (templateId) {
+        case 'nextjs-prisma-sqlite':
+            return {
+                languages: [
+                    {
+                        name: 'TypeScript',
+                        url: 'https://typescriptlang.org',
+                        description: 'Statically typed JavaScript superset',
+                        version: '5',
+                    },
+                ],
+                frameworks: [
+                    {
+                        name: 'Next.js',
+                        url: 'https://nextjs.org',
+                        description: 'Full-stack React framework with App Router, SSR, and API routes',
+                        version: '15',
+                    },
+                    {
+                        name: 'React',
+                        url: 'https://react.dev',
+                        description: 'Component-based UI library',
+                        version: '19',
+                    },
+                ],
+                databases: [
+                    {
+                        name: 'SQLite',
+                        url: 'https://sqlite.org',
+                        description: 'Embedded relational database — zero config, upgradeable to hosted DB',
+                    },
+                ],
+                libraries: [
+                    {
+                        name: 'Prisma',
+                        url: 'https://prisma.io',
+                        description: 'Type-safe database ORM and query builder',
+                        version: '7',
+                    },
+                    {
+                        name: 'Tailwind CSS',
+                        url: 'https://tailwindcss.com',
+                        description: 'Utility-first CSS framework',
+                        version: '4',
+                    },
+                ],
+            };
+        case 'chrome-extension-react':
+            return {
+                languages: [
+                    {
+                        name: 'TypeScript',
+                        url: 'https://typescriptlang.org',
+                        description: 'Statically typed JavaScript superset',
+                        version: '5',
+                    },
+                ],
+                frameworks: [
+                    {
+                        name: 'React',
+                        url: 'https://react.dev',
+                        description: 'Component-based UI library for the popup and options pages',
+                        version: '19',
+                    },
+                    {
+                        name: 'Vite',
+                        url: 'https://vite.dev',
+                        description: 'Fast build tool and dev server',
+                        version: '6',
+                    },
+                ],
+                libraries: [
+                    {
+                        name: 'Tailwind CSS',
+                        url: 'https://tailwindcss.com',
+                        description: 'Utility-first CSS framework',
+                        version: '4',
+                    },
+                ],
+                infrastructure: [
+                    {
+                        name: 'Chrome Manifest V3',
+                        url: 'https://developer.chrome.com/docs/extensions/develop/migrate/what-is-mv3',
+                        description: 'Extension platform with service workers, declarative APIs, and chrome.storage',
+                    },
+                ],
+            };
+        case 'expo-react-native':
+            return {
+                languages: [
+                    {
+                        name: 'TypeScript',
+                        url: 'https://typescriptlang.org',
+                        description: 'Statically typed JavaScript superset',
+                        version: '5',
+                    },
+                ],
+                frameworks: [
+                    {
+                        name: 'Expo',
+                        url: 'https://expo.dev',
+                        description: 'React Native development platform with managed workflow and OTA updates',
+                        version: 'SDK 54',
+                    },
+                    {
+                        name: 'React Native',
+                        url: 'https://reactnative.dev',
+                        description: 'Cross-platform mobile UI framework',
+                    },
+                    {
+                        name: 'Expo Router',
+                        url: 'https://docs.expo.dev/router/introduction/',
+                        description: 'File-based navigation for React Native apps',
+                    },
+                ],
+                libraries: [
+                    {
+                        name: 'NativeWind',
+                        url: 'https://www.nativewind.dev',
+                        description: 'Tailwind CSS for React Native',
+                    },
+                    {
+                        name: 'AsyncStorage',
+                        url: 'https://react-native-async-storage.github.io/async-storage/',
+                        description: 'Persistent key-value storage for React Native',
+                    },
+                ],
+            };
+        default:
+            return {};
+    }
+}
 /**
  * Print dimension guidance when the project has multiple screen sizes.
  * Tells Claude to pick the right dimension for the content being previewed
@@ -250,6 +387,37 @@ function checkbox(text) {
     const highlighted = text.replace(/`([^`]+)`/g, (_m, code) => chalk.cyan(code));
     console.log(`  ${chalk.dim('[ ]')} ${highlighted}`);
 }
+/**
+ * Print a checklist item for the handoff summary.
+ */
+function checkboxHandoff() {
+    checkbox('Update the handoff summary in `.codeyam/config.json` for the next session/AI: `codeyam editor handoff \'{"summary":"..."}\'`');
+}
+/**
+ * Print the handoff context from a previous session or AI provider.
+ */
+function printHandoffContext(root) {
+    try {
+        const configPath = path.join(root, '.codeyam', 'config.json');
+        if (!fs.existsSync(configPath))
+            return;
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        const handoff = config.handoff;
+        if (!handoff || !handoff.summary)
+            return;
+        console.log();
+        console.log(chalk.bold.magenta(`━━━ HANDOFF FROM ${String(handoff.lastProvider || 'unknown').toUpperCase()} (Step ${handoff.lastStep || 'unknown'}) ━━━`));
+        console.log(chalk.magenta(handoff.summary));
+        if (handoff.lastUpdated) {
+            console.log(chalk.dim(`    Updated: ${handoff.lastUpdated}`));
+        }
+        console.log(chalk.bold.magenta('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+        console.log();
+    }
+    catch {
+        // Non-fatal
+    }
+}
 /**
  * Instructions for creating/updating .codeyam/data-structure.json.
  * Only prints creation instructions if the file doesn't exist yet.
@@ -376,6 +544,12 @@ function printExtractionPlanInstructions() {
     console.log(chalk.yellow('  Every component that renders multiple distinct sections should be split into sub-components.'));
     console.log(chalk.yellow('  If a component has N visually distinct parts, it should compose N sub-components.'));
     console.log();
+    console.log(chalk.bold.red('THE DECOMPOSITION RULE: All code should do one thing.'));
+    console.log(chalk.yellow('  Code either contains logic OR brings together smaller pieces to form a coordinated whole.'));
+    console.log(chalk.yellow('  Every opportunity to extract code into a sensible function, helper, or sub-component MUST be taken.'));
+    console.log(chalk.yellow('  Then extract AGAIN from the extracted code — keep going until each piece does one clearly defined thing.'));
+    console.log(chalk.yellow('  This applies to ALL code: backend routes, business logic, frontend components, utilities — everything.'));
+    console.log();
     console.log(chalk.bold('Checklist:'));
     checkbox('Read `.codeyam/glossary.json` — note reusable functions/components');
     checkbox('Read EVERY file used by this page/feature');
@@ -386,6 +560,12 @@ function printExtractionPlanInstructions() {
     console.log(chalk.yellow('    Functions: data transforms, calculations, formatting, validation,'));
     console.log(chalk.yellow('      API response shaping, any logic that is not directly about rendering'));
     console.log(chalk.yellow('    Hooks: data fetching, state management, side effects'));
+    console.log(chalk.yellow('    Inline logic — backend AND frontend (MUST be extracted as named functions):'));
+    console.log(chalk.yellow('      conditionals/ternaries, computed/derived values, data transformations,'));
+    console.log(chalk.yellow('      string formatting/interpolation, array filtering/sorting/mapping callbacks,'));
+    console.log(chalk.yellow('      default value logic, null/undefined guards, date/number formatting,'));
+    console.log(chalk.yellow('      permission/role checks, status derivation (e.g. isOverdue(task)),'));
+    console.log(chalk.yellow('      request/response shaping, error message construction, config lookups'));
     console.log();
     checkbox('Write a numbered extraction plan listing EVERYTHING you will extract');
     console.log(chalk.yellow('    The end state: every page file is ONLY imports + component composition.'));
@@ -396,6 +576,15 @@ function printExtractionPlanInstructions() {
     console.log(chalk.yellow('    — What it is (component, function, hook)'));
     console.log(chalk.yellow('    — Where it currently lives (source file + approximate lines)'));
     console.log(chalk.yellow('    — Where it will go (new file path)'));
+    console.log(chalk.yellow('    — How you will test it (key inputs/outputs and edge cases)'));
+    console.log(chalk.yellow('    — What logic inside it can be further extracted as a separate testable function'));
+    console.log();
+    console.log(chalk.bold.red('BEFORE FINALIZING THE PLAN:'));
+    console.log(chalk.yellow('    Re-read every file ONE MORE TIME. For each piece of code, ask:'));
+    console.log(chalk.yellow('    1. Does this do more than one thing? → Split it into pieces that each do one thing.'));
+    console.log(chalk.yellow('    2. Is there logic here that could be its own function with clear inputs/outputs? → Extract it.'));
+    console.log(chalk.yellow('    3. Can the extracted code itself be broken down further? → Keep extracting.'));
+    console.log(chalk.yellow('    If your plan has fewer functions than components, you probably missed extractable logic.'));
     console.log();
     console.log(chalk.dim('Present the numbered plan, then proceed to step 7 to execute it.'));
 }
@@ -1008,6 +1197,15 @@ function printStep1(root, feature, options, userPrompt) {
     console.log(chalk.dim('    -H "Content-Type: application/json" \\'));
     console.log(chalk.dim('    -d \'{"projectTitle":"My App","projectDescription":"A short description of what this app does"}\''));
     console.log();
+    checkbox('Detect and set the project tech stack:');
+    console.log(chalk.dim('  Scan package.json, framework configs (.env, .env.example, tsconfig.json, next.config.*, prisma/schema.prisma, etc.)'));
+    console.log(chalk.dim('  to detect languages, frameworks, databases, services, libraries, and infrastructure.'));
+    console.log(chalk.dim('  Each item MUST have name, url, and description. version and envKeys are optional.'));
+    console.log(chalk.dim(`  curl -s -X POST http://localhost:${port}/api/editor-project-info \\`));
+    console.log(chalk.dim('    -H "Content-Type: application/json" \\'));
+    console.log(chalk.dim('    -d \'{"techStack":{"languages":[{"name":"TypeScript","url":"https://typescriptlang.org","description":"Statically typed JavaScript superset","version":"5"}],"frameworks":[{"name":"Next.js","url":"https://nextjs.org","description":"Full-stack React framework with SSR and API routes","version":"15"}],"databases":[{"name":"SQLite","url":"https://sqlite.org","description":"Embedded relational database"}],"services":[{"name":"Stripe","url":"https://stripe.com","description":"Payment processing and billing","envKeys":["STRIPE_SECRET_KEY"]}],"libraries":[{"name":"Prisma","url":"https://prisma.io","description":"Type-safe database ORM","version":"7"}],"infrastructure":[]}}\''));
+    console.log(chalk.dim('  Replace the example values with what you detect in this project. Omit empty categories.'));
+    console.log();
     const designSystem = readDesignSystem(root);
     if (designSystem) {
         console.log(chalk.bold.magenta('Design System (from .codeyam/design-system.md):'));
@@ -1021,6 +1219,8 @@ function printStep1(root, feature, options, userPrompt) {
     console.log(chalk.yellow('    Option 2 label: "I\'d like some changes"') +
         chalk.dim(' — user describes changes, you revise the plan, then re-present'));
     console.log();
+    checkboxHandoff();
+    console.log();
     console.log(chalk.dim('This step is for understanding user goals and getting buy-in. Code comes in Step 2.'));
     console.log();
     console.log(chalk.bold.red('━━━ STOP ━━━'));
@@ -1148,6 +1348,8 @@ function printStep2(root, feature) {
         console.log();
         printDataStructureInstructions();
     }
+    console.log();
+    checkboxHandoff();
     stopGate(2);
 }
 // ─── Step 3: Prototype ────────────────────────────────────────────────
@@ -1264,6 +1466,7 @@ function printStep3(root, feature) {
     console.log(chalk.red.bold('  NEVER claim "you should see X" or "the preview shows X" unless you just ran a preview command.'));
     console.log(chalk.red('  The preview only updates when you explicitly refresh it. Verify, then describe.'));
     console.log();
+    checkboxHandoff();
     stopGate(3);
 }
 // ─── Step 4: Verify Prototype ─────────────────────────────────────────
@@ -1321,6 +1524,8 @@ function printStep4(root, feature) {
     console.log(chalk.dim('    A new clone should work with just: git clone → npm run setup → npm run dev'));
     console.log();
     console.log(chalk.dim('Focus on building the prototype. Scenarios and refactoring happen in later steps.'));
+    console.log();
+    checkboxHandoff();
     stopGate(4);
 }
 // ─── Step 5: Confirm ──────────────────────────────────────────────────
@@ -1384,6 +1589,8 @@ function printStep5(root, feature) {
         chalk.dim(' — make changes, refresh preview, re-run `codeyam editor 5`'));
     console.log();
     console.log(chalk.dim('Wait for user approval before moving on. Refactoring and scenarios happen in later steps.'));
+    console.log();
+    checkboxHandoff();
     stopGate(5, { confirm: true });
 }
 // ─── Step 6: Deconstruct ──────────────────────────────────────────────
@@ -1409,6 +1616,8 @@ function printStep6(root, feature) {
     console.log(chalk.yellow('This step is read and plan only. Code extraction happens in step 7.'));
     console.log();
     printExtractionPlanInstructions();
+    console.log();
+    checkboxHandoff();
     stopGate(6);
 }
 // ─── Step 7: Extract ──────────────────────────────────────────────────
@@ -1445,6 +1654,9 @@ function printStep7(root, feature) {
     checkbox('For each function/hook: write MULTIPLE failing tests FIRST, then extract to make them pass');
     console.log(chalk.dim('    Cover: typical inputs, edge cases, empty/null inputs, error conditions'));
     console.log(chalk.dim('    Aim for 3-8 test cases per function depending on complexity'));
+    console.log(chalk.dim('    EVERY conditional branch in the function MUST have a test that exercises it'));
+    console.log(chalk.dim('    EVERY return path MUST be tested — if a function can return 3 different things, write 3+ tests'));
+    console.log(chalk.dim('    Boundary values: 0, 1, -1, empty string, empty array, undefined, null'));
     console.log(chalk.dim('    Hooks count as functions — useDrinks, useAuth, etc. all need test files'));
     console.log(chalk.dim('    Wrap all tests in a describe("FunctionName", ...) block — the audit matches on this name'));
     if (ctx.isExpo) {
@@ -1461,6 +1673,23 @@ function printStep7(root, feature) {
     console.log(chalk.yellow(`    Check: does any file contain raw ${ctx.rawPrimitivesList}?`));
     console.log(chalk.yellow('    If yes → that JSX section is a component waiting to be extracted.'));
     console.log();
+    console.log(chalk.bold('Decomposition pass (backend AND frontend):'));
+    checkbox('Re-read EVERY file you created or modified. For each, extract a function/helper/sub-component for:');
+    console.log(chalk.yellow('    — Conditionals (e.g. `isOverdue ? "red" : "green"` → `getStatusColor(date)`)'));
+    console.log(chalk.yellow('    — Computed values (e.g. `items.filter(...).length` → `countActiveItems(items)`)'));
+    console.log(chalk.yellow('    — Formatting (e.g. `${price.toFixed(2)}` → `formatPrice(price)`)'));
+    console.log(chalk.yellow('    — Data transforms, validation, request/response shaping'));
+    console.log(chalk.yellow('    — Anything doing more than one thing → split until each piece does one clearly defined thing'));
+    checkbox('Then look at what you just extracted — can IT be broken down further? Keep going.');
+    checkbox('Write tests for every extracted function (same TDD: failing tests FIRST)');
+    console.log();
+    console.log(chalk.bold.red('TEST QUALITY SELF-CHECK (before proceeding):'));
+    checkbox('For EACH test file: count the test cases. Fewer than 3 tests for any function is a red flag.');
+    checkbox('For EACH tested function: read the function, count the conditional branches. Every branch MUST have a test.');
+    checkbox('For EACH tested function: verify you test at least one error/edge case, not just happy paths.');
+    console.log(chalk.yellow('    If a function has an if/else, switch, or ternary — each path needs its own test case.'));
+    console.log(chalk.yellow('    If a function handles null/undefined/empty — test those inputs explicitly.'));
+    console.log();
     console.log(chalk.bold('Verify before proceeding:'));
     checkbox('Run all tests and verify they pass');
     checkbox(`Page files contain ONLY imports + component composition — no raw ${ctx.isExpo ? 'React Native primitives' : 'HTML tags'}`);
@@ -1471,6 +1700,8 @@ function printStep7(root, feature) {
     console.log(chalk.dim('Reuse glossary functions when they fit naturally. Extract a new function when the use case diverges.'));
     console.log();
     console.log(chalk.dim('Focus on TDD for functions and extraction for components. Scenarios come in later steps.'));
+    console.log();
+    checkboxHandoff();
     stopGate(7);
 }
 // ─── Step 8: Glossary ─────────────────────────────────────────────────
@@ -1539,6 +1770,15 @@ function printStep9(root, feature) {
     console.log();
     console.log(chalk.dim('Do not proceed until both component isolations and library tests pass.'));
     console.log();
+    console.log(chalk.bold.red('DECOMPOSITION & COVERAGE REVIEW (before running audit):'));
+    checkbox('Re-read every file. Extract any logic that could be its own function/helper/sub-component.');
+    console.log(chalk.yellow('    Code either contains logic OR brings together smaller pieces.'));
+    console.log(chalk.yellow('    Keep extracting until each piece does one clearly defined thing.'));
+    console.log(chalk.yellow('    For each extraction: write failing test first, then extract, then make test pass.'));
+    checkbox('Open each test file and verify: ≥3 test cases per function, happy path + edge case + error case');
+    checkbox('If any function has fewer tests than conditional branches, add the missing tests NOW');
+    checkbox('Update `.codeyam/glossary.json` with any new functions before running audit');
+    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('    The audit auto-fixes incomplete entities by running targeted analysis on just the affected files.'));
@@ -2521,11 +2761,11 @@ function printStep18(root, feature) {
     console.log(chalk.dim('    If the user wants help, guide them through `gh repo create` or manual GitHub setup, then push.'));
     console.log(chalk.dim('    Task management is handled by the ━━━ TASK ━━━ directive below.'));
     console.log();
-    console.log(chalk.bold.yellow('IMPORTANT: After this step, the current feature is DONE.'));
-    console.log(chalk.yellow('  Any new user request — even if it sounds related — is a NEW feature.'));
+    const port = getServerPort();
+    console.log(chalk.bold.yellow('IMPORTANT: After the push succeeds (or the user skips it), the feature is DONE.'));
+    console.log(chalk.yellow(`  Signal the UI by running: curl -s -X POST http://localhost:${port}/api/editor-feature-complete`));
+    console.log(chalk.yellow('  Then STOP and wait. Do NOT ask the user what to build next — the UI handles the transition.'));
     console.log(chalk.yellow('  Do NOT use `codeyam editor change` or start building directly.'));
-    console.log(chalk.yellow('  Ask the user what they want to build. Once they tell you, run `codeyam editor 1` yourself.'));
-    console.log(chalk.yellow('  NEVER tell the user to run `codeyam editor` commands — these are internal. Just ask what to build.'));
     console.log(chalk.yellow('  The change workflow is ONLY for modifications during steps 1-15, not after commit.'));
     stopGate(18, { confirm: true });
 }
@@ -3150,6 +3390,50 @@ function formatApiSubcommandResult(subcommand, data) {
             return null; // journal-list, show/hide-results: keep full JSON
     }
 }
+/**
+ * `codeyam editor handoff '{"summary":"..."}'`
+ *
+ * Update the handoff summary in .codeyam/config.json for other AI providers.
+ */
+function handleHandoff(jsonArg) {
+    if (!jsonArg) {
+        console.error(chalk.red('Error: JSON argument required.'));
+        console.error(chalk.dim('  Usage: codeyam editor handoff \'{"summary":"Built the X component..."}\''));
+        process.exit(1);
+    }
+    let summary;
+    try {
+        const parsed = JSON.parse(jsonArg);
+        summary = parsed.summary;
+    }
+    catch {
+        console.error(chalk.red('Error: Invalid JSON.'));
+        process.exit(1);
+    }
+    if (!summary) {
+        console.error(chalk.red('Error: "summary" field is required.'));
+        process.exit(1);
+    }
+    const root = getProjectRoot();
+    const configPath = path.join(root, '.codeyam', 'config.json');
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        const state = readState(root);
+        const provider = config.provider || 'claude';
+        config.handoff = {
+            summary,
+            lastProvider: provider,
+            lastStep: state?.step,
+            lastUpdated: new Date().toISOString(),
+        };
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+        console.log(chalk.green('✓ Handoff summary updated in .codeyam/config.json'));
+    }
+    catch (err) {
+        console.error(chalk.red(`Error: Could not update config.json: ${err.message}`));
+        process.exit(1);
+    }
+}
 /**
  * `codeyam editor register '{"name":"...","componentName":"...",...}'`
  *
@@ -4018,7 +4302,12 @@ async function handleAudit(options) {
             let detail;
             switch (f.status) {
                 case 'ok':
-                    detail = chalk.dim(` (${f.testFile})`);
+                    if (f.testCaseCount !== undefined && f.testCaseCount < 3) {
+                        detail = chalk.yellow(` (${f.testFile}) — ⚠ only ${f.testCaseCount} test case${f.testCaseCount !== 1 ? 's' : ''}, consider adding more`);
+                    }
+                    else {
+                        detail = chalk.dim(` (${f.testFile}${f.testCaseCount !== undefined ? `, ${f.testCaseCount} tests` : ''})`);
+                    }
                     break;
                 case 'runner_error':
                     detail = chalk.red(` — test runner crashed: ${f.testFile}`);
@@ -4051,6 +4340,9 @@ async function handleAudit(options) {
             }
             console.log(`  ${icon} ${f.name}${detail}`);
         }
+        if (summary.functionsThinCoverage > 0) {
+            console.log(chalk.yellow.bold(`  ⚠ ${summary.functionsThinCoverage} function${summary.functionsThinCoverage !== 1 ? 's' : ''} with thin test coverage (< 3 test cases). Add more tests to cover all branches.`));
+        }
         console.log();
     }
     // Missing from glossary
@@ -4624,6 +4916,10 @@ async function handleTemplate() {
             if (stack?.supportedFormats) {
                 config.appFormats = stack.supportedFormats;
             }
+            // Pre-populate tech stack from template
+            if (stack) {
+                config.techStack = getTechStackForTemplate(stack.id);
+            }
             // Set mobile-first defaults for mobile-app projects
             if (stack?.supportedFormats?.includes('mobile-app')) {
                 config.defaultScreenSize = {
@@ -5296,6 +5592,11 @@ const editorCommand = {
             }
             return;
         }
+        // Subcommand: codeyam editor handoff '{"summary":"..."}'
+        if (argv.step === 'handoff') {
+            await handleHandoff(argv.json || '');
+            return;
+        }
         // Subcommand: codeyam editor register '{"name":"..."}'
         if (argv.step === 'register') {
             await handleRegister(argv.json || '');
@@ -5893,6 +6194,7 @@ const editorCommand = {
                 process.exit(1);
             }
         }
+        printHandoffContext(root);
         switch (step) {
             case 1: {
                 const feature = argv.feature || undefined;