@aussieljk/forkbook 0.0.0-stage → 0.0.1-2

package/dist/_node-chunks/chunk-CCOTJ4FC.js

@@ -0,0 +1,688 @@
+import CJS_COMPAT_NODE_URL_ro17f80mg6k from 'node:url';
+import CJS_COMPAT_NODE_PATH_ro17f80mg6k from 'node:path';
+import CJS_COMPAT_NODE_MODULE_ro17f80mg6k from "node:module";
+
+var __filename = CJS_COMPAT_NODE_URL_ro17f80mg6k.fileURLToPath(import.meta.url);
+var __dirname = CJS_COMPAT_NODE_PATH_ro17f80mg6k.dirname(__filename);
+var require = CJS_COMPAT_NODE_MODULE_ro17f80mg6k.createRequire(import.meta.url);
+
+// ------------------------------------------------------------
+// end of CJS compatibility banner, injected by Forkbook's esbuild configuration
+// ------------------------------------------------------------
+import {
+  getTypeImportSource
+} from "./chunk-6YKBRP72.js";
+import {
+  frameworkToRendererMap
+} from "./chunk-B5J7Q7J4.js";
+
+// src/cli/skills/content/setup-utils/is-react-project.ts
+function isReactProject(projectInfo) {
+  return (projectInfo.rendererPackage ?? (projectInfo.framework ? frameworkToRendererMap[projectInfo.framework] : void 0)) === "@aussieljk/forkbook/react";
+}
+
+// src/cli/skills/content/setup-utils/ext.ts
+function ext(language, jsx) {
+  return language === "ts" ? jsx ? "tsx" : "ts" : jsx ? "jsx" : "js";
+}
+
+// src/cli/skills/content/setup-utils/markdown.ts
+import { dedent } from "ts-dedent";
+function listRules(rules) {
+  return dedent`
+    ${rules.filter(Boolean).map((s, i) => `${i + 1}. ${s}`).join(`
+`)}
+  `;
+}
+function listSteps(steps, options) {
+  let level = options?.level ?? 2, prefix = "#".repeat(level);
+  return dedent`
+    ${steps.filter(Boolean).map((step, i) => `${prefix} Step ${i + 1} \u2014 ${step.title}
+
+${step.body}`).join(`
+
+`)}
+  `;
+}
+function listDOD(dods) {
+  return dedent`
+    ${dods.filter(Boolean).map((s) => `- ${s}`).join(`
+`)}
+  `;
+}
+
+// src/cli/skills/content/setup-prompts/partials/dod.ts
+import { getVitestStorybookRunCommand } from "@aussieljk/forkbook/internal/common";
+import { dedent as dedent2 } from "ts-dedent";
+function cssCheckDOD(ctx) {
+  return dedent2`**Exactly one \`CssCheck\` story exists** somewhere in the new stories, asserting a concrete computed style value read from the component's source.`;
+}
+function storyTagsV1DOD(ctx) {
+  return dedent2`Every story file you wrote that vitest confirmed passing has had \`'needs-work'\` stripped, leaving \`tags: ['ai-generated']\`. Anything still failing keeps \`['ai-generated', 'needs-work']\`.`;
+}
+function storyTagsV2DOD(ctx) {
+  return dedent2`Every story file that passes vitest tests has had \`'needs-work'\` stripped, leaving \`tags: ['ai-generated']\`. Story files with vitest failures keep \`['ai-generated', 'needs-work']\`.`;
+}
+function vitestPassesStrictDOD({ packageManager }) {
+  return dedent2`\`${getVitestStorybookRunCommand(packageManager)}\` passes for the new files.`;
+}
+function vitestPassesWhenExpectedDOD({ packageManager }) {
+  return dedent2`\`${getVitestStorybookRunCommand(packageManager)}\` passes for the new files that don't have \`'needs-work'\` in their tags. Files with \`'needs-work'\` may still fail.`;
+}
+function typeCheckPassesStrictDOD(ctx) {
+  return dedent2`The project's TypeScript check passes for changed files.`;
+}
+function typeCheckPassesWhenExpectedDOD(ctx) {
+  return dedent2`The project's TypeScript check passes for the new files that don't have \`'needs-work'\` in their tags. Files with \`'needs-work'\` may still fail.`;
+}
+function sharedPreviewDOD(ctx) {
+  return dedent2`The shared preview is strong enough that stories don't need per-story fetch/provider workarounds.`;
+}
+function optionalTestInfrastructureDOD(_ctx) {
+  return dedent2`MSW was added only if at least one selected story makes network requests, and MockDate only if at least one selected story depends on the current date or time. Each dependency you added is exercised by at least one verified story. Existing MSW or MockDate setup in the project is left in place.`;
+}
+
+// src/cli/skills/content/setup-prompts/partials/rules.ts
+import { PackageManagerName } from "@aussieljk/forkbook/internal/common";
+import { dedent as dedent3 } from "ts-dedent";
+function nodeModuleReadsRule(ctx) {
+  return dedent3`**Never read or grep inside \`node_modules\`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not \`node_modules\`.`;
+}
+function monorepoRule({
+  monorepoType
+}) {
+  if (monorepoType)
+    return `**${monorepoType} monorepo.** Don't initially look for config or existing Forkbook content in other packages. Start exploring from config and tooling local to the package where you are asked to set up Forkbook. If it uses local monorepo dependencies, build all dependencies found during discovery before writing stories or running tests.`;
+}
+function packageManagerRule({
+  packageManager,
+  packageManagerName
+}) {
+  let storybookCmd = packageManager.getPackageCommand(["forkbook"]);
+  return packageManager.type === PackageManagerName.NPM ? dedent3`**Use \`npm\` for installs and \`${storybookCmd}\` for Forkbook/Vitest CLI commands** (detected from this project's lockfile).` : packageManagerName ? dedent3`**Use \`${packageManagerName}\` for installs and \`${storybookCmd}\` for Forkbook/Vitest CLI commands** (detected from this project's lockfile). Do not use \`npx\` — it invokes npm and fails when the repo enforces a different package manager.` : dedent3`**Detect the package manager once** from the lockfile (\`pnpm-lock.yaml\` → pnpm, \`yarn.lock\` → yarn, \`bun.lockb\` → bun, otherwise npm) and use it for every install and CLI command in this trial. Do not use \`npx\` when the project uses pnpm, yarn, or bun.`;
+}
+function editOverWriteRule({ configDir, tsx }) {
+  return dedent3`**Edit > Write.** For any file you've Read, use \`Edit\`. Use \`Write\` only for new files. The project already has a \`${configDir}/preview.${tsx}\` from \`forkbook init\` — **Edit** it, do not overwrite.`;
+}
+function keepUserWorkRule(ctx) {
+  return dedent3`**Keep the user's work.** Never delete, move, or rewrite the stories, components, or config that existed before you started; add to them instead. The only exception is the \`forkbook init\` examples described in the clean-up step.`;
+}
+function batchTestsRule(ctx) {
+  return dedent3`**Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.`;
+}
+function readBudgetRule(ctx) {
+  return dedent3`**Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (\`index.html\`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.`;
+}
+function readBudgetRuleRelaxed(ctx) {
+  return dedent3`**Read budget: ~40 files for discovery.** Before writing any code you may Read at most ~40 files: \`index.html\`, entry, App, providers, routing, root CSS, 1–2 hooks, 1 test, and spend the rest on components. You may read direct component dependencies essential to their understanding only after having read 20 components (or all components if fewer in the codebase).`;
+}
+function preferSharedFixesRule({
+  configDir,
+  tsx
+}) {
+  return dedent3`**Prefer fixing the shared \`${configDir}/preview.${tsx}\`** over story-local workarounds when multiple stories fail the same way.`;
+}
+function noPolishRule(ctx) {
+  return dedent3`**Stop when the success criteria are met** — don't keep polishing.`;
+}
+
+// src/cli/skills/content/setup-prompts/partials/steps.ts
+import {
+  getMswInitCommand,
+  getVitestStorybookRunCommand as getVitestStorybookRunCommand2
+} from "@aussieljk/forkbook/internal/common";
+import { dedent as dedent5 } from "ts-dedent";
+
+// src/cli/skills/content/setup-prompts/partials/examples.ts
+import { dedent as dedent4 } from "ts-dedent";
+function getPreviewExample(projectInfo) {
+  let { configDir, language, hasCsfFactoryPreview } = projectInfo, tsx = ext(language, isReactProject(projectInfo)), typeImport = getTypeImportSource(projectInfo), providerImport = isReactProject(projectInfo) ? "import { SessionProvider } from '../src/contexts/SessionContext';" : "", decorators = isReactProject(projectInfo) ? dedent4`
+        decorators: [
+          (Story) => (
+            <SessionProvider>
+              <Story />
+            </SessionProvider>
+          ),
+        ],
+      ` : "";
+  return hasCsfFactoryPreview ? dedent4`
+      \`\`\`${tsx}
+      // ${configDir}/preview.${tsx}
+      import { definePreview } from '${typeImport}';
+      import '../src/index.css';
+      // Only include MockDate when selected stories depend on the current date or time.
+      import MockDate from 'mockdate';
+      // Only include MSW when selected stories make network requests.
+      import addonMsw from 'msw-storybook-addon';
+      ${providerImport}
+      import { mswHandlers } from './msw-handlers';
+
+      export default definePreview({
+        addons: [addonMsw()],
+        ${decorators}
+        async beforeEach({ msw }) {
+          msw.use(...mswHandlers);
+          localStorage.setItem('theme', 'dark');
+          MockDate.set('2024-04-01T12:00:00Z');
+        },
+      });
+      \`\`\`
+    ` : language === "js" ? dedent4`
+      \`\`\`${tsx}
+      // ${configDir}/preview.${tsx}
+      import '../src/index.css';
+      // Only include MockDate when selected stories depend on the current date or time.
+      import MockDate from 'mockdate';
+      // Only include MSW when selected stories make network requests.
+      import { mswLoader } from 'msw-storybook-addon/csf3';
+      ${providerImport}
+      import { mswHandlers } from './msw-handlers';
+
+      const preview = {
+        ${decorators}
+        loaders: [mswLoader()],
+        async beforeEach({ msw }) {
+          msw.use(...mswHandlers);
+          localStorage.setItem('theme', 'dark');
+          MockDate.set('2024-04-01T12:00:00Z');
+        },
+      };
+
+      export default preview;
+      \`\`\`
+    ` : dedent4`
+    \`\`\`${tsx}
+    // ${configDir}/preview.${tsx}
+    import type { Preview } from '${typeImport}';
+    import '../src/index.css';
+    // Only include MockDate when selected stories depend on the current date or time.
+    import MockDate from 'mockdate';
+    // Only include MSW when selected stories make network requests.
+    import { mswLoader } from 'msw-storybook-addon/csf3';
+    ${providerImport}
+    import { mswHandlers } from './msw-handlers';
+
+    const preview: Preview = {
+      ${decorators}
+      loaders: [mswLoader()],
+      async beforeEach({ msw }) {
+        msw.use(...mswHandlers);
+        localStorage.setItem('theme', 'dark');
+        MockDate.set('2024-04-01T12:00:00Z');
+      },
+    };
+
+    export default preview;
+    \`\`\`
+  `;
+}
+function getPortalDecoratorExample(projectInfo) {
+  let { language } = projectInfo, tsx = ext(language, isReactProject(projectInfo));
+  return dedent4`
+    \`\`\`${tsx}
+    // Add this entry to the \`decorators\` array of your preview config:
+    (Story) => {
+      for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
+        if (!document.getElementById(id)) {
+          const el = document.createElement('div');
+          el.id = id;
+          document.body.appendChild(el);
+        }
+      }
+      return ${isReactProject(projectInfo) ? "<Story />" : "Story()"};
+    }
+    \`\`\`
+  `;
+}
+function getMainConfigExample(projectInfo) {
+  let { configDir, language } = projectInfo, ts = ext(language, !1), typeImport = getTypeImportSource(projectInfo);
+  return language === "js" ? dedent4`
+      \`\`\`js
+      // ${configDir}/main.js
+      const config = { staticDirs: ['../public'] };
+      export default config;
+      \`\`\`
+    ` : dedent4`
+    \`\`\`${ts}
+    // ${configDir}/main.${ts}
+    import type { StorybookConfig } from '${typeImport}';
+
+    const config: StorybookConfig = { staticDirs: ['../public'] };
+    export default config;
+    \`\`\`
+  `;
+}
+function getStoryExample(projectInfo) {
+  if (!isReactProject(projectInfo))
+    return dedent4`
+      Follow existing stories and the installed framework's Component Story Format. Import the real component using the project's conventions and use its actual props or inputs as \`args\`. Use the framework's rendering syntax for composition, projected content, slots, and event bindings when needed.
+
+      For TypeScript, import \`Meta\` and \`StoryObj\` from '${getTypeImportSource(projectInfo)}' and use the type parameters supported by that framework. Add \`tags: ['ai-generated', 'needs-work']\` to the meta, then export story objects for the component's meaningful states. Include a \`play\` function only when it verifies behavior.
+    `;
+  let { language } = projectInfo, tsx = ext(language, isReactProject(projectInfo)), typeImport = getTypeImportSource(projectInfo);
+  return language === "js" ? dedent4`
+      \`\`\`${tsx}
+      import { expect } from '@aussieljk/forkbook/test';
+      import { Button } from './Button';
+
+      const meta = {
+        component: Button,
+        tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+      };
+
+      export default meta;
+
+      // Smoke check — one is enough per file
+      export const Primary = {
+        args: { children: 'Order now' },
+        play: async ({ canvas }) => {
+          await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+        },
+      };
+
+      // Variant-only stories: no play needed
+      export const Clear = { args: { children: 'Cancel', clear: true } };
+      export const Large = { args: { children: 'Checkout', large: true } };
+      export const WithIcon = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+      \`\`\`
+    ` : dedent4`
+    \`\`\`${tsx}
+    import type { Meta, StoryObj } from '${typeImport}';
+    import { expect } from '@aussieljk/forkbook/test';
+    import { Button } from './Button';
+
+    const meta = {
+      component: Button,
+      tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+    } satisfies Meta<typeof Button>;
+
+    export default meta;
+    type Story = StoryObj<typeof meta>;
+
+    // Smoke check — one is enough per file
+    export const Primary: Story = {
+      args: { children: 'Order now' },
+      play: async ({ canvas }) => {
+        await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+      },
+    };
+
+    // Variant-only stories: no play needed
+    export const Clear: Story = { args: { children: 'Cancel', clear: true } };
+    export const Large: Story = { args: { children: 'Checkout', large: true } };
+    export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+    \`\`\`
+  `;
+}
+function getInteractionPlayExample(projectInfo) {
+  let { language } = projectInfo, tsx = ext(language, isReactProject(projectInfo));
+  return dedent4`
+    \`\`\`${tsx}
+    export const FilledForm${language === "ts" ? ": Story" : ""} = {
+      play: async ({ canvas, userEvent }) => {
+        await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
+        await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
+        await expect(await canvas.findByText(/welcome/i)).toBeVisible();
+      },
+    };
+    \`\`\`
+  `;
+}
+
+// src/cli/skills/content/setup-prompts/partials/steps.ts
+function discoveryStepStrict(projectInfo, { tsx }) {
+  let isReact = isReactProject(projectInfo);
+  return {
+    title: "Discover the runtime (\u226412 reads)",
+    body: dedent5`
+      Identify, in this order:
+
+    - \`index.html\` — \`<link rel="stylesheet">\` tags, inline \`<style>\` blocks, fonts, and any \`<div id="...">\` mount or portal roots that aren't created by JS
+    - ${isReact ? `entry file (\`main.${tsx}\` / \`index.${tsx}\`) \u2014 providers wrapping \`<App />\`, root CSS imports` : "application entry file \u2014 framework initialization, shared services or providers, root CSS imports"}
+    - ${isReact ? `\`App.${tsx}\` \u2014 top-level layout, router usage, providers it consumes` : "root component \u2014 top-level layout, router usage, shared state and services it consumes"}
+    - ${isReact ? "providers / context files \u2014 what they expose" : "shared state / service configuration \u2014 what it exposes"}
+    - root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from \`index.html\`)
+    - ${isReact ? "data hooks \u2014 `fetch(...)`, `useQuery`, `axios`, etc." : "data fetching \u2014 network clients, services, and query utilities"} (capture base URL + endpoints actually called during render)
+    - browser state actually read at render — \`localStorage\`/\`sessionStorage\`/cookie keys
+    - portal targets — ${isReact ? "`createPortal(...)` and the DOM ids it mounts to" : "content rendered outside the component root and the DOM ids it targets"} (e.g. \`#modal-root\`)
+    - 1–2 real page or feature components (your story source-of-truth for ${isReact ? "JSX" : "component usage"} patterns)
+
+    Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
+  `
+  };
+}
+function discoveryStepRelaxed(projectInfo, { tsx }) {
+  let isReact = isReactProject(projectInfo);
+  return {
+    title: "Discover the runtime (\u226440 reads)",
+    body: dedent5`
+      Identify, in this order:
+
+    - \`index.html\` — \`<link rel="stylesheet">\` tags, inline \`<style>\` blocks, fonts, and any \`<div id="...">\` mount or portal roots that aren't created by JS
+    - ${isReact ? `entry file (\`main.${tsx}\` / \`index.${tsx}\`) \u2014 providers wrapping \`<App />\`, root CSS imports` : "application entry file \u2014 framework initialization, shared services or providers, root CSS imports"}
+    - ${isReact ? `\`App.${tsx}\` \u2014 top-level layout, router usage, providers it consumes` : "root component \u2014 top-level layout, router usage, shared state and services it consumes"}
+    - ${isReact ? "providers / context files \u2014 what they expose" : "shared state / service configuration \u2014 what it exposes"}
+    - root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from \`index.html\`)
+    - ${isReact ? "data hooks \u2014 `fetch(...)`, `useQuery`, `axios`, etc." : "data fetching \u2014 network clients, services, and query utilities"} (capture base URL + endpoints actually called during render)
+    - browser state actually read at render — \`localStorage\`/\`sessionStorage\`/cookie keys
+    - portal targets — ${isReact ? "`createPortal(...)` and the DOM ids it mounts to" : "content rendered outside the component root and the DOM ids it targets"} (e.g. \`#modal-root\`)
+    - 1–20 real page or feature components (your story source-of-truth for ${isReact ? "JSX" : "component usage"} patterns)
+
+    Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render? What surrounding context do components need to render?"*
+  `
+  };
+}
+function missingVitestAddonNote({ addons }, packageManager) {
+  return addons.includes("@aussieljk/forkbook/addon-vitest") ? "" : `This project doesn't have \`@aussieljk/forkbook/addon-vitest\` yet, which runs stories as tests. Add it first with \`${packageManager.getPackageCommand([
+    "forkbook",
+    "add",
+    "@aussieljk/forkbook/addon-vitest",
+    "--yes"
+  ])}\`; the steps below need it.
+
+`;
+}
+function verifyStep(projectInfo, { packageManager, tsx }) {
+  let vitestRunAll = getVitestStorybookRunCommand2(packageManager), vitestRunFile = getVitestStorybookRunCommand2(packageManager, `path/to/Foo.stories.${tsx}`);
+  return {
+    title: "Verify in one batch, then iterate only on failures",
+    body: missingVitestAddonNote(projectInfo, packageManager) + dedent5`**Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
+
+    \`\`\`bash
+    ${vitestRunAll}
+    \`\`\`
+
+    Then run the project's TypeScript check (use the script from \`package.json\` — typically \`tsc --noEmit\` or \`${packageManager.getRunCommand("typecheck")}\`). Read the raw output once; don't pipe it through repeated \`grep\`/\`head\` invocations to slice it.
+
+    For each failure:
+
+    1. Read the error.
+    2. If multiple stories share the failure, fix the shared preview setup, not the stories.
+    3. Re-run vitest **only for the affected file(s)**: \`${vitestRunFile}\`.
+    4. Repeat until the file passes, then move on. Cap retries at ~5 per file — if it still fails, leave \`'needs-work'\` tag to inform the user.
+    5. When you keep failing on a story, play function, etc., do not substitute it for easier content that contributes less to codebase understanding.
+
+    **After a file passes**, edit its meta and remove \`'needs-work'\` so its tags become \`['ai-generated']\`. Files you couldn't fix keep \`['ai-generated', 'needs-work']\` — move on, don't loop forever.`
+  };
+}
+function verifyWithAllowedFailureStep(projectInfo, { packageManager, tsx }) {
+  let vitestRunAll = getVitestStorybookRunCommand2(packageManager), vitestRunFile = getVitestStorybookRunCommand2(packageManager, `path/to/Foo.stories.${tsx}`);
+  return {
+    title: "Verify in one batch, then iterate only on failures",
+    body: missingVitestAddonNote(projectInfo, packageManager) + dedent5`**Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
+
+    \`\`\`bash
+    ${vitestRunAll}
+    \`\`\`
+
+    Then run the project's TypeScript check (use the script from \`package.json\` — typically \`tsc --noEmit\` or \`${packageManager.getRunCommand("typecheck")}\`). Read the raw output once; don't pipe it through repeated \`grep\`/\`head\` invocations to slice it.
+
+    For each failure:
+
+    1. Read the error.
+    2. If multiple stories share the failure, fix the shared preview setup, not the stories.
+    3. In subsequent runs, re-run Vitest **only for the affected file(s)**: \`${vitestRunFile}\`.
+    4. Fix any TypeScript issues needed for story files to pass, then re-run TS and Vitest only for those files. Repeat until files pass, or until you have tried 5 times.
+    5. If a story file still fails after those retries, leave the file tagged \`'needs-work'\` and move on — do not keep chasing project-wide TS errors caused by preserved \`'needs-work'\` files.
+    6. When you keep failing on a story, play function, etc., do not substitute it for easier content that contributes less to codebase understanding.
+    **After a file passes**, edit its meta and remove \`'needs-work'\` so its tags become \`['ai-generated']\`. Files you couldn't fix keep \`['ai-generated', 'needs-work']\` — move on, don't loop forever.`
+  };
+}
+function cleanupStep() {
+  return {
+    title: "Clean up",
+    body: "Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts. If you managed to write successful stories, delete the examples that `forkbook init` generated (a `stories/` folder with `Configure.mdx` next to `Button`, `Header`, and `Page`). Don't delete any other stories."
+  };
+}
+function monorepoStep(projectInfo, ctx) {
+  return {
+    title: "Monorepo preparation",
+    body: dedent5`Build any local monorepo dependencies identified during discovery, and keep track of existing errors in the codebase unrelated to the package changes you'll make.`
+  };
+}
+function buildSharedPreviewStep(projectInfo, { configDir, tsx }) {
+  let isReact = isReactProject(projectInfo);
+  return {
+    title: "Build the shared preview",
+    body: dedent5`    Set up Forkbook **once** so most stories work without per-story setup. **Edit the existing \`${configDir}/preview.${tsx}\`** (created by \`forkbook init\`) — add to its existing config object, don't replace it. Add MSW only if a selected story makes network requests. Add MockDate only if a selected story's rendered output depends on the current date or time. Omit their imports and hooks otherwise.
+
+    The example below shows both optional paths. Merge only the pieces the selected stories need into what's already there:
+
+    ${getPreviewExample(projectInfo)}
+
+    Rules for the preview:
+
+    - ${isReact ? "Use the **real** provider tree and the **real** root CSS import. Don't invent providers." : "Use the **real** application setup and the **real** root CSS import. Configure shared services, plugins, routing, and state using the installed framework's setup APIs. Don't invent providers."}
+    - If the app's CSS is loaded via \`<link>\` in \`index.html\` (rather than imported in JS), import the same file from preview so stories render with the same styles.
+    - Seed only the specific browser-state keys the app actually reads. Do **not** clear all of \`localStorage\`/\`sessionStorage\`/cookies, and do not reset Forkbook's own state.
+    - Use \`mockdate\` only when render output depends on the date.
+    - Do not mock \`window\`, \`document\`, \`navigator\`, observers, or \`fetch\` directly.
+    `
+  };
+}
+function buildPortalStep(projectInfo, { configDir, tsx }) {
+  let isReact = isReactProject(projectInfo);
+  return {
+    title: "Portals (in a decorator, not `preview-body.html`)",
+    body: dedent5`If you found ${isReact ? "`createPortal(..., document.getElementById('foo'))`" : "content rendered into a separate DOM target"} in discovery, **add a decorator in \`${configDir}/preview.${tsx}\` that creates the portal root** before the story renders. Do not use \`preview-body.html\`.
+
+    ${getPortalDecoratorExample(projectInfo)}
+
+    Add this decorator to the \`decorators\` array of your preview config. Skip this step entirely if portals only target \`document.body\`.`
+  };
+}
+function mswStep(projectInfo, { configDir, mockDateInstall, mswInstall, packageManager, ts }) {
+  let mswInit = getMswInitCommand(packageManager), mswAddonAdd = packageManager.getPackageCommand([
+    "forkbook",
+    "add",
+    "msw-storybook-addon@3"
+  ]), csfNextNote = projectInfo.hasCsfFactoryPreview ? "\n\n    If `forkbook add` injects `import * as mswStorybookAddon from 'msw-storybook-addon/preview'` and a `mswStorybookAddon` entry into your `definePreview` `addons`, remove both \u2014 that form breaks TypeScript inference for the entire preview. Register the addon with `addonMsw()` as shown below instead.\n" : "";
+  return {
+    title: "Add only the test infrastructure the selected stories need",
+    body: `If a selected story makes network requests during rendering or interaction, register \`msw-storybook-addon\` with \`forkbook add\` (which also adds it to the \`addons\` field of \`${configDir}/main.${ts}\`), install MSW, and generate the worker script:
+
+    \`\`\`bash
+    ${mswAddonAdd}
+    ${mswInstall}
+    ${mswInit}
+    \`\`\`
+${csfNextNote}
+    Make sure \`${configDir}/main.${ts}\` serves \`./public\`:
+
+    ${getMainConfigExample(projectInfo)}
+
+    Put handlers in \`${configDir}/msw-handlers.${ts}\`. Cover only the endpoints your stories will exercise \u2014 no catch-alls.
+
+    \`\`\`${ts}
+    // ${configDir}/msw-handlers.${ts}
+    import { http, HttpResponse } from 'msw';
+
+    export const mswHandlers = [
+      http.get('https://api.example.com/products', () =>
+        HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
+      ),
+    ];
+    \`\`\`
+
+    If a selected story's rendered output depends on the current date or time, install MockDate and configure it in \`beforeEach\`:
+
+    \`\`\`bash
+    ${mockDateInstall}
+    \`\`\`
+
+    If neither condition applies, skip this step. Do not create an empty MSW handler file or install unused dependencies.
+`
+  };
+}
+function writeStoriesStep(projectInfo, { tsx }) {
+  let isReact = isReactProject(projectInfo);
+  return {
+    title: "Write up to 10 story files (in one batch)",
+    body: dedent5`
+
+    This step has **two required deliverables**:
+
+    a. Up to 10 colocated \`*.stories.${tsx}\` files for meaningful targets in the codebase.
+    b. **Exactly one \`CssCheck\` story** added to one of those files (spec below). This step is not complete without it.
+
+    **Substep a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and \`App\` itself when real page components exist.
+
+    Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy ${isReact ? "JSX" : "component usage"} patterns from real pages/routes/tests. If a component already has a story file, add your stories to that file instead of writing a second one.
+
+    **Tag every new story file with \`['ai-generated', 'needs-work']\` from the start.** You will remove \`'needs-work'\` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
+
+    ${getStoryExample(projectInfo)}
+
+    Story rules:
+
+    - Start every meta with \`tags: ['ai-generated', 'needs-work']\`.
+    - Show all imports explicitly.
+    - Don't add a custom \`title\`.
+    - Don't build large story-specific harnesses — fix preview instead.
+    - Don't create new app components.
+
+    **Substep b — add the single \`CssCheck\` story.** Before you finish this step, pick **one** visually distinctive component from the files you just wrote and add a \`CssCheck\` export to that file. Exactly **one** \`CssCheck\` across the whole project — not one per file. This step is not complete until the story exists.
+
+    Why it's mandatory: \`toBeVisible\` passes on an unstyled component. A concrete \`getComputedStyle\` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
+
+    How: read a real styling value from the component's source (e.g. a hex color in ${isReact ? "styled-components" : "a stylesheet"}, a Tailwind class like \`bg-blue-600\`, a CSS variable from the theme), and assert the resolved \`getComputedStyle\` value:
+
+    \`\`\`${tsx}
+    export const CssCheck${projectInfo.language === "ts" ? ": Story" : ""} = {
+      ${isReact ? "args: { children: 'Submit' }," : "...Primary,"}
+      play: async ({ canvas }) => {
+        const button = canvas.getByRole('button'${isReact ? ", { name: /submit/i }" : ""});
+        // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
+        await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
+      },
+    };
+    \`\`\`
+    `
+  };
+}
+function writeStoriesWithAllowedFailuresStep(projectInfo, { tsx }) {
+  let isReact = isReactProject(projectInfo);
+  return {
+    title: "Write up to 10 story files (in one batch)",
+    body: dedent5`
+
+    This step has **two required deliverables**:
+
+    a. Up to 10 colocated \`*.stories.${tsx}\` files for meaningful targets in the codebase.
+    b. **Exactly one \`CssCheck\` story** added to one of those files (spec below). This step is not complete without it.
+
+    **Substep a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and \`App\` itself when real page components exist.
+
+    Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy ${isReact ? "JSX" : "component usage"} patterns from real pages/routes/tests. If a component already has a story file, add your stories to that file instead of writing a second one.
+
+    **Tag every new story file with \`['ai-generated', 'needs-work']\` from the start.** You will remove \`'needs-work'\` only after vitest confirms the file passes, and you will leave the tag if the file is not fully functional at the end of your self-healing loop.
+
+    ${getStoryExample(projectInfo)}
+
+    Story rules:
+
+    - Start every meta with \`tags: ['ai-generated', 'needs-work']\`.
+    - Show all imports explicitly.
+    - Don't add a custom \`title\`.
+    - Don't build large story-specific harnesses — fix preview instead.
+    - Don't create new app components.
+
+    **Substep b — add the single \`CssCheck\` story.** Before you finish this step, pick **one** visually distinctive component from the files you just wrote and add a \`CssCheck\` export to that file. Exactly **one** \`CssCheck\` across the whole project — not one per file. This step is not complete until the story exists.
+
+    Why it's mandatory: \`toBeVisible\` passes on an unstyled component. A concrete \`getComputedStyle\` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
+
+    How: read a real styling value from the component's source (e.g. a hex color in ${isReact ? "styled-components" : "a stylesheet"}, a Tailwind class like \`bg-blue-600\`, a CSS variable from the theme), and assert the resolved \`getComputedStyle\` value:
+
+    \`\`\`${tsx}
+    export const CssCheck${projectInfo.language === "ts" ? ": Story" : ""} = {
+      ${isReact ? "args: { children: 'Submit' }," : "...Primary,"}
+      play: async ({ canvas }) => {
+        const button = canvas.getByRole('button'${isReact ? ", { name: /submit/i }" : ""});
+        // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
+        await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
+      },
+    };
+    \`\`\`
+    `
+  };
+}
+function interactionPlayStep(projectInfo, { tsx }) {
+  return {
+    title: "Add `play` functions only where they prove something non-trivial",
+    body: dedent5`
+    **Do not put a \`play\` on every story.** A \`play\` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good \`play\` per file over five redundant ones.
+
+    Write a \`play\` when it can verify:
+
+    - an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
+    - **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
+    - a **portal** rendered into the right root (query via \`canvasElement.ownerDocument\`)
+    - a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
+    - **accessibility** that the component is responsible for (correct role/label exposure)
+
+    **Skip \`play\` entirely** when a story is just a static variant of the same component (different \`args\`, no new behavior). Repeating \`getByRole(...).toBeVisible()\` across \`Clear\`, \`Large\`, \`WithIcon\` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
+
+    **Smoke plays must prove something the render alone doesn't.** A play that does only \`await expect(canvas.getByRole('button')).toBeVisible()\` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
+
+    - an **aria attribute reflecting state** (\`aria-expanded\`, \`aria-disabled\`, \`aria-checked\`, \`aria-current\`)
+    - a **prop value rendered as text or attribute** (e.g. \`args.label\` appears in the DOM, \`href\` matches \`args.to\`)
+    - **async content arriving** (\`findBy*\`, \`waitFor\` — proves the loader/MSW handler actually resolved)
+    - a **portal mounting in the right root** (queried via \`canvasElement.ownerDocument.body\`)
+
+    If none of those apply, skip the \`play\` and rely on the render itself.
+
+    Concretely, in a \`Button.stories.${tsx}\` with \`Primary\`, \`Clear\`, \`Large\`, \`WithIcon\`:
+
+    - \`Primary\` — keep one smoke \`play\` (one is enough for the file).
+    - \`Clear\`, \`Large\`, \`WithIcon\` — **no \`play\`**. They're variant-only stories.
+
+    (The single \`CssCheck\` story for the whole project was added in Step 5 — don't add another one here.)
+
+    Imports & play context — get this right or vitest will fail in subtle ways:
+
+    - \`expect\` and \`waitFor\` come from \`'@aussieljk/forkbook/test'\` — import those.
+    - \`canvas\`, \`userEvent\`, and \`canvasElement\` come from the **play arguments**: \`async ({ canvas, userEvent, canvasElement }) => { ... }\`. **Do not** \`import { userEvent } from '@aussieljk/forkbook/test'\` and **do not** write \`const canvas = within(canvasElement)\` — both are already provided.
+    - For **portal queries only**, query via \`canvasElement.ownerDocument.body\`. You may import \`within\` from \`'@aussieljk/forkbook/test'\` for that case (e.g. \`within(canvasElement.ownerDocument.body).findByTestId(...)\`). Don't use \`within\` for anything else.
+
+    ${getInteractionPlayExample(projectInfo)}`
+  };
+}
+
+export {
+  isReactProject,
+  ext,
+  listRules,
+  listSteps,
+  listDOD,
+  cssCheckDOD,
+  storyTagsV1DOD,
+  storyTagsV2DOD,
+  vitestPassesStrictDOD,
+  vitestPassesWhenExpectedDOD,
+  typeCheckPassesStrictDOD,
+  typeCheckPassesWhenExpectedDOD,
+  sharedPreviewDOD,
+  optionalTestInfrastructureDOD,
+  nodeModuleReadsRule,
+  monorepoRule,
+  packageManagerRule,
+  editOverWriteRule,
+  keepUserWorkRule,
+  batchTestsRule,
+  readBudgetRule,
+  readBudgetRuleRelaxed,
+  preferSharedFixesRule,
+  noPolishRule,
+  discoveryStepStrict,
+  discoveryStepRelaxed,
+  verifyStep,
+  verifyWithAllowedFailureStep,
+  cleanupStep,
+  monorepoStep,
+  buildSharedPreviewStep,
+  buildPortalStep,
+  mswStep,
+  writeStoriesStep,
+  writeStoriesWithAllowedFailuresStep,
+  interactionPlayStep
+};