forgebook 0.3.3 → 0.4.0

package/dist/bin/forgebook/auditRun.js

@@ -0,0 +1,270 @@
+/**
+ * What `forgebook audit` does: reads a project's files, with no catalogue and no configuration, and reports the values and
+ * components it actually uses, with what to do next.
+ *
+ * @remarks
+ * Nothing of the project runs and nothing is written. It is meant for a project with no design system: the first question
+ * there is what the system already is in practice, and that needs no setup. A report is not a verdict, so it exits 0
+ * whatever it finds; `check-code` is what fails.
+ *
+ * @module
+ */
+import { dirname, join } from "node:path";
+import { plural } from "@ensiria/cli-kit/format";
+import { valueAudit, valueSites } from "../../src/vite/appAudit.js";
+import { repositoryOf, smallFileText } from "../../src/vite/appTokenFiles.js";
+import { readAppTokens } from "../../src/vite/appTokens.js";
+import { projectComponents } from "../../src/vite/componentScan.js";
+import { lookAlikes } from "../../src/vite/lookAlikes.js";
+import { projectFiles, projectFilesAndScripts, UI_PATTERNS } from "../../src/vite/projectFiles.js";
+import { storyCoverage } from "../../src/vite/storyCoverage.js";
+/** A value used this often is worth a name. */
+const WORTH_A_NAME = 3;
+/** How many next steps a report gives. */
+const MOST_ACTIONS = 20;
+/** A word as one word of a command, quoted: values come from the project's files. */
+const quoted = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
+/** The step one value written by hand proposes, when it is used enough to act on. */
+const valueAction = (each, what, folder) => {
+    const args = ["audit", folder, "--value", each.value, "--json"];
+    const reach = { args, command: `forgebook audit ${quoted(folder)} --value ${quoted(each.value)} --json` };
+    if (each.token !== undefined) {
+        const caution = each.tokenFollowsTheme === true ? " It changes with the theme: use it if the value should too." : "";
+        return [
+            {
+                kind: "use-token",
+                message: `Replace ${each.value} with ${each.token}: written by hand ${each.hardCoded} times in ${each.hardCodedFiles} files.${caution}`,
+                count: each.hardCoded,
+                ...reach
+            }
+        ];
+    }
+    return each.hardCoded < WORTH_A_NAME
+        ? []
+        : [
+            {
+                kind: "name-value",
+                message: `${what} ${each.value} is written by hand ${each.hardCoded} times and no token holds it: give it a name, or use one near it.`,
+                count: each.hardCoded,
+                ...reach
+            }
+        ];
+};
+/** The steps a report's values propose. */
+const valueActions = ({ colors, sizes }, folder) => [
+    ...colors.handWritten.flatMap((each) => valueAction(each, "The colour", folder)),
+    ...sizes.font.handWritten.flatMap((each) => valueAction(each, "The font size", folder)),
+    ...sizes.radius.handWritten.flatMap((each) => valueAction(each, "The radius", folder)),
+    ...sizes.space.handWritten.flatMap((each) => valueAction(each, "The spacing", folder)),
+    ...colors.nearDuplicates.map((values) => ({
+        kind: "merge-values",
+        message: `Hard to tell apart: ${values.join(", ")}. Keep one.`,
+        count: values.length
+    }))
+];
+/** The steps a report's look-alikes propose. */
+const componentActions = (alike) => alike.map(({ members, why }) => ({
+    kind: "merge-components",
+    message: `${members.map(({ name }) => name).join(", ")}: ${why}. Compare them (\`members\` has where); keep one if they are the same thing.`,
+    count: members.length,
+    members
+}));
+/** How many components an action's `members` lists at most: the rest are in the report's own lists. */
+const MOST_MEMBERS = 20;
+/** The step components with no story propose: write the first one's stories. */
+const writeStoriesAction = (withoutStories, folder) => {
+    const first = withoutStories[0];
+    if (first === undefined)
+        return [];
+    const file = join(folder, first.file);
+    return [
+        {
+            kind: "write-stories",
+            message: `No story is about ${plural(withoutStories.length, "exported component")}, so nobody sees what exists before writing it again: start with ${first.name}.`,
+            count: withoutStories.length,
+            command: `forgebook new -- ${quoted(file)}`,
+            args: ["new", "--", file],
+            members: withoutStories.slice(0, MOST_MEMBERS)
+        }
+    ];
+};
+/** The step components with stories and no use propose: look at whether each is still needed. */
+const checkUnusedAction = (storiesUnused) => storiesUnused.length === 0
+    ? []
+    : [
+        {
+            kind: "check-unused",
+            message: `Nothing but stories and tests uses ${plural(storiesUnused.length, "component")} with stories: check whether each is still needed, and remove it with its stories if not.`,
+            count: storiesUnused.length,
+            members: storiesUnused.slice(0, MOST_MEMBERS).map(({ name, file, line }) => ({ name, file, line }))
+        }
+    ];
+/**
+ * Whether a manifest is one of a package that goes to a registry: named, and not private. A private package with
+ * `exports` is a workspace's own, whose users are in the repository, so the audit judges what it reads of them, as it does
+ * an application's components (application templates mark themselves private).
+ *
+ * @param manifest - the parsed `package.json`.
+ */
+const isOnTheRegistry = (manifest) => typeof manifest === "object" &&
+    manifest !== null &&
+    "name" in manifest &&
+    typeof manifest.name === "string" &&
+    !("private" in manifest && manifest.private === true);
+/**
+ * Whether a file belongs to a package that goes to a registry, by the nearest manifest above it inside the repository.
+ *
+ * @param dir - the project's folder, which the files are relative to.
+ */
+const publishedPackageOf = (dir) => {
+    const root = repositoryOf(dir);
+    const known = new Map();
+    const folderIsPublished = (folder) => {
+        const cached = known.get(folder);
+        if (cached !== undefined)
+            return cached;
+        const text = smallFileText(join(folder, "package.json"));
+        let answer;
+        if (text !== undefined) {
+            try {
+                answer = isOnTheRegistry(JSON.parse(text));
+            }
+            catch {
+                answer = false;
+            }
+        }
+        else
+            answer = folder === root || folder === dirname(folder) ? false : folderIsPublished(dirname(folder));
+        known.set(folder, answer);
+        return answer;
+    };
+    return (file) => folderIsPublished(dirname(join(dir, file)));
+};
+/**
+ * The report on a project.
+ *
+ * @param dir - its folder.
+ * @param top - how many values a list gives.
+ * @param folder - the folder as the command was given it, for the commands an answer proposes.
+ */
+export const auditDocument = (dir, top, folder = ".") => {
+    const { tokens, sources, unread } = readAppTokens(dir);
+    const notes = [...unread];
+    const { files, scripts } = projectFilesAndScripts(dir, notes);
+    const values = valueAudit(files, tokens, top);
+    const components = projectComponents(files);
+    const alike = lookAlikes(components);
+    const coverage = storyCoverage(components, [...files, ...scripts], publishedPackageOf(dir));
+    return {
+        schema: 1,
+        system: {
+            tokens: tokens.length,
+            own: tokens.filter((token) => token.origin?.kind !== "tailwind-default").length,
+            sources,
+            notes
+        },
+        ...values,
+        components: {
+            count: components.length,
+            lookAlikes: alike,
+            storyFileCount: coverage.storyFileCount,
+            withStories: coverage.withStories,
+            withoutStories: coverage.withoutStories,
+            storiesUnused: coverage.storiesUnused,
+            publishedWithStories: coverage.published
+        },
+        actions: [
+            ...valueActions(values, folder),
+            ...componentActions(alike),
+            ...writeStoriesAction(coverage.withoutStories, folder),
+            ...checkUnusedAction(coverage.storiesUnused)
+        ]
+            .toSorted((first, second) => second.count - first.count)
+            .slice(0, MOST_ACTIONS)
+    };
+};
+/**
+ * Where a value is written by hand.
+ *
+ * @param dir - the project's folder.
+ * @param value - the value.
+ */
+export const auditSitesDocument = (dir, value) => {
+    const notes = [];
+    const files = projectFiles(dir, notes);
+    return { schema: 1, value, sites: valueSites(files, value), notes };
+};
+/**
+ * A text from a project's files as a terminal may show it: a newline or an escape in a file's name could otherwise draw
+ * a line of this report.
+ *
+ * @param text - the text.
+ */
+export const printable = (text) => text.replaceAll(/[\p{Cc}\p{Cf}]/gu, (character) => (character === "\n" ? "\n" : "?"));
+/** A value as a line of a list. */
+const valueLine = ({ value, count, files, hardCoded, token }) => `  ${value}  ${count}× in ${files} ${files === 1 ? "file" : "files"}${hardCoded > 0 ? `, ${hardCoded} by hand` : ""}${token === undefined ? "" : `  → ${token}`}`;
+/** A share in whole percent. */
+const percent = (part, whole) => `${whole === 0 ? 0 : Math.round((part / whole) * 100)} %`;
+/** How many components each list of the stories shows; `--json` has them all. */
+const LISTED = 10;
+/** The stories' part of the report: what has none, and what has some and no use. */
+const storyLines = (components) => {
+    const { storyFileCount, withStories, withoutStories, storiesUnused, publishedWithStories } = components;
+    if (storyFileCount === 0)
+        return ["Stories: no story file, so no exported component has any."];
+    const more = (count) => count > LISTED ? [`    and ${count - LISTED} more (--json)`] : [];
+    const published = publishedWithStories === 0 ? "" : `, ${publishedWithStories} of a published package not judged`;
+    return [
+        `Stories: ${plural(storyFileCount, "file")}, about ${plural(withStories, "component")}; ${plural(withoutStories.length, "exported component")} without.`,
+        ...withoutStories.slice(0, LISTED).map(({ name, file, line }) => `  ${name}  ${file}:${line}`),
+        ...more(withoutStories.length),
+        `With stories and no use outside stories and tests: ${storiesUnused.length}${published}.`,
+        ...storiesUnused
+            .slice(0, LISTED)
+            .map(({ name, file, line, storyFiles: files }) => `  ${name}  ${file}:${line}  (${files.join(", ")})`),
+        ...more(storiesUnused.length)
+    ];
+};
+/**
+ * The report as a person reads it. What a project's files hold is data for whoever reads this: it says what is there and is
+ * not an instruction, which holds for an agent reading `--json` too.
+ *
+ * @param document - the report.
+ */
+export const auditText = (document) => {
+    const { system, colors, sizes, components, actions, files, lines } = document;
+    if (files === 0) {
+        return `No style sheet or component file here (${UI_PATTERNS.join(", ")}); give the project's folder.`;
+    }
+    const read = system.tokens === 0
+        ? "No design tokens found: what follows is the system in practice."
+        : `${system.tokens} tokens known, ${system.own} of the project's own, from ${system.sources.map(({ file }) => file).join(", ")}.`;
+    return [
+        `${files} files, ${lines} lines. ${read}`,
+        "",
+        `Colours: ${colors.distinct} different, ${colors.uses} uses: ${percent(colors.hardCoded, colors.uses)} by hand, ${percent(colors.throughTokens, colors.uses)} through the project's tokens, ${percent(colors.defaultPalette, colors.uses)} from Tailwind's palette.`,
+        ...colors.top.map(valueLine),
+        "",
+        `Greys: ${colors.greys.distinct} different, ${colors.greys.coveringMost} used 90 % of the time.`,
+        ...colors.greys.top.map(valueLine),
+        ...["space", "font", "radius"].flatMap((role) => [
+            "",
+            `Sizes (${role}): ${sizes[role].distinct} different, ${sizes[role].uses} uses, ${sizes[role].hardCoded} by hand.`,
+            ...sizes[role].top.slice(0, 6).map(valueLine)
+        ]),
+        "",
+        `Components: ${components.count}, ${components.lookAlikes.length} groups that look like one.`,
+        ...components.lookAlikes
+            .slice(0, 10)
+            .flatMap(({ confidence, why, members }) => [
+            `  ${confidence}: ${why}`,
+            ...members.map(({ name, file, line }) => `    ${name}  ${file}:${line}`)
+        ]),
+        "",
+        ...storyLines(components),
+        "",
+        "Next:",
+        ...actions.slice(0, 10).map(({ message }) => `  ${message}`),
+        ...system.notes.map((note) => `Not read: ${note}`)
+    ].join("\n");
+};

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

@@ -0,0 +1,21 @@
+import type { ScriptIo } from "@ensiria/cli-kit/io.types";
+/**
+ * The file of Playwright's command, as `@forgebook/testing` in a folder finds it.
+ *
+ * @remarks
+ * Looked for by folder: neither package need export its `package.json`, and a strict install keeps Playwright beside the
+ * testing package, out of the project's reach.
+ *
+ * @param dir - the project's folder.
+ * @returns its path; none when either package is not there.
+ */
+export declare const playwrightCommandFile: (dir: string) => string | undefined;
+/**
+ * Installs the browser.
+ *
+ * @param dir - the project's folder.
+ * @param shouldInstallSystemPackages - whether to install what the browser needs of the system (`--with-deps`), as CI does.
+ * @param io - the run's streams.
+ * @throws a `ScriptError` when the testing package is not there, or the install fails.
+ */
+export declare const installBrowser: (dir: string, shouldInstallSystemPackages: boolean, io: ScriptIo) => Promise<void>;

package/dist/bin/forgebook/browserRun.js

@@ -0,0 +1,57 @@
+/**
+ * What `forgebook browser` runs: installs the browser the stories' checks run on, with the Playwright that will open it.
+ *
+ * @remarks
+ * Each Playwright version wants its own browser build, and a project may have another Playwright of its own at the top of
+ * its `node_modules`, so `playwright install` from the project can fetch a browser the checks never find. The one that
+ * counts is the one `@forgebook/testing` loads, found from that package.
+ *
+ * Playwright's install also deletes every build in the shared browser folder that no project it still knows of uses, so
+ * a plain `playwright install` here can remove the browsers of other projects on the machine. `--no-remove` keeps the
+ * install to adding the one build the checks need: Forgebook never deletes what it did not install.
+ *
+ * @module
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { exec } from "@ensiria/cli-kit/exec";
+import { ScriptError } from "@ensiria/cli-kit/script";
+/** A package's folder as Node finds it going up from a folder, links followed; none when it is not there. */
+const nearestPackage = (dir, name) => {
+    const folder = join(dir, "node_modules", name);
+    if (existsSync(join(folder, "package.json")))
+        return realpathSync(folder);
+    const parent = dirname(dir);
+    return parent === dir ? undefined : nearestPackage(parent, name);
+};
+/**
+ * The file of Playwright's command, as `@forgebook/testing` in a folder finds it.
+ *
+ * @remarks
+ * Looked for by folder: neither package need export its `package.json`, and a strict install keeps Playwright beside the
+ * testing package, out of the project's reach.
+ *
+ * @param dir - the project's folder.
+ * @returns its path; none when either package is not there.
+ */
+export const playwrightCommandFile = (dir) => {
+    const testing = nearestPackage(dir, "@forgebook/testing");
+    const playwright = testing === undefined ? undefined : nearestPackage(testing, "@playwright/test");
+    return playwright === undefined ? undefined : join(playwright, "cli.js");
+};
+/**
+ * Installs the browser.
+ *
+ * @param dir - the project's folder.
+ * @param shouldInstallSystemPackages - whether to install what the browser needs of the system (`--with-deps`), as CI does.
+ * @param io - the run's streams.
+ * @throws a `ScriptError` when the testing package is not there, or the install fails.
+ */
+export const installBrowser = async (dir, shouldInstallSystemPackages, io) => {
+    const command = playwrightCommandFile(dir);
+    if (command === undefined)
+        throw new ScriptError("@forgebook/testing and @playwright/test are not installed here", {
+            hint: "npm install -D @forgebook/testing @playwright/test, or forgebook init --browser"
+        });
+    await exec(process.execPath, [command, "install", "--no-remove", "chromium", ...(shouldInstallSystemPackages ? ["--with-deps"] : [])], { cwd: dir, output: "prefix", prefix: "playwright", io });
+};

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

@@ -0,0 +1,7 @@
+/**
+ * What a failed build says.
+ *
+ * @param error - what the build threw: Vite's bundler lists its errors in `errors`.
+ * @returns the text, a line per error.
+ */
+export declare const buildFailureText: (error: unknown) => string;

package/dist/bin/forgebook/buildFailure.js

@@ -0,0 +1,47 @@
+/**
+ * What `forgebook build` says when the bundler fails: each error on a line, with its file, line and column when they
+ * are known. The bundler's own message holds its frames and a code frame in colours, which only `--verbose` shows.
+ *
+ * @module
+ */
+import { stripVTControlCharacters } from "node:util";
+import { bundlerErrorLines } from "../../src/bundlerErrors.js";
+/** Whether a value is an object, whose fields can be read. */
+const isRecord = (value) => typeof value === "object" && value !== null;
+/**
+ * What an error says of its place, as far as it holds the right shapes.
+ *
+ * @param error - the error, as the bundler gives it.
+ */
+const placeOf = (error) => {
+    const { id, loc } = error;
+    const line = isRecord(loc) ? loc["line"] : undefined;
+    const column = isRecord(loc) ? loc["column"] : undefined;
+    return {
+        ...(typeof id === "string" ? { id } : {}),
+        ...(typeof line === "number" && typeof column === "number" ? { loc: { line, column } } : {})
+    };
+};
+/**
+ * The lines of one of the build's errors.
+ *
+ * @param error - the error, as the bundler gives it.
+ */
+const errorLines = (error) => {
+    if (!isRecord(error))
+        return bundlerErrorLines(String(error));
+    const { message } = error;
+    return bundlerErrorLines(stripVTControlCharacters(String(message)), placeOf(error));
+};
+/**
+ * What a failed build says.
+ *
+ * @param error - what the build threw: Vite's bundler lists its errors in `errors`.
+ * @returns the text, a line per error.
+ */
+export const buildFailureText = (error) => {
+    const list = isRecord(error) ? error["errors"] : undefined;
+    const errors = Array.isArray(list) ? list : [error];
+    const lines = errors.flatMap(errorLines);
+    return lines.length === 0 ? "The build failed" : lines.join("\n");
+};

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

@@ -0,0 +1,52 @@
+/**
+ * `forgebook build --watch`: builds the catalogue, then again each time a file it reads changes, so a folder served
+ * elsewhere (a preview host, a second machine, an embed in an app) follows the code without a dev server.
+ *
+ * @remarks
+ * The bundler's watch mode with its incremental option keeps what it can between builds, and the process keeps the
+ * catalogue's configuration, which is about a third of a whole build on a large catalogue; it still writes the whole
+ * output. It watches the files a build read, so a file nothing read yet cannot wake it: a new story file reaches the list only by a build
+ * that starts over, and that is what a changed listing does. The lists are read again on a timer rather than with a
+ * folder watch, because a pattern's folder may be the project itself, and watching `node_modules` is what a catalogue
+ * must not cost on Linux. A failed build leaves the last good output and waits for the next edit.
+ *
+ * The files are polled: the operating system's file events go missing on a busy machine, and a watch that silently
+ * misses an edit leaves a site out of date with nothing to say so; asking only about the files a build read costs little.
+ *
+ * @module
+ */
+import type { Logger } from "@ensiria/cli-kit/log.types";
+import { type InlineConfig } from "vite";
+/** What each group lists: by the group's text, its files in order, one text a group. */
+export type Listing = ReadonlyMap<string, string>;
+/**
+ * What the groups of a build list now.
+ *
+ * @param moduleIds - the build's module ids; those that are no group are skipped.
+ * @param listFiles - lists a group's files; the disk by default.
+ */
+export declare const listingOf: (moduleIds: Iterable<string>, listFiles?: (group: string) => readonly string[]) => Listing;
+/**
+ * Whether two listings differ: a file added to a group or taken from it.
+ *
+ * @param before - what the last build listed.
+ * @param now - what the groups list now.
+ */
+export declare const isListingChanged: (before: Listing, now: Listing) => boolean;
+/** What a watch reports. */
+export type BuildWatchOptions = {
+    /** The Vite configuration of the build, `build.outDir` set. */
+    readonly vite: InlineConfig;
+    /** Where it says what each build did. */
+    readonly log: Logger;
+    /** Called after each build that succeeded, before it is announced: what must follow the output. */
+    readonly onBuilt: () => Promise<void>;
+    /** Ends the watch when it aborts; the watch runs until then. */
+    readonly signal: AbortSignal;
+};
+/**
+ * Builds, then builds again on every change, until the signal aborts.
+ *
+ * @param options - what to build and report.
+ */
+export declare const watchBuild: (options: BuildWatchOptions) => Promise<void>;

package/dist/bin/forgebook/buildWatch.js

@@ -0,0 +1,137 @@
+import { build, createLogger } from "vite";
+import { DOCS_PAGES_SPECIFIER_PREFIX, FILES_SPECIFIER_PREFIX, storyFileKeys, storyFilesGroupOf } from "../../src/vite/storyFilesModule.js";
+import { buildFailureText } from "./buildFailure.js";
+/** How often the lists of story files and docs pages are read again, in ms. */
+const LISTING_PERIOD = 1000;
+/** How often the files a build read are asked for changes, in ms. */
+const FILE_PERIOD = 300;
+/** The watch's polling: `watcher` is the bundler's own option, and Vite builds it from `chokidar`, which it reads. */
+const POLLED_WATCH = {
+    chokidar: { usePolling: true, interval: FILE_PERIOD },
+    watcher: { usePolling: true, pollInterval: FILE_PERIOD }
+};
+/** The groups' module ids a build reads, each holding a group after its prefix. */
+const GROUP_PREFIXES = [FILES_SPECIFIER_PREFIX, DOCS_PAGES_SPECIFIER_PREFIX].map((prefix) => `\0${prefix}`);
+/**
+ * Vite's logger for a watch: its warnings, without its errors, whose bundler stack this command says on one line.
+ */
+const quietLogger = () => ({ ...createLogger("warn"), error: () => undefined });
+/**
+ * What the groups of a build list now.
+ *
+ * @param moduleIds - the build's module ids; those that are no group are skipped.
+ * @param listFiles - lists a group's files; the disk by default.
+ */
+export const listingOf = (moduleIds, listFiles = (group) => {
+    const { root, patterns } = storyFilesGroupOf(group);
+    return storyFileKeys(root, patterns);
+}) => {
+    const listing = new Map();
+    for (const id of moduleIds) {
+        const prefix = GROUP_PREFIXES.find((each) => id.startsWith(each));
+        if (prefix === undefined)
+            continue;
+        const group = id.slice(prefix.length);
+        listing.set(id, listFiles(group).join("\n"));
+    }
+    return listing;
+};
+/**
+ * Whether two listings differ: a file added to a group or taken from it.
+ *
+ * @param before - what the last build listed.
+ * @param now - what the groups list now.
+ */
+export const isListingChanged = (before, now) => before.size !== now.size || [...before].some(([id, files]) => now.get(id) !== files);
+/**
+ * One run of the bundler's watch mode: resolves when the list of files changes, so a new one starts, or the signal
+ * aborts.
+ *
+ * @param options - what to build and report.
+ * @returns whether a new run must start.
+ */
+const watchUntilListed = async ({ vite, log, onBuilt, signal }) => {
+    let moduleIds = [];
+    const noteModules = {
+        name: "forgebook:build-watch",
+        buildEnd() {
+            moduleIds = [...this.getModuleIds()];
+        }
+    };
+    const output = await build({
+        ...vite,
+        logLevel: "warn",
+        customLogger: quietLogger(),
+        plugins: [...(vite.plugins ?? []), noteModules],
+        build: {
+            ...vite.build,
+            watch: POLLED_WATCH,
+            rolldownOptions: {
+                ...vite.build?.rolldownOptions,
+                experimental: { ...vite.build?.rolldownOptions?.experimental, incrementalBuild: true }
+            }
+        }
+    });
+    if (!("on" in output))
+        return false;
+    const watcher = output;
+    let changes = [];
+    let listed;
+    let isBuilding = true;
+    // one after another: a slow index after a build must never land over the next build's
+    let settling = Promise.resolve();
+    watcher.on("change", (file) => {
+        changes = [...changes, file];
+    });
+    watcher.on("event", (event) => {
+        if (event.code === "START")
+            isBuilding = true;
+        if (event.code === "ERROR") {
+            isBuilding = false;
+            log.error(buildFailureText(event.error));
+            log.info("Waiting for the next edit");
+        }
+        if (event.code !== "BUNDLE_END")
+            return;
+        const touched = changes;
+        changes = [];
+        listed = listingOf(moduleIds);
+        settling = settling.then(onBuilt).then(() => {
+            isBuilding = false;
+            const note = touched.length === 0 ? "" : ` after ${touched.length} changed`;
+            log.success(`Built in ${event.duration} ms${note}; watching for changes`);
+        }, (error) => {
+            isBuilding = false;
+            log.error(error instanceof Error ? error.message : String(error));
+        });
+    });
+    try {
+        return await new Promise((resolve) => {
+            signal.addEventListener("abort", () => resolve(false), { once: true });
+            const timer = setInterval(() => {
+                // a list read while a build runs would be compared with the build before it
+                if (isBuilding || listed === undefined)
+                    return;
+                if (!isListingChanged(listed, listingOf(listed.keys())))
+                    return;
+                clearInterval(timer);
+                log.info("The list of files changed: building from the start");
+                resolve(true);
+            }, LISTING_PERIOD);
+            signal.addEventListener("abort", () => clearInterval(timer), { once: true });
+        });
+    }
+    finally {
+        await watcher.close();
+    }
+};
+/**
+ * Builds, then builds again on every change, until the signal aborts.
+ *
+ * @param options - what to build and report.
+ */
+export const watchBuild = async (options) => {
+    while (await watchUntilListed(options)) {
+        // each run is a watch of its own; a list changing again starts another
+    }
+};

package/dist/bin/forgebook/builtCatalogue.js

@@ -8,7 +8,8 @@ import { rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { createInterface } from "node:readline";
 import { ScriptError } from "@ensiria/cli-kit/script";
-import { AGENT_INDEX_FILE, indexProblems, isAgentIndex } from "../../src/vite/agentIndex.js";
+import { AGENT_INDEX_FILE } from "../../src/agentIndexFile.js";
+import { indexProblems, isAgentIndex } from "../../src/vite/agentIndex.js";
 import { answerMcpMessage, NEW_SESSION } from "../../src/vite/mcpProtocol.js";
 import { pluginsDocument } from "../../src/vite/pluginConfig.js";
 import { catalogueClient, indexClient } from "./agentClient.js";
@@ -29,8 +30,8 @@ export const settleAgentIndex = async (config, outDir, isWanted, log) => {
         return;
     }
     const client = await catalogueClient(config, undefined);
-    const answer = await client.ask("agent-index", new URLSearchParams());
-    await client.close();
+    // its server closes whatever the answer: a watch asks again after every build
+    const answer = await client.ask("agent-index", new URLSearchParams()).finally(() => client.close());
     if (answer.status !== 200 || !isAgentIndex(answer.body)) {
         throw new ScriptError(`The catalogue's index could not be read: ${JSON.stringify(answer.body)}`);
     }
@@ -65,11 +66,14 @@ export const builtCatalogueServer = async (from, version) => {
         ask,
         writeNew: unreachable,
         check: unreachable,
+        stress: unreachable,
         checkPage: unreachable,
         shot: unreachable,
+        verify: unreachable,
         servePreview: unreachable,
-        // a built index keeps no configuration, so it lists no plugins; list_plugins is not among its tools
-        plugins: pluginsDocument([])
+        // a built index keeps no configuration, so it lists no plugins or switches; neither tool is among its tools
+        plugins: pluginsDocument([]),
+        switches: { schema: 1, switches: [] }
     }).filter((tool) => READ_ONLY_TOOLS.has(tool.name));
     return {
         info: { name: "forgebook", version },

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

@@ -29,6 +29,15 @@ export declare const configPathOf: (file: string | undefined) => string | undefi
  * @throws a `ScriptError` when there is none, or it cannot be used.
  */
 export declare const configOf: (file: string | undefined) => Promise<ResolvedConfig>;
+/**
+ * The catalogue's configuration, for a command that reads its stories: a pattern that matches nothing is a mistake there,
+ * and answering "no stories" with success hides it from a person and from CI alike. `forgebook dev` only warns, since
+ * whoever runs it may be about to write the first story.
+ *
+ * @param file - the configuration file given; none to look in the current folder.
+ * @throws a `ScriptError` when there is none, it cannot be used, or one of its story patterns matches nothing.
+ */
+export declare const configWithStoriesOf: (file: string | undefined) => Promise<ResolvedConfig>;
 /**
  * Asks the catalogue one of its answers, from its running dev server or one started for the answer.
  *