@ramon-sg/issue-flow 0.0.0-stage → 0.1.0

package/dist/commands/adapter.js

@@ -0,0 +1,231 @@
+/**
+ * @file `issue-flow adapter …`: what the worktree tools (Orca, https://www.onorca.dev, and
+ * Paseo, https://paseo.sh) run when they make or delete a worktree, so the worktree gets
+ * the same as one of `issue start`. `orca.yaml` and `paseo.json` only call it:
+ *
+ * - `setup [--only <step>]`, when the worktree is made: copies `.worktreeinclude` (Paseo
+ * does not), runs the setup steps and, without `--only`, starts the issue the workspace
+ * came from in it, as `issue start <n> --adopt`. Always exits 0: a failed setup leaves the
+ * worktree usable and says what to run.
+ * - `issue [<url>]`: only the start of the issue. Without a URL it is a setup step and
+ * always exits 0; with one it is run by hand and exits with the code of `issue start`.
+ * - `archive`, before the worktree goes: its teardown (steps, apps, ports, Docker). Always
+ * exits 0, because a failed archive cannot block the deletion.
+ *
+ * The issue comes from the branch under Paseo (`<n>-` at the start or after a `/`) and
+ * from Orca's CLI otherwise. Ported from Abastio's `scripts/orca-hooks.sh`.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { DEFAULT_CONFIG, loadConfig } from "../config.js";
+import { canonicalPath, dockerCleanup } from "../docker.js";
+import { checkoutRoot, currentBranch, locateRepo } from "../git.js";
+import { issueOfBranch } from "../issue-text.js";
+import { inPath } from "../launch.js";
+import { UsageError, warn } from "../output.js";
+import { releasePortClaims } from "../ports.js";
+import { copyWorktreeIncludes } from "../start-place.js";
+import { StartError } from "../start-state.js";
+import { runSetup, teardownWorktree } from "../worktree-steps.js";
+import { issueStart } from "./issue-start.js";
+import { stepPlace } from "./worktree.js";
+/** Orca's CLI, which knows which issue a workspace came from; `ISSUE_FLOW_ORCA_CLI` changes it. */
+export const ORCA_CLI = "orca";
+/**
+ * The number of an issue of the repo by its URL; a slash, an anchor or a query may follow.
+ * @param url - The URL.
+ * @param repo - `owner/repo`.
+ * @returns The number, or null if it is not an issue of the repo.
+ * @example issueOfUrl("https://github.com/acme/widgets/issues/214#top", "acme/widgets") // 214
+ */
+export function issueOfUrl(url, repo) {
+    const found = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/issues\/(\d+)(?:[/?#].*)?$/.exec(url);
+    if (found?.[1] === undefined || found[2] === undefined)
+        return null;
+    return found[1].toLowerCase() === repo.toLowerCase() ? Number(found[2]) : null;
+}
+/**
+ * The issue Orca says the workspace came from: `linkedWorkItem` (with its URL) when it was
+ * made on the desktop, or the number alone in `linkedIssue` when it was made from Orca
+ * Mobile, always of the project's repo. A work item of something else (Linear, a PR) has
+ * no issue URL of the repo.
+ * @param root - The worktree.
+ * @param repo - `owner/repo`.
+ * @param out - Where a failure is said.
+ * @returns The number, null if it came from no issue, or undefined if Orca could not be asked.
+ */
+function orcaIssue(root, repo, out) {
+    const bin = process.env.ISSUE_FLOW_ORCA_CLI ?? ORCA_CLI;
+    const result = bin.includes("/") ? (existsSync(bin) ? run(bin, root) : null) : inPath(bin) ? run(bin, root) : null;
+    let worktree;
+    try {
+        worktree = result === null ? undefined : JSON.parse(result).result?.worktree;
+    }
+    catch {
+        worktree = undefined;
+    }
+    if (worktree === undefined) {
+        warn(out, `could not ask Orca which issue this workspace came from. If it came from one, run 'issue-flow adapter issue <issue-url>' in ${root}.`);
+        return undefined;
+    }
+    const item = worktree.linkedWorkItem;
+    if (item !== undefined && item !== null)
+        return typeof item.url === "string" ? issueOfUrl(item.url, repo) : null;
+    return typeof worktree.linkedIssue === "number" && Number.isInteger(worktree.linkedIssue) ? worktree.linkedIssue : null;
+}
+/**
+ * Runs `<orca> worktree current --json` in the worktree.
+ * @param bin - Orca's CLI.
+ * @param root - The worktree.
+ * @returns Its output, or null if it failed.
+ */
+function run(bin, root) {
+    const result = spawnSync(bin, ["worktree", "current", "--json"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return result.status === 0 ? result.stdout : null;
+}
+/**
+ * Starts an issue in this worktree, as `issue start <n> --adopt`: the branch of the
+ * convention, the draft PR and the assignment, without asking nor opening Claude.
+ * @param options - The options.
+ * @param number - The issue.
+ * @param out - Where to write.
+ * @returns The exit code of `issue start`.
+ * @throws What `issue start` throws.
+ */
+function adopt(options, number, out) {
+    return issueStart({
+        repo: options.repo(),
+        config: options.config,
+        cwd: options.cwd,
+        number,
+        dryRun: false,
+        yes: false,
+        resume: null,
+        forceNew: false,
+        branchMode: false,
+        launch: false,
+        permissions: "default",
+        plan: false,
+        cloud: false,
+        here: false,
+        teleport: false,
+        adopt: true,
+        remoteSession: null,
+    }, out);
+}
+/**
+ * The start of the issue the workspace came from, as a setup step: it never fails, it
+ * says how to retry.
+ * @param options - The options.
+ * @param root - The worktree.
+ * @param out - Where to write.
+ */
+async function linkedIssue(options, root, out) {
+    const paseo = (process.env.PASEO_WORKTREE_PATH ?? "") !== "";
+    let repo;
+    try {
+        repo = options.repo();
+    }
+    catch (error) {
+        warn(out, `could not start the workspace's issue: ${error instanceof Error ? error.message : String(error)}`);
+        return;
+    }
+    const number = paseo ? issueOfBranch(currentBranch(root) ?? "") : orcaIssue(root, repo, out);
+    if (number === null || number === undefined)
+        return;
+    const retry = `to retry, run 'issue-flow adapter issue https://github.com/${repo}/issues/${number}' in ${root}`;
+    try {
+        await adopt(options, number, out);
+    }
+    catch (error) {
+        warn(out, `issue #${number} was not started (${error instanceof Error ? error.message : String(error)}); ${retry}.`);
+    }
+}
+/**
+ * The worktree the command runs in, or null in the main checkout, where there is nothing
+ * to do (Orca never sets up nor archives it).
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns The worktree's place, or null.
+ * @throws StartError outside git.
+ */
+function linkedPlace(options, out) {
+    const place = stepPlace(options, out);
+    return place.root === place.mainRoot ? null : place;
+}
+/**
+ * `adapter setup [--only <step>]`.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns Always 0.
+ * @throws StartError outside git; UsageError if `--only` names no step.
+ * @example await adapterSetup(options, out)
+ */
+export async function adapterSetup(options, out) {
+    const names = options.config.worktrees.setup.map((step) => step.name);
+    if (options.only !== null && !names.includes(options.only))
+        throw new UsageError(`--only expects a setup step of .agents/flow.json (${names.join(", ") || "it has none"}): ${options.only}`);
+    const place = linkedPlace(options, out);
+    if (place === null)
+        return 0;
+    copyWorktreeIncludes(place.mainRoot, place.root, out);
+    await runSetup(place, options.only);
+    if (options.only === null)
+        await linkedIssue(options, place.root, out);
+    return 0;
+}
+/**
+ * `adapter issue [<url>]`.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns The code of `issue start` with a URL, 0 without one.
+ * @throws StartError outside git or if the URL is not an issue of the repo.
+ * @example await adapterIssue({ ...options, url: "https://github.com/acme/widgets/issues/214" }, out)
+ */
+export async function adapterIssue(options, out) {
+    const place = linkedPlace(options, out);
+    if (options.url === null) {
+        if (place !== null)
+            await linkedIssue(options, place.root, out);
+        return 0;
+    }
+    const number = issueOfUrl(options.url, options.repo());
+    if (number === null)
+        throw new StartError(`${options.url} is not an issue of ${options.repo()}; nothing done.`);
+    if (place === null)
+        throw new StartError("an issue starts in a worktree, not in the main checkout.");
+    return adopt(options, number, out);
+}
+/**
+ * `adapter archive`. With git's link broken (the main checkout moved, or its record of the
+ * worktree was deleted) it cannot tell a worktree, but it still frees the ports and the
+ * Docker of the folder, with the config of the main checkout Orca or Paseo name: without
+ * git it cannot be the main checkout, which they never archive.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns Always 0.
+ * @example await adapterArchive(options, out)
+ */
+export async function adapterArchive(options, out) {
+    if (checkoutRoot(options.cwd) !== null) {
+        const place = linkedPlace(options, out);
+        if (place !== null)
+            await teardownWorktree(place);
+        return 0;
+    }
+    const path = canonicalPath(process.env.ORCA_WORKTREE_PATH || process.env.PASEO_WORKTREE_PATH || options.cwd);
+    const main = process.env.ORCA_ROOT_PATH || process.env.PASEO_SOURCE_CHECKOUT_PATH || null;
+    let config = DEFAULT_CONFIG;
+    try {
+        if (main !== null && locateRepo(main) !== null)
+            config = loadConfig(main);
+    }
+    catch {
+        warn(out, "the main checkout's .agents/flow.json is not valid; cleaning the Docker without its prefixes.");
+    }
+    releasePortClaims(path, null);
+    const docker = dockerCleanup(config.worktrees.dockerProjects, path);
+    if (docker.failed.length > 0)
+        warn(out, `could not delete the Docker of ${path}; run 'issue-flow worktree cleanup' later.`);
+    return 0;
+}

package/dist/commands/claude-hooks.d.ts

@@ -0,0 +1,37 @@
+import type { FlowConfig } from "../config.js";
+import { type Output } from "../output.js";
+/**
+ * The JSON Claude Code sends a hook on stdin, or an empty object if there is none (a
+ * terminal, or not JSON).
+ * @returns The fields.
+ * @example hookInput().cwd
+ */
+export declare function hookInput(): Record<string, unknown>;
+/**
+ * `hook worktree-create`: makes `<worktrees.dir>/<name>` on a branch `worktree-<name>`
+ * from `origin/<base>` (or reuses it), copies `.worktreeinclude`, runs the setup and
+ * prints the path, which is all Claude reads from stdout. A `pr-<n>` name is refused:
+ * that is `issue-flow pr worktree <n>`, on the PR's own branch.
+ * @param input - The hook's input (`name`, `cwd`).
+ * @param config - The config.
+ * @param cwd - Where the hook runs, if the input has no `cwd`.
+ * @param out - Where to write; only the path goes to stdout.
+ * @returns 0.
+ * @throws StartError if the worktree cannot be made, which makes Claude not create it.
+ * @example await worktreeCreate({ name: "bold-oak" }, config, cwd, out)
+ */
+export declare function worktreeCreate(input: Record<string, unknown>, config: FlowConfig, cwd: string, out: Output): Promise<number>;
+/**
+ * `hook worktree-remove`: cleans the worktree Claude is deleting (steps, apps, ports,
+ * Docker) and deletes its folder, and its branch if every commit of it is in origin. A
+ * worktree with uncommitted changes is kept. A folder already gone only gets its ports and
+ * Docker freed.
+ * @param input - The hook's input (`worktree_path`).
+ * @param config - The config.
+ * @param cwd - Where the hook runs.
+ * @param out - Where to write.
+ * @returns 0 if the worktree is gone.
+ * @throws StartError if it is kept, or is not a worktree of the repo.
+ * @example await worktreeRemove({ worktree_path: wt }, config, cwd, out)
+ */
+export declare function worktreeRemove(input: Record<string, unknown>, config: FlowConfig, cwd: string, out: Output): Promise<number>;

package/dist/commands/claude-hooks.js

@@ -0,0 +1,162 @@
+/**
+ * @file `issue-flow hook worktree-create` and `hook worktree-remove`: the `WorktreeCreate`
+ * and `WorktreeRemove` hooks of Claude Code, for `claude --worktree <name>` and the
+ * worktrees Claude makes during a session. With them those worktrees get what one of
+ * `issue start` gets: made from `origin/<base>` (the config's base branch, not only the
+ * default one), with `.worktreeinclude` and the setup steps, and cleaned when Claude
+ * deletes them (steps, apps, ports, Docker). Claude only calls `WorktreeRemove` for the
+ * worktrees a `WorktreeCreate` hook made, and then the hook deletes the folder itself.
+ * Ported from Clean Queen's `.claude/hooks/worktree-create.sh` and `worktree-remove.sh`.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isObject } from "../config-base.js";
+import { canonicalPath } from "../docker.js";
+import { git, hasLocal, isClean, locateRepo, safeToDelete, worktrees } from "../git.js";
+import { warn } from "../output.js";
+import { copyWorktreeIncludes } from "../start-place.js";
+import { StartError } from "../start-state.js";
+import { runSetup, teardownWorktree } from "../worktree-steps.js";
+import { baseBranch, stepPlace } from "./worktree.js";
+/** Milliseconds the fetch of the base branch gets before the local ref is used. */
+const FETCH_TIMEOUT_MS = 30_000;
+/** The name Claude gives a worktree: a slug, without `.` or `..` as a whole. */
+const WORKTREE_NAME = /^[A-Za-z0-9._+/-]+$/;
+/** A worktree name that asks for a PR, which `pr worktree` checks out instead. */
+const PR_NAME = /^pr-(\d+)$/;
+/**
+ * The JSON Claude Code sends a hook on stdin, or an empty object if there is none (a
+ * terminal, or not JSON).
+ * @returns The fields.
+ * @example hookInput().cwd
+ */
+export function hookInput() {
+    if (process.stdin.isTTY)
+        return {};
+    try {
+        const value = JSON.parse(readFileSync(0, "utf8"));
+        return isObject(value) ? value : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * A text field of the hook's input.
+ * @param input - The input.
+ * @param key - The field.
+ * @returns Its value, or null if it is missing or empty.
+ */
+function field(input, key) {
+    const value = input[key];
+    return typeof value === "string" && value !== "" ? value : null;
+}
+/**
+ * Fetches the base branch, giving up after `FETCH_TIMEOUT_MS` and never asking for a
+ * password: a hook has no terminal.
+ * @param mainRoot - The main checkout.
+ * @param base - The base branch.
+ * @returns True if it was fetched.
+ */
+function fetchBase(mainRoot, base) {
+    const result = spawnSync("git", ["fetch", "-q", "origin", base], {
+        cwd: mainRoot,
+        stdio: "ignore",
+        timeout: FETCH_TIMEOUT_MS,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    });
+    return result.status === 0;
+}
+/**
+ * `hook worktree-create`: makes `<worktrees.dir>/<name>` on a branch `worktree-<name>`
+ * from `origin/<base>` (or reuses it), copies `.worktreeinclude`, runs the setup and
+ * prints the path, which is all Claude reads from stdout. A `pr-<n>` name is refused:
+ * that is `issue-flow pr worktree <n>`, on the PR's own branch.
+ * @param input - The hook's input (`name`, `cwd`).
+ * @param config - The config.
+ * @param cwd - Where the hook runs, if the input has no `cwd`.
+ * @param out - Where to write; only the path goes to stdout.
+ * @returns 0.
+ * @throws StartError if the worktree cannot be made, which makes Claude not create it.
+ * @example await worktreeCreate({ name: "bold-oak" }, config, cwd, out)
+ */
+export async function worktreeCreate(input, config, cwd, out) {
+    const name = field(input, "name");
+    if (name === null)
+        throw new StartError("the hook got no worktree name.");
+    const pr = PR_NAME.exec(name);
+    if (pr !== null)
+        throw new StartError(`to review a PR, run 'issue-flow pr worktree ${pr[1]}', not 'claude --worktree ${name}'.`);
+    const slug = name.replaceAll("/", "+");
+    if (!WORKTREE_NAME.test(name) || slug === "." || slug === ".." || slug.startsWith("-"))
+        throw new StartError(`the worktree name cannot be '${name}'.`);
+    const located = locateRepo(field(input, "cwd") ?? cwd);
+    if (located === null)
+        throw new StartError(`${field(input, "cwd") ?? cwd} is not a git checkout.`);
+    const { mainRoot } = located;
+    const path = canonicalPath(join(mainRoot, config.worktrees.dir, slug));
+    const branch = `worktree-${slug}`;
+    const base = baseBranch(config, mainRoot);
+    const stderrOnly = { ...out, stdout: (text) => out.stderr(text) };
+    if (!worktrees(mainRoot).some((entry) => entry.path === path)) {
+        if (!fetchBase(mainRoot, base))
+            warn(out, `could not fetch ${base}; using the local origin/${base}.`);
+        if (!git(mainRoot, ["rev-parse", "-q", "--verify", `origin/${base}^{commit}`]).ok)
+            throw new StartError(`there is no origin/${base}, and the worktree is not made on another base.`);
+        const add = hasLocal(mainRoot, branch)
+            ? git(mainRoot, ["worktree", "add", "-q", path, branch])
+            : git(mainRoot, ["worktree", "add", "-q", "--no-track", "-b", branch, path, `origin/${base}`]);
+        if (!add.ok)
+            throw new StartError(`could not make the worktree ${path}: ${add.err}`);
+        copyWorktreeIncludes(mainRoot, path, stderrOnly);
+    }
+    await runSetup({ root: path, mainRoot, base, config, out: stderrOnly, remote: false }, null);
+    out.stdout(`${path}\n`);
+    return 0;
+}
+/**
+ * `hook worktree-remove`: cleans the worktree Claude is deleting (steps, apps, ports,
+ * Docker) and deletes its folder, and its branch if every commit of it is in origin. A
+ * worktree with uncommitted changes is kept. A folder already gone only gets its ports and
+ * Docker freed.
+ * @param input - The hook's input (`worktree_path`).
+ * @param config - The config.
+ * @param cwd - Where the hook runs.
+ * @param out - Where to write.
+ * @returns 0 if the worktree is gone.
+ * @throws StartError if it is kept, or is not a worktree of the repo.
+ * @example await worktreeRemove({ worktree_path: wt }, config, cwd, out)
+ */
+export async function worktreeRemove(input, config, cwd, out) {
+    const given = field(input, "worktree_path");
+    if (given === null)
+        throw new StartError("the hook got no worktree_path; deleting nothing.");
+    const path = canonicalPath(given);
+    const place = stepPlace({ config, cwd: existsSync(path) ? path : (field(input, "cwd") ?? cwd) }, out);
+    const { mainRoot } = place;
+    if (path === mainRoot)
+        throw new StartError("the main checkout is never deleted.");
+    const entry = worktrees(mainRoot).find((item) => item.path === path);
+    if (entry === undefined && existsSync(path))
+        throw new StartError(`${path} is not a worktree of this repo; deleting nothing.`);
+    if (entry === undefined) {
+        await teardownWorktree({ ...place, root: path });
+        git(mainRoot, ["worktree", "prune"]);
+        return 0;
+    }
+    if (!isClean(path))
+        throw new StartError(`${path} has uncommitted changes; kept. See them with 'git -C ${path} status'.`);
+    await teardownWorktree({ ...place, root: path });
+    const removed = git(mainRoot, ["worktree", "remove", "--force", path]);
+    if (!removed.ok)
+        throw new StartError(`could not delete ${path} (its teardown already ran): ${removed.err}`);
+    const { branch } = entry;
+    if (branch === null)
+        return 0;
+    if (safeToDelete(mainRoot, branch, ""))
+        git(mainRoot, ["branch", "-q", "-D", branch]);
+    else
+        warn(out, `kept the branch ${branch}: it has commits that are not in origin.`);
+    return 0;
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,10 @@
+import type { Output } from "../output.js";
+/**
+ * Checks the repo; see the file's header.
+ * @param cwd - Where it runs.
+ * @param out - Where to write.
+ * @returns 0 if everything passes, 1 if not.
+ * @throws SetupError outside a checkout.
+ * @example doctor(process.cwd(), out)
+ */
+export declare function doctor(cwd: string, out: Output): number;

package/dist/commands/doctor.js

@@ -0,0 +1,124 @@
+/**
+ * @file `issue-flow doctor`: whether the repo is set up as `init` leaves it, at this
+ * version. It checks the config, the dev dependencies, the hooks, the tag of the flow's
+ * skills, and `claude-repo-guard` (its own doctor and, on macOS, `weakerNetworkIsolation`,
+ * which `gh` needs inside the sandbox). It changes nothing; each problem says what fixes it.
+ */
+import { ConfigError, isObject } from "../config-base.js";
+import { loadConfig } from "../config.js";
+import { locateRepo } from "../git.js";
+import { WEAKER_NETWORK } from "../guard-config.js";
+import { dependencyVersion } from "../package-edits.js";
+import { hookVersions } from "../settings-hooks.js";
+import { captureNpx, flowSkills, GUARD_CONFIG, GUARD_SPEC, ownVersions, PACKAGE, readJson, SETTINGS_FILE, SetupError, SKILLS_LOCK, } from "../setup-files.js";
+/** What fixes most problems. */
+const RUN_INIT = "run issue-flow init";
+/**
+ * Checks the config.
+ * @param root - The repo.
+ * @returns The check.
+ */
+function configCheck(root) {
+    try {
+        loadConfig(root);
+        return { name: ".agents/flow.json", ok: true, detail: "valid" };
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError))
+            throw error;
+        return { name: ".agents/flow.json", ok: false, detail: error.message };
+    }
+}
+/**
+ * Checks the dev dependencies: `issue-flow` at this version and `github-rest`, which the
+ * skills call.
+ * @param root - The repo.
+ * @param version - This package's version.
+ * @returns The checks.
+ */
+function packageChecks(root, version) {
+    const pkg = readJson(root, "package.json");
+    const flow = dependencyVersion(pkg, PACKAGE);
+    const rest = dependencyVersion(pkg, "@ramon-sg/github-rest");
+    return [
+        { name: PACKAGE, ok: flow === version, detail: flow === null ? `not in package.json: ${RUN_INIT}` : flow === version ? version : `package.json has ${flow}, this is ${version}: run issue-flow upgrade` },
+        { name: "@ramon-sg/github-rest", ok: rest !== null, detail: rest ?? `not in package.json, and the skills call it: ${RUN_INIT}` },
+    ];
+}
+/**
+ * Checks that each hook is there at this version.
+ * @param root - The repo.
+ * @param version - This package's version.
+ * @returns The checks.
+ */
+function hookChecks(root, version) {
+    return Object.entries(hookVersions(readJson(root, SETTINGS_FILE))).map(([event, found]) => ({
+        name: `${event} hook`,
+        ok: found === version,
+        detail: found === null ? `not in ${SETTINGS_FILE}: ${RUN_INIT}` : found === version ? version : `at ${found}, this is ${version}: run issue-flow upgrade`,
+    }));
+}
+/**
+ * Checks that the flow's skills are at this version's tag: they call this CLI, so they go
+ * together.
+ * @param root - The repo.
+ * @param version - This package's version.
+ * @returns The check.
+ */
+function skillsCheck(root, version) {
+    const skills = flowSkills(readJson(root, SKILLS_LOCK));
+    const tag = `v${version}`;
+    const off = skills.filter((skill) => skill.tag !== tag);
+    if (skills.length === 0)
+        return { name: "flow skills", ok: false, detail: `none in ${SKILLS_LOCK}: ${RUN_INIT}` };
+    if (off.length === 0)
+        return { name: "flow skills", ok: true, detail: `${skills.length} at ${tag}` };
+    return { name: "flow skills", ok: false, detail: `${off.map((skill) => `${skill.name} at ${skill.tag ?? "no tag"}`).join(", ")}, this is ${tag}: run issue-flow upgrade` };
+}
+/**
+ * Checks `claude-repo-guard`, if the repo has it: its own doctor and, on macOS, the option
+ * `gh` needs.
+ * @param root - The repo.
+ * @returns The checks.
+ */
+function guardChecks(root) {
+    const options = readJson(root, GUARD_CONFIG);
+    if (options === null)
+        return [{ name: "claude-repo-guard", ok: true, detail: "not installed (Claude opens with your own permissions)" }];
+    const checks = [];
+    if (process.platform === "darwin" && options[WEAKER_NETWORK] !== true)
+        checks.push({ name: WEAKER_NETWORK, ok: false, detail: `not true in ${GUARD_CONFIG}, so gh fails inside the macOS sandbox: ${RUN_INIT}` });
+    const result = captureNpx(root, [GUARD_SPEC, "doctor", "--json"]);
+    let found;
+    try {
+        found = JSON.parse(result?.out ?? "");
+    }
+    catch {
+        found = null;
+    }
+    if (!Array.isArray(found))
+        return [...checks, { name: "claude-repo-guard", ok: false, detail: `could not run its doctor; run 'npx ${GUARD_SPEC} doctor'` }];
+    const failed = found.filter((check) => !isObject(check) || check.ok !== true).map((check) => (isObject(check) ? check : { name: "?", detail: String(check) }));
+    if (failed.length === 0)
+        return [...checks, { name: "claude-repo-guard", ok: true, detail: "its doctor passes" }];
+    return [...checks, ...failed.map((check) => ({ name: `claude-repo-guard: ${String(check.name)}`, ok: false, detail: String(check.detail) }))];
+}
+/**
+ * Checks the repo; see the file's header.
+ * @param cwd - Where it runs.
+ * @param out - Where to write.
+ * @returns 0 if everything passes, 1 if not.
+ * @throws SetupError outside a checkout.
+ * @example doctor(process.cwd(), out)
+ */
+export function doctor(cwd, out) {
+    const located = locateRepo(cwd);
+    if (located === null)
+        throw new SetupError("run doctor inside a checkout of the repo.");
+    const root = located.mainRoot;
+    const { issueFlow } = ownVersions();
+    const checks = [configCheck(root), ...packageChecks(root, issueFlow), ...hookChecks(root, issueFlow), skillsCheck(root, issueFlow), ...guardChecks(root)];
+    for (const check of checks)
+        out.stdout(`${check.ok ? "✓" : "✗"} ${check.name}: ${check.detail}\n`);
+    return checks.every((check) => check.ok) ? 0 : 1;
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,27 @@
+import { type Output } from "../output.js";
+/** Options of `issue-flow init`. */
+export interface InitOptions {
+    cwd: string;
+    yes: boolean;
+    recipes: string[] | null;
+    skills: boolean;
+    guard: boolean;
+    cloud: boolean;
+}
+/**
+ * The URL of the config's schema at a version.
+ * @param version - This package's version.
+ * @returns The URL.
+ * @example schemaUrl("0.1.0") // "https://raw.githubusercontent.com/ramon-sg/issue-flow/v0.1.0/schema.json"
+ */
+export declare function schemaUrl(version: string): string;
+/**
+ * Sets the repo up for the flow; see the file's header.
+ * @param options - The options.
+ * @param out - Where to write and ask.
+ * @returns 0, or 1 if a file was not written or another tool failed.
+ * @throws SetupError outside the main checkout or with a broken file; ConfigError if the
+ * config would be invalid; UsageError for an unknown recipe.
+ * @example await init({ cwd, yes: true, recipes: null, skills: true, guard: true, cloud: true }, out)
+ */
+export declare function init(options: InitOptions, out: Output): Promise<number>;