forgebook 0.1.7 → 0.2.0

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

@@ -1,16 +1,17 @@
 /**
  * The tools `forgebook mcp` offers agents, each answered as the command of the same name answers: `list_stories`,
- * `get_story`, `story_address`, `new_stories`, `check_story`, `recent_errors` and `story_shot`.
+ * `find_component`, `changed_stories`, `get_story`, `story_address`, `new_stories`, `check_story`, `recent_errors`, `story_shot`, `check_code`, `list_tokens`, `get_token`,
+ * `nearest_token`, `list_pages`, `get_page`, `search_catalogue` and `list_plugins`; and `story_preview` (`mcpPreview.ts`),
+ * for a client that renders apps.
  *
  * @module
  */
 import type { StoryCheckReport, StoryShotReport } from "../../src/storyCheck.ts";
-import type { AgentAnswer } from "../../src/vite/agentRoutes.ts";
+import type { PluginsDocument } from "../../src/vite/agent.types.ts";
 import type { McpTool } from "../../src/vite/mcpProtocol.ts";
+import { type Ask } from "./mcpToolParts.ts";
 import type { NewStoriesFile } from "./newStoriesFile.ts";
 import type { StoryCheckInput } from "./storyCheckRun.ts";
-/** Asks the catalogue one of its answers. */
-type Ask = (route: string, params: URLSearchParams) => Promise<AgentAnswer>;
 /** Writes a component's first stories, as `forgebook new --print` does. */
 type NewStories = (file: string, exportName: string | undefined) => Promise<NewStoriesFile>;
 /** Runs the catalogue's checks on a story in a browser: the report, or why it could not run. */
@@ -19,6 +20,8 @@ type Check = (input: StoryCheckInput) => Promise<StoryCheckReport | string>;
 type Shot = (input: StoryCheckInput, outDir: string) => Promise<StoryShotReport | string>;
 /** What the tools reach the catalogue through. */
 export type CatalogueReach = {
+    /** The plugins the configuration lists. */
+    readonly plugins: PluginsDocument;
     /** Asks the catalogue (the running dev server, or the server `forgebook mcp` keeps). */
     readonly ask: Ask;
     /** Writes a component's first stories, the file relative to the catalogue's folder. */
@@ -27,12 +30,15 @@ export type CatalogueReach = {
     readonly check: Check;
     /** Takes a story's pictures. */
     readonly shot: Shot;
+    /** Runs the checks on a page of the application. */
+    readonly checkPage: (address: string) => Promise<StoryCheckReport | string>;
+    /** Serves the catalogue where a browser can open a preview, and answers where. */
+    readonly servePreview: () => Promise<string>;
 };
 /**
  * The tools.
  *
  * @param reach - what they reach the catalogue through.
  */
-export declare const catalogueTools: ({ ask, writeNew, check, shot }: CatalogueReach) => readonly McpTool[];
+export declare const catalogueTools: ({ ask, writeNew, check, shot, checkPage, servePreview, plugins }: CatalogueReach) => readonly McpTool[];
 export {};
-//# sourceMappingURL=mcpTools.d.ts.map

package/dist/bin/forgebook/mcpTools.js

@@ -1,6 +1,8 @@
 /**
  * The tools `forgebook mcp` offers agents, each answered as the command of the same name answers: `list_stories`,
- * `get_story`, `story_address`, `new_stories`, `check_story`, `recent_errors` and `story_shot`.
+ * `find_component`, `changed_stories`, `get_story`, `story_address`, `new_stories`, `check_story`, `recent_errors`, `story_shot`, `check_code`, `list_tokens`, `get_token`,
+ * `nearest_token`, `list_pages`, `get_page`, `search_catalogue` and `list_plugins`; and `story_preview` (`mcpPreview.ts`),
+ * for a client that renders apps.
  *
  * @module
  */
@@ -8,7 +10,11 @@ import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { filteredStories, isStoriesDocument } from "../../src/vite/agentApi.js";
+import { namedStory } from "../../src/vite/agentIds.js";
 import { askErrors } from "./errorsRun.js";
+import { previewTool } from "./mcpPreview.js";
+import { resultOf, textOf, VIEW } from "./mcpToolParts.js";
+import { pageTools } from "./pageTools.js";
 /** The session's folder for pictures; made on the first call. */
 let shotsDir;
 /**
@@ -21,27 +27,139 @@ const shotsFolder = () => {
     mkdirSync(shotsDir, { recursive: true });
     return shotsDir;
 };
-/** The schema of the view argument, shared by the tools. */
-const VIEW = {
-    type: "string",
-    description: "The view the links open in, as the catalogue's address writes it (theme=dark&lang=it); none for the default."
+/** An answer as a tool's result that fails on what it found, as the command of the same name does. */
+const problemsResult = (answer) => {
+    const result = resultOf(answer);
+    const body = answer.body;
+    const hasProblems = typeof body === "object" &&
+        body !== null &&
+        "problems" in body &&
+        Array.isArray(body.problems) &&
+        body.problems.length > 0;
+    return { ...result, isError: result.isError || hasProblems };
 };
-/** A text argument, or none. */
-const textOf = (args, name) => {
-    const value = args[name];
-    return typeof value === "string" && value !== "" ? value : undefined;
-};
-/** An answer as a tool's result: a failure when the catalogue did not answer 200. */
-const resultOf = (answer) => ({
-    structured: answer.body,
-    isError: answer.status !== 200
-});
 /**
  * The tools.
  *
  * @param reach - what they reach the catalogue through.
  */
-export const catalogueTools = ({ ask, writeNew, check, shot }) => [
+export const catalogueTools = ({ ask, writeNew, check, shot, checkPage, servePreview, plugins }) => [
+    ...pageTools(ask),
+    {
+        name: "list_plugins",
+        description: "The plugins this catalogue lists and what each adds: panel tabs (open one with tab=<id> in a view), switches, docs blocks. A tab needs its plugin: a story's parameter does nothing without it.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        call: async () => ({ structured: plugins, isError: false })
+    },
+    {
+        name: "check_page",
+        description: "Run the catalogue's checks on a real page of the application in a browser: accessibility, what spills, console and page errors. Use it on the screen you built; for a story, check_story.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                address: { type: "string", description: "The page's address, as http://localhost:3000/checkout." }
+            },
+            required: ["address"],
+            additionalProperties: false
+        },
+        call: async (args) => {
+            const report = await checkPage(textOf(args, "address") ?? "");
+            return typeof report === "string"
+                ? { structured: { error: report }, isError: true }
+                : { structured: report, isError: false };
+        }
+    },
+    {
+        name: "changed_stories",
+        description: "The stories a change touches: every story that reaches a file git says changed, through the imports. Call it after editing, then run check_story on what it lists.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                since: {
+                    type: "string",
+                    description: "The commit to compare with; HEAD by default, so what is not committed."
+                }
+            },
+            additionalProperties: false
+        },
+        call: async (args) => resultOf(await ask("changed", new URLSearchParams({ since: textOf(args, "since") ?? "" })))
+    },
+    {
+        name: "find_component",
+        description: 'The components a description fits, best first, in your own words ("modal", "radio tile group"): call it before writing a component that may already exist. Each with the words it matched and missed, when to use it, and its first story.',
+        inputSchema: {
+            type: "object",
+            properties: { query: { type: "string", description: "What you are looking for, in any words." } },
+            required: ["query"],
+            additionalProperties: false
+        },
+        call: async (args) => resultOf(await ask("find", new URLSearchParams({ query: textOf(args, "query") ?? "" })))
+    },
+    {
+        name: "check_code",
+        description: "Check what your change adds, new files included, for colours and sizes written by hand, with the token to use, checks turned off with no reason, and deleted tests. It does not check props, imports or deprecated components, so a clean answer is not a review. `skipped` says what it could not check.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                since: {
+                    type: "string",
+                    description: "The commit to compare with; HEAD by default, so what is not committed."
+                }
+            },
+            additionalProperties: false
+        },
+        call: async (args) => problemsResult(await ask("check-code", new URLSearchParams({ since: textOf(args, "since") ?? "" })))
+    },
+    {
+        name: "list_tokens",
+        description: "The design tokens of this catalogue and of the libraries it shows, to use instead of a colour, size or duration written by hand: how many of each type, the first of them, and `clashes` where two authors disagree. To replace a raw value, call nearest_token; for one token's description, get_token.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                category: {
+                    type: "string",
+                    description: "A token type (color) or a first group (space); none for all."
+                },
+                limit: { type: "number", description: "The most tokens to give; 100 by default." }
+            },
+            additionalProperties: false
+        },
+        call: async (args) => resultOf(await ask("tokens", new URLSearchParams({
+            category: textOf(args, "category") ?? "",
+            limit: String(args["limit"] ?? "")
+        })))
+    },
+    {
+        name: "get_token",
+        description: "One design token: its value in each theme, what it is for, the token it aliases, and why not to use it if deprecated.",
+        inputSchema: {
+            type: "object",
+            properties: { name: { type: "string", description: "The token's name, as list_tokens gives it." } },
+            required: ["name"],
+            additionalProperties: false
+        },
+        call: async (args) => resultOf(await ask("token", new URLSearchParams({ name: textOf(args, "name") ?? "" })))
+    },
+    {
+        name: "nearest_token",
+        description: "The tokens nearest a value written by hand, nearest first: call it before writing a raw colour or size. Use a match only when `isClose` or `isExact` is true; otherwise no token fits, so say so rather than force one. Deprecated tokens are left out.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                value: {
+                    type: "string",
+                    description: "The value, as code writes it: #1c1b1b, rgb(1 2 3), 16px, 200ms."
+                },
+                type: {
+                    type: "string",
+                    description: "What to compare with: color, dimension, duration, number, fontWeight, or a CSS property (background, padding, font-size). Read from the value when left out."
+                }
+            },
+            required: ["value"],
+            additionalProperties: false
+        },
+        call: async (args) => resultOf(await ask("nearest-token", new URLSearchParams({ value: textOf(args, "value") ?? "", type: textOf(args, "type") ?? "" })))
+    },
     {
         name: "list_stories",
         description: "List the catalogue's components and stories, with each story's id and the links that open it, and the problems the story index found. Filter by source id or by text in a component's title.",
@@ -68,7 +186,7 @@ export const catalogueTools = ({ ask, writeNew, check, shot }) => [
     },
     {
         name: "get_story",
-        description: "One story in detail: its args as the catalogue renders it, its component's props (types, defaults, descriptions), the components whose stories use it (usedIn), its links in the view asked for, and what failed while reading it.",
+        description: "One story in detail: its args as the catalogue renders it, its component's props (types, defaults, descriptions), the components whose stories use it (usedIn), the device it is shown in by default (device), its design in Figma when it has one (design: the link, the file key and the node id, and the address where a person sees it beside the story), its links in the view asked for, and what failed while reading it.",
         inputSchema: {
             type: "object",
             properties: {
@@ -82,7 +200,7 @@ export const catalogueTools = ({ ask, writeNew, check, shot }) => [
     },
     {
         name: "story_address",
-        description: "The links that open a story in the catalogue and in its frame alone, in the view asked for: give them to a person to look at what you describe.",
+        description: "The links that open a story in the catalogue, in its frame alone, and with no chrome for a wiki or Notion (embed), in the view asked for: give them to a person to look at what you describe.",
         inputSchema: {
             type: "object",
             properties: {
@@ -97,12 +215,10 @@ export const catalogueTools = ({ ask, writeNew, check, shot }) => [
             const answer = await ask("stories", new URLSearchParams({ view: textOf(args, "view") ?? "" }));
             if (answer.status !== 200 || !isStoriesDocument(answer.body))
                 return resultOf(answer);
-            const story = answer.body.components
-                .flatMap((component) => component.stories)
-                .find((each) => each.id === id);
-            return story === undefined
+            const named = namedStory(answer.body, id);
+            return named === undefined
                 ? { structured: { error: `No story "${id}"` }, isError: true }
-                : { structured: { id, links: story.links }, isError: false };
+                : { structured: { id: named.story.id, links: named.story.links }, isError: false };
         }
     },
     {
@@ -148,6 +264,10 @@ export const catalogueTools = ({ ask, writeNew, check, shot }) => [
                 allVariants: {
                     type: "boolean",
                     description: "Check every variant the catalogue's browser tests check."
+                },
+                semantic: {
+                    type: "boolean",
+                    description: "Also ask the model the user configured whether headings, labels and alternatives say the right thing. Its judgements are opinions, in `judgements`."
                 }
             },
             required: ["id"],
@@ -160,7 +280,8 @@ export const catalogueTools = ({ ask, writeNew, check, shot }) => [
             const report = await check({
                 id: textOf(args, "id") ?? "",
                 views,
-                isAllVariants: args["allVariants"] === true
+                isAllVariants: args["allVariants"] === true,
+                isSemantic: args["semantic"] === true
             });
             if (typeof report === "string")
                 return { structured: { error: report }, isError: true };
@@ -187,7 +308,7 @@ export const catalogueTools = ({ ask, writeNew, check, shot }) => [
     },
     {
         name: "story_shot",
-        description: "Take a story's pictures in a browser, one per view, and look at them: the answer holds the pictures themselves, and the PNG files' paths. Views are written as the catalogue's address writes them (theme=dark&width=360) or as words (\"dark it 360\"). Needs @forgebook/testing and Playwright in the project.",
+        description: 'Take a story\'s pictures in a browser, one per view, and look at them: the answer holds the pictures themselves, and the PNG files\' paths. Views are written as the catalogue\'s address writes them (theme=dark&width=360) or as words ("dark it 360"); a device model\'s id in a view ("iphone-16", "pixel-9 landscape") frames the picture in that device. Needs @forgebook/testing and Playwright in the project.',
         inputSchema: {
             type: "object",
             properties: {
@@ -219,6 +340,6 @@ export const catalogueTools = ({ ask, writeNew, check, shot }) => [
             }));
             return { structured: report, isError: false, images };
         }
-    }
+    },
+    previewTool({ ask, serve: servePreview })
 ];
-//# sourceMappingURL=mcpTools.js.map

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

@@ -10,8 +10,8 @@ import type { ComponentDocs } from "../../src/componentDocs.ts";
 export type NewStoriesInput = {
     /** The component's docs (its props). */
     readonly docs: ComponentDocs;
-    /** How the story file imports the component (`./Badge`). */
-    readonly importPath: string;
+    /** The statement that imports the component (`import { Badge } from "./Badge";`). */
+    readonly importStatement: string;
     /** The meta's title (`Actions/Badge`). */
     readonly title: string;
     /** The module the story types come from (`@forgebook/react`). */
@@ -24,4 +24,3 @@ export type NewStoriesInput = {
  * @returns the file, ending with a newline.
  */
 export declare const newStories: (input: NewStoriesInput) => string;
-//# sourceMappingURL=newStories.d.ts.map

package/dist/bin/forgebook/newStories.js

@@ -39,7 +39,9 @@ const LINE_WIDTH = 100;
 const argsCode = (args) => {
     if (args.length === 0)
         return "{}";
-    const pairs = args.map(([name, value]) => `${name}: ${value}`);
+    // a name that is no identifier (Vue's `#default`) is a quoted key
+    const key = (name) => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name));
+    const pairs = args.map(([name, value]) => `${key(name)}: ${value}`);
     const line = `{ ${pairs.join(", ")} }`;
     return line.length <= LINE_WIDTH ? line : `{\n${pairs.map((pair) => `    ${pair}`).join(",\n")}\n  }`;
 };
@@ -95,7 +97,7 @@ export const newStories = (input) => {
         " */",
         `import type { Meta, Story } from ${JSON.stringify(input.typesModule)};`,
         "",
-        `import { ${name} } from ${JSON.stringify(input.importPath)};`,
+        input.importStatement,
         "",
         `export default { title: ${JSON.stringify(input.title)}, component: ${name} } satisfies Meta<typeof ${name}>;`,
         "",
@@ -106,4 +108,3 @@ export const newStories = (input) => {
         .join("\n")
         .replace(/\n+$/, "\n");
 };
-//# sourceMappingURL=newStories.js.map

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

@@ -1,6 +1,6 @@
 /** A component's first stories, ready to write. */
 export type NewStoriesFile = {
-    /** Where they go: `<Component>.stories.tsx` beside the component. */
+    /** Where they go: `<Component>.stories.tsx` beside the component, or the framework's own extension. */
     readonly file: string;
     /** The file's text. */
     readonly text: string;
@@ -10,9 +10,8 @@ export type NewStoriesFile = {
  *
  * @param componentFile - the component's file, absolute.
  * @param exportName - the export to read; the file's only component when none.
- * @param framework - the framework the stories are written for (`react`).
+ * @param framework - the framework the stories are written for (`react`); the catalogue's when none.
  * @throws a `ScriptError` when the file is in no package, the framework cannot read it, or it exports no single
  *   component.
  */
-export declare const newStoriesFile: (componentFile: string, exportName: string | undefined, framework: string) => Promise<NewStoriesFile>;
-//# sourceMappingURL=newStoriesFile.d.ts.map
+export declare const newStoriesFile: (componentFile: string, exportName: string | undefined, framework: string | undefined) => Promise<NewStoriesFile>;

package/dist/bin/forgebook/newStoriesFile.js

@@ -5,11 +5,12 @@
  *
  * @module
  */
-import { basename, dirname, join, relative } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { findUp } from "@ensiria/cli-kit/files";
 import { ScriptError } from "@ensiria/cli-kit/script";
 import { autoTitle, patternBase } from "../../src/vite/autoTitle.js";
 import { findConfigFile, loadConfigFile } from "../../src/vite/configFile.js";
+import { VITE_PATHS } from "../../src/vite/vitePaths.js";
 import { frameworkDocsModule } from "../frameworkDocs.js";
 import { newStories } from "./newStories.js";
 /** The folder the title starts from: the catalogue's first stories pattern's, else `src` for a file under it. */
@@ -18,14 +19,19 @@ const titleBase = async (packageDir, storiesFile) => {
     const [pattern] = config === undefined ? [] : (await loadConfigFile(config)).stories;
     if (pattern !== undefined)
         return patternBase(pattern).replace(/^\.\//, "");
-    return relative(packageDir, storiesFile).split("/")[0] === "src" ? "src" : "";
+    return VITE_PATHS.relative(packageDir, storiesFile).split("/")[0] === "src" ? "src" : "";
+};
+/** The framework of the package's catalogue; React's in a package with none. */
+const catalogueFramework = async (packageDir) => {
+    const config = findConfigFile(packageDir);
+    return config === undefined ? "react" : (await loadConfigFile(config)).framework.name;
 };
 /**
  * A component's first stories.
  *
  * @param componentFile - the component's file, absolute.
  * @param exportName - the export to read; the file's only component when none.
- * @param framework - the framework the stories are written for (`react`).
+ * @param framework - the framework the stories are written for (`react`); the catalogue's when none.
  * @throws a `ScriptError` when the file is in no package, the framework cannot read it, or it exports no single
  *   component.
  */
@@ -34,10 +40,11 @@ export const newStoriesFile = async (componentFile, exportName, framework) => {
     if (manifest === undefined)
         throw new ScriptError(`${componentFile} is in no package`);
     const packageDir = dirname(manifest);
-    const docsModule = await frameworkDocsModule(packageDir, framework);
+    const frameworkName = framework ?? (await catalogueFramework(packageDir));
+    const docsModule = await frameworkDocsModule(packageDir, frameworkName);
     if (docsModule.extractFileComponent === undefined)
-        throw new ScriptError(`@forgebook/${framework} cannot read a component from its file yet`, {
-            hint: `Update @forgebook/${framework}`
+        throw new ScriptError(`@forgebook/${frameworkName} cannot read a component from its file yet`, {
+            hint: `Update @forgebook/${frameworkName}`
         });
     const component = docsModule.extractFileComponent(componentFile, exportName);
     if (typeof component === "string")
@@ -45,14 +52,19 @@ export const newStoriesFile = async (componentFile, exportName, framework) => {
     if (!("file" in component))
         throw new ScriptError(`${componentFile} exports no component`);
     const name = component.docs.name;
-    const file = join(dirname(componentFile), `${name}.stories.tsx`);
-    const title = autoTitle(await titleBase(packageDir, file), relative(packageDir, file)) ?? name;
+    const importPath = `./${basename(componentFile).replace(/\.[cm]?[jt]sx?$/, "")}`;
+    const shape = docsModule.storyFileShape?.(name, componentFile) ?? {
+        extension: ".stories.tsx",
+        importStatement: `import { ${name} } from ${JSON.stringify(importPath)};`
+    };
+    const file = join(dirname(componentFile), `${name}${shape.extension}`);
+    // the title is read by `/`, so the path is written with them on Windows too
+    const title = autoTitle(await titleBase(packageDir, file), VITE_PATHS.relative(packageDir, file)) ?? name;
     const text = newStories({
         docs: component.docs,
-        importPath: `./${basename(componentFile).replace(/\.[cm]?[jt]sx?$/, "")}`,
+        importStatement: shape.importStatement,
         title,
-        typesModule: docsModule.storyTypesModule ?? `@forgebook/${framework}`
+        typesModule: docsModule.storyTypesModule ?? `@forgebook/${frameworkName}`
     });
     return { file, text };
 };
-//# sourceMappingURL=newStoriesFile.js.map

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

@@ -0,0 +1,8 @@
+import type { McpTool } from "../../src/vite/mcpProtocol.ts";
+import { type Ask } from "./mcpToolParts.ts";
+/**
+ * The tools.
+ *
+ * @param ask - asks the catalogue.
+ */
+export declare const pageTools: (ask: Ask) => readonly McpTool[];

package/dist/bin/forgebook/pageTools.js

@@ -0,0 +1,71 @@
+/**
+ * The tools that read a catalogue's docs: `list_pages`, `get_page` and `search_catalogue`, each answered as the command
+ * of the same name answers.
+ *
+ * @module
+ */
+import { isPagesDocument } from "../../src/vite/agentApi.js";
+import { resultOf, textOf, VIEW } from "./mcpToolParts.js";
+/**
+ * The tools.
+ *
+ * @param ask - asks the catalogue.
+ */
+export const pageTools = (ask) => [
+    {
+        name: "list_pages",
+        description: "List the catalogue's docs pages (guides, foundations, recipes) in reading order, each with its id, what it is about, the stories it shows and the address that opens it. Read one with get_page before writing against a guide.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                source: { type: "string", description: "Only this source's pages (its id)." },
+                view: VIEW
+            },
+            additionalProperties: false
+        },
+        call: async (args) => {
+            const answer = await ask("pages", new URLSearchParams({ view: textOf(args, "view") ?? "" }));
+            if (answer.status !== 200 || !isPagesDocument(answer.body))
+                return resultOf(answer);
+            const source = textOf(args, "source");
+            const pages = answer.body.pages.filter((page) => source === undefined || page.source === source);
+            return { structured: { ...answer.body, pages }, isError: false };
+        }
+    },
+    {
+        name: "get_page",
+        description: "One docs page to read: its Markdown (a ```story <id> fence is a live story, which get_story reads), its headings, and the address that opens it for a person.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: {
+                    type: "string",
+                    description: "The page's id, as list_pages gives it; `home` for the catalogue's written home."
+                },
+                view: VIEW
+            },
+            required: ["id"],
+            additionalProperties: false
+        },
+        call: async (args) => resultOf(await ask("page", new URLSearchParams({ id: textOf(args, "id") ?? "", view: textOf(args, "view") ?? "" })))
+    },
+    {
+        name: "search_catalogue",
+        description: "Search the whole catalogue by its text: docs pages, props, events, descriptions, stories and names, as a person's search in the catalogue does. Use it to find which component has a prop, or where the docs say something; to find a component by what it is for, find_component. Each result lists what matched, the words it missed and the address that opens the exact heading or prop.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "The words to look for: a prop's name, a sentence." },
+                limit: { type: "number", description: "How many results to give; 8 by default, 50 at most." },
+                view: VIEW
+            },
+            required: ["query"],
+            additionalProperties: false
+        },
+        call: async (args) => resultOf(await ask("search", new URLSearchParams({
+            query: textOf(args, "query") ?? "",
+            limit: String(args["limit"] ?? ""),
+            view: textOf(args, "view") ?? ""
+        })))
+    }
+];

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

@@ -0,0 +1,14 @@
+/**
+ * The commands that read a catalogue's docs: `pages` (the list), `page` (one, to read) and `search` (everything, by
+ * its text).
+ *
+ * @module
+ */
+import type { CommandNode, CommandScope } from "@ensiria/cli-kit/commands.types";
+import { type ForgebookOptions } from "./catalogueCommands.ts";
+/**
+ * The commands.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export declare const pagesCommands: (forgebook: CommandScope<ForgebookOptions>) => Readonly<Record<string, CommandNode>>;

package/dist/bin/forgebook/pagesCommands.mjs

@@ -0,0 +1,109 @@
+import { EXIT } from "@ensiria/cli-kit/constants";
+import { ScriptError } from "@ensiria/cli-kit/script";
+import { MAX_QUERY } from "../../src/search.js";
+import { isPageDocument, isPagesDocument, isSearchDocument } from "../../src/vite/agentApi.js";
+import { pagesText, pageText, searchText } from "./agentText.js";
+import { askCatalogue, COMMAND, configOf, printAnswer, printTokenAnswer } from "./catalogueCommands.js";
+/** What both commands take. */
+const PAGE_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)."
+    }
+};
+/**
+ * The commands.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export const pagesCommands = (forgebook) => ({
+    pages: forgebook.command({
+        summary: "List the catalogue's docs pages, with their ids and addresses; fail when the index has problems.",
+        json: true,
+        options: {
+            ...PAGE_OPTIONS,
+            source: { type: "string", valueName: "id", description: "Only this source's pages." }
+        },
+        examples: [
+            { command: `${COMMAND} pages`, description: "Every page, in reading order." },
+            { command: `${COMMAND} pages --source kit --json`, description: "One library's pages, as JSON." }
+        ],
+        run: async ({ options, io, log, isJson, style }) => {
+            const config = await configOf(options.config);
+            const params = new URLSearchParams({ view: options.view ?? "" });
+            const body = await askCatalogue(config, options.url, "pages", params, log);
+            if (!isPagesDocument(body))
+                throw new ScriptError("The catalogue's answer has an unexpected shape");
+            const { source } = options;
+            const pages = body.pages.filter((page) => source === undefined || page.source === source);
+            const document = { ...body, pages };
+            printAnswer(pagesText(document, style), document, document.problems, { io, log, isJson });
+        }
+    }),
+    page: forgebook.command({
+        summary: "Print one docs page: its Markdown, its headings with --json, the address that opens it.",
+        json: true,
+        options: PAGE_OPTIONS,
+        positionals: [
+            {
+                name: "id",
+                description: "The page's id, as forgebook pages lists it; home for the catalogue's written home.",
+                required: true
+            }
+        ],
+        examples: [
+            { command: `${COMMAND} page kit:guides-theming`, description: "Read a page." },
+            { command: `${COMMAND} page kit:guides-theming --json`, description: "With its headings, as JSON." }
+        ],
+        run: async ({ args, options, io, log, isJson }) => {
+            const config = await configOf(options.config);
+            const params = new URLSearchParams({ id: args.id, view: options.view ?? "" });
+            const body = await askCatalogue(config, options.url, "page", params, log);
+            if (!isPageDocument(body))
+                throw new ScriptError("The catalogue's answer has an unexpected shape");
+            printAnswer(pageText(body), body, body.problems, { io, log, isJson });
+        }
+    }),
+    search: forgebook.command({
+        summary: "Search the whole catalogue by its text: docs pages, props, descriptions, stories and names.",
+        json: true,
+        options: {
+            ...PAGE_OPTIONS,
+            limit: {
+                type: "number",
+                valueName: "count",
+                description: "How many results to give: 8 by default, 50 at most."
+            }
+        },
+        positionals: [{ name: "query", description: "The words to look for.", required: true }],
+        examples: [
+            { command: `${COMMAND} search onValueChange`, description: "The components with that prop." },
+            {
+                command: `${COMMAND} search "how the theme reaches a story" --json`,
+                description: "A sentence of the docs, with the address of its heading."
+            }
+        ],
+        run: async ({ args, options, io, log, isJson }) => {
+            const config = await configOf(options.config);
+            const { limit } = options;
+            if (limit !== undefined && (!Number.isInteger(limit) || limit < 1))
+                throw new ScriptError("--limit takes a whole number above 0", { exitCode: EXIT.usage });
+            const params = new URLSearchParams({
+                query: args.query.slice(0, MAX_QUERY),
+                view: options.view ?? "",
+                limit: String(limit ?? "")
+            });
+            const body = await askCatalogue(config, options.url, "search", params, log);
+            if (!isSearchDocument(body))
+                throw new ScriptError("The catalogue's answer has an unexpected shape");
+            printTokenAnswer(searchText(body), body, { io, log, isJson });
+        }
+    })
+});

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

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