forgebook 0.1.8 → 0.2.0

package/dist/bin/forgebook/forgebook.mjs

@@ -1,307 +1,23 @@
 #!/usr/bin/env node
 /**
- * The `forgebook` command: runs a catalogue from its `forgebook.config.ts` (`dev`, the dev server) or builds it into
- * static files (`build`), with no page or Vite configuration of the app's own; answers tools and agents with what the
- * catalogue shows (`stories`, `story`, `mcp`); and writes what a project keeps (`docs`, `new`, `agents`).
+ * The `forgebook` command's entry: turns on Node's compile cache, starts a first start's pre-bundling
+ * (`prebundleStart.ts`), then loads the commands (`forgebookCommands.mts`).
+ *
+ * @remarks
+ * Imports run before any code of the module holding them, so the cache has to be on in a module of its own, or the
+ * commands' modules would be compiled before it starts. It sits in the Vite cache folder of the `node_modules` this
+ * installation of Forgebook is in (`compileCacheFolder`), never in the folder the command runs from: the code it holds
+ * is Forgebook's own, so only the place Forgebook was installed may hold it. Removing that `.vite` folder, as a cold
+ * start does, removes it too. Run from its sources, outside any `node_modules`, Forgebook keeps no cache.
  *
  * @module
  */
-import { existsSync, writeFileSync } from "node:fs";
-import { relative, resolve } from "node:path";
-import { createInterface } from "node:readline";
-import { defineCommands } from "@ensiria/cli-kit/commands";
-import { readPackageVersion } from "@ensiria/cli-kit/files";
-import { ScriptError } from "@ensiria/cli-kit/script";
-import { build, createServer } from "vite";
-import { filteredStories, isStoriesDocument, isStoryDocument } from "../../src/vite/agentApi.js";
-import { answerMcpMessage, NEW_SESSION } from "../../src/vite/mcpProtocol.js";
-import { catalogueDocs } from "../forgebook-docs/catalogueDocs.js";
-import { catalogueClient } from "./agentClient.js";
-import { agentLoopCommands } from "./agentLoopCommands.mjs";
-import { storiesText, storyText } from "./agentText.js";
-import { askCatalogue, COMMAND, configOf, FORGEBOOK_OPTIONS, printAnswer } from "./catalogueCommands.js";
-import { catalogueVite } from "./catalogueVite.js";
-import { initCommands } from "./initCommands.mjs";
-import { catalogueTools } from "./mcpTools.js";
-import { newStoriesFile } from "./newStoriesFile.js";
-import { runStoryCheck, runStoryShot } from "./storyCheckRun.js";
-import { openTouchWindow } from "./touchWindowRun.js";
-await defineCommands({
-    name: "forgebook",
-    command: COMMAND,
-    summary: "Run a catalogue of stories from its forgebook.config.ts, build it, or answer tools and agents about it.",
-    icon: "docs",
-    options: FORGEBOOK_OPTIONS,
-    commands: (forgebook) => ({
-        dev: forgebook.command({
-            summary: "Run the catalogue's dev server.",
-            options: {
-                port: {
-                    type: "string",
-                    valueName: "number",
-                    description: "The port to listen on; Vite's by default."
-                },
-                host: {
-                    type: "string",
-                    valueName: "address",
-                    description: "The address to listen on; localhost by default."
-                },
-                force: {
-                    type: "boolean",
-                    description: "Pre-bundle the dependencies again, ignoring Vite's cache (as a first start does)."
-                },
-                touch: {
-                    type: "boolean",
-                    description: "Also open the catalogue in a Chromium window with Chromium's own touch emulation: the mouse makes real " +
-                        "touch events, native scrolling included (needs @forgebook/testing and Playwright). Still a computer: no " +
-                        "virtual keyboard, no iOS Safari; a device remains the last word."
-                }
-            },
-            examples: [
-                { command: `${COMMAND} dev`, description: "Run the catalogue of the folder you are in." },
-                { command: `${COMMAND} dev --port 6006`, description: "On a given port." },
-                { command: `${COMMAND} dev --touch`, description: "And try the stories with Chromium's real touch." }
-            ],
-            run: async ({ options, onInterrupt, log }) => {
-                const config = await configOf(options.config);
-                const port = options.port === undefined ? undefined : Number(options.port);
-                if (port !== undefined && !Number.isInteger(port))
-                    throw new ScriptError(`--port ${options.port} is not a port`);
-                const server = await createServer(await catalogueVite(config, {
-                    server: {
-                        ...(port === undefined ? {} : { port, strictPort: true }),
-                        ...(options.host === undefined ? {} : { host: options.host })
-                    },
-                    ...(options.force === true ? { optimizeDeps: { force: true } } : {})
-                }));
-                await server.listen();
-                server.printUrls();
-                if (options.touch === true)
-                    await openTouchWindow(config.dir, server.resolvedUrls?.local[0], log);
-                await new Promise((done) => {
-                    onInterrupt(() => {
-                        void server.close().then(done);
-                    });
-                });
-            }
-        }),
-        build: forgebook.command({
-            summary: "Build the catalogue into static files.",
-            options: {
-                out: { type: "string", valueName: "folder", description: "The folder to write; dist by default." }
-            },
-            examples: [{ command: `${COMMAND} build --out site`, description: "Build it into static files." }],
-            run: async ({ options, log }) => {
-                const config = await configOf(options.config);
-                await build(await catalogueVite(config, { build: { outDir: resolve(config.dir, options.out ?? "dist") } }));
-                log.success(`${config.title} built`);
-            }
-        }),
-        stories: forgebook.command({
-            summary: "List the catalogue's stories, with their ids and links; fail when the index has problems.",
-            json: true,
-            options: {
-                source: { type: "string", valueName: "id", description: "Only this source's stories." },
-                component: {
-                    type: "string",
-                    valueName: "text",
-                    description: "Only components whose title holds this text."
-                },
-                view: {
-                    type: "string",
-                    valueName: "query",
-                    description: "The view the links open in, as the catalogue's address writes it (theme=dark&lang=it)."
-                },
-                "used-in": {
-                    type: "boolean",
-                    description: "Add each component's \"Used in\": the components whose stories use it (reads the package's import graph)."
-                },
-                url: {
-                    type: "string",
-                    env: "FORGEBOOK_URL",
-                    valueName: "address",
-                    description: "Where forgebook dev runs, when not at Vite's default address (http://localhost:5173)."
-                }
-            },
-            examples: [
-                { command: `${COMMAND} stories`, description: "Every story." },
-                {
-                    command: `${COMMAND} stories --component select --used-in --json`,
-                    description: "The selects, with the components whose stories use them."
-                },
-                { command: `${COMMAND} stories --component button --json`, description: "The buttons, as JSON." }
-            ],
-            run: async ({ options, io, log, isJson, style }) => {
-                const config = await configOf(options.config);
-                const params = new URLSearchParams({
-                    view: options.view ?? "",
-                    usedIn: String(options["used-in"] === true)
-                });
-                const body = await askCatalogue(config, options.url, "stories", params, log);
-                if (!isStoriesDocument(body))
-                    throw new ScriptError("The catalogue's answer has an unexpected shape");
-                const document = filteredStories(body, { source: options.source, component: options.component });
-                printAnswer(storiesText(document, style), document, document.problems, { io, log, isJson });
-            }
-        }),
-        docs: forgebook.command({
-            summary: "Write a package's CATALOG.md and llms.txt, for agents writing code with it; --check fails when stale.",
-            json: true,
-            options: {
-                package: {
-                    type: "string",
-                    default: ".",
-                    valueName: "folder",
-                    description: "The package's folder; the current folder by default."
-                },
-                framework: {
-                    type: "string",
-                    default: "react",
-                    valueName: "name",
-                    description: "The framework the stories are written for: its package, @forgebook/<name>, reads the props."
-                },
-                check: {
-                    type: "boolean",
-                    short: "c",
-                    description: "Change nothing; fail when a file is stale or a file cannot be read (CI)."
-                }
-            },
-            examples: [
-                {
-                    command: `${COMMAND} docs`,
-                    description: "Rewrite the CATALOG.md and llms.txt of the package you are in."
-                },
-                { command: `${COMMAND} docs --check`, description: "Check them in CI." }
-            ],
-            run: ({ options, log }) => catalogueDocs({
-                packageDir: resolve(options.package),
-                framework: options.framework,
-                isCheck: options.check,
-                fixCommand: `${COMMAND} docs`
-            }, log)
-        }),
-        new: forgebook.command({
-            summary: "Write a component's first stories from its props: the main story, one per choice, the worst case.",
-            options: {
-                export: {
-                    type: "string",
-                    valueName: "name",
-                    description: "The component to read; the file's only one by default."
-                },
-                framework: {
-                    type: "string",
-                    default: "react",
-                    valueName: "name",
-                    description: "The framework the stories are written for: its package, @forgebook/<name>, reads the props."
-                },
-                print: { type: "boolean", description: "Print the file instead of writing it." },
-                force: { type: "boolean", description: "Replace a stories file that exists." }
-            },
-            positionals: [{ name: "file", description: "The component's file.", required: true }],
-            examples: [
-                { command: `${COMMAND} new src/Badge.tsx`, description: "Write src/Badge.stories.tsx." },
-                {
-                    command: `${COMMAND} new src/menu.tsx --export Menu --print`,
-                    description: "One of several, printed."
-                }
-            ],
-            run: async ({ args, options, io, log }) => {
-                const written = await newStoriesFile(resolve(args.file), options.export, options.framework);
-                if (options.print) {
-                    io.stdout.write(written.text);
-                    return;
-                }
-                const shown = relative(process.cwd(), written.file);
-                if (existsSync(written.file) && options.force !== true)
-                    throw new ScriptError(`${shown} exists`, {
-                        hint: "Give --force to replace it, or --print to see it"
-                    });
-                writeFileSync(written.file, written.text);
-                log.success(`${shown} written`);
-                log.info(`${COMMAND} stories --component ${written.text.match(/title: "([^"]*)"/)?.[1] ?? ""} lists them`);
-            }
-        }),
-        ...agentLoopCommands(forgebook),
-        ...initCommands(forgebook),
-        mcp: forgebook.command({
-            summary: "Serve the catalogue's stories to an agent over the Model Context Protocol, on stdin and stdout.",
-            header: false,
-            options: {
-                url: {
-                    type: "string",
-                    env: "FORGEBOOK_URL",
-                    valueName: "address",
-                    description: "Where forgebook dev runs, when not at Vite's default address (http://localhost:5173)."
-                }
-            },
-            examples: [
-                {
-                    command: `${COMMAND} mcp`,
-                    description: "What an agent's MCP configuration runs (npx forgebook mcp)."
-                }
-            ],
-            run: async ({ options, io, log }) => {
-                const config = await configOf(options.config);
-                // kept for the server's life: an agent's questions in a row each answer at once
-                const client = await catalogueClient(config, options.url);
-                log.debug(client.runningAt === undefined ? "Answering from a server of its own" : `Asking ${client.runningAt}`);
-                const server = {
-                    info: { name: "forgebook", version: readPackageVersion(import.meta.dirname) },
-                    instructions: `The stories of the Forgebook catalogue "${config.title}". list_stories finds a story's id, get_story gives its args and its component's props, story_address gives the links a person opens to see it.`,
-                    tools: catalogueTools({
-                        ask: client.ask,
-                        writeNew: (file, exportName) => newStoriesFile(resolve(config.dir, file), exportName, config.framework.name),
-                        check: (input) => runStoryCheck(config, options.url, input),
-                        shot: (input, outDir) => runStoryShot(config, options.url, input, outDir)
-                    })
-                };
-                let session = NEW_SESSION;
-                // stdout carries only the protocol's messages, one per line, answered in the order they came
-                for await (const line of createInterface({ input: io.stdin })) {
-                    if (line.trim() === "")
-                        continue;
-                    const step = await answerMcpMessage(line, session, server);
-                    session = step.session;
-                    if (step.reply !== undefined)
-                        io.stdout.write(`${step.reply}\n`);
-                }
-                await client.close();
-            }
-        }),
-        story: forgebook.command({
-            summary: "One story in detail: its args, its component's props, its links; fail when it cannot be read.",
-            json: true,
-            options: {
-                view: {
-                    type: "string",
-                    valueName: "query",
-                    description: "The view the links open in, as the catalogue's address writes it (theme=dark&lang=it)."
-                },
-                url: {
-                    type: "string",
-                    env: "FORGEBOOK_URL",
-                    valueName: "address",
-                    description: "Where forgebook dev runs, when not at Vite's default address (http://localhost:5173)."
-                }
-            },
-            positionals: [
-                { name: "id", description: "The story's id, as forgebook stories lists it.", required: true }
-            ],
-            examples: [
-                {
-                    command: `${COMMAND} story kit:actions-button--primary --view theme=dark --json`,
-                    description: "A story, its links in the dark theme, as JSON."
-                }
-            ],
-            run: async ({ args, options, io, log, isJson, style }) => {
-                const config = await configOf(options.config);
-                const params = new URLSearchParams({ id: args.id, view: options.view ?? "" });
-                const body = await askCatalogue(config, options.url, "story", params, log);
-                if (!isStoryDocument(body))
-                    throw new ScriptError("The catalogue's answer has an unexpected shape");
-                printAnswer(storyText(body, style), body, body.problems, { io, log, isJson });
-            }
-        })
-    })
-}).run();
-//# sourceMappingURL=forgebook.mjs.map
+import { enableCompileCache } from "node:module";
+import { compileCacheFolder } from "./compileCache.js";
+const folder = compileCacheFolder(import.meta.dirname);
+if (folder !== undefined)
+    enableCompileCache(folder);
+// a first start's pre-bundling works while the commands load
+const { prebundleEarly } = await import("./prebundleStart.js");
+prebundleEarly(process.argv.slice(2));
+await import("./forgebookCommands.mjs");

package/dist/bin/forgebook/forgebookCommands.d.mts

@@ -0,0 +1 @@
+export {};

package/dist/bin/forgebook/forgebookCommands.mjs

@@ -0,0 +1,292 @@
+/**
+ * The `forgebook` command's commands, loaded by its entry (`forgebook.mts`): runs a catalogue from its
+ * `forgebook.config.ts` (`dev`, the dev server) or builds it into static files (`build`), with no page or Vite
+ * configuration of the app's own; answers tools and agents with what the catalogue shows (`stories`, `story`, `mcp`);
+ * and writes what a project keeps (`docs`, `new`, `agents`).
+ *
+ * @remarks
+ * What only one command needs and weighs (the compiler, the Markdown reader, the Storybook importer) is imported by
+ * that command when it runs, so `forgebook dev` starts without it.
+ *
+ * @module
+ */
+import { existsSync, writeFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { defineCommands } from "@ensiria/cli-kit/commands";
+import { ScriptError } from "@ensiria/cli-kit/script";
+import { build } from "vite";
+import { filteredStories, isStoriesDocument, isStoryDocument } from "../../src/vite/agentApi.js";
+import { agentLoopCommands } from "./agentLoopCommands.mjs";
+import { storiesText, storyText } from "./agentText.js";
+import { settleAgentIndex } from "./builtCatalogue.js";
+import { askCatalogue, COMMAND, configOf, FORGEBOOK_OPTIONS, printAnswer } from "./catalogueCommands.js";
+import { catalogueVite, withReadableNames } from "./catalogueVite.js";
+import { devCommands } from "./devCommands.mjs";
+import { initCommands } from "./initCommands.mjs";
+import { mcpCommands } from "./mcpCommand.mjs";
+import { newStoriesFile } from "./newStoriesFile.js";
+import { pagesCommands } from "./pagesCommands.mjs";
+import { runTokens } from "./tokensRun.js";
+import { visualCommands } from "./visualCommands.mjs";
+await defineCommands({
+    name: "forgebook",
+    command: COMMAND,
+    summary: "Run a catalogue of stories from its forgebook.config.ts, build it, or answer tools and agents about it.",
+    icon: "docs",
+    options: FORGEBOOK_OPTIONS,
+    commands: (forgebook) => ({
+        ...devCommands(forgebook),
+        build: forgebook.command({
+            summary: "Build the catalogue into static files.",
+            options: {
+                out: { type: "string", valueName: "folder", description: "The folder to write; dist by default." },
+                base: {
+                    type: "string",
+                    valueName: "path",
+                    description: "The path the catalogue is served under (/pr-12/); the root by default."
+                },
+                "agent-index": {
+                    type: "boolean",
+                    description: "Also write what agents read, for forgebook mcp --from: props, docs, tokens, public."
+                },
+                "readable-names": {
+                    type: "boolean",
+                    description: "Name each script after its module as well as its hash (build.readableNames in the configuration)."
+                }
+            },
+            examples: [
+                { command: `${COMMAND} build --out site`, description: "Build it into static files." },
+                {
+                    command: `${COMMAND} build --base /pr-12/`,
+                    description: "For a host that serves it under a sub-path."
+                }
+            ],
+            run: async ({ options, log }) => {
+                const config = withReadableNames(await configOf(options.config), options["readable-names"]);
+                const outDir = resolve(config.dir, options.out ?? "dist");
+                await build(await catalogueVite(config, {
+                    ...(options.base === undefined ? {} : { base: options.base }),
+                    build: { outDir }
+                }));
+                await settleAgentIndex(config, outDir, options["agent-index"] === true, log);
+                log.success(`${config.title} built`);
+            }
+        }),
+        stories: forgebook.command({
+            summary: "List the catalogue's stories, with their ids and links; fail when the index has problems.",
+            json: true,
+            options: {
+                source: { type: "string", valueName: "id", description: "Only this source's stories." },
+                component: {
+                    type: "string",
+                    valueName: "text",
+                    description: "Only components whose title holds this text."
+                },
+                view: {
+                    type: "string",
+                    valueName: "query",
+                    description: "The view the links open in, as the catalogue's address writes it (theme=dark&lang=it)."
+                },
+                "used-in": {
+                    type: "boolean",
+                    description: "Add each component's \"Used in\": the components whose stories use it (reads the package's import graph)."
+                },
+                url: {
+                    type: "string",
+                    env: "FORGEBOOK_URL",
+                    valueName: "address",
+                    description: "Where forgebook dev runs, when not at Vite's default address (http://localhost:5173)."
+                }
+            },
+            examples: [
+                { command: `${COMMAND} stories`, description: "Every story." },
+                {
+                    command: `${COMMAND} stories --component select --used-in --json`,
+                    description: "The selects, with the components whose stories use them."
+                },
+                { command: `${COMMAND} stories --component button --json`, description: "The buttons, as JSON." }
+            ],
+            run: async ({ options, io, log, isJson, style }) => {
+                const config = await configOf(options.config);
+                const params = new URLSearchParams({
+                    view: options.view ?? "",
+                    usedIn: String(options["used-in"] === true)
+                });
+                const body = await askCatalogue(config, options.url, "stories", params, log);
+                if (!isStoriesDocument(body))
+                    throw new ScriptError("The catalogue's answer has an unexpected shape");
+                const document = filteredStories(body, { source: options.source, component: options.component });
+                printAnswer(storiesText(document, style), document, document.problems, { io, log, isJson });
+            }
+        }),
+        tokens: forgebook.command({
+            summary: "List the catalogue's design tokens, show one, or find the one nearest a value written by hand.",
+            json: true,
+            positionals: [{ name: "name", description: "A token's name, to see that one." }],
+            options: {
+                category: {
+                    type: "string",
+                    valueName: "name",
+                    description: "Only a token type (color) or a first group (space)."
+                },
+                nearest: {
+                    type: "string",
+                    valueName: "value",
+                    description: "The tokens nearest this value, as code writes it: #1c1b1b, 16px, 200ms."
+                },
+                type: {
+                    type: "string",
+                    valueName: "type",
+                    description: "With --nearest, what to compare with: color, dimension, duration, number, fontWeight, or a CSS property; read from the value when left out."
+                },
+                limit: {
+                    type: "string",
+                    valueName: "number",
+                    description: "The most tokens a list gives; 100 by default, with the total beside them."
+                },
+                url: {
+                    type: "string",
+                    env: "FORGEBOOK_URL",
+                    valueName: "address",
+                    description: "Where forgebook dev runs, when not at Vite's default address (http://localhost:5173)."
+                }
+            },
+            examples: [
+                { command: `${COMMAND} tokens --category color`, description: "Every colour." },
+                { command: `${COMMAND} tokens color.brand.primary --json`, description: "One token." },
+                {
+                    command: `${COMMAND} tokens --nearest "#1c1b1b"`,
+                    description: "What to write instead of that colour."
+                },
+                {
+                    command: `${COMMAND} tokens --nearest 13px --type dimension`,
+                    description: "And instead of that size."
+                }
+            ],
+            run: async ({ options, args, io, log, isJson }) => {
+                const config = await configOf(options.config);
+                const { nearest, category, type, limit, url } = options;
+                await runTokens({ config, url, context: { io, log, isJson } }, { name: args.name, nearest, category, type, limit });
+            }
+        }),
+        docs: forgebook.command({
+            summary: "Write a package's CATALOG.md and llms.txt, for agents writing code with it; --check fails when stale.",
+            json: true,
+            options: {
+                package: {
+                    type: "string",
+                    default: ".",
+                    valueName: "folder",
+                    description: "The package's folder; the current folder by default."
+                },
+                framework: {
+                    type: "string",
+                    default: "react",
+                    valueName: "name",
+                    description: "The framework the stories are written for: its package, @forgebook/<name>, reads the props."
+                },
+                check: {
+                    type: "boolean",
+                    short: "c",
+                    description: "Change nothing; fail when a file is stale or a file cannot be read (CI)."
+                }
+            },
+            examples: [
+                {
+                    command: `${COMMAND} docs`,
+                    description: "Rewrite the CATALOG.md and llms.txt of the package you are in."
+                },
+                { command: `${COMMAND} docs --check`, description: "Check them in CI." }
+            ],
+            run: async ({ options, log }) => {
+                // the docs writer loads the compiler and the Markdown reader: only this command needs them
+                const { catalogueDocs } = await import("../forgebook-docs/catalogueDocs.js");
+                return catalogueDocs({
+                    packageDir: resolve(options.package),
+                    framework: options.framework,
+                    isCheck: options.check,
+                    fixCommand: `${COMMAND} docs`
+                }, log);
+            }
+        }),
+        new: forgebook.command({
+            summary: "Write a component's first stories from its props: the main story, one per choice, the worst case.",
+            options: {
+                export: {
+                    type: "string",
+                    valueName: "name",
+                    description: "The component to read; the file's only one by default."
+                },
+                framework: {
+                    type: "string",
+                    valueName: "name",
+                    description: "The framework the stories are written for: its package, @forgebook/<name>, reads the props. The catalogue's by default, else react."
+                },
+                print: { type: "boolean", description: "Print the file instead of writing it." },
+                force: { type: "boolean", description: "Replace a stories file that exists." }
+            },
+            positionals: [{ name: "file", description: "The component's file.", required: true }],
+            examples: [
+                { command: `${COMMAND} new src/Badge.tsx`, description: "Write src/Badge.stories.tsx." },
+                {
+                    command: `${COMMAND} new src/menu.tsx --export Menu --print`,
+                    description: "One of several, printed."
+                }
+            ],
+            run: async ({ args, options, io, log }) => {
+                const written = await newStoriesFile(resolve(args.file), options.export, options.framework);
+                if (options.print) {
+                    io.stdout.write(written.text);
+                    return;
+                }
+                const shown = relative(process.cwd(), written.file);
+                if (existsSync(written.file) && options.force !== true)
+                    throw new ScriptError(`${shown} exists`, {
+                        hint: "Give --force to replace it, or --print to see it"
+                    });
+                writeFileSync(written.file, written.text);
+                log.success(`${shown} written`);
+                log.info(`${COMMAND} stories --component ${written.text.match(/title: "([^"]*)"/)?.[1] ?? ""} lists them`);
+            }
+        }),
+        ...agentLoopCommands(forgebook),
+        ...pagesCommands(forgebook),
+        ...visualCommands(forgebook),
+        ...initCommands(forgebook),
+        ...mcpCommands(forgebook),
+        story: forgebook.command({
+            summary: "One story in detail: its args, its component's props, its links; fail when it cannot be read.",
+            json: true,
+            options: {
+                view: {
+                    type: "string",
+                    valueName: "query",
+                    description: "The view the links open in, as the catalogue's address writes it (theme=dark&lang=it)."
+                },
+                url: {
+                    type: "string",
+                    env: "FORGEBOOK_URL",
+                    valueName: "address",
+                    description: "Where forgebook dev runs, when not at Vite's default address (http://localhost:5173)."
+                }
+            },
+            positionals: [
+                { name: "id", description: "The story's id, as forgebook stories lists it.", required: true }
+            ],
+            examples: [
+                {
+                    command: `${COMMAND} story kit:actions-button--primary --view theme=dark --json`,
+                    description: "A story, its links in the dark theme, as JSON."
+                }
+            ],
+            run: async ({ args, options, io, log, isJson, style }) => {
+                const config = await configOf(options.config);
+                const params = new URLSearchParams({ id: args.id, view: options.view ?? "" });
+                const body = await askCatalogue(config, options.url, "story", params, log);
+                if (!isStoryDocument(body))
+                    throw new ScriptError("The catalogue's answer has an unexpected shape");
+                printAnswer(storyText(body, style), body, body.problems, { io, log, isJson });
+            }
+        })
+    })
+}).run();

package/dist/bin/forgebook/importers/storybook.d.ts

@@ -1,6 +1,12 @@
 import { type ViewSwitch } from "../../../src/switches.ts";
+import { type VitePaths } from "../../../src/vite/vitePaths.ts";
+import { type ImportedFramework } from "./storybookFrameworks.ts";
 /** What a configuration takes from another tool's files. */
 export type ImportedConfig = {
+    /** The Forgebook framework the stories are written for. */
+    readonly framework: ImportedFramework;
+    /** The framework's options, plain values (`{ dir: "web", nextConfig: "next.config.js" }`); none when there are none. */
+    readonly frameworkOptions: Readonly<Record<string, unknown>> | undefined;
     /** The catalogue's name: the package's, or the folder's. */
     readonly title: string;
     /** The story files, as globs from the project's folder. */
@@ -13,7 +19,7 @@ export type ImportedConfig = {
     readonly notes: readonly string[];
 };
 /**
- * Every glob a glob with alternatives stands for: `@(a|b)` and `{a,b}` written out, nested ones too, so the
+ * Every glob a glob with alternatives stands for: `@(a|b)`, `?(a|b)` and `{a,b}` written out, nested ones too, so the
  * configuration lists plain globs a person reads at a glance.
  *
  * @param glob - the glob.
@@ -26,9 +32,10 @@ export declare const expandedGlobs: (glob: string) => string[];
  * @param entries - `main`'s `stories`.
  * @param storybookDir - the `.storybook` folder, absolute.
  * @param projectDir - the project's folder, absolute.
- * @returns the globs, and what was not read.
+ * @param paths - the path functions; the running system's unless a test names another.
+ * @returns the globs, with forward slashes on every system as globs take them, and what was not read.
  */
-export declare const storyGlobs: (entries: readonly unknown[], storybookDir: string, projectDir: string) => {
+export declare const storyGlobs: (entries: readonly unknown[], storybookDir: string, projectDir: string, paths?: VitePaths) => {
     readonly globs: string[];
     readonly notes: string[];
 };
@@ -50,4 +57,3 @@ export declare const previewSwitches: (text: string, file: string) => {
  * @returns what a Forgebook configuration takes from it, or why it cannot be read.
  */
 export declare const importStorybook: (projectDir: string) => Promise<ImportedConfig | string>;
-//# sourceMappingURL=storybook.d.ts.map