forgebook 0.1.2 → 0.1.4

package/dist/bin/forgebook/agentText.js

@@ -0,0 +1,91 @@
+/**
+ * The answers of `forgebook stories`, `forgebook story`, `forgebook check` and `forgebook errors` as text for a
+ * terminal: a table of the stories, one story's facts, a check's problems, the frames' errors, the pictures taken. Pure: documents in, text out, laid out with cli-kit's helpers.
+ *
+ * @remarks
+ * Nothing is cut to the terminal's width: ids and links are what a reader copies, so a long line wraps instead.
+ *
+ * @module
+ */
+import { formatJson } from "@ensiria/cli-kit/files";
+import { keyValue, table } from "@ensiria/cli-kit/layout";
+/** The style with no width to fit, so no cell is cut. */
+const uncut = (style) => ({ ...style, width: Number.POSITIVE_INFINITY });
+/**
+ * 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.
+ *
+ * @param document - the stories document.
+ * @param style - colours, glyphs and width.
+ */
+export const storiesText = (document, style) => table(document.components.flatMap((component) => component.stories.map((story) => [
+    story.id,
+    `${component.title} › ${story.name}${story.isUnlisted ? " (unlisted)" : ""}`
+])), { columns: [{ header: "Id" }, { header: "Story", tone: "muted" }] }, uncut(style));
+/**
+ * One story's facts: where it is, where it opens, its args and its component's props.
+ *
+ * @param document - the story document.
+ * @param style - colours, glyphs and width.
+ */
+export const storyText = (document, style) => {
+    const entries = [
+        ["Story", `${document.component.title} › ${document.story.name}`],
+        ["Id", document.story.id],
+        ["File", document.component.file],
+        ["Opens at", document.story.links.address],
+        ["Frame", document.story.links.frame],
+        ["Args", JSON.stringify(document.args)],
+        ["Props", document.docs === undefined ? "none" : document.docs.props.map((prop) => prop.name).join(", ")]
+    ];
+    if (document.story.description !== undefined)
+        entries.push(["About", document.story.description]);
+    return keyValue(entries, uncut(style));
+};
+/**
+ * A check's report as a table: one row per problem, its story, its view and its kind; a story that passes in a view gets
+ * one row saying so.
+ *
+ * @param report - the check's report.
+ * @param style - colours, glyphs and width.
+ */
+export const checkText = (report, style) => table(report.results.flatMap((result) => result.problems.length === 0
+    ? [[result.storyId, result.view || "default", "passes"]]
+    : result.problems.map((problem) => [
+        result.storyId,
+        result.view || "default",
+        `${problem.kind}: ${problem.message}`
+    ])), { columns: [{ header: "Story" }, { header: "View", tone: "muted" }, { header: "Result" }] }, uncut(style));
+/**
+ * The frames' errors as a table: their number, the story, what went wrong; nothing when there are none.
+ *
+ * @param document - the errors document.
+ * @param style - colours, glyphs and width.
+ */
+export const errorsText = (document, style) => document.errors.length === 0
+    ? ""
+    : table(document.errors.map((error) => [String(error.n), error.storyId, `${error.kind}: ${error.message}`]), { columns: [{ header: "#", tone: "muted" }, { header: "Story" }, { header: "Error" }] }, uncut(style));
+/**
+ * What `forgebook errors` prints of an answer: its JSON (one line per error while following, so each can be read as it
+ * comes), or its table.
+ *
+ * @param document - the errors document.
+ * @param mode - whether as JSON, and whether following.
+ * @param style - colours, glyphs and width.
+ */
+export const errorsOutput = (document, mode, style) => {
+    if (!mode.isJson)
+        return `${errorsText(document, style)}\n`;
+    if (mode.isFollowing)
+        return document.errors.map((error) => `${JSON.stringify(error)}\n`).join("");
+    return formatJson(document);
+};
+/**
+ * The pictures taken as a table: the story, the view, the file.
+ *
+ * @param report - the picture run's report.
+ * @param shownFile - how a file is written for the reader (relative to where the command runs).
+ * @param style - colours, glyphs and width.
+ */
+export const shotText = (report, shownFile, style) => table(report.shots.map((shot) => [shot.storyId, shot.view || "default", shownFile(shot.file)]), { columns: [{ header: "Story" }, { header: "View", tone: "muted" }, { header: "Picture" }] }, uncut(style));
+//# sourceMappingURL=agentText.js.map

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

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

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"}