forgebook 0.1.3 → 0.1.5

package/dist/bin/forgebook/storyCheckRun.js

@@ -0,0 +1,178 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * What `forgebook check` and `forgebook shot` (and their MCP tools `check_story` and `story_shot`) run: the stories an
+ * id names, opened in a browser in the views asked for, checked or pictured through `@forgebook/testing`, loaded from
+ * the project.
+ *
+ * @remarks
+ * The core has no browser: the testing package (and Playwright under it) is the project's, loaded from the catalogue's
+ * folder only when a run starts, and named in the error when it is missing. An id is a story's, or a component's, which
+ * stands for its listed stories. A view is written in the address's form or as words (`viewWords.ts`). The catalogue is
+ * served over HTTP (the running dev server, or one of its own for the run), since a browser opens the frames.
+ *
+ * @module
+ */
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { isStoryCheckReport, isStoryShotReport } from "../../src/storyCheck.js";
+import { catalogueSwitches } from "../../src/switches.js";
+import { viewQuery } from "../../src/viewWords.js";
+import { isStoriesDocument } from "../../src/vite/agentApi.js";
+import { AGENT_API } from "../../src/vite/agentRoutes.js";
+import { servedCatalogue } from "./agentClient.js";
+/** What the project installs to run the stories in a browser, and how. */
+const INSTALL = "Stories run in a browser with @forgebook/testing: npm install -D @forgebook/testing @playwright/test, then npx playwright install chromium";
+/**
+ * The stories an id names: the story itself, or a component's listed stories.
+ *
+ * @param document - the catalogue's stories.
+ * @param id - the id.
+ */
+export const storiesNamed = (document, id) => {
+    const component = document.components.find((each) => each.id === id);
+    if (component !== undefined)
+        return component.stories.filter((story) => !story.isUnlisted);
+    return document.components.flatMap((each) => each.stories.filter((story) => story.id === id));
+};
+/**
+ * The views in the address's form, or why one cannot be read.
+ *
+ * @param views - the views as given.
+ * @param switches - the catalogue's switches.
+ */
+const queriesOf = (views, switches) => {
+    const queries = [];
+    for (const view of views) {
+        const read = viewQuery(view, switches);
+        if ("error" in read)
+            return read.error;
+        queries.push(read.query);
+    }
+    return queries;
+};
+/**
+ * A function the testing package exports, resolved from the catalogue's folder as the project's own code would: the
+ * check, the pictures, the touch window.
+ *
+ * @param dir - the catalogue's folder.
+ * @param specifier - its module (`@forgebook/testing/check`).
+ * @param name - its name (`checkStories`).
+ * @returns the function, or why it cannot be had.
+ */
+export const testingFunction = async (dir, specifier, name) => {
+    let resolved;
+    try {
+        resolved = createRequire(join(dir, "package.json")).resolve(specifier);
+    }
+    catch {
+        return INSTALL;
+    }
+    const module = await import(__rewriteRelativeImportExtension(pathToFileURL(resolved).href));
+    if (typeof module !== "object" || module === null || !(name in module))
+        return `${specifier} has no ${name}: update @forgebook/testing`;
+    const found = Reflect.get(module, name);
+    if (typeof found !== "function")
+        return `${specifier}'s ${name} is not a function`;
+    return async (request) => {
+        const answer = await found(request);
+        return answer;
+    };
+};
+/**
+ * The catalogue's stories, asked of its served address.
+ *
+ * @param origin - where it is served.
+ */
+const storiesAt = async (origin) => {
+    const response = await fetch(`${origin}${AGENT_API}stories`);
+    const body = await response.json();
+    return isStoriesDocument(body) ? body : `The catalogue answered ${response.status} for its stories`;
+};
+/**
+ * Runs one of the testing package's functions on the stories an id names, the catalogue served while it runs.
+ *
+ * @param config - the catalogue's configuration.
+ * @param url - where `forgebook dev` runs, when not at Vite's default address.
+ * @param input - the id, the views and whether to run every variant.
+ * @param run - the function and what it adds to the request.
+ * @returns its answer, or why it could not run.
+ */
+const runOnStories = async (config, url, input, run) => {
+    const call = await testingFunction(config.dir, run.specifier, run.name);
+    if (typeof call === "string")
+        return call;
+    const switches = catalogueSwitches(config.switches, config.languages, config.lists.controls);
+    const views = queriesOf(input.views, switches);
+    if (typeof views === "string")
+        return views;
+    const served = await servedCatalogue(config, url);
+    try {
+        const document = await storiesAt(served.origin);
+        if (typeof document === "string")
+            return document;
+        const stories = storiesNamed(document, input.id);
+        if (stories.length === 0)
+            return `No story or component "${input.id}"`;
+        const request = {
+            frameUrl: `${served.origin}/frame.html`,
+            stories: stories.map((story) => ({
+                id: story.id,
+                ...(story.height === undefined ? {} : { height: story.height })
+            })),
+            switches,
+            lists: config.lists,
+            views,
+            isAllVariants: input.isAllVariants
+        };
+        return await call({ ...request, ...run.extra });
+    }
+    finally {
+        await served.close();
+    }
+};
+/**
+ * Runs the catalogue's checks.
+ *
+ * @param config - the catalogue's configuration.
+ * @param url - where `forgebook dev` runs, when not at Vite's default address.
+ * @param input - the id, the views and whether to check every variant.
+ * @returns the report, or why the check could not run.
+ */
+export const runStoryCheck = async (config, url, input) => {
+    const answer = await runOnStories(config, url, input, {
+        specifier: "@forgebook/testing/check",
+        name: "checkStories",
+        extra: {}
+    });
+    if (typeof answer === "string" || isStoryCheckReport(answer))
+        return answer;
+    return "@forgebook/testing/check answered something that is not a check's report";
+};
+/**
+ * Takes the stories' pictures.
+ *
+ * @param config - the catalogue's configuration.
+ * @param url - where `forgebook dev` runs, when not at Vite's default address.
+ * @param input - the id, the views and whether to picture every variant.
+ * @param outDir - the folder the pictures go in, absolute.
+ * @returns the pictures, or why they could not be taken.
+ */
+export const runStoryShot = async (config, url, input, outDir) => {
+    const answer = await runOnStories(config, url, input, {
+        specifier: "@forgebook/testing/shot",
+        name: "shotStories",
+        extra: { outDir }
+    });
+    if (typeof answer === "string" || isStoryShotReport(answer))
+        return answer;
+    return "@forgebook/testing/shot answered something that is not a picture run's report";
+};
+//# sourceMappingURL=storyCheckRun.js.map

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

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

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

@@ -0,0 +1,17 @@
+/**
+ * What `forgebook dev --touch` runs once the dev server listens: the testing package's touch window (Chromium with its
+ * own touch emulation), loaded from the project, opened on the catalogue's address without holding the server up.
+ *
+ * @module
+ */
+import type { Logger } from "@ensiria/cli-kit/log.types";
+/**
+ * Opens the touch window on the catalogue; the dev server keeps running when the window closes.
+ *
+ * @param dir - the catalogue's folder, where the testing package is resolved.
+ * @param url - the dev server's address; none when it gave none.
+ * @param log - the command's logger.
+ * @throws when the testing package or the address is missing.
+ */
+export declare const openTouchWindow: (dir: string, url: string | undefined, log: Logger) => Promise<void>;
+//# sourceMappingURL=touchWindowRun.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"touchWindowRun.d.ts","sourceRoot":"","sources":["../../../bin/forgebook/touchWindowRun.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAMzD;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAU,KAAK,MAAM,EAAE,KAAK,MAAM,GAAG,SAAS,EAAE,KAAK,MAAM,KAAG,OAAO,CAAC,IAAI,CAOrG,CAAC"}

package/dist/bin/forgebook/touchWindowRun.js

@@ -0,0 +1,21 @@
+import { ScriptError } from "@ensiria/cli-kit/script";
+import { testingFunction } from "./storyCheckRun.js";
+/**
+ * Opens the touch window on the catalogue; the dev server keeps running when the window closes.
+ *
+ * @param dir - the catalogue's folder, where the testing package is resolved.
+ * @param url - the dev server's address; none when it gave none.
+ * @param log - the command's logger.
+ * @throws when the testing package or the address is missing.
+ */
+export const openTouchWindow = async (dir, url, log) => {
+    if (url === undefined)
+        throw new ScriptError("The dev server gave no address to open the touch window on");
+    const open = await testingFunction(dir, "@forgebook/testing/touch", "openTouchWindow");
+    if (typeof open === "string")
+        throw new ScriptError(open);
+    const request = { url };
+    log.info("Touch window open: the mouse makes real touch events there (Chromium's emulation)");
+    void open(request).then(() => log.info("Touch window closed; the dev server keeps running"));
+};
+//# sourceMappingURL=touchWindowRun.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"touchWindowRun.js","sourceRoot":"","sources":["../../../bin/forgebook/touchWindowRun.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAGtD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAAE,GAAW,EAAE,GAAuB,EAAE,GAAW,EAAiB,EAAE;IACxG,IAAI,GAAG,KAAK,SAAS;QAAE,MAAM,IAAI,WAAW,CAAC,4DAA4D,CAAC,CAAC;IAC3G,MAAM,IAAI,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE,0BAA0B,EAAE,iBAAiB,CAAC,CAAC;IACvF,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,MAAM,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAuB,EAAE,GAAG,EAAE,CAAC;IAC5C,GAAG,CAAC,IAAI,CAAC,mFAAmF,CAAC,CAAC;IAC9F,KAAK,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAS,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC,CAAC;AACrG,CAAC,CAAC"}

package/dist/bin/forgebook-docs/catalogueDocs.d.ts

@@ -0,0 +1,24 @@
+import type { Logger } from "@ensiria/cli-kit/log.types";
+import type { CatalogueDocsReport } from "./catalogueDocs.types.ts";
+/** What `catalogueDocs` is asked. */
+export type CatalogueDocsRequest = {
+    /** The package's folder, absolute. */
+    readonly packageDir: string;
+    /** The framework the stories are written for (`react`). */
+    readonly framework: string;
+    /** Whether to change nothing and fail when a file is stale (CI). */
+    readonly isCheck: boolean;
+    /** The command that rewrites the files, for the hint of a stale one. */
+    readonly fixCommand: string;
+};
+/**
+ * Writes the package's `CATALOG.md` and `llms.txt`, or checks them.
+ *
+ * @param request - the package, its framework, whether to check, and the command that fixes them.
+ * @param log - where to report.
+ * @returns the report, for `--json`.
+ * @throws a `ScriptError` in a check when a file is stale or a file could not be read, or when the package's options
+ *   are wrong.
+ */
+export declare const catalogueDocs: (request: CatalogueDocsRequest, log: Logger) => Promise<CatalogueDocsReport>;
+//# sourceMappingURL=catalogueDocs.d.ts.map

package/dist/bin/forgebook-docs/catalogueDocs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogueDocs.d.ts","sourceRoot":"","sources":["../../../bin/forgebook-docs/catalogueDocs.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAIzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AASpE,qCAAqC;AACrC,MAAM,MAAM,oBAAoB,GAAG;IACjC,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS,oBAAoB,EAC7B,KAAK,MAAM,KACV,OAAO,CAAC,mBAAmB,CA+C7B,CAAC"}

package/dist/bin/forgebook-docs/catalogueDocs.js

@@ -0,0 +1,71 @@
+/**
+ * Writes a package's `CATALOG.md` and `llms.txt`, or checks that both are up to date: what `forgebook docs` and its
+ * former name `forgebook-docs` run.
+ *
+ * @module
+ */
+import { join, relative } from "node:path";
+import { readFileSafe, readJson, writeIfChanged } from "@ensiria/cli-kit/files";
+import { plural } from "@ensiria/cli-kit/format";
+import { ScriptError } from "@ensiria/cli-kit/script";
+import { frameworkDocsModule } from "../frameworkDocs.js";
+import { catalogueMarkdown } from "./catalogueMarkdown.js";
+import { catalogueOptionsOf } from "./catalogueOptions.js";
+import { collectDocs } from "./collectDocs.js";
+import { llmsText } from "./llmsText.js";
+/** The file an agent reads first, beside the catalogue. */
+const LLMS_FILE = "llms.txt";
+/**
+ * Writes the package's `CATALOG.md` and `llms.txt`, or checks them.
+ *
+ * @param request - the package, its framework, whether to check, and the command that fixes them.
+ * @param log - where to report.
+ * @returns the report, for `--json`.
+ * @throws a `ScriptError` in a check when a file is stale or a file could not be read, or when the package's options
+ *   are wrong.
+ */
+export const catalogueDocs = async (request, log) => {
+    const { packageDir } = request;
+    const { options, problems: optionProblems } = catalogueOptionsOf(readJson(join(packageDir, "package.json")));
+    if (optionProblems.length > 0)
+        throw new ScriptError(optionProblems.join("; "), {
+            hint: "Fix the forgebook.catalog key of package.json"
+        });
+    const file = join(packageDir, options.file);
+    const llmsFile = join(packageDir, LLMS_FILE);
+    const shown = (path) => relative(process.cwd(), path);
+    const { data, problems } = collectDocs(packageDir, (await frameworkDocsModule(packageDir, request.framework)).extractStoryComponent, options);
+    for (const problem of problems)
+        log.error(problem);
+    const text = catalogueMarkdown(data, options.sections);
+    const llms = llmsText({
+        packageName: data.packageName,
+        description: data.description,
+        catalogueFile: options.file
+    });
+    const counts = {
+        components: data.components.length,
+        modules: data.modules.length,
+        sassModules: data.sassModules.length,
+        styleSheets: data.styleSheets.length
+    };
+    const report = { file: shown(file), llmsFile: shown(llmsFile), counts, problems };
+    if (request.isCheck) {
+        if (problems.length > 0)
+            throw new ScriptError(`${plural(problems.length, "file")} could not be read`);
+        const written = [
+            [file, text],
+            [llmsFile, llms]
+        ];
+        for (const [path, expected] of written) {
+            if (readFileSafe(path) !== expected)
+                throw new ScriptError(`${shown(path)} is stale`, { hint: `Run ${request.fixCommand}` });
+        }
+        log.success(`${shown(file)} and ${LLMS_FILE} are up to date`);
+        return { status: "valid", ...report };
+    }
+    const isWritten = [writeIfChanged(file, text), writeIfChanged(llmsFile, llms)].some(Boolean);
+    log.success(`${shown(file)} and ${LLMS_FILE} ${isWritten ? "written" : "already up to date"}`);
+    return { status: isWritten ? "written" : "up-to-date", ...report };
+};
+//# sourceMappingURL=catalogueDocs.js.map

package/dist/bin/forgebook-docs/catalogueDocs.js.map

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

package/dist/bin/forgebook-docs/catalogueDocs.types.d.ts

@@ -57,11 +57,17 @@ export type CatalogueComponent = {
     readonly docs: ComponentDocs;
     /** Its stories' names. */
     readonly stories: readonly string[];
+    /** The export name of its main story (`parameters.main`, else its first); none without stories. */
+    readonly mainStory: string | undefined;
 };
 /** Everything `CATALOG.md` lists. */
 export type CatalogueData = {
     /** The package's name (`@acme/ui`). */
     readonly packageName: string;
+    /** The package's description, from its manifest; none when it has none. */
+    readonly description: string | undefined;
+    /** The id its stories carry in a catalogue, read from its `./stories` export; none when not written plainly. */
+    readonly sourceId: string | undefined;
     /** The components with stories, by title. */
     readonly components: readonly CatalogueComponent[];
     /** The other exported modules. */
@@ -77,6 +83,8 @@ export type CatalogueDocsReport = {
     readonly status: "written" | "up-to-date" | "valid";
     /** The file, relative to the working directory. */
     readonly file: string;
+    /** `llms.txt`, beside it, relative to the folder the command runs in. */
+    readonly llmsFile: string;
     /** How many components, modules, Sass modules and style sheets it lists. */
     readonly counts: {
         readonly components: number;

package/dist/bin/forgebook-docs/catalogueDocs.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalogueDocs.types.d.ts","sourceRoot":"","sources":["../../../bin/forgebook-docs/catalogueDocs.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"catalogueDocs.types.d.ts","sourceRoot":"","sources":["../../../bin/forgebook-docs/catalogueDocs.types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEhE,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG;IACvB,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kBAAkB;IAClB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;IAC7C,yEAAyE;IACzE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG;IACvB,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;CACzC,CAAC;AAEF,qDAAqD;AACrD,MAAM,MAAM,cAAc,GAAG;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAAC;IACpC,gBAAgB;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,8BAA8B;AAC9B,MAAM,MAAM,cAAc,GAAG;IAC3B,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gCAAgC;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C,CAAC;AAEF,iCAAiC;AACjC,MAAM,MAAM,cAAc,GAAG;IAC3B,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,kCAAkC;AAClC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gBAAgB;IAChB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,mGAAmG;IACnG,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC,CAAC;AAEF,qCAAqC;AACrC,MAAM,MAAM,aAAa,GAAG;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,gHAAgH;IAChH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,+BAA+B;IAC/B,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;CACjD,CAAC;AAEF,6BAA6B;AAC7B,MAAM,MAAM,mBAAmB,GAAG;IAChC,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,OAAO,CAAC;IACpD,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC"}

package/dist/bin/forgebook-docs/catalogueMarkdown.d.ts

@@ -1,9 +1,11 @@
 import type { CatalogueData } from "./catalogueDocs.types.ts";
+import type { CatalogueSection } from "./catalogueOptions.ts";
 /**
  * The text of `CATALOG.md`.
  *
  * @param data - what the command read.
+ * @param sections - the kinds of entries to list, in this order.
  * @returns the Markdown, ending with a newline.
  */
-export declare const catalogueMarkdown: (data: CatalogueData) => string;
+export declare const catalogueMarkdown: (data: CatalogueData, sections: readonly CatalogueSection[]) => string;
 //# sourceMappingURL=catalogueMarkdown.d.ts.map

package/dist/bin/forgebook-docs/catalogueMarkdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalogueMarkdown.d.ts","sourceRoot":"","sources":["../../../bin/forgebook-docs/catalogueMarkdown.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAsB,aAAa,EAA0B,MAAM,0BAA0B,CAAC;AAkG1G;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,aAAa,KAAG,MA6CvD,CAAC"}
+{"version":3,"file":"catalogueMarkdown.d.ts","sourceRoot":"","sources":["../../../bin/forgebook-docs/catalogueMarkdown.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAsB,aAAa,EAA0B,MAAM,0BAA0B,CAAC;AAC1G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AA0J9D;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,aAAa,EAAE,UAAU,SAAS,gBAAgB,EAAE,KAAG,MAc9F,CAAC"}

package/dist/bin/forgebook-docs/catalogueMarkdown.js

@@ -1,3 +1,4 @@
+import { storyId } from "../../src/storyTree.js";
 /** The props whose keys are the parts. */
 const PART_MAPS = ["classNames", "styles", "refs"];
 /** A prop in short. */
@@ -22,8 +23,8 @@ const shortProp = (prop) => {
 const sentence = (text) => text.replace(/\.$/, "");
 /** The import of a subpath. */
 const importOf = (packageName, subpath) => `${packageName}${subpath.slice(1)}`;
-/** One component's line. */
-const componentLine = (packageName, component) => {
+/** One component's line, ending with its main story's id when the package's source id is known. */
+const componentLine = (packageName, component, sourceId) => {
     const { docs } = component;
     const where = ` \`${importOf(packageName, component.subpath)}\``;
     // the part maps are summed up by the parts at the end of the line
@@ -32,7 +33,10 @@ const componentLine = (packageName, component) => {
         .map(shortProp)
         .join(" ");
     const parts = docs.parts.length === 0 ? "" : ` · parts: ${docs.parts.join(", ")}`;
-    return `- **${docs.name}**${where}: ${sentence(docs.description)}. ${props}${parts}`;
+    const story = sourceId === undefined || component.mainStory === undefined
+        ? ""
+        : ` · story: \`${storyId(sourceId, component.title, component.mainStory)}\``;
+    return `- **${docs.name}**${where}: ${sentence(docs.description)}. ${props}${parts}${story}`;
 };
 /** Letters and digits only, lower case: how a subpath and an export name are compared. */
 const comparable = (text) => text.toLowerCase().replace(/[^a-z0-9]/g, "");
@@ -76,57 +80,73 @@ const byPlace = (left, right) => {
         leftGroup.localeCompare(rightGroup) ||
         leftName.localeCompare(rightName));
 };
+/** The lines of one kind of entries, a heading first; none when the package has none of it. */
+const sectionLines = (data, section) => {
+    if (section === "components") {
+        const lines = ["## Components", ""];
+        if (data.components.length === 0)
+            return [...lines, "None yet.", ""];
+        let heading = "";
+        for (const component of [...data.components].sort(byPlace)) {
+            const group = component.title.split("/").slice(0, -1).join(" › ");
+            if (group !== heading) {
+                lines.push(`### ${group}`);
+                heading = group;
+            }
+            lines.push(componentLine(data.packageName, component, data.sourceId));
+        }
+        return [...lines, ""];
+    }
+    if (section === "modules") {
+        if (data.modules.length === 0)
+            return [];
+        const modules = [...data.modules].sort((left, right) => left.subpath.localeCompare(right.subpath));
+        return ["## Modules", "", ...modules.map((module) => moduleLine(data.packageName, module)), ""];
+    }
+    if (section === "sassModules") {
+        if (data.sassModules.length === 0)
+            return [];
+        return [
+            "## Sass modules",
+            "",
+            `\`@use "pkg:${data.packageName}/scss/<name>"\`.`,
+            "",
+            ...data.sassModules.map((module) => {
+                const members = module.members.map((member) => `${member.name}(${member.parameters.join(", ")}): ${sentence(member.summary)}`);
+                return `- \`${module.subpath.slice("./scss/".length)}\`: ${members.join("; ")}`;
+            }),
+            ""
+        ];
+    }
+    if (data.styleSheets.length === 0)
+        return [];
+    return [
+        "## Style sheets",
+        "",
+        ...data.styleSheets.map((sheet) => `- \`${importOf(data.packageName, sheet.subpath)}\`: ${sheet.summary}`),
+        ""
+    ];
+};
 /**
  * The text of `CATALOG.md`.
  *
  * @param data - what the command read.
+ * @param sections - the kinds of entries to list, in this order.
  * @returns the Markdown, ending with a newline.
  */
-export const catalogueMarkdown = (data) => {
+export const catalogueMarkdown = (data, sections) => {
     const lines = [
         `# ${data.packageName}`,
         "",
-        "<!-- GENERATED by forgebook-docs from the exports, their TSDoc and the stories: do not edit. -->",
+        "<!-- GENERATED by forgebook docs from the exports, their TSDoc and the stories: do not edit. -->",
         "",
         "Read before writing a component, hook or helper: what exists, how to import it, its props in short",
-        "(`a|b*`: values, `*` the default; `!` required; `onX(value)`: an event).",
-        ""
+        data.sourceId === undefined
+            ? "(`a|b*`: values, `*` the default; `!` required; `onX(value)`: an event)."
+            : "(`a|b*`: values, `*` the default; `!` required; `onX(value)`: an event), and a story that shows it (`story:`).",
+        "",
+        ...sections.flatMap((section) => sectionLines(data, section))
     ];
-    lines.push("## Components", "");
-    if (data.components.length === 0)
-        lines.push("None yet.", "");
-    let heading = "";
-    for (const component of [...data.components].sort(byPlace)) {
-        const group = component.title.split("/").slice(0, -1).join(" › ");
-        if (group !== heading) {
-            lines.push(`### ${group}`);
-            heading = group;
-        }
-        lines.push(componentLine(data.packageName, component));
-    }
-    if (data.components.length > 0)
-        lines.push("");
-    if (data.modules.length > 0) {
-        lines.push("## Modules", "");
-        const modules = [...data.modules].sort((left, right) => left.subpath.localeCompare(right.subpath));
-        for (const module of modules)
-            lines.push(moduleLine(data.packageName, module));
-        lines.push("");
-    }
-    if (data.sassModules.length > 0) {
-        lines.push("## Sass modules", "", `\`@use "pkg:${data.packageName}/scss/<name>"\`.`, "");
-        for (const module of data.sassModules) {
-            const members = module.members.map((member) => `${member.name}(${member.parameters.join(", ")}): ${sentence(member.summary)}`);
-            lines.push(`- \`${module.subpath.slice("./scss/".length)}\`: ${members.join("; ")}`);
-        }
-        lines.push("");
-    }
-    if (data.styleSheets.length > 0) {
-        lines.push("## Style sheets", "");
-        for (const sheet of data.styleSheets)
-            lines.push(`- \`${importOf(data.packageName, sheet.subpath)}\`: ${sheet.summary}`);
-        lines.push("");
-    }
     return `${lines.join("\n").trimEnd()}\n`;
 };
 //# sourceMappingURL=catalogueMarkdown.js.map

package/dist/bin/forgebook-docs/catalogueMarkdown.js.map

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

package/dist/bin/forgebook-docs/catalogueOptions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * How a package sets its `CATALOG.md`: the `forgebook.catalog` key of its `package.json`, checked. A library has no
+ * catalogue configuration of its own, and the key travels with the package.
+ *
+ * @module
+ */
+/** The kinds of entries the file lists, in the order they are written by default. */
+export declare const CATALOGUE_SECTIONS: readonly ["components", "modules", "sassModules", "styleSheets"];
+/** One kind of entries. */
+export type CatalogueSection = (typeof CATALOGUE_SECTIONS)[number];
+/** How a package's `CATALOG.md` is written. */
+export type CatalogueOptions = {
+    /** The file's name, in the package's folder. @defaultValue `"CATALOG.md"` */
+    readonly file: string;
+    /** The kinds of entries it lists, in this order. @defaultValue every kind, components first */
+    readonly sections: readonly CatalogueSection[];
+    /** Export subpaths left out (`./internal/tokens`); a trailing `*` leaves out every subpath it starts. */
+    readonly exclude: readonly string[];
+};
+/** The options of a package that sets none. */
+export declare const DEFAULT_CATALOGUE_OPTIONS: CatalogueOptions;
+/**
+ * A package's catalogue options, from its manifest, with what is wrong in them.
+ *
+ * @param manifest - the package's `package.json`, parsed.
+ * @returns the options (the defaults where it sets none or sets them wrongly) and one message per mistake.
+ */
+export declare const catalogueOptionsOf: (manifest: unknown) => {
+    readonly options: CatalogueOptions;
+    readonly problems: readonly string[];
+};
+/**
+ * Whether an export subpath is left out by the options.
+ *
+ * @param subpath - the subpath (`./internal/tokens`).
+ * @param exclude - the options' `exclude`.
+ */
+export declare const isExcluded: (subpath: string, exclude: readonly string[]) => boolean;
+//# sourceMappingURL=catalogueOptions.d.ts.map

package/dist/bin/forgebook-docs/catalogueOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogueOptions.d.ts","sourceRoot":"","sources":["../../../bin/forgebook-docs/catalogueOptions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qFAAqF;AACrF,eAAO,MAAM,kBAAkB,kEAAmE,CAAC;AAEnG,2BAA2B;AAC3B,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,+CAA+C;AAC/C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+FAA+F;IAC/F,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,yGAAyG;IACzG,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,CAAC;AAEF,+CAA+C;AAC/C,eAAO,MAAM,yBAAyB,EAAE,gBAIvC,CAAC;AAsCF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,UAAU,OAAO,KAChB;IAAE,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAa5E,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,SAAS,SAAS,MAAM,EAAE,KAAG,OAGtE,CAAC"}