forgebook 0.1.8 → 0.2.0

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

@@ -11,6 +11,14 @@ export type CatalogueClient = {
     /** Stops the server it started; nothing for a running one. */
     readonly close: () => Promise<void>;
 };
+/**
+ * The answers of a built catalogue, from its index.
+ *
+ * @param from - its address, or its folder; the links work from an address, and are paths from a folder.
+ * @returns the client.
+ * @throws when there is no index, or this version cannot read it.
+ */
+export declare const indexClient: (from: string) => Promise<CatalogueClient>;
 /** A catalogue a browser can open: its address, and how to let it go. */
 export type ServedCatalogue = {
     /** Its address (`http://localhost:5173`). */
@@ -36,4 +44,25 @@ export declare const servedCatalogue: (config: ResolvedConfig, url: string | und
  * @param url - where `forgebook dev` runs, when not at Vite's default address.
  */
 export declare const catalogueClient: (config: ResolvedConfig, url: string | undefined) => Promise<CatalogueClient>;
-//# sourceMappingURL=agentClient.d.ts.map
+/** Where a client that renders apps gets a story's preview from. */
+export type PreviewServer = {
+    /** The address previews will come from, with nothing started: a host may read it before any story is asked for. */
+    readonly origin: () => Promise<string>;
+    /** Serves the catalogue at that address, once, and answers it. */
+    readonly serve: () => Promise<string>;
+    /** Stops what it started. */
+    readonly close: () => Promise<void>;
+};
+/**
+ * The previews' server: the running dev server, or one of its own started when the first preview is asked for.
+ *
+ * @remarks
+ * A host learns the origin it may frame when it reads the app's resource, which it may do at connection, long before
+ * anyone asks for a story. So the address is settled then, a port taken from the system and left free, and the server
+ * comes up on that port only when a story is asked for; were another program to take the port in between, the preview
+ * fails and the page falls back to a picture.
+ *
+ * @param config - the catalogue's configuration.
+ * @param runningAt - the running dev server, when there is one.
+ */
+export declare const previewServer: (config: ResolvedConfig, runningAt: string | undefined) => PreviewServer;

package/dist/bin/forgebook/agentClient.js

@@ -6,13 +6,18 @@
  * A running `forgebook dev` answers at once and its links work. A server of their own is started in the same process
  * (Vite in middleware mode: no port, nothing reachable from outside) and the same function answers; its links name
  * where `forgebook dev` serves by default, so they work once it runs. A server found at the address is used only when
- * it says it serves this catalogue's folder (`ROOT_HEADER`), never another project's catalogue on the same port.
+ * it says it serves this catalogue's folder (`ROOT_HEADER`), never another project's catalogue on the same port. A
+ * server of their own keeps its pre-bundled dependencies apart from the dev server's (`commandServer.ts`).
  *
  * @module
  */
+import { readFile } from "node:fs/promises";
+import { createServer as createNetServer } from "node:net";
+import { resolve } from "node:path";
 import { createServer } from "vite";
-import { AGENT_API, agentAnswer, ROOT_HEADER, rootHeaderValue } from "../../src/vite/agentRoutes.js";
-import { catalogueVite } from "./catalogueVite.js";
+import { AGENT_INDEX_FILE, indexAnswer, isAgentIndex } from "../../src/vite/agentIndex.js";
+import { AGENT_API, agentAnswer, agentServer, ROOT_HEADER, rootHeaderValue } from "../../src/vite/agentRoutes.js";
+import { commandServerVite } from "./commandServer.js";
 /** Where `forgebook dev` serves when no port is given: Vite's default. */
 export const DEFAULT_ORIGIN = "http://localhost:5173";
 /**
@@ -45,17 +50,112 @@ const runningClient = async (origin, config) => {
  * @param origin - the address the links name.
  */
 const ownClient = async (config, origin) => {
-    const server = await createServer(await catalogueVite(config, {
+    const server = await createServer(await commandServerVite(config, {
         server: { middlewareMode: true, hmr: false },
         appType: "custom",
         logLevel: "error"
     }));
     return {
-        ask: (route, params) => agentAnswer((id) => server.ssrLoadModule(id), config, route, params, origin),
+        ask: (route, params) => agentAnswer(agentServer(server, config), config, route, params, { catalogue: origin, frames: origin }),
         runningAt: undefined,
         close: () => server.close()
     };
 };
+/** The largest index read, in bytes, and how long an address may take: what it answers is not trusted. */
+const MAX_INDEX_BYTES = 64 * 1024 * 1024;
+const INDEX_TIMEOUT = 30_000;
+/** A response's text, up to the largest index: an endless answer would otherwise fill the memory. */
+const boundedText = async (response, address) => {
+    const parts = [];
+    let size = 0;
+    for await (const part of response.body ?? []) {
+        size += part.byteLength;
+        if (size > MAX_INDEX_BYTES)
+            throw new Error(`${address} is over ${MAX_INDEX_BYTES} bytes`);
+        parts.push(part);
+    }
+    return Buffer.concat(parts).toString("utf8");
+};
+/** Where `forgebook mcp --from` reads the index: a built catalogue's address, or its folder. */
+const indexSource = (from) => {
+    if (!/^https?:\/\//i.test(from)) {
+        return { text: () => readFile(resolve(from, AGENT_INDEX_FILE), "utf8"), origin: "" };
+    }
+    const origin = from.replace(/\/+$/, "");
+    const address = `${origin}/${AGENT_INDEX_FILE}`;
+    const text = async () => {
+        const response = await fetch(address, { signal: AbortSignal.timeout(INDEX_TIMEOUT) });
+        if (!response.ok)
+            throw new Error(`${address} answered ${response.status}`);
+        return boundedText(response, address);
+    };
+    return { text, origin };
+};
+/** The parsed index: a host's fallback page is not JSON, and that is the same as no index. */
+const parsedIndex = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** An answer that can be sent: a file's shape is checked only at its top, and text too deep to write must not end the server. */
+const sendable = (answer) => {
+    try {
+        JSON.stringify(answer.body);
+        return answer;
+    }
+    catch {
+        return { status: 500, body: { error: "The index holds an answer that cannot be written" } };
+    }
+};
+/**
+ * The answers of a built catalogue, from its index.
+ *
+ * @param from - its address, or its folder; the links work from an address, and are paths from a folder.
+ * @returns the client.
+ * @throws when there is no index, or this version cannot read it.
+ */
+export const indexClient = async (from) => {
+    const { text, origin } = indexSource(from);
+    const index = parsedIndex(await text());
+    if (!isAgentIndex(index)) {
+        throw new Error(`${from} holds no index this version reads: \`forgebook build --agent-index\` writes it`);
+    }
+    const pages = { page: `${origin}/`, frame: `${origin}/frame.html` };
+    return {
+        ask: async (route, params) => sendable(indexAnswer(index, pages, route, params)),
+        runningAt: undefined,
+        close: async () => undefined
+    };
+};
+/**
+ * A dev server of its own, listening on the local address.
+ *
+ * @param config - the catalogue's configuration.
+ * @param port - the port, which must be free; 0 for any free one.
+ */
+const ownListening = async (config, port) => {
+    const server = await createServer(await commandServerVite(config, {
+        server: { port, strictPort: port !== 0, host: "127.0.0.1" },
+        logLevel: "error"
+    }));
+    try {
+        await server.listen();
+    }
+    catch (error) {
+        // a server that could not listen still watches the files, which would keep the process alive
+        await server.close();
+        throw error;
+    }
+    const address = server.resolvedUrls?.local[0]?.replace(/\/+$/, "");
+    if (address === undefined) {
+        await server.close();
+        throw new Error("The catalogue's dev server started with no address");
+    }
+    return { origin: address, runningAt: undefined, close: () => server.close() };
+};
 /**
  * The catalogue served over HTTP, for a browser to open its frames: the running dev server at the address when it
  * serves this catalogue, else a dev server of its own on a free port (its answers' middleware has no address).
@@ -68,14 +168,7 @@ export const servedCatalogue = async (config, url) => {
     const running = await runningClient(origin, config);
     if (running !== undefined)
         return { origin, runningAt: origin, close: async () => undefined };
-    const server = await createServer(await catalogueVite(config, { server: { port: 0, host: "127.0.0.1" }, logLevel: "error" }));
-    await server.listen();
-    const address = server.resolvedUrls?.local[0]?.replace(/\/+$/, "");
-    if (address === undefined) {
-        await server.close();
-        throw new Error("The catalogue's dev server started with no address");
-    }
-    return { origin: address, runningAt: undefined, close: () => server.close() };
+    return ownListening(config, 0);
 };
 /**
  * The catalogue's answers: the running dev server at the address when it serves this catalogue, a server of its own
@@ -88,4 +181,52 @@ export const catalogueClient = async (config, url) => {
     const origin = (url ?? DEFAULT_ORIGIN).replace(/\/+$/, "");
     return (await runningClient(origin, config)) ?? ownClient(config, origin);
 };
-//# sourceMappingURL=agentClient.js.map
+/** A port free right now, asked of the system. */
+const freePort = () => new Promise((done, fail) => {
+    const probe = createNetServer();
+    probe.once("error", fail);
+    probe.listen(0, "127.0.0.1", () => {
+        const address = probe.address();
+        const port = typeof address === "object" && address !== null ? address.port : 0;
+        probe.close(() => done(port));
+    });
+});
+/**
+ * The previews' server: the running dev server, or one of its own started when the first preview is asked for.
+ *
+ * @remarks
+ * A host learns the origin it may frame when it reads the app's resource, which it may do at connection, long before
+ * anyone asks for a story. So the address is settled then, a port taken from the system and left free, and the server
+ * comes up on that port only when a story is asked for; were another program to take the port in between, the preview
+ * fails and the page falls back to a picture.
+ *
+ * @param config - the catalogue's configuration.
+ * @param runningAt - the running dev server, when there is one.
+ */
+export const previewServer = (config, runningAt) => {
+    if (runningAt !== undefined)
+        return { origin: async () => runningAt, serve: async () => runningAt, close: async () => undefined };
+    let port;
+    let served;
+    const portOf = () => {
+        port ??= freePort();
+        return port;
+    };
+    const started = async () => ownListening(config, await portOf());
+    return {
+        origin: async () => `http://127.0.0.1:${await portOf()}`,
+        serve: async () => {
+            served ??= started();
+            try {
+                return (await served).origin;
+            }
+            catch (error) {
+                served = undefined;
+                throw error;
+            }
+        },
+        close: async () => {
+            await (await served)?.close();
+        }
+    };
+};

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

@@ -6,4 +6,3 @@ import { type ForgebookOptions } from "./catalogueCommands.ts";
  * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
  */
 export declare const agentLoopCommands: (forgebook: CommandScope<ForgebookOptions>) => Readonly<Record<string, CommandNode>>;
-//# sourceMappingURL=agentLoopCommands.d.mts.map

package/dist/bin/forgebook/agentLoopCommands.mjs

@@ -4,7 +4,7 @@
  * (a story's pictures, to look at it).
  *
  * @remarks
- * Defined here, on the scope `forgebook.mts` hands them, so the entry stays a list of commands; their work lives in
+ * Defined here, on the scope `forgebookCommands.mts` hands them, so the commands module stays a list of commands; their work lives in
  * their own modules (`agentsText.ts`, `storyCheckRun.ts`, `errorsRun.ts`).
  *
  * @module
@@ -14,12 +14,16 @@ import { dirname, relative, 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 { isChangedStoriesDocument, isFoundComponentsDocument } from "../../src/vite/agentApi.js";
 import { catalogueClient } from "./agentClient.js";
-import { agentsSkill, withAgentsSection } from "./agentsText.js";
-import { checkText, errorsOutput, shotText } from "./agentText.js";
-import { COMMAND, configOf } from "./catalogueCommands.js";
+import { agentsSkill, SKILL_FOLDERS, withAgentsSection } from "./agentsText.js";
+import { checkText, errorsOutput, foundComponentsText, shotText } from "./agentText.js";
+import { askCatalogue, COMMAND, configOf, printAnswer } from "./catalogueCommands.js";
+import { runCheckCode } from "./checkCodeRun.js";
 import { askErrors, followErrors, sinceOf } from "./errorsRun.js";
-import { runStoryCheck, runStoryShot } from "./storyCheckRun.js";
+import { storyCheckCommands } from "./storyCheckCommands.mjs";
+import { runPageCheck, runStoryCheck, runStoryShot } from "./storyCheckRun.js";
+import { BASELINES_FOLDER, updateBaselines } from "./visualCommands.mjs";
 /**
  * The catalogue the errors are asked of: only frames open in a browser report to a running dev server, so without one
  * there is nothing to list (said) and nothing ever to follow (refused).
@@ -43,26 +47,33 @@ const errorsClient = async (config, url, isFollowing, log) => {
     log.warn("No catalogue running there: only frames open in a browser report, so there is nothing to list");
     return client;
 };
+/** Where `forgebook dev` runs, for the commands that ask it. */
+const URL_OPTION = {
+    type: "string",
+    env: "FORGEBOOK_URL",
+    valueName: "address",
+    description: "Where forgebook dev runs, when not at Vite's default address (http://localhost:5173)."
+};
+/** The stories a change touches, as the catalogue answers. */
+const changedOf = async (config, options, log) => {
+    const params = new URLSearchParams({ since: options.since ?? "" });
+    const body = await askCatalogue(config, options.url, "changed", params, log);
+    if (!isChangedStoriesDocument(body))
+        throw new ScriptError("The catalogue's answer has an unexpected shape");
+    return body;
+};
 /**
  * The commands.
  *
  * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
  */
 export const agentLoopCommands = (forgebook) => ({
-    check: forgebook.command({
-        summary: "Run the catalogue's checks on a story in a browser: accessibility, spills, overlays, errors.",
+    ...storyCheckCommands(forgebook),
+    find: forgebook.command({
+        summary: "Find components by what they are for, in your own words.",
         json: true,
+        positionals: [{ name: "query", description: "What you are looking for.", required: true }],
         options: {
-            view: {
-                type: "string",
-                multiple: true,
-                valueName: "query",
-                description: "A view to check it in, as the catalogue's address writes it (theme=dark&width=360); the default view when none."
-            },
-            "all-variants": {
-                type: "boolean",
-                description: "Check every variant the catalogue's browser tests check."
-            },
             url: {
                 type: "string",
                 env: "FORGEBOOK_URL",
@@ -70,26 +81,93 @@ export const agentLoopCommands = (forgebook) => ({
                 description: "Where forgebook dev runs, when not at Vite's default address (http://localhost:5173)."
             }
         },
-        positionals: [
-            { name: "id", description: "A story's id, or a component's for its listed stories.", required: true }
+        examples: [
+            { command: `${COMMAND} find modal`, description: "Whatever this catalogue calls a modal." },
+            { command: `${COMMAND} find "radio tile group" --json`, description: "As an agent asks." }
         ],
+        run: async ({ options, args, io, log, isJson }) => {
+            const config = await configOf(options.config);
+            const params = new URLSearchParams({ query: args.query });
+            const body = await askCatalogue(config, options.url, "find", params, log);
+            if (!isFoundComponentsDocument(body)) {
+                throw new ScriptError("The catalogue's answer has an unexpected shape");
+            }
+            printAnswer(foundComponentsText(body), body, [], { io, log, isJson });
+        }
+    }),
+    changed: forgebook.command({
+        summary: "List the stories a change touches, through what they import.",
+        json: true,
+        options: {
+            since: {
+                type: "string",
+                valueName: "ref",
+                description: "The commit to compare with; HEAD by default, so what is not committed."
+            },
+            url: URL_OPTION
+        },
         examples: [
-            {
-                command: `${COMMAND} check kit:inputs-select--overview`,
-                description: "One story, in the default view."
+            { command: `${COMMAND} changed`, description: "What your uncommitted work touches." },
+            { command: `${COMMAND} changed --since origin/develop --json`, description: "What a branch touches." }
+        ],
+        run: async ({ options, io, log, isJson }) => {
+            const config = await configOf(options.config);
+            const body = await changedOf(config, options, log);
+            const text = body.stories.map((story) => story.id).join("\n");
+            io.stdout.write(isJson ? formatJson(body) : `${text === "" ? "No story touched." : text}\n`);
+        }
+    }),
+    verify: forgebook.command({
+        summary: "Run the catalogue's checks on every story a change touches, with one exit code.",
+        json: true,
+        options: {
+            since: {
+                type: "string",
+                valueName: "ref",
+                description: "The commit to compare with; HEAD by default, so what is not committed."
             },
+            url: URL_OPTION
+        },
+        examples: [
+            { command: `${COMMAND} verify`, description: "Before you say a change is done." },
+            { command: `${COMMAND} verify --since origin/develop --json`, description: "In a pull request." }
+        ],
+        run: async ({ options, io, log, isJson, style }) => {
+            const config = await configOf(options.config);
+            const { stories, files } = await changedOf(config, options, log);
+            const reports = [];
+            for (const story of stories) {
+                const report = await runStoryCheck(config, options.url, {
+                    id: story.id,
+                    views: [],
+                    isAllVariants: false
+                });
+                if (typeof report === "string")
+                    throw new ScriptError(report);
+                reports.push(report);
+            }
+            const problems = reports
+                .flatMap((report) => report.results)
+                .reduce((sum, each) => sum + each.problems.length, 0);
+            const text = reports.length === 0 ? "No story touched." : reports.map((each) => checkText(each, style)).join("\n");
+            io.stdout.write(isJson ? formatJson({ schema: 1, files, stories, reports, problems }) : `${text}\n`);
+            if (problems > 0)
+                throw new ScriptError(`${problems} problems`, { exitCode: EXIT.failure, isReported: true });
+        }
+    }),
+    "check-page": forgebook.command({
+        summary: "Run the checks on a real page of the application: accessibility, what spills, its errors.",
+        json: true,
+        positionals: [{ name: "address", description: "The page's address.", required: true }],
+        examples: [
             {
-                command: `${COMMAND} check kit:inputs-select --view "theme=dark" --json`,
-                description: "Every story of a component, in the dark theme, as JSON."
+                command: `${COMMAND} check-page http://localhost:3000/checkout`,
+                description: "The screen you built."
             }
         ],
         run: async ({ args, options, io, isJson, style }) => {
             const config = await configOf(options.config);
-            const report = await runStoryCheck(config, options.url, {
-                id: args.id,
-                views: options.view ?? [],
-                isAllVariants: options["all-variants"] === true
-            });
+            const report = await runPageCheck(config, [args.address]);
             if (typeof report === "string")
                 throw new ScriptError(report);
             io.stdout.write(isJson ? formatJson(report) : `${checkText(report, style)}\n`);
@@ -98,6 +176,34 @@ export const agentLoopCommands = (forgebook) => ({
                 throw new ScriptError(`${problems} problems`, { exitCode: EXIT.failure, isReported: true });
         }
     }),
+    "check-code": forgebook.command({
+        summary: "Check what a change adds against the design system, with an exit code for CI.",
+        json: true,
+        options: {
+            since: {
+                type: "string",
+                valueName: "ref",
+                description: "The commit to compare with; HEAD by default, so what is not committed."
+            },
+            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} check-code`, description: "Your uncommitted work." },
+            {
+                command: `${COMMAND} check-code --since origin/develop --json`,
+                description: "A pull request, in CI."
+            }
+        ],
+        run: async ({ options, io, log, isJson }) => {
+            const config = await configOf(options.config);
+            await runCheckCode({ config, url: options.url, context: { io, log, isJson } }, options.since);
+        }
+    }),
     errors: forgebook.command({
         summary: "List what the open frames reported while you edited: stories that could not be shown, plays that failed.",
         json: true,
@@ -157,17 +263,20 @@ export const agentLoopCommands = (forgebook) => ({
                 type: "string",
                 multiple: true,
                 valueName: "view",
-                description: 'A view to picture it in: the address\'s form (theme=dark&width=360) or words ("dark it 360"); the default view when none.'
+                description: 'A view to picture it in: the address\'s form (theme=dark&width=360) or words ("dark it 360"), a device model\'s id ("iphone-16") for a framed picture; the default view when none.'
             },
             "all-variants": {
                 type: "boolean",
                 description: "Picture every variant the catalogue's browser tests check."
             },
+            update: {
+                type: "boolean",
+                description: `Store them as the baselines forgebook diff compares with: ${BASELINES_FOLDER} beside the configuration, or --out.`
+            },
             out: {
                 type: "string",
-                default: "forgebook-shots",
                 valueName: "folder",
-                description: "The folder the pictures go in."
+                description: "The folder the pictures go in; forgebook-shots by default."
             },
             url: {
                 type: "string",
@@ -184,6 +293,10 @@ export const agentLoopCommands = (forgebook) => ({
                 command: `${COMMAND} shot kit:data-badge--default --view "dark 360"`,
                 description: "Dark, 360 px wide."
             },
+            {
+                command: `${COMMAND} shot kit:screens-settings--default --view "iphone-16" --view "dark pixel-9 landscape"`,
+                description: "Framed in an iPhone 16, then in a Pixel 9 on its side, dark."
+            },
             {
                 command: `${COMMAND} shot kit:data-badge --all-variants --json`,
                 description: "Every story of a component in every variant, listed as JSON."
@@ -191,7 +304,14 @@ export const agentLoopCommands = (forgebook) => ({
         ],
         run: async ({ args, options, io, isJson, style }) => {
             const config = await configOf(options.config);
-            const report = await runStoryShot(config, options.url, { id: args.id, views: options.view ?? [], isAllVariants: options["all-variants"] === true }, resolve(options.out));
+            const input = {
+                id: args.id,
+                views: options.view ?? [],
+                isAllVariants: options["all-variants"] === true
+            };
+            const report = options.update === true
+                ? await updateBaselines(config, options.url, input, options.out)
+                : await runStoryShot(config, options.url, input, resolve(options.out ?? "forgebook-shots"));
             if (typeof report === "string")
                 throw new ScriptError(report);
             io.stdout.write(isJson ? formatJson(report) : `${shotText(report, (file) => relative(process.cwd(), file), style)}\n`);
@@ -208,13 +328,13 @@ export const agentLoopCommands = (forgebook) => ({
             },
             skill: {
                 type: "boolean",
-                description: "Also write them as a Claude Code skill, .claude/skills/forgebook/SKILL.md."
+                description: `Also write them as an Agent Skill, SKILL.md in ${SKILL_FOLDERS.join(" and ")}.`
             },
             print: { type: "boolean", description: "Print the instructions instead of writing them." }
         },
         examples: [
             { command: `${COMMAND} agents`, description: "Add or renew Forgebook's section of AGENTS.md." },
-            { command: `${COMMAND} agents --skill`, description: "And the Claude Code skill." }
+            { command: `${COMMAND} agents --skill`, description: "And the skill, for any agent." }
         ],
         run: ({ options, io, log }) => {
             const section = readFileSync(new URL("./agents.md", import.meta.url), "utf8");
@@ -228,11 +348,12 @@ export const agentLoopCommands = (forgebook) => ({
             log.success(`${relative(process.cwd(), file)}: Forgebook's section ${isNew ? "written" : "renewed"}`);
             if (options.skill !== true)
                 return;
-            const skill = resolve(".claude", "skills", "forgebook", "SKILL.md");
-            mkdirSync(dirname(skill), { recursive: true });
-            writeFileSync(skill, agentsSkill(section));
-            log.success(`${relative(process.cwd(), skill)} written`);
+            for (const folder of SKILL_FOLDERS) {
+                const skill = resolve(folder, "SKILL.md");
+                mkdirSync(dirname(skill), { recursive: true });
+                writeFileSync(skill, agentsSkill(section));
+                log.success(`${relative(process.cwd(), skill)} written`);
+            }
         }
     })
 });
-//# sourceMappingURL=agentLoopCommands.mjs.map

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

@@ -1,6 +1,8 @@
 import type { OutputStyle } from "@ensiria/cli-kit/log.types";
-import type { StoryCheckReport, StoryShotReport } from "../../src/storyCheck.ts";
-import type { ErrorsDocument, StoriesDocument, StoryDocument } from "../../src/vite/agent.types.ts";
+import type { StoryCheckReport, StoryDiffReport, StoryShotReport } from "../../src/storyCheck.ts";
+import type { CheckedCodeDocument, ErrorsDocument, FoundComponentsDocument, NearestTokensDocument, PageDocument, PagesDocument, PluginsDocument, SearchDocument, StoriesDocument, StoryDocument, TokensDocument } from "../../src/vite/agent.types.ts";
+import type { DesignToken } from "../../src/vite/designTokens.ts";
+import type { TokenClash } from "../../src/vite/tokenClashes.ts";
 /**
  * The stories as a table: one row per story, its id first (what `forgebook story` takes, never cut), then its
  * component's title and its name.
@@ -51,4 +53,73 @@ export declare const errorsOutput: (document: ErrorsDocument, mode: {
  * @param style - colours, glyphs and width.
  */
 export declare const shotText: (report: StoryShotReport, shownFile: (file: string) => string, style: OutputStyle) => string;
-//# sourceMappingURL=agentText.d.ts.map
+/**
+ * A comparison with the baselines as a person reads it.
+ *
+ * @param report - the results.
+ * @param shownFile - how a file is named.
+ * @param style - the output's style.
+ */
+export declare const diffText: (report: StoryDiffReport, shownFile: (file: string) => string, style: OutputStyle) => string;
+/**
+ * Tokens as a person reads them: one line each, how many there are when it is more than the list, and why when none.
+ *
+ * @param document - the answer.
+ */
+export declare const tokensText: (document: TokensDocument) => string;
+/**
+ * One token as a person reads it.
+ *
+ * @param token - the token.
+ */
+export declare const tokenText: (token: DesignToken) => string;
+/**
+ * A clash as a person reads it: which file's value stands, and which it replaced.
+ *
+ * @param clash - the clash.
+ */
+export declare const clashText: ({ name, mode, kept, replaced }: TokenClash) => string;
+/**
+ * The tokens nearest a value as a person reads them, saying which are really near.
+ *
+ * @param document - the answer.
+ */
+export declare const nearestTokensText: (document: NearestTokensDocument) => string;
+/**
+ * The components a query found as a person reads them, saying which words did not match.
+ *
+ * @param document - the answer.
+ */
+export declare const foundComponentsText: (document: FoundComponentsDocument) => string;
+/**
+ * What a change broke as a person reads it, a line a problem.
+ *
+ * @param document - the answer.
+ */
+export declare const checkedCodeText: (document: CheckedCodeDocument) => string;
+/**
+ * The catalogue's plugins, one per line.
+ *
+ * @param document - the answer.
+ */
+export declare const pluginsText: (document: PluginsDocument) => string;
+/**
+ * The docs pages as a table: one row per page, its id first (what `forgebook page` takes), then its title and how many
+ * stories it shows.
+ *
+ * @param document - the pages document.
+ * @param style - colours, glyphs and width.
+ */
+export declare const pagesText: (document: PagesDocument, style: OutputStyle) => string;
+/**
+ * One docs page as a person reads it: where it opens, then its Markdown.
+ *
+ * @param document - the page's document.
+ */
+export declare const pageText: (document: PageDocument) => string;
+/**
+ * What a search found as a person reads it: each result with its address, then what matched inside it.
+ *
+ * @param document - the search's document.
+ */
+export declare const searchText: (document: SearchDocument) => string;