forgebook 0.3.3 → 0.4.0

package/dist/bin/forgebook/stressCases.js

@@ -0,0 +1,79 @@
+import { switchWithRole } from "../../src/switches.js";
+import { WORST_NUMBER, WORST_TEXT, WORST_WORD } from "../../src/worstCase.js";
+/** Text in a right-to-left script, with a number and a Latin word in it, as real content mixes them. */
+export const RTL_TEXT = "مرحبا بالعالم، هذا نص طويل بعض الشيء 12345 Forgebook";
+/** The window's width a 200 % zoom lays a page out in, from the default window's 1,280 px. */
+const ZOOMED_WIDTH = 640;
+/** A phone held upright, narrower than any variant the catalogue's tests check. */
+const NARROW_WIDTH = 320;
+/**
+ * A text prop that names something rather than shows it (an id, a reference to one, a class, a form field's name, an
+ * address), or a slot for a picture (an icon, an avatar). A long text there is no case, only an invalid value, and checks
+ * would find the value, not the component: text in an icon's slot draws over the label beside it.
+ */
+const NAMES_SOMETHING = /^(?:icon|avatar|image|img|logo|id|key|name|form|qa|role|lang|dir|slot|as|type|target|rel|href|src|htmlFor|for|tabIndex|autoComplete|inputMode|pattern|accept|class|className|testId)$|(?:ClassName|Class|Id|Ids|Url|Href|Src|Ref|Key|Icon|Avatar|Image|Logo)$|^aria-(?:labelledby|describedby|details|controls|owns|activedescendant|errormessage|flowto)$|^data-/;
+/**
+ * What axe finds when a control is given no text: an empty label is the case's doing, so a finding of these in `empty`
+ * would blame the component for the value it was given.
+ */
+const NAME_RULES = [
+    "button-name",
+    "link-name",
+    "label",
+    "select-name",
+    "input-button-name",
+    "aria-input-field-name",
+    "empty-heading"
+];
+/** The view that sets a switch of a role to the first value matching, when the catalogue has one. */
+const switchView = (switches, role, isWanted) => {
+    const found = switchWithRole(switches, role);
+    const value = found?.values.find(isWanted);
+    return found === undefined || value === undefined
+        ? undefined
+        : `${found.id}=${encodeURIComponent(value.value)}`;
+};
+/** The values that give every prop of a list one value. */
+const allOf = (props, value) => Object.fromEntries(props.map((prop) => [prop.name, value]));
+/**
+ * The cases for one story.
+ *
+ * @param controls - the props its values can set, as `forgebook story` lists them.
+ * @param switches - the catalogue's switches.
+ */
+export const stressPlan = (controls, switches) => {
+    const texts = controls.filter((each) => (each.control === "text" || each.control === "textarea") && !NAMES_SOMETHING.test(each.name));
+    const numbers = controls.filter((each) => each.control === "number" || each.control === "range");
+    const huge = Object.fromEntries(numbers.map((prop) => [prop.name, prop.max ?? WORST_NUMBER]));
+    const dark = switchView(switches, "colorScheme", (value) => value.scheme === "dark");
+    const more = switchView(switches, "contrast", (value) => value.isMore === true);
+    const rtl = switchView(switches, "direction", (value) => value.value === "rtl");
+    const noText = "no prop takes text";
+    const cases = [
+        texts.length === 0
+            ? `long-text: ${noText}`
+            : { name: "long-text", args: allOf(texts, WORST_TEXT), view: "" },
+        texts.length === 0
+            ? `unbreakable: ${noText}`
+            : { name: "unbreakable", args: allOf(texts, WORST_WORD), view: "" },
+        texts.length === 0
+            ? `empty: ${noText}`
+            : { name: "empty", args: allOf(texts, ""), view: "", expectedRules: NAME_RULES },
+        numbers.length === 0
+            ? "huge-number: no prop takes a number"
+            : { name: "huge-number", args: huge, view: "" },
+        rtl === undefined
+            ? { name: "rtl", args: allOf(texts, RTL_TEXT), view: "", isRtl: true }
+            : { name: "rtl", args: allOf(texts, RTL_TEXT), view: rtl },
+        { name: "zoom-200", args: {}, view: "", width: ZOOMED_WIDTH },
+        { name: "narrow", args: allOf(texts, WORST_TEXT), view: "", width: NARROW_WIDTH },
+        dark === undefined ? "dark: the catalogue has no dark scheme" : { name: "dark", args: {}, view: dark },
+        more === undefined
+            ? "contrast: the catalogue has no more-contrast value"
+            : { name: "contrast", args: {}, view: more }
+    ];
+    return {
+        cases: cases.filter((each) => typeof each !== "string"),
+        skipped: cases.filter((each) => typeof each === "string")
+    };
+};

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

@@ -0,0 +1,12 @@
+import { type StressReport } from "../../src/storyCheck.ts";
+import type { ResolvedConfig } from "../../src/vite/configFile.ts";
+/**
+ * Runs the stress matrix on the stories an id names: each drawn plain, then with worst-case values and views it never
+ * declared, and what each case breaks that the plain story does not.
+ *
+ * @param config - the catalogue's configuration.
+ * @param url - where `forgebook dev` runs, when not at Vite's default address.
+ * @param id - a story's id, or a component's for its listed stories.
+ * @returns the report, or why it could not run.
+ */
+export declare const runStoryStress: (config: ResolvedConfig, url: string | undefined, id: string) => Promise<StressReport | string>;

package/dist/bin/forgebook/stressRun.js

@@ -0,0 +1,61 @@
+/**
+ * What `forgebook check --stress` and `check_story` with `stress` run: the cases of each story an id names, built from its
+ * props and the catalogue's switches (`stressCases.ts`), drawn by `@forgebook/testing/stress` against the served catalogue.
+ *
+ * @module
+ */
+import { deviceDefaultOf, NO_DEVICE } from "../../src/deviceView.js";
+import { isStressReport } from "../../src/storyCheck.js";
+import { catalogueSwitches } from "../../src/switches.js";
+import { isStoryDocument } from "../../src/vite/agentApi.js";
+import { AGENT_API } from "../../src/vite/agentRoutes.js";
+import { servedCatalogue } from "./agentClient.js";
+import { storiesAt, storiesNamed, testingFunction } from "./storyCheckRun.js";
+import { stressPlan } from "./stressCases.js";
+/**
+ * Runs the stress matrix on the stories an id names: each drawn plain, then with worst-case values and views it never
+ * declared, and what each case breaks that the plain story does not.
+ *
+ * @param config - the catalogue's configuration.
+ * @param url - where `forgebook dev` runs, when not at Vite's default address.
+ * @param id - a story's id, or a component's for its listed stories.
+ * @returns the report, or why it could not run.
+ */
+export const runStoryStress = async (config, url, id) => {
+    const call = await testingFunction(config.dir, "@forgebook/testing/stress", "stressStories");
+    if (typeof call === "string")
+        return call;
+    const switches = catalogueSwitches(config.switches, config.languages, config.lists.controls);
+    const served = await servedCatalogue(config, url);
+    try {
+        const document = await storiesAt(served.origin);
+        if (typeof document === "string")
+            return document;
+        const stories = storiesNamed(document, id, deviceDefaultOf(NO_DEVICE, config.lists.device));
+        if (stories.length === 0)
+            return `No story or component "${id}"`;
+        const planned = await Promise.all(stories.map(async (story) => {
+            const response = await fetch(`${served.origin}${AGENT_API}story?id=${encodeURIComponent(story.id)}`);
+            const body = await response.json();
+            return isStoryDocument(body) ? { story, plan: stressPlan(body.controls, switches) } : story.id;
+        }));
+        const unread = planned.filter((each) => typeof each === "string");
+        if (unread.length > 0)
+            return `The catalogue could not say what these stories take: ${unread.join(", ")}`;
+        const plans = planned.filter((each) => typeof each !== "string");
+        const request = {
+            frameUrl: `${served.origin}/frame.html`,
+            stories: plans.map(({ story, plan }) => ({ story, cases: plan.cases })),
+            switches,
+            lists: config.lists
+        };
+        const answer = await call(request);
+        if (!isStressReport(answer))
+            return "@forgebook/testing/stress answered something that is not a stress report";
+        const skipped = plans.flatMap(({ story, plan }) => plan.skipped.map((each) => `${story.id}: ${each}`));
+        return { ...answer, skipped };
+    }
+    finally {
+        await served.close();
+    }
+};

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

@@ -0,0 +1,27 @@
+/**
+ * What a stress run says to a person, and when it fails.
+ *
+ * @module
+ */
+import type { StressReport } from "../../src/storyCheck.ts";
+import type { McpToolResult } from "../../src/vite/mcpProtocol.ts";
+/**
+ * Whether a run found what a case breaks, or a case it could not judge.
+ *
+ * @param report - the run.
+ */
+export declare const isStressFailure: (report: StressReport) => boolean;
+/**
+ * The run, a line per problem a case adds, then one line that sums it up.
+ *
+ * @param report - the run.
+ */
+export declare const stressText: (report: StressReport) => string;
+/**
+ * What `check_story` answers with `stress`: the run, an error when a case breaks something, and a refusal of the options
+ * it does not take, since it chooses its own values and views.
+ *
+ * @param stress - runs the stress matrix on an id.
+ * @param args - the tool's arguments.
+ */
+export declare const stressToolResult: (stress: (id: string) => Promise<StressReport | string>, args: Readonly<Record<string, unknown>>) => Promise<McpToolResult>;

package/dist/bin/forgebook/stressText.js

@@ -0,0 +1,46 @@
+/**
+ * Whether a run found what a case breaks, or a case it could not judge.
+ *
+ * @param report - the run.
+ */
+export const isStressFailure = (report) => report.cases.some((each) => each.name !== "plain" && (each.problems.length > 0 || each.notVerified !== undefined));
+/**
+ * The run, a line per problem a case adds, then one line that sums it up.
+ *
+ * @param report - the run.
+ */
+export const stressText = (report) => {
+    const cases = report.cases.filter((each) => each.name !== "plain");
+    const lines = cases.flatMap((each) => [
+        ...(each.notVerified === undefined
+            ? []
+            : [`${each.storyId} ${each.name}: not judged: ${each.notVerified}`]),
+        ...each.problems.map((problem) => `${each.storyId} ${each.name}: ${problem.message}`)
+    ]);
+    const breaking = cases.filter((each) => each.problems.length > 0).length;
+    return [
+        ...lines,
+        ...(report.skipped ?? []).map((each) => `not run: ${each}`),
+        `${cases.length} cases, ${breaking} break what the plain story does not`
+    ].join("\n");
+};
+/**
+ * What `check_story` answers with `stress`: the run, an error when a case breaks something, and a refusal of the options
+ * it does not take, since it chooses its own values and views.
+ *
+ * @param stress - runs the stress matrix on an id.
+ * @param args - the tool's arguments.
+ */
+export const stressToolResult = async (stress, args) => {
+    if (args["views"] !== undefined || args["allVariants"] === true || args["semantic"] === true)
+        return {
+            structured: {
+                error: "stress chooses its own values and views: leave out views, allVariants and semantic"
+            },
+            isError: true
+        };
+    const stressed = await stress(typeof args["id"] === "string" ? args["id"] : "");
+    if (typeof stressed === "string")
+        return { structured: { error: stressed }, isError: true };
+    return { structured: stressed, isError: isStressFailure(stressed) };
+};

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

@@ -0,0 +1,45 @@
+import type { StoryCheckReport, StoryCheckResult, StoryProblem } from "../../src/storyCheck.ts";
+import type { ResolvedConfig } from "../../src/vite/configFile.ts";
+/**
+ * A problem as a key two runs share when it is the same problem: an accessibility rule by its element (its message
+ * carries measures, as a contrast's ratio), anything else by its message without what differs between runs.
+ *
+ * @param result - the story and view it was found in.
+ * @param problem - the problem.
+ * @param folders - the folders to take out of its message: the working tree's and the base's.
+ */
+export declare const problemKey: (result: Pick<StoryCheckResult, "storyId" | "view">, problem: StoryProblem, folders: readonly string[]) => string;
+/** What the base's report says, split: the change's problems, those the base had, and stories the base did not see. */
+export type SplitByBase = {
+    /** The change's report with only the problems the base did not have. */
+    readonly report: StoryCheckReport;
+    /** The problems the base had too, by story and view. */
+    readonly existing: readonly StoryCheckResult[];
+    /** How many stories the base never saw in their final state: their problems all count. */
+    readonly unseen: number;
+};
+/**
+ * The head's results split into the problems the change brought and those the base had too, each of the base's
+ * problems matching one of the change's.
+ *
+ * @param head - the report on the change.
+ * @param base - the report on the base, for the stories that failed on the change.
+ * @param folders - the working tree's folder and the base's, taken out of the messages.
+ */
+export declare const splitByBase: (head: StoryCheckReport, base: StoryCheckReport, folders: readonly string[]) => SplitByBase;
+/** The base's run: its report, the folder it ran in and the working tree's root, or why it could not run. */
+export type BaseRun = {
+    readonly report: StoryCheckReport;
+    readonly folder: string;
+    readonly root: string;
+} | string;
+/**
+ * Runs stories on the base commit, in a worktree of its own beside the repository, removed after.
+ *
+ * @param config - the catalogue's configuration on the change.
+ * @param base - the base commit, as `git merge-base` gave it.
+ * @param ids - the stories to run.
+ * @param isAllVariants - whether every variant runs, as on the change.
+ * @param runEnv - the run's environment.
+ */
+export declare const runOnBase: (config: ResolvedConfig, base: string, ids: readonly string[], isAllVariants: boolean, runEnv: Readonly<Record<string, string | undefined>>) => Promise<BaseRun>;

package/dist/bin/forgebook/verifyBase.js

@@ -0,0 +1,196 @@
+/**
+ * The stories `verify` found a problem in, run again on the commit the change starts from, so the verdict counts only
+ * what the change brought: an application whose stories already break an accessibility rule would otherwise fail every
+ * change, and a red verdict that is always red tells an agent nothing.
+ *
+ * @remarks
+ * The base is checked out with `git worktree add --detach` beside the repository (a hidden folder next to it, named
+ * after the base and the process, removed after; one a run left behind is removed by the next), so the working tree is
+ * never touched. It has no dependencies of its own: each `node_modules` folder of the working tree gets a twin in it whose
+ * entries link to the working tree's, except a workspace package, which links to the same package in the base, so the
+ * base runs its own code. Its catalogue is served by a server of its own for the run, which runs the base's configuration.
+ * A problem is the same in both when its story, view, kind and rule match and, for an accessibility rule, its element,
+ * else its message once addresses, positions and the two folders are taken out; each problem of the base matches one of
+ * the change's, so a second copy of an old problem is new.
+ *
+ * @module
+ */
+import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { findConfigFile } from "../../src/vite/configFile.js";
+import { gitOutput, gitOutputIn } from "../../src/vite/gitChange.js";
+import { configOf } from "./catalogueCommands.js";
+import { isProcessRunning } from "./commandCacheClaim.js";
+import { runStoriesCheck } from "./storyCheckRun.js";
+/** Folders whose `node_modules` are not looked for: the base's own copies of them hold no package. */
+const NOT_WALKED = new Set(["node_modules", ".git"]);
+/** How deep folders are searched for a `node_modules` to link: a monorepo's packages sit a few levels down. */
+const MAX_DEPTH = 4;
+/**
+ * The folders of a tree, relative to it, that hold a `node_modules`, at most `MAX_DEPTH` levels down.
+ *
+ * @param root - the working tree's root.
+ */
+const modulesFolders = (root) => {
+    const found = [];
+    const walk = (folder, depth) => {
+        if (existsSync(join(root, folder, "node_modules")))
+            found.push(folder);
+        if (depth >= MAX_DEPTH)
+            return;
+        for (const entry of readdirSync(join(root, folder), { withFileTypes: true })) {
+            if (entry.isDirectory() && !NOT_WALKED.has(entry.name) && !entry.name.startsWith("."))
+                walk(join(folder, entry.name), depth + 1);
+        }
+    };
+    walk("", 0);
+    return found;
+};
+/** Where a working tree's package link should point in the base: the same package there, when it is a workspace's. */
+const linkTarget = (entry, root, folder) => {
+    if (!lstatSync(entry).isSymbolicLink())
+        return entry;
+    const real = realpathSync(entry);
+    const inside = relative(root, real);
+    const isWorkspace = !inside.startsWith("..") && !inside.split(sep).includes("node_modules");
+    return isWorkspace ? join(folder, inside) : entry;
+};
+/**
+ * Gives a base folder a `node_modules` twin of the working tree's: each entry linked to the working tree's, a workspace
+ * package to the base's own.
+ *
+ * @param from - the working tree's `node_modules`.
+ * @param to - the base's, made.
+ * @param root - the working tree's root.
+ * @param folder - the base's root.
+ */
+const twinModules = (from, to, root, folder) => {
+    mkdirSync(to, { recursive: true });
+    for (const name of readdirSync(from)) {
+        const entry = join(from, name);
+        if (name.startsWith("@") && lstatSync(entry).isDirectory())
+            twinModules(entry, join(to, name), root, folder);
+        else
+            symlinkSync(linkTarget(entry, root, folder), join(to, name), "junction");
+    }
+};
+/** The prefix of the folders a base runs in, beside the repository. */
+const folderPrefix = (root) => `.${basename(root)}-forgebook-base-`;
+/**
+ * The environment of the git commands that make, remove and prune the base's worktree: without `GIT_INDEX_FILE`, which
+ * git sets for its hooks. A pre-commit hook that runs `verify` would otherwise have the base's checkout written into the
+ * index of the commit being made: a relative one fails the checkout, and an absolute one (`git commit -a`) turns the
+ * commit into the base's files.
+ *
+ * @param env - the run's environment.
+ */
+const worktreeEnv = (env) => Object.fromEntries(Object.entries(env).filter(([name]) => name !== "GIT_INDEX_FILE"));
+/** Removes the base folders a run that is gone left beside the repository, and git's record of them. */
+const sweep = async (root, env) => {
+    const prefix = folderPrefix(root);
+    for (const name of readdirSync(dirname(root)).filter((each) => each.startsWith(prefix))) {
+        const pid = Number(name.split("-").pop());
+        if (Number.isInteger(pid) && !isProcessRunning(pid))
+            rmSync(join(dirname(root), name), { recursive: true, force: true });
+    }
+    await gitOutputIn(root, env, "worktree", "prune").catch(() => undefined);
+};
+/** Positions, query stamps and addresses: what differs between two runs of the same code. */
+const RUN_NOISE = [/https?:\/\/[^\s)'"]+/g, /:\d+:\d+/g, /\?[a-z]=[\w.-]+/g];
+/** A problem's message with what differs between two runs of the same story taken out. */
+const plainMessage = (message, folders) => RUN_NOISE.reduce((text, noise) => text.replace(noise, ""), folders.reduce((text, folder) => text.split(folder).join("<root>"), message));
+/**
+ * A problem as a key two runs share when it is the same problem: an accessibility rule by its element (its message
+ * carries measures, as a contrast's ratio), anything else by its message without what differs between runs.
+ *
+ * @param result - the story and view it was found in.
+ * @param problem - the problem.
+ * @param folders - the folders to take out of its message: the working tree's and the base's.
+ */
+export const problemKey = (result, problem, folders) => [
+    result.storyId,
+    result.view,
+    problem.kind,
+    problem.rule ?? "",
+    problem.kind === "axe" ? (problem.element ?? "") : plainMessage(problem.message, folders)
+].join("\u0000");
+/**
+ * The head's results split into the problems the change brought and those the base had too, each of the base's
+ * problems matching one of the change's.
+ *
+ * @param head - the report on the change.
+ * @param base - the report on the base, for the stories that failed on the change.
+ * @param folders - the working tree's folder and the base's, taken out of the messages.
+ */
+export const splitByBase = (head, base, folders) => {
+    const left = new Map();
+    const seen = base.results.filter((result) => result.notVerified === undefined);
+    for (const result of seen)
+        for (const problem of result.problems) {
+            const key = problemKey(result, problem, folders);
+            left.set(key, (left.get(key) ?? 0) + 1);
+        }
+    const results = head.results.map((result) => {
+        const brought = [];
+        const old = [];
+        for (const problem of result.problems) {
+            const key = problemKey(result, problem, folders);
+            const count = left.get(key) ?? 0;
+            if (count > 0) {
+                left.set(key, count - 1);
+                old.push(problem);
+            }
+            else
+                brought.push(problem);
+        }
+        return { result, brought, old };
+    });
+    return {
+        report: { ...head, results: results.map(({ result, brought }) => ({ ...result, problems: brought })) },
+        existing: results
+            .filter(({ old }) => old.length > 0)
+            .map(({ result, old }) => ({ ...result, problems: old })),
+        unseen: base.results.length - seen.length
+    };
+};
+/**
+ * Runs stories on the base commit, in a worktree of its own beside the repository, removed after.
+ *
+ * @param config - the catalogue's configuration on the change.
+ * @param base - the base commit, as `git merge-base` gave it.
+ * @param ids - the stories to run.
+ * @param isAllVariants - whether every variant runs, as on the change.
+ * @param runEnv - the run's environment.
+ */
+export const runOnBase = async (config, base, ids, isAllVariants, runEnv) => {
+    const env = worktreeEnv(runEnv);
+    const root = (await gitOutput(config.dir, "rev-parse", "--show-toplevel")).trim();
+    const folder = join(dirname(root), `${folderPrefix(root)}${base.slice(0, 12)}-${process.pid}`);
+    const twins = [];
+    try {
+        await sweep(root, env);
+        await gitOutputIn(root, env, "worktree", "add", "--detach", "--force", folder, base);
+        for (const each of modulesFolders(root)) {
+            const twin = join(folder, each, "node_modules");
+            if (!existsSync(join(folder, each)) || existsSync(twin))
+                continue;
+            twinModules(join(root, each, "node_modules"), twin, root, folder);
+            twins.push(twin);
+        }
+        const configFile = findConfigFile(join(folder, relative(root, config.dir)));
+        if (configFile === undefined)
+            return "the catalogue has no configuration at the base";
+        const report = await runStoriesCheck(await configOf(configFile), undefined, { ids, isAllVariants });
+        return typeof report === "string" ? report : { report, folder, root };
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    finally {
+        // the links go first, so nothing that removes the worktree can follow one into the working tree
+        for (const twin of twins)
+            rmSync(twin, { recursive: true, force: true });
+        await gitOutputIn(root, env, "worktree", "remove", "--force", folder).catch(() => undefined);
+        rmSync(folder, { recursive: true, force: true });
+    }
+};

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

@@ -0,0 +1,13 @@
+/**
+ * `forgebook verify`: whether a change is done, with one exit code.
+ *
+ * @module
+ */
+import type { CommandNode, CommandScope } from "@ensiria/cli-kit/commands.types";
+import { type ForgebookOptions } from "./catalogueCommands.ts";
+/**
+ * The command.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export declare const verifyCommands: (forgebook: CommandScope<ForgebookOptions>) => Readonly<Record<string, CommandNode>>;

package/dist/bin/forgebook/verifyCommand.mjs

@@ -0,0 +1,125 @@
+import { EXIT } from "@ensiria/cli-kit/constants";
+import { formatJson } from "@ensiria/cli-kit/files";
+import { ScriptError } from "@ensiria/cli-kit/script";
+import { isVisibilityDocument } from "../../src/vite/agentVisibility.js";
+import { emptyStoryGlobsProblems } from "../../src/vite/emptyStoryGlobs.js";
+import { catalogueClient } from "./agentClient.js";
+import { verifyText, visibilityText } from "./agentText.js";
+import { COMMAND, configOf, configWithStoriesOf } from "./catalogueCommands.js";
+import { runStoriesCheck } from "./storyCheckRun.js";
+import { runOnBase } from "./verifyBase.js";
+import { errorOf, isVerifyFailure, runVerify } from "./verifyRun.js";
+/**
+ * The command.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export const verifyCommands = (forgebook) => ({
+    verify: forgebook.command({
+        summary: "Say whether a change is done: every changed UI file in stories that ran, in every variant, and what it adds against the design system.",
+        json: true,
+        options: {
+            since: {
+                type: "string",
+                valueName: "ref",
+                description: "The commit to compare with, from where the branch left it; the default branch by default, so what is committed on this branch counts."
+            },
+            quick: {
+                type: "boolean",
+                description: "Only the default view of each story: faster, and the verdict says so."
+            },
+            "all-problems": {
+                type: "boolean",
+                description: "Fail on every problem the stories have, not only those the change brought: the stories that found one are not run again on the base."
+            },
+            url: {
+                type: "string",
+                env: "FORGEBOOK_URL",
+                valueName: "address",
+                description: "Where forgebook dev runs, when not at Vite's default address (http://localhost:5173)."
+            }
+        },
+        examples: [
+            { command: `${COMMAND} verify`, description: "Before you say a change is done." },
+            { command: `${COMMAND} verify --since origin/develop --json`, description: "In a pull request." },
+            { command: `${COMMAND} verify --quick`, description: "While you work: the default view of each story." }
+        ],
+        run: async ({ options, io, log, isJson, style }) => {
+            // a pattern that matches nothing leaves the answer not verified, and the rest of it is still given
+            const config = await configOf(options.config);
+            const client = await catalogueClient(config, options.url);
+            try {
+                const document = await runVerify({
+                    dir: config.dir,
+                    ask: client.ask,
+                    check: (input) => runStoriesCheck(config, options.url, input),
+                    checkBase: (base, input) => runOnBase(config, base, input.ids, input.isAllVariants, io.env)
+                }, {
+                    since: options.since,
+                    isQuick: options.quick === true,
+                    isAllProblems: options["all-problems"] === true,
+                    configProblems: emptyStoryGlobsProblems(config)
+                });
+                if (typeof document === "string")
+                    throw new ScriptError(document);
+                io.stdout.write(isJson ? formatJson(document) : `${verifyText(document, style)}\n`);
+                // the line says them to a person; a pipeline reading the JSON still shows them in its log
+                if (isJson)
+                    for (const each of document.skipped)
+                        log.warn(each);
+                if (isVerifyFailure(document))
+                    throw new ScriptError(document.summary, { exitCode: EXIT.failure, isReported: true });
+            }
+            finally {
+                await client.close();
+            }
+        }
+    }),
+    visibility: forgebook.command({
+        summary: "List the published components an agent cannot see, with the fix for each: no story of their own, stories all tagged !dev, no props to read, no TSDoc.",
+        json: true,
+        options: {
+            since: {
+                type: "string",
+                valueName: "ref",
+                description: "Only those a change touches or starts publishing, as verify holds them; every published component by default."
+            },
+            url: {
+                type: "string",
+                env: "FORGEBOOK_URL",
+                valueName: "address",
+                description: "Where forgebook dev runs, when not at Vite's default address (http://localhost:5173)."
+            }
+        },
+        examples: [
+            {
+                command: `${COMMAND} visibility`,
+                description: "What a library's agents will rebuild instead of reuse."
+            },
+            { command: `${COMMAND} visibility --json`, description: "As an agent asks." }
+        ],
+        run: async ({ options, io, log, isJson }) => {
+            const config = await configWithStoriesOf(options.config);
+            const client = await catalogueClient(config, options.url);
+            try {
+                const params = new URLSearchParams(options.since === undefined ? {} : { since: options.since });
+                const answer = await client.ask("visibility", params);
+                if (answer.status !== 200 || !isVisibilityDocument(answer.body))
+                    throw new ScriptError(errorOf(answer.body, answer.status));
+                const document = answer.body;
+                io.stdout.write(isJson ? formatJson(document) : `${visibilityText(document)}\n`);
+                if (isJson)
+                    for (const each of document.skipped)
+                        log.warn(each);
+                if (document.unseen.length > 0)
+                    throw new ScriptError(`${document.unseen.length} published components agents cannot see`, {
+                        exitCode: EXIT.failure,
+                        isReported: true
+                    });
+            }
+            finally {
+                await client.close();
+            }
+        }
+    })
+});