forgebook 0.3.3 → 0.4.1

package/dist/bin/forgebook/catalogueCommands.js

@@ -9,6 +9,8 @@ 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 { emptyStoryGlobs, emptyStoryGlobsMessage } from "../../src/vite/emptyStoryGlobs.js";
+import { hiddenStoryFolders, hiddenStoryFoldersMessage } from "../../src/vite/hiddenStoryFiles.js";
 import { catalogueClient } from "./agentClient.js";
 /** The options every `forgebook` command takes. */
 export const FORGEBOOK_OPTIONS = {
@@ -46,6 +48,27 @@ export const configOf = async (file) => {
         throw new ScriptError(error instanceof Error ? error.message : String(error));
     }
 };
+/**
+ * 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 const configWithStoriesOf = async (file) => {
+    const config = await configOf(file);
+    const globs = emptyStoryGlobs(config);
+    if (globs.length > 0) {
+        const hidden = hiddenStoryFolders(config);
+        throw new ScriptError(emptyStoryGlobsMessage(globs), {
+            hint: hidden.length > 0
+                ? hiddenStoryFoldersMessage(hidden)
+                : `Correct the pattern, or write the first story: ${COMMAND} new <component file>`
+        });
+    }
+    return config;
+};
 /**
  * Asks the catalogue one of its answers, from its running dev server or one started for the answer.
  *

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

@@ -5,8 +5,12 @@ import type { ResolvedConfig } from "../../src/vite/configFile.ts";
  *
  * @param config - the catalogue's configuration, read.
  * @param overrides - what the command sets (the port, the output folder); its plugins run after the catalogue's.
+ * @param command - what it runs for: a `vite.config` may be a function of it, and of the mode that follows from it.
+ * @param isOneShot - whether the server is a one-shot command's, whose app plugins start nothing of their own.
+ * @param isQuickScan - whether the dependency scan reads only the story files itself (`ScanFindings.isQuick`): a first
+ * start's pre-bundling, which scans again without it when a script stops the scan.
  */
-export declare const catalogueVite: (config: ResolvedConfig, overrides: InlineConfig) => Promise<InlineConfig>;
+export declare const catalogueVite: (config: ResolvedConfig, overrides: InlineConfig, command?: "serve" | "build", isOneShot?: boolean, isQuickScan?: boolean) => Promise<InlineConfig>;
 /**
  * The configuration with the frames' port the command line gives (`--frame-port`), over the file's.
  *

package/dist/bin/forgebook/catalogueVite.js

@@ -1,7 +1,7 @@
 /**
  * The Vite configuration the `forgebook` command runs a catalogue with: its folder as the root, Forgebook's plugin
- * with the configuration already read, the framework's own plugins, and the server's export conditions taken from the
- * pages'; and where the command line puts the frames.
+ * with the configuration already read, the framework's own plugins, what the app's own build adds, and the server's
+ * export conditions taken from the pages'; and where the command line puts the frames.
  *
  * @module
  */
@@ -9,17 +9,23 @@ import { ScriptError } from "@ensiria/cli-kit/script";
 import { forgebookPlugin } from "../../src/vite/forgebookPlugin.js";
 import { ISOLATED_FRAMES } from "../../src/vite/framesConfig.js";
 import { serverConditions } from "../../src/vite/serverConditions.js";
+import { appBuildOf } from "./appBuild/appBuild.js";
 import { unresolvedImports } from "./viteCache.js";
 /**
  * Vite's configuration for a catalogue.
  *
  * @param config - the catalogue's configuration, read.
  * @param overrides - what the command sets (the port, the output folder); its plugins run after the catalogue's.
+ * @param command - what it runs for: a `vite.config` may be a function of it, and of the mode that follows from it.
+ * @param isOneShot - whether the server is a one-shot command's, whose app plugins start nothing of their own.
+ * @param isQuickScan - whether the dependency scan reads only the story files itself (`ScanFindings.isQuick`): a first
+ * start's pre-bundling, which scans again without it when a script stops the scan.
  */
-export const catalogueVite = async (config, overrides) => {
+export const catalogueVite = async (config, overrides, command = "serve", isOneShot = false, isQuickScan = false) => {
     // what a first start's pre-bundling left out, left out here too: it is part of the pre-bundle's hash, and a server
     // whose hash differed would pre-bundle everything again itself
     const unresolved = unresolvedImports(config.dir);
+    const app = await appBuildOf(config, { command, mode: overrides.mode ?? (command === "build" ? "production" : "development") }, isOneShot);
     return {
         ...overrides,
         ...(unresolved.length === 0
@@ -31,11 +37,13 @@ export const catalogueVite = async (config, overrides) => {
                 }
             }),
         root: config.dir,
-        // the configuration file is Forgebook's: a vite.config beside it is not read
+        // the configuration file is Forgebook's: of a vite.config beside it, `appBuildOf` takes what stories need
         configFile: false,
         plugins: [
-            forgebookPlugin({ config }),
-            ...((await config.framework.vitePlugins?.()) ?? []),
+            forgebookPlugin({ config, isQuickScan }),
+            ...((await config.framework.vitePlugins?.({ readsAppBuild: config.appBuild.viteConfig !== false })) ??
+                []),
+            ...app.plugins,
             ...(overrides.plugins ?? []),
             // the server loads the stories and previews for tools: it resolves them as the pages do
             serverConditions()

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

@@ -0,0 +1,18 @@
+/** Whether a process runs. */
+export declare const isProcessRunning: (pid: number) => boolean;
+/** A cache folder a server may use, and how to give it back. */
+export type CacheClaim = {
+    /** The folder: the shared one, or the server's own. */
+    readonly folder: string;
+    /** Whether it is the shared folder. */
+    readonly isShared: boolean;
+    /** Gives it back: unlocks the shared folder, or removes the server's own. Safe to call more than once. */
+    readonly release: () => void;
+};
+/**
+ * Claims a cache folder for a server: the shared one when no live server holds it, else one of the server's own beside it.
+ *
+ * @param shared - the shared folder.
+ * @returns the claim, given back when the server closes.
+ */
+export declare const claimCommandCache: (shared: string) => CacheClaim;

package/dist/bin/forgebook/commandCacheClaim.js

@@ -0,0 +1,170 @@
+/**
+ * Which cache folder a server a command starts may use: the shared one, kept warm from one command to the next, when no
+ * other live server holds it, else one of its own for as long as it runs (`commandServer.ts`).
+ *
+ * @remarks
+ * Two servers on one cache folder rewrite each other's pre-bundled dependencies: when one's optimizer discovers a package
+ * the other did not, it replaces the whole `deps` folder, and the other's frames ask for a bundle that is gone and fail
+ * with "504 (Outdated Optimize Dep)". Two commands run together in one project as soon as an agent runs `verify` while
+ * `forgebook mcp` serves, or two checks run side by side. A lock file beside the shared folder names the process that
+ * holds it; one whose process is gone is taken over. A server that finds it held runs on a folder named after its
+ * process, removed when it closes, or by the next claim when its process ended first.
+ *
+ * @module
+ */
+import { closeSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, statSync, writeSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+/** Whether a process runs. */
+export const isProcessRunning = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // the process exists, and belongs to another user
+        return error instanceof Error && "code" in error && error.code === "EPERM";
+    }
+};
+/** The lock file of a shared folder, beside it. */
+const lockFile = (shared) => `${shared}.lock`;
+/** The prefix of the folders servers that found the shared one held run on, beside it. */
+const ownPrefix = (shared) => `${basename(shared)}-own-`;
+/** How long a lock file may name no process before it counts as one a process left while writing it. */
+const UNWRITTEN_LOCK_MS = 10_000;
+/**
+ * Removes a file or folder, leaving it when the system will not: on Windows a file another program holds open cannot
+ * go, and what is left is removed by a later claim, never a reason to fail the command.
+ *
+ * @param path - the file or folder.
+ */
+const removeIfPossible = (path) => {
+    try {
+        rmSync(path, { recursive: true, force: true });
+    }
+    catch {
+        // left for the next claim's sweep
+    }
+};
+/** The process a lock file names, or none when it names none (written halfway, or by hand). */
+const lockHolder = (file) => {
+    try {
+        const pid = Number(readFileSync(file, "utf8").trim());
+        return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Creates a file naming this process; false when it exists. */
+const tryCreate = (file) => {
+    let handle;
+    try {
+        handle = openSync(file, "wx");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+    try {
+        writeSync(handle, String(process.pid));
+    }
+    finally {
+        closeSync(handle);
+    }
+    return true;
+};
+/**
+ * Whether a lock is one no live process holds: its process is gone, or it has named none for longer than a write takes
+ * (a process that ended between creating and writing it).
+ */
+const isStale = (file) => {
+    const holder = lockHolder(file);
+    if (holder !== undefined)
+        return !isProcessRunning(holder);
+    const stats = statSync(file, { throwIfNoEntry: false });
+    return stats !== undefined && Date.now() - stats.mtimeMs > UNWRITTEN_LOCK_MS;
+};
+/**
+ * Takes the lock, taking it over from a process that is gone. A take-over is itself guarded by a file only one process
+ * can create: two processes that both find the lock stale would otherwise each remove it, the second removing the
+ * first one's new lock, and both would run on the shared folder.
+ *
+ * @param file - the lock file.
+ * @returns whether this process holds it now.
+ */
+const lock = (file) => {
+    if (tryCreate(file))
+        return true;
+    if (!isStale(file))
+        return false;
+    const takeOver = `${file}.take-over`;
+    if (!tryCreate(takeOver)) {
+        // a take-over left by a process that ended in it is cleared for the next claim; this one runs apart
+        if (isStale(takeOver))
+            removeIfPossible(takeOver);
+        return false;
+    }
+    try {
+        // read again under the take-over: another process may have taken the lock over and released it since
+        if (!isStale(file))
+            return false;
+        removeIfPossible(file);
+        return tryCreate(file);
+    }
+    finally {
+        removeIfPossible(takeOver);
+    }
+};
+/** Removes the folders of servers whose process is gone. */
+const sweepOwn = (parent, prefix) => {
+    for (const name of readdirSync(parent).filter((each) => each.startsWith(prefix))) {
+        const pid = Number(name.slice(prefix.length).split("-")[0]);
+        if (Number.isInteger(pid) && pid > 0 && !isProcessRunning(pid))
+            removeIfPossible(join(parent, name));
+    }
+};
+/** How many own folders this process has made: two servers of one process each get one. */
+let ownCount = 0;
+/** What to give back if the process ends before its servers close. */
+const pending = new Set();
+/** Whether the process's exit gives back what is still held. */
+let isExitHooked = false;
+/** Gives back every claim still held: the process is ending, and its lock would otherwise read as live until reused. */
+const releaseAll = () => {
+    for (const release of pending)
+        release();
+};
+/**
+ * Claims a cache folder for a server: the shared one when no live server holds it, else one of the server's own beside it.
+ *
+ * @param shared - the shared folder.
+ * @returns the claim, given back when the server closes.
+ */
+export const claimCommandCache = (shared) => {
+    const parent = dirname(shared);
+    mkdirSync(parent, { recursive: true });
+    sweepOwn(parent, ownPrefix(shared));
+    const isShared = lock(lockFile(shared));
+    ownCount += 1;
+    const folder = isShared ? shared : join(parent, `${ownPrefix(shared)}${process.pid}-${ownCount}`);
+    let isReleased = false;
+    const release = () => {
+        if (isReleased)
+            return;
+        isReleased = true;
+        pending.delete(release);
+        if (isShared) {
+            if (lockHolder(lockFile(shared)) === process.pid)
+                removeIfPossible(lockFile(shared));
+        }
+        else
+            removeIfPossible(folder);
+    };
+    pending.add(release);
+    if (!isExitHooked) {
+        isExitHooked = true;
+        process.on("exit", releaseAll);
+    }
+    return { folder, isShared, release };
+};

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

@@ -2,6 +2,14 @@ import type { InlineConfig } from "vite";
 import type { ResolvedConfig } from "../../src/vite/configFile.ts";
 /** The folder, inside the catalogue's Vite cache folder, where the servers commands start keep their cache. */
 export declare const COMMAND_CACHE_FOLDER = "forgebook-commands";
+/**
+ * Ends a command that started a server, once its answer is out: a plugin of the app's build may leave a watcher or a timer
+ * behind, which would keep the process, and whoever waits for it, waiting for ever. A command that started none, or a dev
+ * server, ends as it would.
+ *
+ * @param code - the code the command ended with.
+ */
+export declare const leaveAfterCommand: (code: number) => void;
 /**
  * Vite's configuration for a server a command starts: the catalogue's, with a cache of its own.
  *

package/dist/bin/forgebook/commandServer.js

@@ -8,32 +8,80 @@
  * that are gone or of another bundle and fail as outdated. A command's server therefore keeps its cache in a folder of
  * its own inside the one the dev server uses: still warm from one command to the next, never the dev server's, and
  * outside its watcher (Vite ignores everything under its cache folder) and its cleanup (only the `deps` folder and
- * `_temp_` folders are removed).
+ * `_temp_` folders are removed). Two commands' servers at once are kept apart the same way (`commandCacheClaim.ts`).
  *
  * @module
  */
 import { join } from "node:path";
 import { catalogueVite } from "./catalogueVite.js";
+import { claimCommandCache } from "./commandCacheClaim.js";
 import { viteCacheDir } from "./viteCache.js";
 /** The folder, inside the catalogue's Vite cache folder, where the servers commands start keep their cache. */
 export const COMMAND_CACHE_FOLDER = "forgebook-commands";
 /**
- * Moves the server's cache into {@link COMMAND_CACHE_FOLDER} of the folder Vite would use: run after every other
- * plugin, so a framework's plugin that sets its own cache folder is followed too.
+ * Moves the server's cache into {@link COMMAND_CACHE_FOLDER} of the folder Vite would use, or into a folder of its own
+ * beside it while another server holds that one (`commandCacheClaim.ts`): run after every other plugin, so a framework's
+ * plugin that sets its own cache folder is followed too.
+ *
+ * @remarks
+ * The folder is claimed once per plugin and given back when the last server using it closes. A server Vite restarts (an
+ * `.env` file changed) is made anew with the same plugin before the old one closes: counting the servers keeps the
+ * claim through the restart, where giving it back at the old server's close would take the folder from the new one.
+ * `closeBundle` runs once per environment of a server; its client environment counts it.
+ */
+const commandCache = () => {
+    let claim;
+    let servers = 0;
+    return {
+        name: "forgebook:command-cache",
+        config: {
+            order: "post",
+            handler: (current) => {
+                claim ??= claimCommandCache(join(viteCacheDir(current), COMMAND_CACHE_FOLDER));
+                servers += 1;
+                return { cacheDir: claim.folder };
+            }
+        },
+        closeBundle() {
+            if (this.environment.name !== "client" || claim === undefined)
+                return;
+            servers -= 1;
+            if (servers > 0)
+                return;
+            claim.release();
+            claim = undefined;
+        }
+    };
+};
+/** Whether this process started a server for a command. */
+let hasStartedServer = false;
+/**
+ * Ends a command that started a server, once its answer is out: a plugin of the app's build may leave a watcher or a timer
+ * behind, which would keep the process, and whoever waits for it, waiting for ever. A command that started none, or a dev
+ * server, ends as it would.
+ *
+ * @param code - the code the command ended with.
+ */
+export const leaveAfterCommand = (code) => {
+    if (hasStartedServer)
+        process.stdout.write("", () => process.exit(code));
+};
+/**
+ * Sends what plugins log to stderr: a command's stdout is its answer (`--json`, the MCP protocol), and a plugin of the app's
+ * build that says what it fetches would break it. Nothing of the commands' own goes through `console`.
  */
-const commandCache = () => ({
-    name: "forgebook:command-cache",
-    config: {
-        order: "post",
-        handler: (current) => ({
-            cacheDir: join(viteCacheDir(current), COMMAND_CACHE_FOLDER)
-        })
-    }
-});
+const keepPluginsOffStdout = () => {
+    const { error } = console;
+    Object.assign(console, { log: error, info: error, debug: error });
+};
 /**
  * Vite's configuration for a server a command starts: the catalogue's, with a cache of its own.
  *
  * @param config - the catalogue's configuration, read.
  * @param overrides - what the command sets (the port, middleware mode).
  */
-export const commandServerVite = (config, overrides) => catalogueVite(config, { ...overrides, plugins: [...(overrides.plugins ?? []), commandCache()] });
+export const commandServerVite = (config, overrides) => {
+    hasStartedServer = true;
+    keepPluginsOffStdout();
+    return catalogueVite(config, { ...overrides, plugins: [...(overrides.plugins ?? []), commandCache()] }, "serve", true);
+};

package/dist/bin/forgebook/forgebookCommands.mjs

@@ -10,22 +10,30 @@
  *
  * @module
  */
-import { existsSync, writeFileSync } from "node:fs";
-import { relative, resolve } from "node:path";
+import { resolve } from "node:path";
 import { defineCommands } from "@ensiria/cli-kit/commands";
+import { formatJson, readPackageVersion } from "@ensiria/cli-kit/files";
 import { ScriptError } from "@ensiria/cli-kit/script";
 import { build } from "vite";
 import { filteredStories, isStoriesDocument, isStoryDocument } from "../../src/vite/agentApi.js";
+import { realFolder } from "../../src/vite/realFolder.js";
 import { agentLoopCommands } from "./agentLoopCommands.mjs";
+import { agentSetupCommands } from "./agentSetupCommands.mjs";
 import { storiesText, storyText } from "./agentText.js";
+import { auditCommands } from "./auditCommand.mjs";
+import { buildFailureText } from "./buildFailure.js";
 import { settleAgentIndex } from "./builtCatalogue.js";
-import { askCatalogue, COMMAND, configOf, FORGEBOOK_OPTIONS, printAnswer } from "./catalogueCommands.js";
+import { askCatalogue, COMMAND, configOf, configWithStoriesOf, FORGEBOOK_OPTIONS, printAnswer } from "./catalogueCommands.js";
 import { catalogueVite, withReadableNames } from "./catalogueVite.js";
+import { leaveAfterCommand } from "./commandServer.js";
 import { devCommands } from "./devCommands.mjs";
+import { graphCommands } from "./graphCommand.mjs";
+import { guideCommands } from "./guideCommand.mjs";
 import { initCommands } from "./initCommands.mjs";
 import { mcpCommands } from "./mcpCommand.mjs";
-import { newStoriesFile } from "./newStoriesFile.js";
+import { migrateCommands } from "./migrate/migrateCommand.mjs";
 import { pagesCommands } from "./pagesCommands.mjs";
+import { proofCommands } from "./proofCommand.mjs";
 import { runTokens } from "./tokensRun.js";
 import { visualCommands } from "./visualCommands.mjs";
 await defineCommands({
@@ -33,6 +41,8 @@ await defineCommands({
     command: COMMAND,
     summary: "Run a catalogue of stories from its forgebook.config.ts, build it, or answer tools and agents about it.",
     icon: "docs",
+    // the commit hook `init --agents` writes asks `--version` whether Forgebook is installed before it runs `verify`
+    version: readPackageVersion(import.meta.dirname),
     options: FORGEBOOK_OPTIONS,
     commands: (forgebook) => ({
         ...devCommands(forgebook),
@@ -52,6 +62,10 @@ await defineCommands({
                 "readable-names": {
                     type: "boolean",
                     description: "Name each script after its module as well as its hash (build.readableNames in the configuration)."
+                },
+                watch: {
+                    type: "boolean",
+                    description: "Stay running, and build again when a file the catalogue reads changes."
                 }
             },
             examples: [
@@ -59,16 +73,37 @@ await defineCommands({
                 {
                     command: `${COMMAND} build --base /pr-12/`,
                     description: "For a host that serves it under a sub-path."
+                },
+                {
+                    command: `${COMMAND} build --watch --out site`,
+                    description: "Keep site up to date as files change, for a host that serves the folder."
                 }
             ],
-            run: async ({ options, log }) => {
-                const config = withReadableNames(await configOf(options.config), options["readable-names"]);
-                const outDir = resolve(config.dir, options.out ?? "dist");
-                await build(await catalogueVite(config, {
+            run: async ({ options, log, onInterrupt }) => {
+                const config = withReadableNames(await configWithStoriesOf(options.config), options["readable-names"]);
+                // in the form of Vite's root, which empties an output it sees inside it
+                const outDir = realFolder(resolve(config.dir, options.out ?? "dist"));
+                const vite = await catalogueVite(config, {
                     ...(options.base === undefined ? {} : { base: options.base }),
                     build: { outDir }
-                }));
-                await settleAgentIndex(config, outDir, options["agent-index"] === true, log);
+                }, "build");
+                const settle = () => settleAgentIndex(config, outDir, options["agent-index"] === true, log);
+                if (options.watch === true) {
+                    const { watchBuild } = await import("./buildWatch.js");
+                    const stop = new AbortController();
+                    onInterrupt(() => stop.abort());
+                    await watchBuild({ vite, log, onBuilt: settle, signal: stop.signal });
+                    return;
+                }
+                try {
+                    await build(vite);
+                }
+                catch (error) {
+                    if (error instanceof Error && error.stack !== undefined)
+                        log.debug(error.stack);
+                    throw new ScriptError(buildFailureText(error));
+                }
+                await settle();
                 log.success(`${config.title} built`);
             }
         }),
@@ -82,6 +117,12 @@ await defineCommands({
                     valueName: "text",
                     description: "Only components whose title holds this text."
                 },
+                tag: {
+                    type: "string",
+                    multiple: true,
+                    valueName: "tag",
+                    description: "Only stories with any of these tags; !name leaves a tag's out, as the address's tag= does."
+                },
                 view: {
                     type: "string",
                     valueName: "query",
@@ -104,10 +145,14 @@ await defineCommands({
                     command: `${COMMAND} stories --component select --used-in --json`,
                     description: "The selects, with the components whose stories use them."
                 },
-                { command: `${COMMAND} stories --component button --json`, description: "The buttons, as JSON." }
+                { command: `${COMMAND} stories --component button --json`, description: "The buttons, as JSON." },
+                {
+                    command: `${COMMAND} stories --tag beta --tag '!wip'`,
+                    description: "The stories in beta, but for those in progress."
+                }
             ],
             run: async ({ options, io, log, isJson, style }) => {
-                const config = await configOf(options.config);
+                const config = await configWithStoriesOf(options.config);
                 const params = new URLSearchParams({
                     view: options.view ?? "",
                     usedIn: String(options["used-in"] === true)
@@ -115,7 +160,11 @@ await defineCommands({
                 const body = await askCatalogue(config, options.url, "stories", params, log);
                 if (!isStoriesDocument(body))
                     throw new ScriptError("The catalogue's answer has an unexpected shape");
-                const document = filteredStories(body, { source: options.source, component: options.component });
+                const document = filteredStories(body, {
+                    source: options.source,
+                    component: options.component,
+                    tags: options.tag
+                });
                 printAnswer(storiesText(document, style), document, document.problems, { io, log, isJson });
             }
         }),
@@ -211,6 +260,7 @@ await defineCommands({
         }),
         new: forgebook.command({
             summary: "Write a component's first stories from its props: the main story, one per choice, the worst case.",
+            json: true,
             options: {
                 export: {
                     type: "string",
@@ -223,7 +273,11 @@ await defineCommands({
                     description: "The framework the stories are written for: its package, @forgebook/<name>, reads the props. The catalogue's by default, else react."
                 },
                 print: { type: "boolean", description: "Print the file instead of writing it." },
-                force: { type: "boolean", description: "Replace a stories file that exists." }
+                force: { type: "boolean", description: "Replace a stories file that exists." },
+                repair: {
+                    type: "boolean",
+                    description: "Draw the stories in a browser, and draw them inside the components their errors name (a provider), at most twice. It serves the catalogue for the run, which runs the project's Vite configuration and the stories' code, as check does. JSX frameworks only."
+                }
             },
             positionals: [{ name: "file", description: "The component's file.", required: true }],
             examples: [
@@ -231,29 +285,37 @@ await defineCommands({
                 {
                     command: `${COMMAND} new src/menu.tsx --export Menu --print`,
                     description: "One of several, printed."
+                },
+                {
+                    command: `${COMMAND} new src/Sidebar.tsx --repair`,
+                    description: "Drawn, and given the providers it needs."
                 }
             ],
-            run: async ({ args, options, io, log }) => {
-                const written = await newStoriesFile(resolve(args.file), options.export, options.framework);
-                if (options.print) {
-                    io.stdout.write(written.text);
+            run: async ({ args, options, io, log, isJson }) => {
+                // the repair round reads programs with the compiler: loaded when the command runs, not when the CLI starts
+                const { runNew } = await import("./newRepairRun.js");
+                const outcome = await runNew(resolve(args.file), options);
+                if (outcome.printed !== undefined) {
+                    io.stdout.write(outcome.printed);
                     return;
                 }
-                const shown = relative(process.cwd(), written.file);
-                if (existsSync(written.file) && options.force !== true)
-                    throw new ScriptError(`${shown} exists`, {
-                        hint: "Give --force to replace it, or --print to see it"
-                    });
-                writeFileSync(written.file, written.text);
-                log.success(`${shown} written`);
-                log.info(`${COMMAND} stories --component ${written.text.match(/title: "([^"]*)"/)?.[1] ?? ""} lists them`);
+                if (isJson)
+                    io.stdout.write(formatJson(outcome.document));
+                for (const [tone, line] of outcome.lines)
+                    log[tone](line);
             }
         }),
         ...agentLoopCommands(forgebook),
+        ...guideCommands(forgebook),
+        ...auditCommands(forgebook),
+        ...graphCommands(forgebook),
         ...pagesCommands(forgebook),
         ...visualCommands(forgebook),
+        ...proofCommands(forgebook),
         ...initCommands(forgebook),
+        ...agentSetupCommands(forgebook),
         ...mcpCommands(forgebook),
+        ...migrateCommands(forgebook),
         story: forgebook.command({
             summary: "One story in detail: its args, its component's props, its links; fail when it cannot be read.",
             json: true,
@@ -263,6 +325,11 @@ await defineCommands({
                     valueName: "query",
                     description: "The view the links open in, as the catalogue's address writes it (theme=dark&lang=it)."
                 },
+                args: {
+                    type: "string",
+                    valueName: "json",
+                    description: "Values to set, as JSON: checked as a link's are, against `controls`; the links carry those taken, and a value left out fails the command."
+                },
                 url: {
                     type: "string",
                     env: "FORGEBOOK_URL",
@@ -277,11 +344,19 @@ await defineCommands({
                 {
                     command: `${COMMAND} story kit:actions-button--primary --view theme=dark --json`,
                     description: "A story, its links in the dark theme, as JSON."
+                },
+                {
+                    command: `${COMMAND} story kit:forms-select--overview --args '{"tags":["a","b"]}' --json`,
+                    description: "The links that open a story with these values, once checked."
                 }
             ],
             run: async ({ args, options, io, log, isJson, style }) => {
                 const config = await configOf(options.config);
-                const params = new URLSearchParams({ id: args.id, view: options.view ?? "" });
+                const params = new URLSearchParams({
+                    id: args.id,
+                    view: options.view ?? "",
+                    ...(options.args === undefined ? {} : { args: options.args })
+                });
                 const body = await askCatalogue(config, options.url, "story", params, log);
                 if (!isStoryDocument(body))
                     throw new ScriptError("The catalogue's answer has an unexpected shape");
@@ -289,4 +364,6 @@ await defineCommands({
             }
         })
     })
-}).run();
+})
+    .run()
+    .then(leaveAfterCommand);