@slowcook-ai/cli 0.7.5 → 0.7.7

package/dist/commands/testgen/agent.d.ts

@@ -1,10 +1,26 @@
-import type { ForgeAdapter } from "@slowcook-ai/core";
+import type { ForgeAdapter, Spec } from "@slowcook-ai/core";
 import type { LlmClient } from "../refine/llm.js";
 export declare const LABEL_TESTS_READY = "tests-ready";
 export declare const LABEL_OVERRIDE_FREEZE = "override-freeze";
 export declare const TESTS_INTEGRATION_DIR = "tests/integration";
 export declare const MANIFESTS_DIR = ".brewing/manifests";
 export declare const MOCK_HELPERS_DIR = "tests/helpers/mocks";
+/**
+ * Which artifacts testgen should emit for a given spec. Computed per-spec
+ * based on what already exists on disk + whether the spec has `ui_behavior`:
+ *
+ * - `"full"` — neither handler tests nor UI tests exist; emit both (plus
+ *   any needed stubs + helpers).
+ * - `"handler-only"` — spec has no `ui_behavior`; handler tests don't exist.
+ *   Emit handler test + handler stubs + helpers. This is 0.7.0 behavior.
+ * - `"ui-only"` — handler tests already exist; spec has `ui_behavior`; UI
+ *   tests are missing. Emit ONLY UI test + UI stubs. Use-case: 0.7.5 adoption
+ *   on a brownfield story where the backend was built before UI tests existed.
+ *
+ * Mode is inferred by `collectTargetSpecs`; the LLM is told which mode it's
+ * in via the user message so it emits only what's needed.
+ */
+export type TestgenMode = "full" | "handler-only" | "ui-only";
 export interface TestgenContext {
     repoRoot: string;
     forge: ForgeAdapter;
@@ -42,6 +58,10 @@ export type TestgenOutcome = {
  * citing the supersede chain in the PR body for auditability).
  */
 export declare function runTestgen(ctx: TestgenContext): Promise<TestgenOutcome>;
+export interface TargetSpec {
+    spec: Spec;
+    mode: TestgenMode;
+}
 export declare function buildProjectContext(repoRoot: string): string;
 /**
  * Phase B2 (0.7.0) testgen output: one test file, zero-or-more route stubs,
@@ -50,6 +70,7 @@ export declare function buildProjectContext(repoRoot: string): string;
  * against existing files, and writes only what's new.
  */
 export interface TestgenBundle {
+    /** Handler test file content. Empty string when mode is `"ui-only"`. */
     testContent: string;
     stubs: Array<{
         path: string;
@@ -59,23 +80,34 @@ export interface TestgenBundle {
         path: string;
         contents: string;
     }>;
+    /** UI component test file content (tier-1 UI). Empty string when mode is `"handler-only"`. */
+    uiTestContent: string;
+    /** UI component stubs — React/TSX files under src/components/ or src/app/**\/*.tsx. */
+    uiStubs: Array<{
+        path: string;
+        contents: string;
+    }>;
 }
 /**
  * Parse XML-tagged multi-artifact output into a TestgenBundle.
  *
  * Accepted shape (from the prompt):
- *   <test_file>...</test_file>
- *   <stub path="src/app/api/foo/route.ts">...</stub>   (zero or more)
- *   <helper path="tests/helpers/mocks/bar.ts">...</helper>  (zero or more)
+ *   <test_file>...</test_file>                    — required unless mode="ui-only"
+ *   <stub path="src/app/api/foo/route.ts">...</stub>         (zero or more)
+ *   <helper path="tests/helpers/mocks/bar.ts">...</helper>   (zero or more)
+ *   <ui_test_file>...</ui_test_file>              — required when mode="ui-only" or "full" with UI
+ *   <ui_stub path="src/components/foo.tsx">...</ui_stub>     (zero or more)
+ *
+ * Mode semantics (0.7.7+):
+ * - `"handler-only"` — `<test_file>` required; `<ui_test_file>` ignored if present.
+ * - `"ui-only"` — `<ui_test_file>` required; `<test_file>` ignored if present.
+ * - `"full"` — both `<test_file>` required AND `<ui_test_file>` required.
  *
  * Tolerant of code-fenced output: if the LLM wraps the whole thing in
  * ```, we strip it. If a block's contents are themselves code-fenced,
- * we strip those too — tier-1 test / helper / stub files are raw TS.
- *
- * Throws if `<test_file>` is missing or empty — that's the one mandatory
- * artifact.
+ * we strip those too — tier-1 test / helper / stub / UI files are raw TS/TSX.
  */
-export declare function parseTestgenBundle(raw: string, storyId: string): TestgenBundle;
+export declare function parseTestgenBundle(raw: string, storyId: string, mode?: TestgenMode): TestgenBundle;
 /**
  * Tier-1 conformance lint. Run on every generated test file before commit.
  * Catches patterns the prompt forbids — inline `vi.mock`, `fetch(...)`,
@@ -107,5 +139,12 @@ export declare function lintTierOneTest(filePath: string, source: string): TierO
  * Robust against typical usage; falls back to a single synthetic entry if
  * nothing recognisable is found.
  */
+/**
+ * Read an existing test file from disk and extract its test IDs. Thin
+ * wrapper around extractTestIdsFromFile for the "ui-only" code path where
+ * the handler test already exists and we need its IDs to preserve in the
+ * rewritten combined manifest.
+ */
+export declare function extractTestIdsFromExistingFile(repoRoot: string, filePath: string): string[];
 export declare function extractTestIdsFromFile(filePath: string, source: string): string[];
 //# sourceMappingURL=agent.d.ts.map

package/dist/commands/testgen/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/commands/testgen/agent.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAQ,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AASlD,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAC/C,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AACzD,eAAO,MAAM,aAAa,uBAAuB,CAAC;AAClD,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,YAAY,CAAC;IACpB,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,GAAG,EAAE,OAAO,CAAC;IACb,2EAA2E;IAC3E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,GAAG,EAAE,IAAI,CAAC;CACX;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,EAAE,CAAA;CAAE,GACzG;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CA8I7E;AAkED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA8F5D;AAsCD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD;AAqBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,CAiC9E;AASD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AA6DD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAepF;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CA4BjF"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/commands/testgen/agent.ts"],"names":[],"mappings":"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"}

package/dist/commands/testgen/agent.js

@@ -17,53 +17,75 @@ export const MOCK_HELPERS_DIR = "tests/helpers/mocks";
  * citing the supersede chain in the PR body for auditability).
  */
 export async function runTestgen(ctx) {
-    const specs = collectTargetSpecs(ctx);
-    if (specs.length === 0) {
+    const targets = collectTargetSpecs(ctx);
+    if (targets.length === 0) {
         return { kind: "nothing-to-generate", reason: "no active specs without tests" };
     }
     // Produce per-spec artifacts in a scratch area; commit together at the end.
     const generated = [];
     const toRemove = [];
-    for (const spec of specs) {
+    for (const { spec, mode } of targets) {
         const projectContext = buildProjectContext(ctx.repoRoot);
-        const bundle = await generateTestBundle(spec, ctx, projectContext);
-        const testPath = join(TESTS_INTEGRATION_DIR, `story-${spec.story_id}.test.ts`);
-        // Tier-1 conformance gate: if the LLM slipped back to tier-0 habits
-        // (inline vi.mock, fetch(), etc.), we refuse to ship the file. Halts
-        // loudly here rather than quietly producing HTTP-loopback tests the
-        // brewing loop can't ratchet against. The caller can re-run with a
-        // different seed or hand-edit and re-run testgen.
-        const violations = lintTierOneTest(testPath, bundle.testContent);
-        if (violations.length > 0) {
-            const details = violations
-                .slice(0, 10)
-                .map((v) => `  - line ${v.line}: \`${v.pattern}\` — ${v.reason}`)
-                .join("\n");
-            const more = violations.length > 10 ? `\n  - (+${violations.length - 10} more)` : "";
-            throw new Error(`testgen output for story-${spec.story_id} violates tier-1 conventions (${violations.length} issue(s)):\n${details}${more}\n\n` +
-                `The LLM emitted patterns banned by docs/plans/0.7-testgen-two-tier.md §4.1-§7.3. ` +
-                `Re-run testgen with a different model/seed, or hand-edit the generated file to use project mock helpers.`);
+        const bundle = await generateTestBundle(spec, ctx, projectContext, mode);
+        const testPath = handlerTestPathFor(spec.story_id);
+        const uiTestPath = uiTestPathFor(spec.story_id);
+        // Tier-1 conformance gate for handler tests (run only when mode emits one).
+        // Halts loudly if the LLM slipped back to tier-0 habits (inline vi.mock,
+        // fetch(), etc.) rather than quietly producing HTTP-loopback tests the
+        // brewing loop can't ratchet against.
+        if (mode !== "ui-only" && bundle.testContent) {
+            const violations = lintTierOneTest(testPath, bundle.testContent);
+            if (violations.length > 0) {
+                const details = violations
+                    .slice(0, 10)
+                    .map((v) => `  - line ${v.line}: \`${v.pattern}\` — ${v.reason}`)
+                    .join("\n");
+                const more = violations.length > 10 ? `\n  - (+${violations.length - 10} more)` : "";
+                throw new Error(`testgen output for story-${spec.story_id} violates tier-1 conventions (${violations.length} issue(s)):\n${details}${more}\n\n` +
+                    `The LLM emitted patterns banned by docs/plans/0.7-testgen-two-tier.md §4.1-§7.3. ` +
+                    `Re-run testgen with a different model/seed, or hand-edit the generated file to use project mock helpers.`);
+            }
         }
         // De-dupe stubs + helpers: skip anything whose target file exists and
         // isn't a @slowcook-stub (for stubs) or isn't empty (for helpers). This
         // lets testgen re-run safely without clobbering in-progress impls.
         const stubsToWrite = bundle.stubs.filter((s) => shouldWriteStub(ctx.repoRoot, s.path));
         const helpersToWrite = bundle.helpers.filter((h) => shouldWriteHelper(ctx.repoRoot, h.path));
-        const manifestIds = extractTestIdsFromFile(testPath, bundle.testContent);
+        const uiStubsToWrite = bundle.uiStubs.filter((s) => shouldWriteStub(ctx.repoRoot, s.path));
+        // Manifest: combine handler + UI test IDs. When mode is "ui-only" the
+        // handler manifest already exists on disk — for simplicity we still
+        // rewrite it here with the combined shape, preserving the handler IDs
+        // by re-extracting from the existing file.
+        const handlerIds = mode === "ui-only"
+            ? extractTestIdsFromExistingFile(ctx.repoRoot, testPath)
+            : extractTestIdsFromFile(testPath, bundle.testContent);
+        const uiIds = mode !== "handler-only" && bundle.uiTestContent
+            ? extractTestIdsFromFile(uiTestPath, bundle.uiTestContent)
+            : [];
+        const manifestTests = [
+            ...handlerIds.map((id) => ({ id, file: testPath })),
+            ...uiIds.map((id) => ({ id, file: uiTestPath })),
+        ];
         const manifest = buildManifest({
             slowcookVersion: ctx.cliVersion,
             storyId: spec.story_id,
-            tests: manifestIds.map((id) => ({ id, file: testPath })),
-            suites: [{ suite: "backend", command: "npx vitest list", test_count: manifestIds.length }],
+            tests: manifestTests,
+            suites: [
+                { suite: "backend", command: "npx vitest list", test_count: manifestTests.length },
+            ],
             now: ctx.now,
         });
         generated.push({
             spec,
-            testPath,
-            fileContents: bundle.testContent,
+            mode,
+            testPath: mode === "ui-only" ? "" : testPath,
+            fileContents: mode === "ui-only" ? "" : bundle.testContent,
             manifest,
             stubs: stubsToWrite,
             helpers: helpersToWrite,
+            uiTestPath: mode === "handler-only" ? "" : uiTestPath,
+            uiFileContents: mode === "handler-only" ? "" : bundle.uiTestContent,
+            uiStubs: uiStubsToWrite,
         });
         for (const superseded of spec.supersedes) {
             toRemove.push(superseded);
@@ -71,7 +93,9 @@ export async function runTestgen(ctx) {
     }
     // Apply to disk: write new, delete superseded
     for (const g of generated) {
-        writeFileAt(ctx.repoRoot, g.testPath, g.fileContents);
+        if (g.testPath && g.fileContents) {
+            writeFileAt(ctx.repoRoot, g.testPath, g.fileContents);
+        }
         const manifestPath = join(MANIFESTS_DIR, `story-${g.spec.story_id}.json`);
         writeFileAt(ctx.repoRoot, manifestPath, JSON.stringify(g.manifest, null, 2) + "\n");
         for (const stub of g.stubs) {
@@ -80,6 +104,12 @@ export async function runTestgen(ctx) {
         for (const helper of g.helpers) {
             writeFileAt(ctx.repoRoot, helper.path, helper.contents);
         }
+        if (g.uiTestPath && g.uiFileContents) {
+            writeFileAt(ctx.repoRoot, g.uiTestPath, g.uiFileContents);
+        }
+        for (const stub of g.uiStubs) {
+            writeFileAt(ctx.repoRoot, stub.path, stub.contents);
+        }
     }
     const actuallyRemoved = [];
     for (const id of toRemove) {
@@ -93,12 +123,17 @@ export async function runTestgen(ctx) {
     // Git: branch, stage, commit, push
     await ctx.forge.git.createBranch(ctx.branchName);
     for (const g of generated) {
-        await ctx.forge.git.stage(g.testPath);
+        if (g.testPath)
+            await ctx.forge.git.stage(g.testPath);
         await ctx.forge.git.stage(join(MANIFESTS_DIR, `story-${g.spec.story_id}.json`));
         for (const stub of g.stubs)
             await ctx.forge.git.stage(stub.path);
         for (const helper of g.helpers)
             await ctx.forge.git.stage(helper.path);
+        if (g.uiTestPath)
+            await ctx.forge.git.stage(g.uiTestPath);
+        for (const stub of g.uiStubs)
+            await ctx.forge.git.stage(stub.path);
     }
     for (const id of actuallyRemoved) {
         await ctx.forge.git.stage(join(TESTS_INTEGRATION_DIR, `story-${id}.test.ts`));
@@ -125,6 +160,36 @@ export async function runTestgen(ctx) {
             draft: true,
             labels,
         });
+        // Post one audit-trail comment per spec's source_issue so the issue
+        // thread tells the whole pipeline story (refine posted earlier; brew
+        // posts next). Best-effort — don't fail the testgen run on a bad
+        // comment post.
+        for (const g of generated) {
+            const src = g.spec.source_issue?.match(/^#?(\d+)$/)?.[1];
+            if (!src)
+                continue;
+            const testCount = g.manifest.tests.length;
+            const fileParts = [];
+            if (g.testPath)
+                fileParts.push(`\`${g.testPath}\``);
+            if (g.uiTestPath)
+                fileParts.push(`\`${g.uiTestPath}\``);
+            const modeNote = g.mode === "ui-only"
+                ? " *(UI tests only — handler tests already merged)*"
+                : g.mode === "full"
+                    ? " *(handler + UI tests)*"
+                    : "";
+            const body = `### slowcook · tests opened\n\n` +
+                `[PR #${pr.number}](${pr.url}) — \`story-${g.spec.story_id}\`, ${testCount} test(s) in ${fileParts.join(" + ")}${modeNote}.\n\n` +
+                `Review the test shape + stubs, merge when ready. Merge triggers \`slowcook-brew-auto\`.\n\n` +
+                `---\n*Generated by \`slowcook testgen\`.*`;
+            try {
+                await ctx.forge.createIssueComment(parseInt(src, 10), body);
+            }
+            catch {
+                /* best effort — audit trail is nice-to-have */
+            }
+        }
         return {
             kind: "tests-emitted",
             storyIds,
@@ -177,25 +242,51 @@ function shouldWriteStub(repoRoot, path) {
 function shouldWriteHelper(repoRoot, path) {
     return !existsSync(join(repoRoot, path));
 }
+function handlerTestPathFor(storyId) {
+    return join(TESTS_INTEGRATION_DIR, `story-${storyId}.test.ts`);
+}
+function uiTestPathFor(storyId) {
+    return join(TESTS_INTEGRATION_DIR, `story-${storyId}-ui.test.tsx`);
+}
+function specHasUiBehavior(spec) {
+    return !!spec.ui_behavior && Object.keys(spec.ui_behavior).length > 0;
+}
 function collectTargetSpecs(ctx) {
     const index = readIndex(ctx.repoRoot);
     const all = Object.entries(index.stories)
         .filter(([, entry]) => entry.status === "active")
         .map(([id]) => id);
     const targetIds = ctx.specId ? [ctx.specId] : all;
-    const specs = [];
+    const targets = [];
     for (const id of targetIds) {
-        const testPath = join(ctx.repoRoot, TESTS_INTEGRATION_DIR, `story-${id}.test.ts`);
-        if (existsSync(testPath) && !ctx.specId)
-            continue; // skip specs already tested, unless explicit --spec
+        const handlerTestAbs = join(ctx.repoRoot, handlerTestPathFor(id));
+        const uiTestAbs = join(ctx.repoRoot, uiTestPathFor(id));
+        const handlerExists = existsSync(handlerTestAbs);
+        const uiExists = existsSync(uiTestAbs);
+        let spec;
         try {
-            specs.push(readSpec(ctx.repoRoot, id));
+            spec = readSpec(ctx.repoRoot, id);
         }
         catch {
             // spec file missing despite being in index — skip
+            continue;
         }
+        const hasUi = specHasUiBehavior(spec);
+        const needsHandler = !handlerExists;
+        const needsUi = hasUi && !uiExists;
+        if (!needsHandler && !needsUi) {
+            // Already has everything — skip unless explicit --spec requests it
+            if (!ctx.specId)
+                continue;
+            // With --spec, we still skip if nothing's missing; there's nothing to do.
+            continue;
+        }
+        const mode = needsHandler && needsUi ? "full" :
+            needsHandler ? "handler-only" :
+                "ui-only";
+        targets.push({ spec, mode });
     }
-    return specs;
+    return targets;
 }
 export function buildProjectContext(repoRoot) {
     const bits = [];
@@ -255,6 +346,21 @@ export function buildProjectContext(repoRoot) {
                 bits.push(`- … (${routes.length - 50} more)`);
         }
     }
+    // List existing React components + client-side pages so the LLM knows
+    // NOT to emit a <ui_stub> block for a component that already exists.
+    // Components live at src/components/**; client pages live at
+    // src/app/**/page.tsx (or layout.tsx, though we don't usually brew layouts).
+    const componentsDir = join(repoRoot, "src", "components");
+    const pagesUnderApp = existsSync(appDir) ? listReactComponents(appDir) : [];
+    const libComponents = existsSync(componentsDir) ? listReactComponents(componentsDir) : [];
+    const allComponents = [...libComponents, ...pagesUnderApp].sort();
+    if (allComponents.length > 0) {
+        bits.push(`\n### Existing React component / page files (tsx)\n\nThese already exist — do NOT emit a \`<ui_stub>\` block for any of them. If a UI test imports one of these, assume it's real code and skip stub generation.`);
+        for (const c of allComponents.slice(0, 50))
+            bits.push(`- \`${c}\``);
+        if (allComponents.length > 50)
+            bits.push(`- … (${allComponents.length - 50} more)`);
+    }
     // List existing mock helpers so the LLM knows which to import. The
     // helper pattern is load-bearing for the future record-and-replay swap
     // (plans/0.7-testgen-two-tier.md §4.3). Helpers NOT listed here will
@@ -294,6 +400,45 @@ export function buildProjectContext(repoRoot) {
  * testgen LLM so it doesn't emit a <stub> for a file that already
  * exists.
  */
+/**
+ * Walk a React directory and return every `.tsx` file's repo-relative
+ * path. Used to surface existing components + client pages so testgen
+ * doesn't emit <ui_stub> blocks for files that already have real
+ * implementations.
+ */
+function listReactComponents(dir) {
+    const out = [];
+    const walk = (d) => {
+        let entries;
+        try {
+            entries = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            if (name === "node_modules" || name.startsWith("."))
+                continue;
+            const full = join(d, name);
+            let stat;
+            try {
+                stat = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory())
+                walk(full);
+            else if (stat.isFile() && name.endsWith(".tsx") && !name.endsWith(".test.tsx")) {
+                const srcIdx = full.indexOf("src/");
+                const rel = srcIdx >= 0 ? full.slice(srcIdx) : full;
+                out.push(rel);
+            }
+        }
+    };
+    walk(dir);
+    return out;
+}
 function listAppRouterFiles(appDir) {
     const out = [];
     const walk = (dir) => {
@@ -326,9 +471,15 @@ function listAppRouterFiles(appDir) {
     walk(appDir);
     return out;
 }
-async function generateTestBundle(spec, ctx, projectContext) {
+async function generateTestBundle(spec, ctx, projectContext, mode) {
     const systemPrompt = TESTGEN_SYSTEM(projectContext);
-    const userMessage = `Here is the spec YAML. Generate the tier-1 test bundle (test file + any needed stubs + any needed helpers):\n\n\`\`\`yaml\n${YAML.stringify(spec)}\n\`\`\``;
+    const modeInstruction = {
+        "full": "Generate BOTH the handler tier-1 test bundle (`<test_file>` + any `<stub>` + any `<helper>`) AND the UI tier-1 bundle (`<ui_test_file>` + any `<ui_stub>`). This story has both API and UI scope.",
+        "handler-only": "Generate the handler tier-1 test bundle (`<test_file>` + any `<stub>` + any `<helper>`). This story has no `ui_behavior`, so do NOT emit `<ui_test_file>` or `<ui_stub>` blocks.",
+        "ui-only": "Handler tests already exist for this story. Emit ONLY the UI tier-1 bundle: `<ui_test_file>` + any `<ui_stub>` blocks needed to make the UI tests collect. Do NOT emit `<test_file>`, `<stub>`, or `<helper>` blocks — those artifacts are already on disk and should not be regenerated.",
+    };
+    const userMessage = `${modeInstruction[mode]}\n\n` +
+        `Here is the spec YAML:\n\n\`\`\`yaml\n${YAML.stringify(spec)}\n\`\`\``;
     const raw = await ctx.llm.complete({
         system: systemPrompt,
         cacheSystem: true,
@@ -336,34 +487,46 @@ async function generateTestBundle(spec, ctx, projectContext) {
         messages: [{ role: "user", content: userMessage }],
         maxTokens: 16384,
     });
-    return parseTestgenBundle(raw, spec.story_id);
+    return parseTestgenBundle(raw, spec.story_id, mode);
 }
 /**
  * Parse XML-tagged multi-artifact output into a TestgenBundle.
  *
  * Accepted shape (from the prompt):
- *   <test_file>...</test_file>
- *   <stub path="src/app/api/foo/route.ts">...</stub>   (zero or more)
- *   <helper path="tests/helpers/mocks/bar.ts">...</helper>  (zero or more)
+ *   <test_file>...</test_file>                    — required unless mode="ui-only"
+ *   <stub path="src/app/api/foo/route.ts">...</stub>         (zero or more)
+ *   <helper path="tests/helpers/mocks/bar.ts">...</helper>   (zero or more)
+ *   <ui_test_file>...</ui_test_file>              — required when mode="ui-only" or "full" with UI
+ *   <ui_stub path="src/components/foo.tsx">...</ui_stub>     (zero or more)
+ *
+ * Mode semantics (0.7.7+):
+ * - `"handler-only"` — `<test_file>` required; `<ui_test_file>` ignored if present.
+ * - `"ui-only"` — `<ui_test_file>` required; `<test_file>` ignored if present.
+ * - `"full"` — both `<test_file>` required AND `<ui_test_file>` required.
  *
  * Tolerant of code-fenced output: if the LLM wraps the whole thing in
  * ```, we strip it. If a block's contents are themselves code-fenced,
- * we strip those too — tier-1 test / helper / stub files are raw TS.
- *
- * Throws if `<test_file>` is missing or empty — that's the one mandatory
- * artifact.
+ * we strip those too — tier-1 test / helper / stub / UI files are raw TS/TSX.
  */
-export function parseTestgenBundle(raw, storyId) {
+export function parseTestgenBundle(raw, storyId, mode = "handler-only") {
     const trimmed = raw.trim();
     // Strip outer code fence if the LLM wrapped everything
     const outerFenceMatch = trimmed.match(/^```[a-z]*\s*\n([\s\S]*)\n```$/);
     const body = outerFenceMatch && outerFenceMatch[1] ? outerFenceMatch[1] : trimmed;
+    const handlerRequired = mode !== "ui-only";
+    const uiRequired = mode !== "handler-only";
     const testMatch = body.match(/<test_file>([\s\S]*?)<\/test_file>/);
-    if (!testMatch || !testMatch[1]) {
-        throw new Error(`testgen: LLM output for story-${storyId} missing a <test_file> block. ` +
+    if (handlerRequired && (!testMatch || !testMatch[1])) {
+        throw new Error(`testgen: LLM output for story-${storyId} missing a <test_file> block (mode=${mode}). ` +
             `Got ${body.length} chars starting with: ${body.slice(0, 120)}...`);
     }
-    const testContent = stripInnerFence(testMatch[1]);
+    const testContent = testMatch && testMatch[1] ? stripInnerFence(testMatch[1]) : "";
+    const uiTestMatch = body.match(/<ui_test_file>([\s\S]*?)<\/ui_test_file>/);
+    if (uiRequired && (!uiTestMatch || !uiTestMatch[1])) {
+        throw new Error(`testgen: LLM output for story-${storyId} missing a <ui_test_file> block (mode=${mode}). ` +
+            `Got ${body.length} chars starting with: ${body.slice(0, 120)}...`);
+    }
+    const uiTestContent = uiTestMatch && uiTestMatch[1] ? stripInnerFence(uiTestMatch[1]) : "";
     const stubs = [];
     const stubRe = /<stub\s+path="([^"]+)">([\s\S]*?)<\/stub>/g;
     let m;
@@ -381,7 +544,15 @@ export function parseTestgenBundle(raw, storyId) {
         if (p && c.trim())
             helpers.push({ path: p, contents: stripInnerFence(c) });
     }
-    return { testContent, stubs, helpers };
+    const uiStubs = [];
+    const uiStubRe = /<ui_stub\s+path="([^"]+)">([\s\S]*?)<\/ui_stub>/g;
+    while ((m = uiStubRe.exec(body)) !== null) {
+        const p = m[1] ?? "";
+        const c = m[2] ?? "";
+        if (p && c.trim())
+            uiStubs.push({ path: p, contents: stripInnerFence(c) });
+    }
+    return { testContent, stubs, helpers, uiTestContent, uiStubs };
 }
 function stripInnerFence(raw) {
     const t = raw.trim();
@@ -468,6 +639,24 @@ export function lintTierOneTest(filePath, source) {
  * Robust against typical usage; falls back to a single synthetic entry if
  * nothing recognisable is found.
  */
+/**
+ * Read an existing test file from disk and extract its test IDs. Thin
+ * wrapper around extractTestIdsFromFile for the "ui-only" code path where
+ * the handler test already exists and we need its IDs to preserve in the
+ * rewritten combined manifest.
+ */
+export function extractTestIdsFromExistingFile(repoRoot, filePath) {
+    const abs = join(repoRoot, filePath);
+    if (!existsSync(abs))
+        return [];
+    try {
+        const source = readFileSync(abs, "utf8");
+        return extractTestIdsFromFile(filePath, source);
+    }
+    catch {
+        return [];
+    }
+}
 export function extractTestIdsFromFile(filePath, source) {
     // Strip comments and blank string-literal contents so commented-out or
     // string-embedded `describe`/`it` don't register. Offsets are preserved
@@ -612,7 +801,22 @@ function buildPrBody(args) {
     sections.push("## Tests added");
     for (const g of args.generated) {
         const manifestCount = g.manifest.tests.length;
-        sections.push(`- \`story-${g.spec.story_id}\` — *${g.spec.title}* — ${manifestCount} test(s) in \`${g.testPath}\``);
+        const parts = [];
+        if (g.testPath)
+            parts.push(`\`${g.testPath}\``);
+        if (g.uiTestPath)
+            parts.push(`\`${g.uiTestPath}\``);
+        const modeTag = g.mode === "ui-only" ? " *(ui-only mode — handler tests already present)*" : g.mode === "full" ? " *(handler + UI)*" : "";
+        sections.push(`- \`story-${g.spec.story_id}\` — *${g.spec.title}* — ${manifestCount} test(s) in ${parts.join(" + ")}${modeTag}`);
+    }
+    const allUiStubs = args.generated.flatMap((g) => g.uiStubs);
+    if (allUiStubs.length > 0) {
+        sections.push("");
+        sections.push("## Generated UI stubs (React components / pages)");
+        sections.push("Minimal placeholder components so tier-1 UI tests can collect. Each carries an \`@slowcook-stub\` marker on line 1. **Brewing will replace these bodies** with the real component implementation. Reviewer check: correct file path + default export present + \`@slowcook-stub\` marker intact. Signature-wrong = PR-wrong — flag it now.");
+        for (const s of allUiStubs) {
+            sections.push(`- \`${s.path}\``);
+        }
     }
     const allStubs = args.generated.flatMap((g) => g.stubs);
     if (allStubs.length > 0) {