forgebook 0.3.3 → 0.4.0

package/dist/bin/forgebook/proofWorkflow.js

@@ -0,0 +1,205 @@
+/**
+ * The GitHub workflow `forgebook proof --write-workflow` writes: the comparison in one job, the comment in another.
+ *
+ * @remarks
+ * The job that runs the branch's code holds no write token, and its checkout keeps no credential, so code under review
+ * has nothing to write with. It can still write what it likes in its result, so the job that posts, which runs nothing of
+ * the branch, trusts no text of it: it writes the comment itself from `proof.json`, every name in a code span or a fenced
+ * block with its backticks taken out, so nothing there is a mention, a link or an image, and it asks GitHub itself which
+ * files the pull request edits. `pull_request_target`, which would give a fork's code a write token, is never used. A
+ * fork's run has a read-only token, so the posting step cannot post: the proof stays in the run's summary and artefact.
+ *
+ * @module
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { CHECKOUT, DOWNLOAD, SETUP_BUN, SETUP_NODE, SETUP_PNPM, UPLOAD } from "./workflowActions.js";
+/** Where the workflow is written, from the repository's folder. */
+export const WORKFLOW_FILE = ".github/workflows/forgebook-proof.yml";
+/** Which of a pull request's files shape the run, as grep reads it; `proofRun.ts` holds the same for what it says itself. */
+const MAKES_THE_PROOF_TEXT = String.raw `^(\.github/|patches/)|(^|/)(forgebook\.(config|preview)\.[^/]+|vite\.config\.[^/]+|package\.json|package-lock\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml|yarn\.lock|bun\.lock|\.npmrc|\.yarnrc\.yml|\.pnpmfile\.c?js)$`;
+/** What finds the comment again, so a new push replaces it. */
+export const COMMENT_MARKER = "<!-- forgebook-proof -->";
+/** A package manager, by the lockfile that names it, and how it installs exactly what is locked. */
+const MANAGERS = [
+    {
+        lockfile: "pnpm-lock.yaml",
+        install: "pnpm install --frozen-lockfile",
+        setup: [`      - uses: ${SETUP_PNPM}`],
+        run: "pnpm exec"
+    },
+    {
+        lockfile: "yarn.lock",
+        install: "yarn install --immutable",
+        setup: ["      - run: corepack enable"],
+        run: "yarn exec"
+    },
+    {
+        lockfile: "bun.lock",
+        install: "bun install --frozen-lockfile",
+        setup: [`      - uses: ${SETUP_BUN}`],
+        run: "bunx"
+    },
+    { lockfile: "package-lock.json", install: "npm ci", setup: [], run: "npx" }
+];
+/**
+ * The command that installs what a checkout locks; none when no lockfile says.
+ *
+ * @param root - the checkout's folder.
+ */
+export const installCommandOf = (root) => MANAGERS.find(({ lockfile }) => existsSync(join(root, lockfile)))?.install;
+/**
+ * The comment, written from the proof by a job that trusts none of it, as jq reads it: `$files` are the edits GitHub names,
+ * `$run` the run's address, `$pictures` the pictures' address once checked. Backticks are written `\u0060` so this stays
+ * one template literal.
+ */
+export const COMMENT_FILTER = String.raw `def word: tostring | gsub("[\u0060\r\n\t|]"; " ") | .[0:120];
+def line: tostring | gsub("\u0060"; "'") | gsub("\r"; " ") | .[0:600];
+def fence($lines): "\u0060\u0060\u0060text\n" + ($lines | map(line) | join("\n")) + "\n\u0060\u0060\u0060";
+def row: "| \u0060 " + (.storyId | word) + " \u0060 | \u0060 " + ((if .view == "" then "default" else .view end) | word) + " \u0060 | "
+  + (if (.status | IN("changed","resized","new","broken","removed","unstable")) then .status else "unknown" end)
+  + " | " + ((.percent | tonumber? // 0) * 100 | round / 100 | tostring) + " % |";
+[
+  "### Forgebook proof",
+  "",
+  "Made by this branch's own run, so a hostile branch could forge what follows. Files it edits that shape the run, as GitHub lists them:",
+  "",
+  (if ($files | length) == 0 then "None." else fence($files[:100]) end),
+  "",
+  (if $pictures == "" then "[The run](" + $run + ")" else "[Before and after pictures](" + $pictures + "): open index.html in the download." end),
+  "",
+  "#### States touched",
+  "",
+  ((.states | length | tostring) + " differ, " + (.same | tonumber? // 0 | tostring) + " the same."),
+  "",
+  (if (.states | length) == 0 then "" else "| Story | View | Compared with the base | Pixels |\n|---|---|---|---|\n" + (.states[:40] | map(row) | join("\n")) end),
+  "",
+  "#### Checked",
+  "",
+  fence(["verdict: " + (.verdict | tostring), .summary] + .checked),
+  "",
+  "#### Not checked",
+  "",
+  (if (.notChecked | length) == 0 then "Nothing this run knows of." else fence(.notChecked[:60]) end)
+] | join("\n")`;
+/** What posts the comment, as the workflow's step runs it: with no proof, it says the run did not finish. */
+const POST_SCRIPT = String.raw `marker='${COMMENT_MARKER}'
+run_url="$GITHUB_SERVER_URL/$REPOSITORY/actions/runs/$RUN"
+if gh api "repos/$REPOSITORY/pulls/$PULL/files" --paginate --jq '.[].filename' > files.txt; then
+  grep -E "$OWN_FILES" files.txt | jq -R . | jq -s . > own.json || echo '[]' > own.json
+else
+  echo '["GitHub did not list the files: read them in the pull request"]' > own.json
+fi
+pictures=""
+artifact_id=$(basename "$ARTIFACT")
+case "$ARTIFACT" in
+  "$run_url/artifacts/$artifact_id")
+    if [ -n "$artifact_id" ] && [ -z "$(printf '%s' "$artifact_id" | tr -d 0-9)" ]; then pictures="$ARTIFACT"; fi
+    ;;
+esac
+if [ -s proof.json ] && text=$(jq -r --slurpfile own own.json --arg run "$run_url" --arg pictures "$pictures" "\$own[0] as \$files | $COMMENT_FILTER" proof.json); then
+  body="$marker"$'\n'"$text"
+else
+  body="$marker"$'\n'"### Forgebook proof"$'\n\n'"This run did not finish, so nothing is proved for this commit: [read the run]($run_url)."
+fi
+found=$(gh api "repos/$REPOSITORY/issues/$PULL/comments" --paginate --jq ".[] | select(.user.login == \"github-actions[bot]\" and (.body | startswith(\"$marker\"))) | .id" | head -n 1)
+if [ -n "$found" ]; then
+  gh api --method PATCH "repos/$REPOSITORY/issues/comments/$found" -f body="$body" > /dev/null
+else
+  gh api --method POST "repos/$REPOSITORY/issues/$PULL/comments" -f body="$body" > /dev/null
+fi`;
+/** A block of text at a YAML block's indent. */
+const indented = (text, spaces) => text
+    .split("\n")
+    .map((line) => (line === "" ? "" : `${" ".repeat(spaces)}${line}`))
+    .join("\n");
+/**
+ * The job that posts, the same for every project.
+ *
+ * @param download - the action that fetches the proof, as `uses` writes it.
+ */
+export const commentJob = (download) => `  comment:
+    needs: proof
+    if: \${{ !cancelled() }}
+    runs-on: ubuntu-latest
+    # runs nothing of the branch; a fork's token stays read-only whatever this asks
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: ${download}
+        continue-on-error: true
+        with:
+          name: forgebook-proof
+      - name: Post one comment
+        continue-on-error: true
+        env:
+          GH_TOKEN: \${{ github.token }}
+          ARTIFACT: \${{ needs.proof.outputs.artifact }}
+          PULL: \${{ github.event.pull_request.number }}
+          REPOSITORY: \${{ github.repository }}
+          RUN: \${{ github.run_id }}
+          OWN_FILES: ${JSON.stringify(MAKES_THE_PROOF_TEXT)}
+          COMMENT_FILTER: |
+${indented(COMMENT_FILTER, 12)}
+        run: |
+${indented(POST_SCRIPT, 10)}
+`;
+/**
+ * The workflow's text.
+ *
+ * @param root - the repository's folder, whose lockfile names the package manager.
+ * @param catalogue - the catalogue's folder, relative to it; empty when it is the repository's.
+ */
+export const proofWorkflow = (root, catalogue) => {
+    const manager = MANAGERS.find(({ lockfile }) => existsSync(join(root, lockfile))) ?? {
+        install: "npm install",
+        setup: [],
+        run: "npx"
+    };
+    const folder = catalogue === "" ? [] : [`        working-directory: ${JSON.stringify(catalogue)}`];
+    return `# A picture of every state a pull request touches, against its base, drawn in this run with nothing stored.
+name: forgebook proof
+on:
+  pull_request:
+
+# a newer push replaces the run, so an older one cannot overwrite its comment
+concurrency:
+  group: forgebook-proof-\${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  proof:
+    runs-on: ubuntu-latest
+    # what runs here is the branch's code: no write token, and no credential left in its checkout
+    permissions:
+      contents: read
+    outputs:
+      artifact: \${{ steps.pictures.outputs.artifact-url }}
+    steps:
+      - uses: ${CHECKOUT}
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+${[...manager.setup, ""].join("\n")}      - uses: ${SETUP_NODE}
+        with:
+          node-version: 24
+      - run: ${manager.install}
+      - run: ${manager.run} playwright install --with-deps chromium
+      - name: Compare the base and this branch
+${[...folder, ""].join("\n")}        run: ${manager.run} forgebook proof --base "origin/$BASE_REF" --out "$RUNNER_TEMP/forgebook-proof" --fail-on-verdict
+        env:
+          BASE_REF: \${{ github.base_ref }}
+      - name: Keep the proof in the run's summary
+        if: \${{ !cancelled() }}
+        run: cat "$RUNNER_TEMP/forgebook-proof/comment.md" >> "$GITHUB_STEP_SUMMARY" || true
+      - id: pictures
+        if: \${{ !cancelled() }}
+        uses: ${UPLOAD}
+        with:
+          name: forgebook-proof
+          path: \${{ runner.temp }}/forgebook-proof
+          if-no-files-found: ignore
+          retention-days: 14
+
+${commentJob(DOWNLOAD)}`;
+};

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

@@ -0,0 +1,8 @@
+import type { McpTool } from "../../src/vite/mcpProtocol.ts";
+import { type Ask } from "./mcpToolParts.ts";
+/**
+ * The tool that gives a story's links, with values when it is given some.
+ *
+ * @param ask - asks the catalogue.
+ */
+export declare const storyAddressTool: (ask: Ask) => McpTool;

package/dist/bin/forgebook/setArgsTool.js

@@ -0,0 +1,70 @@
+/**
+ * `story_address`: a story's links; given values, those that open it with the ones it takes, and what it left out, checked
+ * by the catalogue as a link's values are.
+ *
+ * @module
+ */
+import { isStoriesDocument, isStoryDocument } from "../../src/vite/agentApi.js";
+import { namedStory } from "../../src/vite/agentIds.js";
+import { resultOf, textOf, VIEW } from "./mcpToolParts.js";
+/** The tool's `args`, as an agent is told of them. */
+const SET_ARGS_PROPERTY = {
+    type: "object",
+    description: 'Values to set, by prop, as plain JSON: nested objects and lists as their shape says, `{ "of": type, "named": name }` for a named value, `{ "forgebookUnset": true }` for no value over the story\'s own.'
+};
+/**
+ * The answer.
+ *
+ * @param ask - asks the catalogue.
+ * @param id - the story's id.
+ * @param view - the view the links open in.
+ * @param values - the values, as the tool received them.
+ */
+const setArgsResult = async (ask, id, view, values) => {
+    const params = new URLSearchParams({ id, view: view ?? "", args: JSON.stringify(values) });
+    const answer = await ask("story", params);
+    if (answer.status !== 200 || !isStoryDocument(answer.body))
+        return resultOf(answer);
+    const { story, setArgs, problems } = answer.body;
+    return {
+        structured: {
+            id: story.id,
+            links: story.links,
+            accepted: setArgs?.accepted ?? {},
+            dropped: setArgs?.dropped ?? [],
+            problems
+        },
+        isError: false
+    };
+};
+/**
+ * The tool that gives a story's links, with values when it is given some.
+ *
+ * @param ask - asks the catalogue.
+ */
+export const storyAddressTool = (ask) => ({
+    name: "story_address",
+    description: "The links that open a story in the catalogue, in its frame alone, and with no chrome for a wiki or Notion (embed), in the view asked for: give them to a person to look at what you describe. With args, the links open the story with those values, once checked as a link's are against the controls get_story lists; what it takes and what it leaves out are in the answer.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            id: { type: "string", description: "The story's id, as list_stories gives it." },
+            view: VIEW,
+            args: SET_ARGS_PROPERTY
+        },
+        required: ["id"],
+        additionalProperties: false
+    },
+    call: async (args) => {
+        const id = textOf(args, "id") ?? "";
+        if (args["args"] !== undefined)
+            return setArgsResult(ask, id, textOf(args, "view"), args["args"]);
+        const answer = await ask("stories", new URLSearchParams({ view: textOf(args, "view") ?? "" }));
+        if (answer.status !== 200 || !isStoriesDocument(answer.body))
+            return resultOf(answer);
+        const named = namedStory(answer.body, id);
+        return named === undefined
+            ? { structured: { error: `No story "${id}"` }, isError: true }
+            : { structured: { id: named.story.id, links: named.story.links }, isError: false };
+    }
+});

package/dist/bin/forgebook/storyCheckCommands.mjs

@@ -2,9 +2,32 @@ import { EXIT } from "@ensiria/cli-kit/constants";
 import { formatJson } from "@ensiria/cli-kit/files";
 import { ScriptError } from "@ensiria/cli-kit/script";
 import { checkText } from "./agentText.js";
-import { COMMAND, configOf } from "./catalogueCommands.js";
+import { COMMAND, configWithStoriesOf } from "./catalogueCommands.js";
 import { SEMANTIC_OPTIONS, semanticModelOf } from "./semanticOptions.js";
 import { runStoryCheck } from "./storyCheckRun.js";
+import { runStoryStress } from "./stressRun.js";
+import { isStressFailure, stressText } from "./stressText.js";
+/** Refuses what `--stress` does not take: it chooses its own values and views. */
+const refuseWithStress = (options) => {
+    if ((options.view ?? []).length > 0 || options["all-variants"] === true || options.semantic === true)
+        throw new ScriptError("--stress chooses its own values and views: leave out --view, --all-variants and --semantic", {
+            exitCode: EXIT.usage
+        });
+};
+/** Runs the stress matrix and prints it, failing when a case breaks what the plain story does not. */
+const stressRun = async ({ config, url, id, io, log, isJson }) => {
+    const stressed = await runStoryStress(config, url, id);
+    if (typeof stressed === "string")
+        throw new ScriptError(stressed);
+    io.stdout.write(isJson ? formatJson(stressed) : `${stressText(stressed)}\n`);
+    for (const each of isJson ? (stressed.skipped ?? []) : [])
+        log.warn(each);
+    if (isStressFailure(stressed))
+        throw new ScriptError("A case breaks what the plain story does not", {
+            exitCode: EXIT.failure,
+            isReported: true
+        });
+};
 /**
  * The command.
  *
@@ -29,6 +52,10 @@ export const storyCheckCommands = (forgebook) => ({
                 type: "boolean",
                 description: "Also ask the configured model, sending it each story's tree and picture."
             },
+            stress: {
+                type: "boolean",
+                description: "Draw it with worst-case values and views it never declared (long text, unbreakable words, huge numbers, empty, right to left, 200 % zoom, narrow, dark, more contrast), with no story written, and report what each breaks that the plain story does not."
+            },
             ...SEMANTIC_OPTIONS,
             url: {
                 type: "string",
@@ -48,10 +75,19 @@ export const storyCheckCommands = (forgebook) => ({
             {
                 command: `${COMMAND} check kit:inputs-select --view "theme=dark" --json`,
                 description: "Every story of a component, in the dark theme, as JSON."
+            },
+            {
+                command: `${COMMAND} check kit:inputs-select--overview --stress --json`,
+                description: "The states nobody wrote a story for."
             }
         ],
-        run: async ({ args, options, io, isJson, style }) => {
-            const config = await configOf(options.config);
+        run: async ({ args, options, io, log, isJson, style }) => {
+            const config = await configWithStoriesOf(options.config);
+            if (options.stress === true) {
+                refuseWithStress(options);
+                await stressRun({ config, url: options.url, id: args.id, io, log, isJson });
+                return;
+            }
             const report = await runStoryCheck(config, options.url, {
                 id: args.id,
                 views: options.view ?? [],
@@ -64,6 +100,9 @@ export const storyCheckCommands = (forgebook) => ({
             const problems = report.results.reduce((count, result) => count + result.problems.length, 0);
             if (problems > 0)
                 throw new ScriptError(`${problems} problems`, { exitCode: EXIT.failure, isReported: true });
+            const notVerified = report.results.filter((result) => result.notVerified !== undefined).length;
+            if (notVerified > 0)
+                throw new ScriptError(`${notVerified} not verified`, { exitCode: EXIT.failure, isReported: true });
         }
     })
 });

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

@@ -2,6 +2,17 @@ import { type DeviceDefault } from "../../src/deviceView.ts";
 import { type SemanticModel, type StoryCheckReport, type StoryCheckStory, type StoryDiffReport, type StoryDiffRequest, type StoryShotReport } from "../../src/storyCheck.ts";
 import type { StoriesDocument } from "../../src/vite/agent.types.ts";
 import type { ResolvedConfig } from "../../src/vite/configFile.ts";
+/** What a run on several stories is asked: their ids, and whether to run every variant. */
+export type StoriesCheckInput = {
+    /** The stories' ids. */
+    readonly ids: readonly string[];
+    /** Story files, absolute, whose stories run too: a file just written has no id a caller knows yet. */
+    readonly files?: readonly string[];
+    /** Serve the catalogue for the run even when a dev server runs: a file just written must be read as it is now. */
+    readonly isOwnServer?: boolean;
+    /** Run every variant the catalogue's browser tests check; else the default view. */
+    readonly isAllVariants: boolean;
+};
 /** What a run is asked: the id, the views and whether to run every variant. */
 export type StoryCheckInput = {
     /** A story's id, or a component's for its listed stories. */
@@ -32,6 +43,12 @@ export declare const storiesNamed: (document: StoriesDocument, id: string, catal
  * @returns the function, or why it cannot be had.
  */
 export declare const testingFunction: (dir: string, specifier: string, name: string) => Promise<((request: unknown) => Promise<unknown>) | string>;
+/**
+ * The catalogue's stories, asked of its served address.
+ *
+ * @param origin - where it is served.
+ */
+export declare const storiesAt: (origin: string) => Promise<StoriesDocument | string>;
 /**
  * Runs the catalogue's checks.
  *
@@ -42,6 +59,15 @@ export declare const testingFunction: (dir: string, specifier: string, name: str
  * @returns the report, or why the check could not run.
  */
 export declare const runStoryCheck: (config: ResolvedConfig, url: string | undefined, input: StoryCheckInput, model?: SemanticModel | string) => Promise<StoryCheckReport | string>;
+/**
+ * Runs the catalogue's checks on several stories, on one browser and one server: what `verify` asks.
+ *
+ * @param config - the catalogue's configuration.
+ * @param url - where `forgebook dev` runs, when not at Vite's default address.
+ * @param input - the stories, and whether to check every variant.
+ * @returns the report, or why the check could not run.
+ */
+export declare const runStoriesCheck: (config: ResolvedConfig, url: string | undefined, input: StoriesCheckInput) => Promise<StoryCheckReport | string>;
 /**
  * Takes the stories' pictures.
  *
@@ -73,6 +99,30 @@ export declare const runStoryDiff: (config: ResolvedConfig, url: string | undefi
     readonly baselines: string;
     readonly outDir: string;
 }) => Promise<StoryDiffReport | string>;
+/**
+ * Takes several stories' pictures from one server and no other: what `proof` asks of each side.
+ *
+ * @param config - the catalogue's configuration, whose testing package and switches both sides are drawn with.
+ * @param origin - the server.
+ * @param input - the stories, and whether to picture every variant.
+ * @param outDir - the folder the pictures go in, absolute.
+ * @returns the pictures, or why they could not be taken.
+ */
+export declare const runStoriesShot: (config: ResolvedConfig, origin: string, input: StoriesCheckInput, outDir: string) => Promise<StoryShotReport | string>;
+/**
+ * Compares several stories' pictures with a folder of pictures, from one server and no other: what `proof` asks of the
+ * change.
+ *
+ * @param config - the catalogue's configuration.
+ * @param origin - the server.
+ * @param input - the stories, and whether to compare every variant.
+ * @param folders - the pictures to compare with and the folder the new ones go in, absolute.
+ * @returns the results, or why they could not be had.
+ */
+export declare const runStoriesDiff: (config: ResolvedConfig, origin: string, input: StoriesCheckInput, folders: {
+    readonly baselines: string;
+    readonly outDir: string;
+}) => Promise<StoryDiffReport | string>;
 /**
  * Checks pages of an application.
  *

package/dist/bin/forgebook/storyCheckRun.js

@@ -31,8 +31,11 @@ import { isStoriesDocument } from "../../src/vite/agentApi.js";
 import { formerIdOf, namedComponent, namedStory } from "../../src/vite/agentIds.js";
 import { AGENT_API } from "../../src/vite/agentRoutes.js";
 import { servedCatalogue } from "./agentClient.js";
+import { idsOfFiles } from "./storyFileIds.js";
 /** What the project installs to run the stories in a browser, and how. */
-const INSTALL = "Stories run in a browser with @forgebook/testing: npm install -D @forgebook/testing @playwright/test, then npx playwright install chromium";
+const INSTALL = "Stories run in a browser with @forgebook/testing: npm install -D @forgebook/testing @playwright/test, then forgebook browser";
+/** How many pages a run on several stories opens at once: enough to matter, few enough for a laptop or a CI runner. */
+const STORIES_AT_ONCE = 4;
 /**
  * A story of the document as a check reads it.
  *
@@ -44,6 +47,7 @@ const checkedStory = (component, story, catalogueDevice) => {
     const formerId = formerIdOf(component, story);
     return {
         id: story.id,
+        file: story.file,
         ...(formerId === undefined ? {} : { formerId }),
         ...(story.height === undefined ? {} : { height: story.height }),
         ...(story.isLogic ? { isLogic: true } : {}),
@@ -97,8 +101,12 @@ export const testingFunction = async (dir, specifier, name) => {
     try {
         resolved = createRequire(join(dir, "package.json")).resolve(specifier);
     }
-    catch {
-        return INSTALL;
+    catch (error) {
+        // installed, and older than the function asked for
+        const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+        return code === "ERR_PACKAGE_PATH_NOT_EXPORTED"
+            ? `${specifier} is not in this @forgebook/testing: update it`
+            : INSTALL;
     }
     const module = await import(__rewriteRelativeImportExtension(pathToFileURL(resolved).href));
     if (typeof module !== "object" || module === null || !(name in module))
@@ -116,7 +124,7 @@ export const testingFunction = async (dir, specifier, name) => {
  *
  * @param origin - where it is served.
  */
-const storiesAt = async (origin) => {
+export const storiesAt = async (origin) => {
     const response = await fetch(`${origin}${AGENT_API}stories`);
     const body = await response.json();
     return isStoriesDocument(body) ? body : `The catalogue answered ${response.status} for its stories`;
@@ -135,17 +143,20 @@ const runOnStories = async (config, url, input, run) => {
     if (typeof call === "string")
         return call;
     const switches = catalogueSwitches(config.switches, config.languages, config.lists.controls);
-    const views = queriesOf(input.views, switches);
+    const views = queriesOf(input.views ?? [], switches);
     if (typeof views === "string")
         return views;
-    const served = await servedCatalogue(config, url);
+    const served = run.exactOrigin === undefined
+        ? await servedCatalogue(config, url, "ids" in input && input.isOwnServer === true)
+        : { origin: run.exactOrigin, close: async () => undefined };
     try {
         const document = await storiesAt(served.origin);
         if (typeof document === "string")
             return document;
-        const stories = storiesNamed(document, input.id, deviceDefaultOf(NO_DEVICE, config.lists.device));
+        const ids = "ids" in input ? [...input.ids, ...idsOfFiles(document, config.dir, input.files ?? [])] : [input.id];
+        const stories = ids.flatMap((id) => storiesNamed(document, id, deviceDefaultOf(NO_DEVICE, config.lists.device)));
         if (stories.length === 0)
-            return `No story or component "${input.id}"`;
+            return `No story or component "${ids.join(", ")}"`;
         const request = {
             frameUrl: `${served.origin}/frame.html`,
             stories,
@@ -154,7 +165,11 @@ const runOnStories = async (config, url, input, run) => {
             views,
             isAllVariants: input.isAllVariants
         };
-        return await call({ ...request, ...run.extra(document) });
+        return await call({
+            ...request,
+            ...("ids" in input ? { concurrency: STORIES_AT_ONCE } : {}),
+            ...run.extra(document)
+        });
     }
     finally {
         await served.close();
@@ -182,6 +197,24 @@ export const runStoryCheck = async (config, url, input, model) => {
         return answer;
     return "@forgebook/testing/check answered something that is not a check's report";
 };
+/**
+ * Runs the catalogue's checks on several stories, on one browser and one server: what `verify` asks.
+ *
+ * @param config - the catalogue's configuration.
+ * @param url - where `forgebook dev` runs, when not at Vite's default address.
+ * @param input - the stories, and whether to check every variant.
+ * @returns the report, or why the check could not run.
+ */
+export const runStoriesCheck = async (config, url, input) => {
+    const answer = await runOnStories(config, url, input, {
+        specifier: "@forgebook/testing/check",
+        name: "checkStories",
+        extra: () => ({})
+    });
+    if (typeof answer === "string" || isStoryCheckReport(answer))
+        return answer;
+    return "@forgebook/testing/check answered something that is not a check's report";
+};
 /**
  * Takes the stories' pictures.
  *
@@ -234,6 +267,47 @@ export const runStoryDiff = async (config, url, input, folders) => {
         return answer;
     return "@forgebook/testing/diff answered something that is not a comparison's report";
 };
+/**
+ * Takes several stories' pictures from one server and no other: what `proof` asks of each side.
+ *
+ * @param config - the catalogue's configuration, whose testing package and switches both sides are drawn with.
+ * @param origin - the server.
+ * @param input - the stories, and whether to picture every variant.
+ * @param outDir - the folder the pictures go in, absolute.
+ * @returns the pictures, or why they could not be taken.
+ */
+export const runStoriesShot = async (config, origin, input, outDir) => {
+    const answer = await runOnStories(config, origin, input, {
+        specifier: "@forgebook/testing/shot",
+        name: "shotStories",
+        exactOrigin: origin,
+        extra: () => ({ outDir })
+    });
+    if (typeof answer === "string" || isStoryShotReport(answer))
+        return answer;
+    return "@forgebook/testing/shot answered something that is not a picture run's report";
+};
+/**
+ * Compares several stories' pictures with a folder of pictures, from one server and no other: what `proof` asks of the
+ * change.
+ *
+ * @param config - the catalogue's configuration.
+ * @param origin - the server.
+ * @param input - the stories, and whether to compare every variant.
+ * @param folders - the pictures to compare with and the folder the new ones go in, absolute.
+ * @returns the results, or why they could not be had.
+ */
+export const runStoriesDiff = async (config, origin, input, folders) => {
+    const answer = await runOnStories(config, origin, input, {
+        specifier: "@forgebook/testing/diff",
+        name: "diffStories",
+        exactOrigin: origin,
+        extra: () => folders
+    });
+    if (typeof answer === "string" || isStoryDiffReport(answer))
+        return answer;
+    return "@forgebook/testing/diff answered something that is not a comparison's report";
+};
 /**
  * Checks pages of an application.
  *

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

@@ -0,0 +1,15 @@
+/**
+ * The ids of the stories a catalogue lists for some story files: `forgebook new --repair` checks the file it just
+ * wrote, whose ids no caller knows yet.
+ *
+ * @module
+ */
+import type { StoriesDocument } from "../../src/vite/agent.types.ts";
+/**
+ * The ids of the listed stories of some story files.
+ *
+ * @param document - the catalogue's stories.
+ * @param dir - the catalogue's folder, which the document's files are relative to.
+ * @param files - the files, absolute.
+ */
+export declare const idsOfFiles: (document: StoriesDocument, dir: string, files: readonly string[]) => string[];

package/dist/bin/forgebook/storyFileIds.js

@@ -0,0 +1,14 @@
+import { VITE_PATHS } from "../../src/vite/vitePaths.js";
+/**
+ * The ids of the listed stories of some story files.
+ *
+ * @param document - the catalogue's stories.
+ * @param dir - the catalogue's folder, which the document's files are relative to.
+ * @param files - the files, absolute.
+ */
+export const idsOfFiles = (document, dir, files) => {
+    const wanted = new Set(files.map((file) => VITE_PATHS.normalize(file)));
+    return document.components.flatMap((component) => component.stories
+        .filter((story) => story.file !== undefined && wanted.has(VITE_PATHS.resolve(dir, story.file)))
+        .map((story) => story.id));
+};

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

@@ -0,0 +1,31 @@
+/**
+ * The cases of a stress run, from a story's props and the catalogue's switches: what `forgebook check --stress` asks the
+ * testing package to draw, with no story written.
+ *
+ * @remarks
+ * Pure. Only text a person reads is filled: a prop that names something (an id, a class, an address) is left alone. A text case needs a prop that takes text, a number case one that takes a number: a case with nothing to set is
+ * named as not run, never counted as passed. The values are the ones `forgebook new` writes in a story's worst case
+ * (`worstCase.ts`), so both test the same edges. Right to left uses the catalogue's direction switch when it has one,
+ * with text in a right-to-left script; dark and contrast use its scheme and contrast switches, and are not run without them.
+ *
+ * @module
+ */
+import type { StressCaseRequest } from "../../src/storyCheck.ts";
+import type { StoryControl } from "../../src/storyControls.ts";
+import { type ViewSwitch } from "../../src/switches.ts";
+/** Text in a right-to-left script, with a number and a Latin word in it, as real content mixes them. */
+export declare const RTL_TEXT = "\u0645\u0631\u062D\u0628\u0627 \u0628\u0627\u0644\u0639\u0627\u0644\u0645\u060C \u0647\u0630\u0627 \u0646\u0635 \u0637\u0648\u064A\u0644 \u0628\u0639\u0636 \u0627\u0644\u0634\u064A\u0621 12345 Forgebook";
+/** The cases a run asks for, and those it could not. */
+export type StressPlan = {
+    /** The cases to draw. */
+    readonly cases: readonly StressCaseRequest[];
+    /** The cases not run, and why. */
+    readonly skipped: readonly string[];
+};
+/**
+ * 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 declare const stressPlan: (controls: readonly StoryControl[], switches: readonly ViewSwitch[]) => StressPlan;