forgebook 0.1.3 → 0.1.4

package/dist/bin/forgebook/agents.md

@@ -0,0 +1,46 @@
+## Stories (Forgebook)
+
+This project's components have stories, shown by [Forgebook](https://github.com/ensiria/forgebook) (`forgebook dev`).
+When you add or change a component, add or change its stories, then check them with the commands below: they answer
+in JSON with `--json`, and every answer carries the links that open a story for a person.
+
+### Writing a story file
+
+- One file per component, beside it: `Badge.tsx` and `Badge.stories.tsx`, in CSF 3 (Storybook's format; Forgebook
+  reads it, never MDX or addons).
+- The meta is the default export; the stories are named exports, each with a one-line TSDoc saying what it shows (the
+  catalogue shows that sentence):
+
+  ```tsx
+  import type { Meta, Story } from "@forgebook/react";
+
+  import { Badge } from "./Badge";
+
+  export default { title: "Data/Badge", component: Badge } satisfies Meta<typeof Badge>;
+
+  /** The label as most pages use it. */
+  export const Default: Story<typeof Badge> = { args: { label: "New" }, parameters: { main: true } };
+  ```
+
+- `parameters.main: true` marks the one real, well-made use drawn at the top of the component's page.
+- `parameters.group` puts a story under a heading of the page (`"states"`, `"worst-case"`); keep one story per
+  meaningful state, not one per prop value.
+- Add a worst case: very long text, words without spaces, huge numbers (`forgebook new` writes one).
+- `parameters.height` gives the frame the room an overlay the story opens needs (a menu, a popover), in CSS px.
+- Texts a person reads come from the source's texts, not from the story: `args: { label: storyText("badge.new") }`
+  (`@forgebook/story-format/texts`), or `useStoryText()` inside a `render`.
+- Write `title`, `parameters.main`, `group` and `height` as plain values: the catalogue reads them without running
+  the file.
+
+### Commands
+
+| Command | What it is for |
+|---|---|
+| `npx forgebook new src/Badge.tsx` | A component's first stories, from its typed props |
+| `npx forgebook stories --component badge --json` | The stories and their ids; fails when a story file is broken |
+| `npx forgebook story <id> --json` | One story: its args, its component's props, the components whose stories use it |
+| `npx forgebook check <id> --json` | The catalogue's checks on one story: accessibility, spills, overlays, errors, a failed play |
+| `npx forgebook errors --json` | What the open frames reported while you edited: render errors, failed plays |
+| `npx forgebook shot <id> --view "dark 360"` | The story as a picture, to look at it (a view as words, or `theme=dark&width=360`) |
+
+Run `npx forgebook <command> --help` for the options. With an MCP client, `npx forgebook mcp` offers the same as tools.

package/dist/bin/forgebook/agentsText.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The instructions `forgebook agents` gives a project's coding agents: Forgebook's section of the project's
+ * `AGENTS.md`, and the same text as a Claude Code skill.
+ *
+ * @remarks
+ * The section sits between two markers, so running the command again replaces its own text and leaves the rest of the
+ * file as the project wrote it. `AGENTS.md` is the file Codex reads and Claude Code reads when the project has no
+ * `CLAUDE.md` (one that has can import it with `@AGENTS.md`). Pure: texts in, text out.
+ *
+ * @module
+ */
+/** The line before Forgebook's section. */
+export declare const AGENTS_START = "<!-- forgebook:start: written by `forgebook agents`, replaced when it runs again -->";
+/** The line after it. */
+export declare const AGENTS_END = "<!-- forgebook:end -->";
+/**
+ * A file's text with Forgebook's section in it: put in place of the one already there, else added at the end.
+ *
+ * @param existing - the file's text, or none when there is no file yet.
+ * @param section - the instructions.
+ */
+export declare const withAgentsSection: (existing: string | undefined, section: string) => string;
+/**
+ * The instructions as a Claude Code skill: its name and when to use it, then the text.
+ *
+ * @param section - the instructions.
+ */
+export declare const agentsSkill: (section: string) => string;
+//# sourceMappingURL=agentsText.d.ts.map

package/dist/bin/forgebook/agentsText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentsText.d.ts","sourceRoot":"","sources":["../../../bin/forgebook/agentsText.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,2CAA2C;AAC3C,eAAO,MAAM,YAAY,yFAC+D,CAAC;AAEzF,yBAAyB;AACzB,eAAO,MAAM,UAAU,2BAA2B,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,GAAG,SAAS,EAAE,SAAS,MAAM,KAAG,MAUjF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,KAAG,MAShC,CAAC"}

package/dist/bin/forgebook/agentsText.js

@@ -0,0 +1,48 @@
+/**
+ * The instructions `forgebook agents` gives a project's coding agents: Forgebook's section of the project's
+ * `AGENTS.md`, and the same text as a Claude Code skill.
+ *
+ * @remarks
+ * The section sits between two markers, so running the command again replaces its own text and leaves the rest of the
+ * file as the project wrote it. `AGENTS.md` is the file Codex reads and Claude Code reads when the project has no
+ * `CLAUDE.md` (one that has can import it with `@AGENTS.md`). Pure: texts in, text out.
+ *
+ * @module
+ */
+/** The line before Forgebook's section. */
+export const AGENTS_START = "<!-- forgebook:start: written by `forgebook agents`, replaced when it runs again -->";
+/** The line after it. */
+export const AGENTS_END = "<!-- forgebook:end -->";
+/**
+ * A file's text with Forgebook's section in it: put in place of the one already there, else added at the end.
+ *
+ * @param existing - the file's text, or none when there is no file yet.
+ * @param section - the instructions.
+ */
+export const withAgentsSection = (existing, section) => {
+    const block = `${AGENTS_START}\n${section.trim()}\n${AGENTS_END}\n`;
+    if (existing === undefined || existing.trim() === "")
+        return block;
+    const start = existing.indexOf(AGENTS_START);
+    const end = existing.indexOf(AGENTS_END, start);
+    if (start !== -1 && end !== -1) {
+        const after = existing.slice(end + AGENTS_END.length).replace(/^\n/, "");
+        return `${existing.slice(0, start)}${block}${after}`;
+    }
+    return `${existing.replace(/\n*$/, "")}\n\n${block}`;
+};
+/**
+ * The instructions as a Claude Code skill: its name and when to use it, then the text.
+ *
+ * @param section - the instructions.
+ */
+export const agentsSkill = (section) => [
+    "---",
+    "name: forgebook",
+    "description: Write, check and look at this project's component stories with Forgebook (CSF 3). Use when adding or changing a component, or its stories.",
+    "---",
+    "",
+    section.trim(),
+    ""
+].join("\n");
+//# sourceMappingURL=agentsText.js.map

package/dist/bin/forgebook/agentsText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentsText.js","sourceRoot":"","sources":["../../../bin/forgebook/agentsText.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,2CAA2C;AAC3C,MAAM,CAAC,MAAM,YAAY,GACvB,sFAAsF,CAAC;AAEzF,yBAAyB;AACzB,MAAM,CAAC,MAAM,UAAU,GAAG,wBAAwB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,QAA4B,EAAE,OAAe,EAAU,EAAE;IACzF,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,OAAO,CAAC,IAAI,EAAE,KAAK,UAAU,IAAI,CAAC;IACpE,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACnE,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAChD,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACzE,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,KAAK,GAAG,KAAK,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,CAAC;AACvD,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAe,EAAU,EAAE,CACrD;IACE,KAAK;IACL,iBAAiB;IACjB,yJAAyJ;IACzJ,KAAK;IACL,EAAE;IACF,OAAO,CAAC,IAAI,EAAE;IACd,EAAE;CACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC"}

package/dist/bin/forgebook/catalogueCommands.d.ts

@@ -0,0 +1,51 @@
+import type { ScriptIo } from "@ensiria/cli-kit/io.types";
+import type { Logger } from "@ensiria/cli-kit/log.types";
+import type { StoriesDocument, StoryDocument } from "../../src/vite/agent.types.ts";
+import { type ResolvedConfig } from "../../src/vite/configFile.ts";
+/** The options every `forgebook` command takes: the configuration file. */
+export type ForgebookOptions = {
+    /** The configuration file. */
+    readonly config: {
+        readonly type: "string";
+        readonly valueName: string;
+        readonly description: string;
+    };
+};
+/** The options every `forgebook` command takes. */
+export declare const FORGEBOOK_OPTIONS: ForgebookOptions;
+/** The command, as the hints print it. */
+export declare const COMMAND = "forgebook";
+/**
+ * The catalogue's configuration: the file given, or the one in the folder the command runs in.
+ *
+ * @param file - the configuration file given; none to look in the current folder.
+ * @throws a `ScriptError` when there is none, or it cannot be used.
+ */
+export declare const configOf: (file: string | undefined) => Promise<ResolvedConfig>;
+/**
+ * Asks the catalogue one of its answers, from its running dev server or one started for the answer.
+ *
+ * @param config - the catalogue's configuration.
+ * @param url - where `forgebook dev` runs, when not at Vite's default address.
+ * @param route - the answer (`stories`, `story`).
+ * @param params - its query.
+ * @param log - where to say where the answer comes from.
+ * @throws a `ScriptError` when the catalogue answers with an error.
+ */
+export declare const askCatalogue: (config: ResolvedConfig, url: string | undefined, route: string, params: URLSearchParams, log: Logger) => Promise<unknown>;
+/**
+ * Prints an answer, its JSON with `--json`, its problems as warnings, and ends with a failure when it has problems,
+ * so a CI step fails on a broken story file.
+ *
+ * @param text - the answer as text for a terminal.
+ * @param document - the answer as data.
+ * @param problems - what is wrong in it.
+ * @param context - the run's io, logger and `--json` mode.
+ * @throws a reported `ScriptError` when there are problems.
+ */
+export declare const printAnswer: (text: string, document: StoriesDocument | StoryDocument, problems: readonly string[], context: {
+    readonly io: ScriptIo;
+    readonly log: Logger;
+    readonly isJson: boolean;
+}) => void;
+//# sourceMappingURL=catalogueCommands.d.ts.map

package/dist/bin/forgebook/catalogueCommands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogueCommands.d.ts","sourceRoot":"","sources":["../../../bin/forgebook/catalogueCommands.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGzD,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEpF,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,8BAA8B,CAAC;AAGtC,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CACxG,CAAC;AAEF,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,EAAE,gBAM/B,CAAC;AAEF,0CAA0C;AAC1C,eAAO,MAAM,OAAO,cAAc,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAU,MAAM,MAAM,GAAG,SAAS,KAAG,OAAO,CAAC,cAAc,CAW/E,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,cAAc,EACtB,KAAK,MAAM,GAAG,SAAS,EACvB,OAAO,MAAM,EACb,QAAQ,eAAe,EACvB,KAAK,MAAM,KACV,OAAO,CAAC,OAAO,CAsBjB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GACtB,MAAM,MAAM,EACZ,UAAU,eAAe,GAAG,aAAa,EACzC,UAAU,SAAS,MAAM,EAAE,EAC3B,SAAS;IAAE,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,KACjF,IAKF,CAAC"}

package/dist/bin/forgebook/catalogueCommands.js

@@ -0,0 +1,90 @@
+/**
+ * What the `forgebook` commands share: their common options, the command's name for hints, the catalogue's
+ * configuration, an answer asked of the catalogue, and an answer printed.
+ *
+ * @module
+ */
+import { resolve } from "node:path";
+import { EXIT } from "@ensiria/cli-kit/constants";
+import { formatJson } from "@ensiria/cli-kit/files";
+import { ScriptError } from "@ensiria/cli-kit/script";
+import { CONFIG_FILES, findConfigFile, loadConfigFile } from "../../src/vite/configFile.js";
+import { catalogueClient } from "./agentClient.js";
+/** The options every `forgebook` command takes. */
+export const FORGEBOOK_OPTIONS = {
+    config: {
+        type: "string",
+        valueName: "file",
+        description: "The configuration file; forgebook.config.ts in the current folder by default."
+    }
+};
+/** The command, as the hints print it. */
+export const COMMAND = "forgebook";
+/**
+ * The catalogue's configuration: the file given, or the one in the folder the command runs in.
+ *
+ * @param file - the configuration file given; none to look in the current folder.
+ * @throws a `ScriptError` when there is none, or it cannot be used.
+ */
+export const configOf = async (file) => {
+    const found = file === undefined ? findConfigFile(process.cwd()) : resolve(file);
+    if (found === undefined)
+        throw new ScriptError(`No ${CONFIG_FILES[0]} here`, {
+            hint: `Run ${COMMAND} in the catalogue's folder, or give --config`
+        });
+    try {
+        return await loadConfigFile(found);
+    }
+    catch (error) {
+        throw new ScriptError(error instanceof Error ? error.message : String(error));
+    }
+};
+/**
+ * Asks the catalogue one of its answers, from its running dev server or one started for the answer.
+ *
+ * @param config - the catalogue's configuration.
+ * @param url - where `forgebook dev` runs, when not at Vite's default address.
+ * @param route - the answer (`stories`, `story`).
+ * @param params - its query.
+ * @param log - where to say where the answer comes from.
+ * @throws a `ScriptError` when the catalogue answers with an error.
+ */
+export const askCatalogue = async (config, url, route, params, log) => {
+    const client = await catalogueClient(config, url);
+    log.debug(client.runningAt === undefined
+        ? "No catalogue running: answered by a server of its own"
+        : `Asked ${client.runningAt}`);
+    let answer;
+    try {
+        answer = await client.ask(route, params);
+    }
+    finally {
+        await client.close();
+    }
+    if (answer.status !== 200) {
+        const { body } = answer;
+        const message = typeof body === "object" && body !== null && "error" in body && typeof body.error === "string"
+            ? body.error
+            : `The catalogue answered ${answer.status}`;
+        throw new ScriptError(message);
+    }
+    return answer.body;
+};
+/**
+ * Prints an answer, its JSON with `--json`, its problems as warnings, and ends with a failure when it has problems,
+ * so a CI step fails on a broken story file.
+ *
+ * @param text - the answer as text for a terminal.
+ * @param document - the answer as data.
+ * @param problems - what is wrong in it.
+ * @param context - the run's io, logger and `--json` mode.
+ * @throws a reported `ScriptError` when there are problems.
+ */
+export const printAnswer = (text, document, problems, context) => {
+    context.io.stdout.write(context.isJson ? formatJson(document) : `${text}\n`);
+    for (const problem of problems)
+        context.log.warn(problem);
+    if (problems.length > 0)
+        throw new ScriptError(`${problems.length} problems`, { exitCode: EXIT.failure, isReported: true });
+};
+//# sourceMappingURL=catalogueCommands.js.map

package/dist/bin/forgebook/catalogueCommands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogueCommands.js","sourceRoot":"","sources":["../../../bin/forgebook/catalogueCommands.ts"],"names":[],"mappings":"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"}

package/dist/bin/forgebook/errorsRun.d.ts

@@ -0,0 +1,27 @@
+import type { ErrorsDocument } from "../../src/vite/agent.types.ts";
+import type { CatalogueClient } from "./agentClient.ts";
+/**
+ * The number to ask for the errors after, from the command line: 0, every error kept, when none or not a number.
+ *
+ * @param text - `--since`'s value, if given.
+ */
+export declare const sinceOf: (text: string | undefined) => number;
+/**
+ * The errors after a number, and the index's problems.
+ *
+ * @param ask - asks the catalogue.
+ * @param since - the number of the last error already read; 0 for every one kept.
+ * @returns the document, or why the catalogue could not answer.
+ */
+export declare const askErrors: (ask: CatalogueClient["ask"], since: number) => Promise<ErrorsDocument | string>;
+/**
+ * Follows the errors: each answer with new ones handed on, until the catalogue stops answering or the signal aborts.
+ *
+ * @param ask - asks the catalogue.
+ * @param since - the number of the last error already read.
+ * @param onErrors - called with each answer that has new errors.
+ * @param signal - stops following; none to follow until the process ends.
+ * @returns why it stopped, when the catalogue could not answer.
+ */
+export declare const followErrors: (ask: CatalogueClient["ask"], since: number, onErrors: (document: ErrorsDocument) => void, signal?: AbortSignal) => Promise<string | undefined>;
+//# sourceMappingURL=errorsRun.d.ts.map

package/dist/bin/forgebook/errorsRun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorsRun.d.ts","sourceRoot":"","sources":["../../../bin/forgebook/errorsRun.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAKxD;;;;GAIG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,GAAG,SAAS,KAAG,MAGlD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GACpB,KAAK,eAAe,CAAC,KAAK,CAAC,EAC3B,OAAO,MAAM,KACZ,OAAO,CAAC,cAAc,GAAG,MAAM,CAKjC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GACvB,KAAK,eAAe,CAAC,KAAK,CAAC,EAC3B,OAAO,MAAM,EACb,UAAU,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,EAC5C,SAAS,WAAW,KACnB,OAAO,CAAC,MAAM,GAAG,SAAS,CAc5B,CAAC"}

package/dist/bin/forgebook/errorsRun.js

@@ -0,0 +1,60 @@
+/**
+ * What `forgebook errors` and the MCP tool `recent_errors` run: the errors the open frames reported, asked of the
+ * catalogue once, or followed as they come.
+ *
+ * @module
+ */
+import { setTimeout as sleep } from "node:timers/promises";
+import { isErrorsDocument } from "../../src/vite/agentApi.js";
+/** How often a follower asks for new errors, in ms. */
+const FOLLOW_MS = 1000;
+/**
+ * The number to ask for the errors after, from the command line: 0, every error kept, when none or not a number.
+ *
+ * @param text - `--since`'s value, if given.
+ */
+export const sinceOf = (text) => {
+    const since = Number(text ?? "0");
+    return Number.isInteger(since) && since > 0 ? since : 0;
+};
+/**
+ * The errors after a number, and the index's problems.
+ *
+ * @param ask - asks the catalogue.
+ * @param since - the number of the last error already read; 0 for every one kept.
+ * @returns the document, or why the catalogue could not answer.
+ */
+export const askErrors = async (ask, since) => {
+    const answer = await ask("errors", new URLSearchParams({ since: String(since) }));
+    return answer.status === 200 && isErrorsDocument(answer.body)
+        ? answer.body
+        : `The catalogue answered ${answer.status} for its errors`;
+};
+/**
+ * Follows the errors: each answer with new ones handed on, until the catalogue stops answering or the signal aborts.
+ *
+ * @param ask - asks the catalogue.
+ * @param since - the number of the last error already read.
+ * @param onErrors - called with each answer that has new errors.
+ * @param signal - stops following; none to follow until the process ends.
+ * @returns why it stopped, when the catalogue could not answer.
+ */
+export const followErrors = async (ask, since, onErrors, signal) => {
+    let last = since;
+    while (signal?.aborted !== true) {
+        const document = await askErrors(ask, last);
+        if (typeof document === "string")
+            return document;
+        if (document.errors.length > 0)
+            onErrors(document);
+        last = document.last;
+        try {
+            await sleep(FOLLOW_MS, undefined, signal === undefined ? {} : { signal });
+        }
+        catch {
+            // aborted while waiting: the loop's own check ends it
+        }
+    }
+    return undefined;
+};
+//# sourceMappingURL=errorsRun.js.map

package/dist/bin/forgebook/errorsRun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorsRun.js","sourceRoot":"","sources":["../../../bin/forgebook/errorsRun.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAG3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAG9D,uDAAuD;AACvD,MAAM,SAAS,GAAG,IAAI,CAAC;AAEvB;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAwB,EAAU,EAAE;IAC1D,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC;IAClC,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,EAC5B,GAA2B,EAC3B,KAAa,EACqB,EAAE;IACpC,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,QAAQ,EAAE,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IAClF,OAAO,MAAM,CAAC,MAAM,KAAK,GAAG,IAAI,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC;QAC3D,CAAC,CAAC,MAAM,CAAC,IAAI;QACb,CAAC,CAAC,0BAA0B,MAAM,CAAC,MAAM,iBAAiB,CAAC;AAC/D,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,GAA2B,EAC3B,KAAa,EACb,QAA4C,EAC5C,MAAoB,EACS,EAAE;IAC/B,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,OAAO,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC5C,IAAI,OAAO,QAAQ,KAAK,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAClD,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACnD,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QAC5E,CAAC;QAAC,MAAM,CAAC;YACP,sDAAsD;QACxD,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC"}

package/dist/bin/forgebook/forgebook.mjs

@@ -1,106 +1,36 @@
 #!/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; and answers tools and agents
- * (`stories`, `story`) with what the catalogue shows.
+ * 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`).
  *
  * @module
  */
-import { resolve } from "node:path";
+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 { EXIT } from "@ensiria/cli-kit/constants";
-import { formatJson, readPackageVersion } from "@ensiria/cli-kit/files";
+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 { CONFIG_FILES, findConfigFile, loadConfigFile } from "../../src/vite/configFile.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";
-/** The command, as the hints print it. */
-const COMMAND = "forgebook";
-/**
- * The catalogue's configuration: the file given, or the one in the folder the command runs in.
- *
- * @param file - the configuration file given; none to look in the current folder.
- * @throws a `ScriptError` when there is none, or it cannot be used.
- */
-const configOf = async (file) => {
-    const found = file === undefined ? findConfigFile(process.cwd()) : resolve(file);
-    if (found === undefined)
-        throw new ScriptError(`No ${CONFIG_FILES[0]} here`, {
-            hint: `Run ${COMMAND} in the catalogue's folder, or give --config`
-        });
-    try {
-        return await loadConfigFile(found);
-    }
-    catch (error) {
-        throw new ScriptError(error instanceof Error ? error.message : String(error));
-    }
-};
-/**
- * Asks the catalogue one of its answers, from its running dev server or one started for the answer.
- *
- * @param config - the catalogue's configuration.
- * @param url - where `forgebook dev` runs, when not at Vite's default address.
- * @param route - the answer (`stories`, `story`).
- * @param params - its query.
- * @param log - where to say where the answer comes from.
- * @throws a `ScriptError` when the catalogue answers with an error.
- */
-const askCatalogue = async (config, url, route, params, log) => {
-    const client = await catalogueClient(config, url);
-    log.debug(client.runningAt === undefined
-        ? "No catalogue running: answered by a server of its own"
-        : `Asked ${client.runningAt}`);
-    let answer;
-    try {
-        answer = await client.ask(route, params);
-    }
-    finally {
-        await client.close();
-    }
-    if (answer.status !== 200) {
-        const { body } = answer;
-        const message = typeof body === "object" && body !== null && "error" in body && typeof body.error === "string"
-            ? body.error
-            : `The catalogue answered ${answer.status}`;
-        throw new ScriptError(message);
-    }
-    return answer.body;
-};
-/**
- * Prints an answer, its JSON with `--json`, its problems as warnings, and ends with a failure when it has problems,
- * so a CI step fails on a broken story file.
- *
- * @param text - the answer as text for a terminal.
- * @param document - the answer as data.
- * @param problems - what is wrong in it.
- * @param context - the run's io, logger and `--json` mode.
- * @throws a reported `ScriptError` when there are problems.
- */
-const printAnswer = (text, document, problems, context) => {
-    context.io.stdout.write(context.isJson ? formatJson(document) : `${text}\n`);
-    for (const problem of problems)
-        context.log.warn(problem);
-    if (problems.length > 0)
-        throw new ScriptError(`${problems.length} problems`, { exitCode: EXIT.failure, isReported: true });
-};
+import { newStoriesFile } from "./newStoriesFile.js";
+import { runStoryCheck, runStoryShot } from "./storyCheckRun.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: {
-        config: {
-            type: "string",
-            valueName: "file",
-            description: "The configuration file; forgebook.config.ts in the current folder by default."
-        }
-    },
+    options: FORGEBOOK_OPTIONS,
     commands: (forgebook) => ({
         dev: forgebook.command({
             summary: "Run the catalogue's dev server.",
@@ -172,6 +102,10 @@ await defineCommands({
                     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",
@@ -181,11 +115,18 @@ await defineCommands({
             },
             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 ?? "" });
+                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");
@@ -193,6 +134,85 @@ await defineCommands({
                 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,
@@ -218,7 +238,12 @@ await defineCommands({
                 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(client.ask)
+                    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