forgebook 0.3.3 → 0.4.0

package/dist/bin/forgebook/agentSetup/agentFiles.js

@@ -0,0 +1,319 @@
+/**
+ * What `forgebook init --agents` writes for a project's coding agents: `.mcp.json`, the instructions and the skill, the CI
+ * workflow, and a hook that runs `verify` when an assistant finishes or before a commit.
+ *
+ * @remarks
+ * Every file is merged or left as it is, never replaced: `.mcp.json` and the assistants' settings keep what they hold, the
+ * instructions go between their markers, a workflow or a pre-commit hook already there stays and is named. They go at the
+ * repository's root, where assistants and CI start, and they find a package's catalogue through its folder. Which hooks is
+ * asked with `--hooks`; by default those of the assistants the repository shows signs of, and otherwise a pre-commit hook,
+ * which any assistant meets. A file that is a link is never written through. Nothing here runs the project's code.
+ *
+ * @module
+ */
+import { execFileSync } from "node:child_process";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative } from "node:path";
+import { VITE_PATHS } from "../../../src/vite/vitePaths.js";
+import { agentsSection } from "../agentGuide.js";
+import { agentsSkill, SKILL_FOLDERS, withAgentsSection } from "../agentsText.js";
+import { ASSISTANT_NAMES, ASSISTANTS, withMcpServer, withStopHook } from "./assistantHooks.js";
+import { WORKFLOW_FILE, workflowText } from "./ciWorkflow.js";
+import { forgebookCommandLine, forgebookInstalledLine, isPlainFolder, mcpServerOf } from "./projectRunner.js";
+/** The lock files a locked install reads. */
+const LOCK_FILES = ["package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"];
+/** How an assistant's hook names the project's root, for those whose documentation gives one. */
+const PROJECT_ROOT_VARIABLE = {
+    claude: "$CLAUDE_PROJECT_DIR/",
+    gemini: "$GEMINI_PROJECT_DIR/"
+};
+/** What marks a pre-commit hook as written here. */
+const OWN_PRE_COMMIT = /forgebook\b.*\bverify/;
+/**
+ * A project's repository root: the nearest folder holding `.git` whose repository tracks it, or the project's otherwise.
+ *
+ * @param projectDir - the project's folder.
+ */
+export const repositoryRoot = (projectDir) => {
+    let dir = projectDir;
+    while (true) {
+        if (existsSync(join(dir, ".git")))
+            return isTrackedBy(dir, projectDir) ? dir : projectDir;
+        const parent = dirname(dir);
+        if (parent === dir || dir === homedir())
+            return projectDir;
+        dir = parent;
+    }
+};
+/**
+ * Whether a repository holds a project: a home folder kept in git is above many projects it knows nothing of, and what is
+ * written at its root would be that person's settings for every project.
+ *
+ * @param root - the repository's folder.
+ * @param projectDir - the project's folder.
+ */
+const isTrackedBy = (root, projectDir) => {
+    if (root === projectDir)
+        return true;
+    try {
+        execFileSync("git", ["ls-files", "--error-unmatch", join(projectDir, "package.json")], {
+            cwd: root,
+            stdio: "pipe"
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * The hooks to write when none are named: those of the assistants the repository shows signs of, otherwise the commit's.
+ *
+ * @param root - the repository's root.
+ */
+export const detectedHooks = (root) => {
+    const used = ASSISTANT_NAMES.filter((name) => ASSISTANTS[name].markers.some((marker) => existsSync(join(root, marker))));
+    return used.length === 0 ? ["pre-commit"] : used;
+};
+/** Whether a path, or a folder on the way to it from the root, is a link: writing through one would change a file elsewhere. */
+const isLink = (root, name) => {
+    const parts = name.split("/");
+    return parts.some((_, index) => lstatSync(join(root, ...parts.slice(0, index + 1)), { throwIfNoEntry: false })?.isSymbolicLink() ===
+        true);
+};
+/** A file's text; none when it is not there. */
+const readIfThere = (file) => existsSync(file) ? readFileSync(file, "utf8") : undefined;
+/** Writes a file, its folder made. */
+const writeInto = (file, text) => {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, text);
+};
+/**
+ * Applies a merge to a file.
+ *
+ * @param root - the repository's root.
+ * @param name - the file, from there.
+ * @param merge - what to make of its text.
+ * @param done - what the run has done.
+ * @returns whether the file holds what it should now.
+ */
+const mergeFile = (root, name, merge, done) => {
+    const file = join(root, name);
+    if (isLink(root, name)) {
+        done.nextSteps.push({
+            kind: "setup",
+            file: name,
+            message: `${name} is a link, so it was left as it is: add Forgebook to it by hand`
+        });
+        return false;
+    }
+    const text = readIfThere(file);
+    const merged = merge(text);
+    if (merged.kind === "unreadable") {
+        done.nextSteps.push({
+            kind: "setup",
+            file: name,
+            message: `${name} could not be read as the JSON it should be, so it was left as it is: add Forgebook to it by hand`
+        });
+        return false;
+    }
+    if (merged.kind === "unchanged" || merged.text === text) {
+        done.unchanged.push(name);
+        return true;
+    }
+    writeInto(file, merged.text);
+    done.written.push(name);
+    return true;
+};
+/** Writes the instructions into `AGENTS.md`, between their markers, and the skill. */
+const writeInstructions = (root, framework, done) => {
+    const section = agentsSection([framework]);
+    mergeFile(root, "AGENTS.md", (text) => ({ kind: "written", text: withAgentsSection(text, section) }), done);
+    for (const folder of SKILL_FOLDERS)
+        mergeFile(root, `${folder}/SKILL.md`, () => ({ kind: "written", text: agentsSkill(section) }), done);
+};
+/** Writes the workflow on a repository with GitHub's signs, leaving one there; another host is told. */
+const writeWorkflow = (root, manager, folder, done) => {
+    const file = join(root, WORKFLOW_FILE);
+    if (isLink(root, WORKFLOW_FILE)) {
+        done.nextSteps.push({
+            kind: "setup",
+            file: WORKFLOW_FILE,
+            message: `${WORKFLOW_FILE} is a link, so no workflow was written`
+        });
+        return;
+    }
+    if (existsSync(file)) {
+        done.unchanged.push(WORKFLOW_FILE);
+        return;
+    }
+    const isGitHub = existsSync(join(root, ".github")) ||
+        /github\.com/.test(readIfThere(join(root, ".git", "config")) ?? "") ||
+        !existsSync(join(root, ".git"));
+    if (!isGitHub) {
+        done.nextSteps.push({
+            kind: "setup",
+            file: undefined,
+            message: `This repository is not on GitHub, so no workflow was written: in its CI, run ${forgebookCommandLine(manager, folder, "browser --with-deps")}, then ${forgebookCommandLine(manager, folder, "verify --since <target branch>")}`
+        });
+        return;
+    }
+    const hasLockFile = LOCK_FILES.some((name) => existsSync(join(root, name)));
+    writeInto(file, workflowText(manager, folder, hasLockFile));
+    done.written.push(WORKFLOW_FILE);
+};
+/** The folder a repository's git hooks are read from, as git says; none outside a repository or with `core.hooksPath`. */
+const gitHooksFolder = (root) => {
+    try {
+        const custom = execFileSync("git", ["config", "core.hooksPath"], {
+            cwd: root,
+            encoding: "utf8",
+            stdio: "pipe"
+        });
+        if (custom.trim() !== "")
+            return undefined;
+    }
+    catch {
+        // git says nothing when it is not set, by failing
+    }
+    try {
+        const path = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-path", "hooks"], {
+            cwd: root,
+            encoding: "utf8",
+            stdio: "pipe"
+        });
+        // git may name the folder in a short form (Windows' 8.3 names): the long one, as the root is named, compares
+        const folder = path.trim();
+        return existsSync(folder) ? realpathSync.native(folder) : folder;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The text of a pre-commit hook. */
+const preCommitLines = ({ installed, verify }) => "# Written by forgebook init --agents: a change whose UI is red does not get committed\n" +
+    // a teammate who has not installed yet commits as before: a hook that cannot run must not stop every commit
+    `if ${installed} >/dev/null 2>&1; then\n  ${verify}\nfi\n`;
+/** Adds `verify` to Husky's hook, which the repository keeps under version control. */
+const writeHusky = (root, commands, done) => {
+    const name = ".husky/pre-commit";
+    const file = join(root, name);
+    if (isLink(root, name)) {
+        done.nextSteps.push({
+            kind: "setup",
+            file: name,
+            message: `${name} is a link, so it was left as it is: add \`${commands.verify}\` to it`
+        });
+        return undefined;
+    }
+    const text = readIfThere(file) ?? "";
+    if (OWN_PRE_COMMIT.test(text))
+        done.unchanged.push(name);
+    else {
+        writeInto(file, `${text.replace(/\n*$/, text === "" ? "" : "\n")}${preCommitLines(commands)}`);
+        chmodSync(file, 0o755);
+        done.written.push(name);
+    }
+    return { name: "pre-commit", file: name, effect: "blocks-commit" };
+};
+/** Writes the commit's hook where the repository's tools keep it, or says why it did not. */
+const writePreCommit = (root, commands, done) => {
+    if (existsSync(join(root, ".husky")))
+        return writeHusky(root, commands, done);
+    const other = ["lefthook.yml", ".lefthook.yml", ".pre-commit-config.yaml"].find((name) => existsSync(join(root, name)));
+    const folder = other === undefined ? gitHooksFolder(root) : undefined;
+    const file = folder === undefined ? undefined : join(folder, "pre-commit");
+    // set up again, a hook that already runs verify (an earlier run's) is this one's own, not a setup of the repository's
+    if (file !== undefined &&
+        lstatSync(file, { throwIfNoEntry: false })?.isFile() === true &&
+        OWN_PRE_COMMIT.test(readIfThere(file) ?? "")) {
+        const shown = VITE_PATHS.normalize(relative(realpathSync.native(root), file));
+        done.unchanged.push(shown);
+        return { name: "pre-commit", file: shown, effect: "blocks-commit" };
+    }
+    const isTaken = file === undefined ||
+        existsSync(file) ||
+        lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink() === true;
+    if (isTaken) {
+        done.nextSteps.push({
+            kind: "setup",
+            file: other,
+            message: `The repository's commits have a hook setup of their own${other === undefined ? "" : ` (${other})`}, which was left as it is: add \`${commands.verify}\` to it`
+        });
+        return undefined;
+    }
+    writeInto(file, `#!/bin/sh\n${preCommitLines(commands)}`);
+    chmodSync(file, 0o755);
+    const shown = VITE_PATHS.normalize(relative(realpathSync.native(root), file));
+    done.written.push(shown);
+    done.nextSteps.push({
+        kind: "setup",
+        file: shown,
+        message: `${shown} holds the commit's hook, and git does not share that folder: a teammate's clone has none, so commit a hook setup (Husky, Lefthook) if they should have it too`
+    });
+    return { name: "pre-commit", file: shown, effect: "blocks-commit" };
+};
+/** Writes one hook. */
+const writeHook = (root, name, manager, folder, done) => {
+    if (name === "pre-commit")
+        return writePreCommit(root, {
+            installed: forgebookInstalledLine(manager, folder),
+            verify: forgebookCommandLine(manager, folder, "verify --quick")
+        }, done);
+    const assistant = ASSISTANTS[name];
+    // these two name their project's root, so a hook started from another folder still finds the package
+    const base = PROJECT_ROOT_VARIABLE[name] ?? "";
+    const command = forgebookCommandLine(manager, folder, `hook ${name}`, base);
+    if (!mergeFile(root, assistant.file, (text) => withStopHook(name, text, command), done))
+        return undefined;
+    if (assistant.caveat !== undefined)
+        done.nextSteps.push({
+            kind: "setup",
+            file: assistant.file,
+            message: `${assistant.caveat}: ${assistant.file}`
+        });
+    return { name, file: assistant.file, effect: assistant.effect };
+};
+/**
+ * Writes what a project's coding agents need.
+ *
+ * @param request - what for.
+ */
+export const writeAgentFiles = ({ projectDir, framework, manager, hooks }) => {
+    const root = repositoryRoot(projectDir);
+    const folder = VITE_PATHS.normalize(relative(root, projectDir));
+    const done = { written: [], unchanged: [], nextSteps: [] };
+    if (!isPlainFolder(folder))
+        return {
+            root: VITE_PATHS.normalize(relative(projectDir, root)) || ".",
+            written: [],
+            unchanged: [],
+            hooks: [],
+            nextSteps: [
+                {
+                    kind: "setup",
+                    file: undefined,
+                    message: "This folder's name holds characters a shell or a workflow would read as code, so nothing was written for the agents: run forgebook init --agents from a folder with a plain name"
+                }
+            ]
+        };
+    // before anything is written: the skill's own folder must not read as a sign of an assistant
+    const names = hooks === undefined
+        ? detectedHooks(root)
+        : [...ASSISTANT_NAMES, "pre-commit"].filter((name) => hooks.includes(name));
+    mergeFile(root, ".mcp.json", (text) => withMcpServer(text, mcpServerOf(manager, folder)), done);
+    writeInstructions(root, framework, done);
+    writeWorkflow(root, manager, folder, done);
+    const written = names.flatMap((name) => {
+        const hook = writeHook(root, name, manager, folder, done);
+        return hook === undefined ? [] : [hook];
+    });
+    return {
+        root: VITE_PATHS.normalize(relative(projectDir, root)) || ".",
+        written: done.written,
+        unchanged: done.unchanged,
+        hooks: written,
+        nextSteps: done.nextSteps
+    };
+};

package/dist/bin/forgebook/agentSetup/assistantHooks.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The assistants whose hook format `forgebook init --agents` writes, and what it writes for each: a hook that runs
+ * `forgebook hook <assistant>` when the assistant is about to finish.
+ *
+ * @remarks
+ * Only formats read in each assistant's own documentation are here; another assistant gets the pre-commit hook or the
+ * instructions. All four read JSON, so a file the project already has is merged, and one that cannot be parsed is left
+ * as it is and named. Cursor's `stop` hook cannot refuse to finish: it starts another turn with a message, so what it
+ * does is said separately (`effect`). Pure: text in, text out.
+ *
+ * @see https://code.claude.com/docs/en/hooks
+ * @see https://developers.openai.com/codex/hooks
+ * @see https://cursor.com/docs/agent/hooks
+ * @see https://geminicli.com/docs/hooks/reference/
+ * @module
+ */
+/** An assistant with a hook format. */
+export type AssistantName = "claude" | "codex" | "cursor" | "gemini";
+/** What a person reads about an assistant's hook, and where it goes. */
+export type Assistant = {
+    /** Its name, for a person. */
+    readonly label: string;
+    /** The file holding its project hooks, from the repository's root. */
+    readonly file: string;
+    /** What in a repository says it is used. */
+    readonly markers: readonly string[];
+    /** What the hook can do: refuse to finish, or start another turn. */
+    readonly effect: "blocks" | "continues";
+    /** What the assistant asks before the hook runs; none when it runs at once. */
+    readonly caveat: string | undefined;
+};
+/** The assistants, by the name `forgebook hook` takes. */
+export declare const ASSISTANTS: Readonly<Record<AssistantName, Assistant>>;
+/** The names, in the order they are listed. */
+export declare const ASSISTANT_NAMES: readonly AssistantName[];
+/** What came of merging a file. */
+export type MergedFile = {
+    /** The file's new text. */
+    readonly kind: "written";
+    /** Its text. */
+    readonly text: string;
+} | {
+    /** It already holds it. */
+    readonly kind: "unchanged";
+} | {
+    /** It cannot be parsed, or its shape is not the documented one: left as it is. */
+    readonly kind: "unreadable";
+};
+/**
+ * An assistant's hooks file with Forgebook's hook in it: everything else stays as it was.
+ *
+ * @param assistant - the assistant.
+ * @param text - the file's text; none when there is no file.
+ * @param command - the command the hook runs.
+ */
+export declare const withStopHook: (assistant: AssistantName, text: string | undefined, command: string) => MergedFile;
+/** The command of an MCP server, as a client starts it. */
+export type McpServer = {
+    /** The program. */
+    readonly command: string;
+    /** Its arguments. */
+    readonly args: readonly string[];
+};
+/**
+ * A `.mcp.json` with Forgebook's server in it: the other servers stay, and a server already named `forgebook` is the
+ * project's own choice, so it stays as well.
+ *
+ * @param text - the file's text; none when there is no file.
+ * @param server - how the client starts Forgebook's server.
+ */
+export declare const withMcpServer: (text: string | undefined, server: McpServer) => MergedFile;

package/dist/bin/forgebook/agentSetup/assistantHooks.js

@@ -0,0 +1,125 @@
+/**
+ * The assistants whose hook format `forgebook init --agents` writes, and what it writes for each: a hook that runs
+ * `forgebook hook <assistant>` when the assistant is about to finish.
+ *
+ * @remarks
+ * Only formats read in each assistant's own documentation are here; another assistant gets the pre-commit hook or the
+ * instructions. All four read JSON, so a file the project already has is merged, and one that cannot be parsed is left
+ * as it is and named. Cursor's `stop` hook cannot refuse to finish: it starts another turn with a message, so what it
+ * does is said separately (`effect`). Pure: text in, text out.
+ *
+ * @see https://code.claude.com/docs/en/hooks
+ * @see https://developers.openai.com/codex/hooks
+ * @see https://cursor.com/docs/agent/hooks
+ * @see https://geminicli.com/docs/hooks/reference/
+ * @module
+ */
+/** The assistants, by the name `forgebook hook` takes. */
+export const ASSISTANTS = {
+    claude: {
+        label: "Claude Code",
+        file: ".claude/settings.json",
+        markers: [".claude", "CLAUDE.md"],
+        effect: "blocks",
+        caveat: undefined
+    },
+    codex: {
+        label: "Codex",
+        file: ".codex/hooks.json",
+        markers: [".codex"],
+        effect: "blocks",
+        caveat: "Codex runs a project's hooks once they are reviewed and trusted"
+    },
+    cursor: {
+        label: "Cursor",
+        file: ".cursor/hooks.json",
+        markers: [".cursor", ".cursorrules"],
+        effect: "continues",
+        caveat: undefined
+    },
+    gemini: {
+        label: "Gemini CLI",
+        file: ".gemini/settings.json",
+        markers: [".gemini", "GEMINI.md"],
+        effect: "blocks",
+        caveat: undefined
+    }
+};
+/** The names, in the order they are listed. */
+export const ASSISTANT_NAMES = ["claude", "codex", "cursor", "gemini"];
+/** How long a hook may run, in seconds: a first start pre-bundles, and every view of every story runs. */
+const HOOK_SECONDS = 600;
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Whether a list of an event's entries already holds this very command: another package's catalogue has its own. */
+const holdsOwnHook = (entries, command) => JSON.stringify(entries).includes(JSON.stringify(command));
+/** What an assistant's file holds for one event: its name and the entry to add. */
+const eventEntry = (assistant, command) => {
+    const hook = { type: "command", command };
+    if (assistant === "cursor")
+        return { event: "stop", entry: { command, timeout: HOOK_SECONDS, loop_limit: 5 } };
+    if (assistant === "gemini")
+        return {
+            event: "AfterAgent",
+            entry: { hooks: [{ ...hook, name: "forgebook-verify", timeout: HOOK_SECONDS * 1000 }] }
+        };
+    return { event: "Stop", entry: { hooks: [{ ...hook, timeout: HOOK_SECONDS }] } };
+};
+/** The text of a parsed JSON file, or why it stays as it is: a file's top level must be an object. */
+const parsedObject = (text) => {
+    if (text === undefined || text.trim() === "")
+        return {};
+    try {
+        const parsed = JSON.parse(text);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * An assistant's hooks file with Forgebook's hook in it: everything else stays as it was.
+ *
+ * @param assistant - the assistant.
+ * @param text - the file's text; none when there is no file.
+ * @param command - the command the hook runs.
+ */
+export const withStopHook = (assistant, text, command) => {
+    const file = parsedObject(text);
+    if (file === undefined)
+        return { kind: "unreadable" };
+    const hooks = file["hooks"] ?? {};
+    if (!isRecord(hooks))
+        return { kind: "unreadable" };
+    const { event, entry } = eventEntry(assistant, command);
+    const entries = hooks[event] ?? [];
+    if (!Array.isArray(entries))
+        return { kind: "unreadable" };
+    if (holdsOwnHook(entries, command))
+        return { kind: "unchanged" };
+    const merged = {
+        ...(assistant === "cursor" ? { version: 1 } : {}),
+        ...file,
+        hooks: { ...hooks, [event]: [...entries, entry] }
+    };
+    return { kind: "written", text: `${JSON.stringify(merged, null, 2)}\n` };
+};
+/**
+ * A `.mcp.json` with Forgebook's server in it: the other servers stay, and a server already named `forgebook` is the
+ * project's own choice, so it stays as well.
+ *
+ * @param text - the file's text; none when there is no file.
+ * @param server - how the client starts Forgebook's server.
+ */
+export const withMcpServer = (text, server) => {
+    const file = parsedObject(text);
+    if (file === undefined)
+        return { kind: "unreadable" };
+    const servers = file["mcpServers"] ?? {};
+    if (!isRecord(servers))
+        return { kind: "unreadable" };
+    if ("forgebook" in servers)
+        return { kind: "unchanged" };
+    const merged = { ...file, mcpServers: { ...servers, forgebook: server } };
+    return { kind: "written", text: `${JSON.stringify(merged, null, 2)}\n` };
+};

package/dist/bin/forgebook/agentSetup/ciWorkflow.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The GitHub Actions workflow `forgebook init --agents` writes: on every pull request it installs the project, its browser,
+ * and runs `forgebook verify` against the branch the pull request targets.
+ *
+ * @remarks
+ * The whole history is fetched, since `verify` compares with where the branch left its target. The target's name comes
+ * through the environment and not into the script, where a branch's name could be read as shell. Its permissions are the
+ * least a read needs, and its actions are pinned as `workflowActions.ts` says. Pure.
+ *
+ * @module
+ */
+import type { PackageManagerName } from "../newProject/newProject.types.ts";
+/** The workflow's file, from the repository's root. */
+export declare const WORKFLOW_FILE = ".github/workflows/forgebook-verify.yml";
+/**
+ * The workflow's text.
+ *
+ * @param manager - the package manager.
+ * @param folder - the catalogue's folder from the repository's root, with forward slashes, plain (`isPlainFolder`); empty
+ * when it is the root.
+ * @param hasLockFile - whether the repository keeps a lock file, which a locked install needs.
+ */
+export declare const workflowText: (manager: PackageManagerName, folder: string, hasLockFile?: boolean) => string;

package/dist/bin/forgebook/agentSetup/ciWorkflow.js

@@ -0,0 +1,55 @@
+import { CHECKOUT, SETUP_BUN, SETUP_NODE } from "../workflowActions.js";
+import { forgebookCommandLine } from "./projectRunner.js";
+/** The workflow's file, from the repository's root. */
+export const WORKFLOW_FILE = ".github/workflows/forgebook-verify.yml";
+/** The steps that bring a package manager, and its install with the lock file. */
+const SETUP = {
+    npm: { steps: [], install: "npm ci" },
+    pnpm: { steps: ["      - run: corepack enable"], install: "pnpm install --frozen-lockfile" },
+    yarn: { steps: ["      - run: corepack enable"], install: "yarn install --immutable" },
+    bun: { steps: [`      - uses: ${SETUP_BUN}`], install: "bun install --frozen-lockfile" }
+};
+/**
+ * The workflow's text.
+ *
+ * @param manager - the package manager.
+ * @param folder - the catalogue's folder from the repository's root, with forward slashes, plain (`isPlainFolder`); empty
+ * when it is the root.
+ * @param hasLockFile - whether the repository keeps a lock file, which a locked install needs.
+ */
+export const workflowText = (manager, folder, hasLockFile = true) => {
+    const { steps, install: lockedInstall } = SETUP[manager];
+    const install = hasLockFile ? lockedInstall : `${manager} install`;
+    const browser = forgebookCommandLine(manager, folder, "browser --with-deps");
+    const verify = forgebookCommandLine(manager, folder, 'verify --since "origin/$BASE_BRANCH"');
+    return [
+        "# Written by `forgebook init --agents`: a pull request is not done until its changed UI ran in its stories.",
+        "name: Forgebook verify",
+        "",
+        "on:",
+        "  pull_request:",
+        "",
+        "permissions:",
+        "  contents: read",
+        "",
+        "jobs:",
+        "  verify:",
+        "    runs-on: ubuntu-latest",
+        "    timeout-minutes: 30",
+        "    steps:",
+        `      - uses: ${CHECKOUT}`,
+        "        with:",
+        "          fetch-depth: 0",
+        `      - uses: ${SETUP_NODE}`,
+        "        with:",
+        "          node-version: 24",
+        ...steps,
+        `      - run: ${install}`,
+        `      - run: ${browser}`,
+        `      - run: ${verify}`,
+        "        env:",
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: this is GitHub Actions' syntax, in the file it reads
+        "          BASE_BRANCH: ${{ github.base_ref }}",
+        ""
+    ].join("\n");
+};

package/dist/bin/forgebook/agentSetup/drawCandidates.d.ts

@@ -0,0 +1,25 @@
+/** How many candidates come back: past these, the reason is rarely the component. */
+export declare const CANDIDATE_LIMIT = 8;
+/**
+ * How promising a component's path is: lower comes first.
+ *
+ * @param path - the file, from the project's folder, with forward slashes.
+ * @param size - its size in bytes.
+ */
+export declare const candidateRank: (path: string, size: number) => number;
+/**
+ * The top folders story patterns cover: a component outside them gets stories the catalogue does not list.
+ *
+ * @param patterns - the patterns (`{app,components}/**\/*.stories.tsx`).
+ * @returns the folders; none when any pattern covers more than folders can say, so nothing is left out.
+ */
+export declare const storyFolders: (patterns: readonly string[]) => readonly string[];
+/**
+ * The project's component files to try, the most promising first.
+ *
+ * @param projectDir - the project's folder.
+ * @param framework - the adapter's name.
+ * @param folders - the top folders to look in; every one when none.
+ * @returns the files, from the project's folder.
+ */
+export declare const drawCandidates: (projectDir: string, framework: string, folders?: readonly string[]) => readonly string[];