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

package/dist/start-state.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @file What `issue start` knows about the issue once it chose the branch and the place:
+ * shared by the summary, the preparation and the publishing, so none of them asks git or
+ * GitHub twice.
+ */
+import type { IssueView } from "@ramon-sg/github-rest";
+import type { FlowConfig, Namer } from "./config.js";
+import type { PrKind, StartMode } from "./issue-text.js";
+import type { Permissions } from "./launch.js";
+import type { Output } from "./output.js";
+import type { WorkState } from "./work-state.js";
+/** Options of `issue start`. */
+export interface StartOptions {
+    repo: string;
+    config: FlowConfig;
+    cwd: string;
+    number: number;
+    namer?: Namer;
+    dryRun: boolean;
+    yes: boolean;
+    resume: string | null;
+    forceNew: boolean;
+    branchMode: boolean;
+    launch: boolean;
+    permissions: Permissions;
+    plan: boolean;
+    cloud: boolean;
+    here: boolean;
+    teleport: boolean;
+    adopt: boolean;
+    remoteSession: string | null;
+}
+/** The branch of the worktree `--adopt` runs in, and whether another tool just made it. */
+export interface Adopted {
+    current: string;
+    fresh: boolean;
+}
+/** Error that stops `issue start`: exits 1 with the message. */
+export declare class StartError extends Error {
+}
+/** The issue, its work and where it goes. */
+export interface StartState {
+    options: StartOptions;
+    out: Output;
+    commonDir: string;
+    mainRoot: string;
+    startRoot: string;
+    base: string;
+    issue: IssueView;
+    labels: string[];
+    work: WorkState;
+    found: string | null;
+    branch: string;
+    pr: {
+        number: number;
+        state: "OPEN" | "CLOSED";
+    } | null;
+    kind: PrKind;
+    mode: StartMode;
+    workDir: string;
+    plan: string | null;
+    adopted: Adopted | null;
+    cloudSession: string | null;
+}
+/**
+ * The command that starts or resumes this issue, for the messages.
+ * @param number - The issue.
+ * @param extra - Flags to add.
+ * @returns The command.
+ * @example again(42) // "issue-flow issue start 42"
+ */
+export declare function again(number: number, extra?: string): string;

package/dist/start-state.js

@@ -0,0 +1,13 @@
+/** Error that stops `issue start`: exits 1 with the message. */
+export class StartError extends Error {
+}
+/**
+ * The command that starts or resumes this issue, for the messages.
+ * @param number - The issue.
+ * @param extra - Flags to add.
+ * @returns The command.
+ * @example again(42) // "issue-flow issue start 42"
+ */
+export function again(number, extra = "") {
+    return `issue-flow issue start ${number}${extra === "" ? "" : ` ${extra}`}`;
+}

package/dist/start-summary.d.ts

@@ -0,0 +1,42 @@
+import { type PermissionArgs } from "./launch.js";
+import { type StartState } from "./start-state.js";
+import type { StepPlace } from "./worktree-steps.js";
+/**
+ * Whether the start commit is needed: no PR and the branch has no commits of its own, so
+ * GitHub would not let a PR open.
+ * @param state - The start.
+ * @returns True if it is.
+ * @example needsStartCommit(state)
+ */
+export declare function needsStartCommit(state: StartState): boolean;
+/**
+ * One branch on one line: where it is, its own commits and, if asked, its PR.
+ * @param state - The start.
+ * @param branch - The branch.
+ * @param withPr - Whether to add its PR.
+ * @returns The text.
+ * @example describeBranch(state, "feat/42-x", true) // "feat/42-x (only in origin, 0 own commits), PR #7, OPEN"
+ */
+export declare function describeBranch(state: StartState, branch: string, withPr: boolean): string;
+/**
+ * The actions it will take, joined with " + ".
+ * @param state - The start.
+ * @returns The text.
+ * @example plannedActions(state) // "create the branch from origin/main + empty commit + push -u + …"
+ */
+export declare function plannedActions(state: StartState): string;
+/**
+ * The summary that is confirmed.
+ * @param state - The start.
+ * @param permissions - How Claude will open.
+ * @returns The text.
+ * @example summary(state, permissions)
+ */
+export declare function summary(state: StartState, permissions: PermissionArgs): string;
+/**
+ * Where the worktree's steps run, for its setup and its teardown.
+ * @param state - The start.
+ * @returns The place.
+ * @example stepPlaceOf(state).root
+ */
+export declare function stepPlaceOf(state: StartState): StepPlace;

package/dist/start-summary.js

@@ -0,0 +1,217 @@
+/**
+ * @file The summary `issue start` shows before asking: the issue, what it already has,
+ * the branch, the place, the session and the actions it will take. Ported from
+ * `plan_actions`, `describe_branch` and `print_summary` in Abastio's
+ * `scripts/start-issue.sh`.
+ */
+import { existsSync } from "node:fs";
+import { relative } from "node:path";
+import { currentBranch, git, hasLocal, onOrigin, ownCommits } from "./git.js";
+import { cloudSessionUrl, issueColor, issueHeader, prBody, sameCloudSession, sessionName } from "./issue-text.js";
+import { savedSession } from "./launch.js";
+import { again } from "./start-state.js";
+import { branchPr, openPrsElsewhere } from "./work-state.js";
+/** Width of the summary's labels. */
+const LABEL_WIDTH = 14;
+/**
+ * A summary line: the label padded, then the value; later lines of the value are indented.
+ * @param label - The label, with its colon.
+ * @param value - The value, maybe several lines.
+ * @returns The line.
+ */
+function line(label, value) {
+    const pad = " ".repeat(LABEL_WIDTH);
+    return `${label.padEnd(LABEL_WIDTH)}${value.split("\n").join(`\n${pad}`)}\n`;
+}
+/**
+ * Whether the start commit is needed: no PR and the branch has no commits of its own, so
+ * GitHub would not let a PR open.
+ * @param state - The start.
+ * @returns True if it is.
+ * @example needsStartCommit(state)
+ */
+export function needsStartCommit(state) {
+    return state.pr === null && ownCommits(state.mainRoot, state.branch, state.base) === 0;
+}
+/**
+ * One branch on one line: where it is, its own commits and, if asked, its PR.
+ * @param state - The start.
+ * @param branch - The branch.
+ * @param withPr - Whether to add its PR.
+ * @returns The text.
+ * @example describeBranch(state, "feat/42-x", true) // "feat/42-x (only in origin, 0 own commits), PR #7, OPEN"
+ */
+export function describeBranch(state, branch, withPr) {
+    const local = hasLocal(state.mainRoot, branch);
+    const remote = onOrigin(state.mainRoot, branch);
+    const where = local ? (remote ? "local and in origin" : "only local") : remote ? "only in origin" : "deleted";
+    const text = `${branch} (${where}, ${ownCommits(state.mainRoot, branch, state.base)} own commits)`;
+    const pr = withPr ? branchPr(state.work.prs, branch) : null;
+    return pr === null ? text : `${text}, PR #${pr.number}, ${pr.state}`;
+}
+/**
+ * The actions it will take, joined with " + ".
+ * @param state - The start.
+ * @returns The text.
+ * @example plannedActions(state) // "create the branch from origin/main + empty commit + push -u + …"
+ */
+export function plannedActions(state) {
+    if (state.mode === "cloud")
+        return "open the cloud session, which makes the branch, the commit, the PR and the assignment";
+    const actions = placeActions(state);
+    const { mainRoot, branch } = state;
+    const { number, remoteSession } = state.options;
+    const commit = needsStartCommit(state);
+    if (commit)
+        actions.push("empty commit");
+    if (commit || !onOrigin(mainRoot, branch))
+        actions.push("push -u");
+    if (state.pr === null) {
+        const first = prBody(state.options.config.start.prBody, number, state.kind).split("\n")[0];
+        actions.push(`draft PR (${first})`);
+        const others = openPrsElsewhere(state.work.prs, branch);
+        if (state.kind === "part" && others.length > 0)
+            actions.push(`Part of #${number} in the open PRs (${others.map((pr) => `#${pr}`).join(", ")})`);
+    }
+    if (state.pr?.state === "CLOSED")
+        actions.push(`reopen PR #${state.pr.number}`);
+    if (state.issue.assignees.length === 0)
+        actions.push(`assign #${number} to @me`);
+    if (state.mode === "here" && remoteSession !== null && !sameCloudSession(state.cloudSession, remoteSession))
+        actions.push("note the session in the PR");
+    if (actions.length > 0)
+        return actions.join(" + ");
+    return state.adopted === null ? "none: only open the session" : "none: everything was already done";
+}
+/**
+ * The first action, about the branch: rename the adopted one, create it, make the
+ * worktree on it or check it out.
+ * @param state - The start.
+ * @returns None or one action.
+ */
+function placeActions(state) {
+    const { adopted, branch } = state;
+    if (adopted !== null)
+        return adopted.current === branch ? [] : [`rename the branch ${adopted.current} to ${branch}`];
+    if (state.found === null)
+        return [`create the branch from origin/${state.base}`];
+    if (state.mode === "worktree" && !existsSync(state.workDir))
+        return ["create the worktree on the branch"];
+    if (state.mode !== "worktree" && currentBranch(state.workDir) !== branch)
+        return ["check out the branch"];
+    return [];
+}
+/**
+ * Merged branches that got commits after their merge: a new round starts from the base
+ * and does not bring them. The heads of their merged PRs count as merged too, because a
+ * squash or rebase merge leaves the branch's commits out of the base.
+ * @param state - The start.
+ * @returns One warning line per branch.
+ */
+function mergedLeftovers(state) {
+    const lines = [];
+    for (const merged of state.work.mergedBranches) {
+        const ref = hasLocal(state.mainRoot, merged) ? merged : `origin/${merged}`;
+        const heads = state.work.prs
+            .filter((pr) => pr.branch === merged && pr.state === "MERGED" && pr.head !== "")
+            .map((pr) => pr.head)
+            .filter((head) => git(state.mainRoot, ["cat-file", "-e", `${head}^{commit}`]).ok);
+        const count = git(state.mainRoot, ["rev-list", "--count", ref, "--not", `origin/${state.base}`, ...heads]);
+        if (count.ok && count.out !== "0")
+            lines.push(line("Note:", `${merged} has ${count.out} commits that are not in ${state.base}`));
+    }
+    return lines;
+}
+/**
+ * The lines about the branch: what was found, the live branches and the new one, or the
+ * round and the new branch.
+ * @param state - The start.
+ * @returns The lines.
+ */
+function branchLines(state) {
+    const { work } = state;
+    if (state.found !== null) {
+        const found = [`branch ${describeBranch(state, state.branch, false)}`];
+        if (state.pr !== null)
+            found.push(`PR #${state.pr.number}, ${state.pr.state}`);
+        if (state.mode === "worktree" && existsSync(state.workDir))
+            found.push(`worktree at ${relative(state.mainRoot, state.workDir)}`);
+        return [line("Found:", found.join("\n")), line("Planned:", state.plan ?? "no")];
+    }
+    if (work.candidates.length > 0)
+        return [
+            line("Branches:", work.candidates.map((branch) => describeBranch(state, branch, true)).join("\n")),
+            line("New branch:", state.branch),
+        ];
+    if (work.mergedPrs.length === 0)
+        return [line("Branch:", state.branch)];
+    return [
+        line("Round:", `${work.mergedPrs.length + 1} (already merged: PR ${work.mergedPrs.map((pr) => `#${pr}`).join(", ")})`),
+        line("Planned:", state.plan ?? "no"),
+        ...mergedLeftovers(state),
+        line("Branch:", state.branch),
+    ];
+}
+/**
+ * The summary that is confirmed.
+ * @param state - The start.
+ * @param permissions - How Claude will open.
+ * @returns The text.
+ * @example summary(state, permissions)
+ */
+export function summary(state, permissions) {
+    const { issue, options } = state;
+    const header = issueHeader(issue.body);
+    const color = issueColor(state.labels, options.config.colors);
+    const opensHere = state.adopted === null && (state.mode === "worktree" || state.mode === "branch");
+    return [
+        line("Issue:", `#${issue.number} — ${issue.title}`),
+        ...(header.length > 0 ? [line("Summary:", header.join("\n"))] : []),
+        line("Labels:", state.labels.join(" · ")),
+        line("Color:", color === null ? "none" : `${color.color} (${color.label})`),
+        ...branchLines(state),
+        line("Mode:", modeText(state)),
+        ...(opensHere ? [...sessionLines(state), line("Permissions:", permissions.label)] : []),
+        line("Actions:", plannedActions(state)),
+    ].join("");
+}
+/**
+ * Where the work goes, for the summary.
+ * @param state - The start.
+ * @returns The text.
+ */
+function modeText(state) {
+    if (state.adopted !== null)
+        return `adopted worktree at ${state.workDir}`;
+    if (state.mode === "here")
+        return "this session (--here)";
+    if (state.mode === "cloud")
+        return "cloud (the session makes the branch and the PR)";
+    return state.mode === "worktree" ? `worktree at ${relative(state.mainRoot, state.workDir)}` : "branch in the main checkout";
+}
+/**
+ * The session lines: the branch's local session or, with `--teleport`, the cloud one it
+ * brings. Without `--teleport`, a cloud session noted in the PR adds how to bring it.
+ * @param state - The start.
+ * @returns The lines.
+ */
+function sessionLines(state) {
+    const { cloudSession, options } = state;
+    if (options.teleport)
+        return [line("Session:", cloudSession === null ? "cloud (chosen from teleport's list)" : `cloud ${cloudSession} (brought with teleport)`)];
+    const saved = savedSession(state.commonDir, state.branch) !== null;
+    const lines = [line("Session:", `${sessionName(state.branch, state.mode)}${saved ? " (exists, resumed)" : ""}`)];
+    if (cloudSession !== null)
+        lines.push(line("Cloud:", `the issue has a cloud session (${cloudSessionUrl(cloudSession)}). To bring it: ${again(options.number, "--teleport")}`));
+    return lines;
+}
+/**
+ * Where the worktree's steps run, for its setup and its teardown.
+ * @param state - The start.
+ * @returns The place.
+ * @example stepPlaceOf(state).root
+ */
+export function stepPlaceOf(state) {
+    const { workDir, mainRoot, base, out, options } = state;
+    return { root: workDir, mainRoot, base, config: options.config, out, remote: false };
+}

package/dist/stop-apps.d.ts

@@ -0,0 +1,14 @@
+import { type Output } from "./output.js";
+import type { PortsConfig } from "./worktree-config.js";
+/**
+ * Stops the apps of a worktree: TERM to each one that listens on a port of its block (to its
+ * process group, if the group's leader runs in the worktree too), and KILL to those still
+ * there after `GRACE_SECONDS`.
+ * @param ports - The range of ports.
+ * @param base - The block's first port.
+ * @param root - The worktree, with its symlinks resolved.
+ * @param out - Where to say it.
+ * @returns How many processes listened.
+ * @example await stopApps(ports, 21430, "/repo/.claude/worktrees/feat+42-x", out)
+ */
+export declare function stopApps(ports: PortsConfig, base: number, root: string, out: Output): Promise<number>;

package/dist/stop-apps.js

@@ -0,0 +1,127 @@
+/**
+ * @file Stops the apps of a worktree before it goes: the processes that listen on a port of
+ * its block and run inside its folder. A dev server (turbo, `bun run dev`) starts each app
+ * in its own process group, which would outlive the worktree's terminals with the ports
+ * taken; the group gets TERM and, if the app is still there after some seconds, KILL. The
+ * group is signalled only if its leader also runs in the worktree: an app started without
+ * its own group shares that of whoever launched it (a terminal, Claude, Orca), and then
+ * only the app gets the signal. A process outside the worktree is never touched, even on
+ * one of its ports, and neither is the group `issue-flow` runs in. Needs `lsof`; without it nothing is stopped. Ported from
+ * `stop_apps` in Abastio's `scripts/orca-hooks.sh`.
+ */
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { setTimeout as sleep } from "node:timers/promises";
+import { inPath } from "./launch.js";
+import { warn } from "./output.js";
+/** Seconds the apps get to end on their own before they are killed. */
+const GRACE_SECONDS = 5;
+/**
+ * Runs a command and gives its output, or null if it failed.
+ * @param command - The program.
+ * @param args - Its arguments.
+ * @returns The output.
+ */
+function output(command, args) {
+    const result = spawnSync(command, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return result.status === 0 ? result.stdout : null;
+}
+/**
+ * The processes that listen on a TCP port of a range, with one `lsof`.
+ * @param first - The first port.
+ * @param last - The last port.
+ * @returns Their pids.
+ */
+function listeners(first, last) {
+    const text = output("lsof", ["-nP", `-iTCP:${first}-${last}`, "-sTCP:LISTEN", "-t"]) ?? "";
+    return text.split("\n").filter((line) => /^\d+$/.test(line)).map(Number);
+}
+/**
+ * The folder a process runs in, with its symlinks resolved.
+ * @param pid - The process.
+ * @returns The folder, or null if it cannot be read.
+ */
+function processDir(pid) {
+    const line = (output("lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"]) ?? "").split("\n").find((item) => item.startsWith("n/"));
+    if (line === undefined)
+        return null;
+    try {
+        return realpathSync(line.slice(1));
+    }
+    catch {
+        return line.slice(1);
+    }
+}
+/**
+ * The process group of a process.
+ * @param pid - The process.
+ * @returns The group, or null if the process is gone.
+ */
+function processGroup(pid) {
+    const text = (output("ps", ["-o", "pgid=", "-p", String(pid)]) ?? "").trim();
+    return /^\d+$/.test(text) ? Number(text) : null;
+}
+/**
+ * The processes of the worktree that listen on a port of its block.
+ * @param ports - The range of ports.
+ * @param base - The block's first port.
+ * @param root - The worktree, with its symlinks resolved.
+ * @returns Their pids.
+ */
+function appPids(ports, base, root) {
+    return [...new Set(listeners(base, base + ports.blockSize - 1))].filter((pid) => inside(pid, root));
+}
+/**
+ * Whether a process runs in the worktree.
+ * @param pid - The process.
+ * @param root - The worktree, with its symlinks resolved.
+ * @returns True if its folder is the worktree or inside it.
+ */
+function inside(pid, root) {
+    const dir = processDir(pid);
+    return dir !== null && (dir === root || dir.startsWith(`${root}/`));
+}
+/**
+ * Sends a signal to each target: a negative number is a process group.
+ * @param targets - The groups and processes.
+ * @param signal - The signal.
+ */
+function signal(targets, signal) {
+    for (const target of targets)
+        try {
+            process.kill(target, signal);
+        }
+        catch {
+            continue;
+        }
+}
+/**
+ * Stops the apps of a worktree: TERM to each one that listens on a port of its block (to its
+ * process group, if the group's leader runs in the worktree too), and KILL to those still
+ * there after `GRACE_SECONDS`.
+ * @param ports - The range of ports.
+ * @param base - The block's first port.
+ * @param root - The worktree, with its symlinks resolved.
+ * @param out - Where to say it.
+ * @returns How many processes listened.
+ * @example await stopApps(ports, 21430, "/repo/.claude/worktrees/feat+42-x", out)
+ */
+export async function stopApps(ports, base, root, out) {
+    if (!inPath("lsof"))
+        return 0;
+    const pids = appPids(ports, base, root);
+    if (pids.length === 0)
+        return 0;
+    const own = processGroup(process.pid);
+    const targets = [...new Set(pids.map((pid) => {
+            const group = processGroup(pid);
+            return group === null || group === own || !inside(group, root) ? pid : -group;
+        }))];
+    warn(out, `stopping the apps that run in ${root}.`);
+    signal(targets, "SIGTERM");
+    for (let waited = 0; waited < GRACE_SECONDS && appPids(ports, base, root).length > 0; waited += 1)
+        await sleep(1000);
+    if (appPids(ports, base, root).length > 0)
+        signal(targets, "SIGKILL");
+    return pids.length;
+}

package/dist/usage.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @file The usage text of the CLI, printed with `--help` and after a usage error.
+ */
+/** Usage text. */
+export declare const USAGE = "Usage:\n  issue-flow issue branch <n>... [--namer claude|title] [--json] [-R owner/repo]\n  issue-flow issue branch --missing [--limit <n>] [--namer claude|title] [--dry-run | --yes] [--json] [-R owner/repo]\n  issue-flow issue start <n> [--branch] [--dry-run | --yes] [--resume <branch> | --new] [--no-launch]\n                             [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --plan [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --cloud | --here | --teleport | --adopt [...]\n  issue-flow worktree setup [--only <step>]\n  issue-flow worktree teardown [--path <dir>]\n  issue-flow worktree ports [--next]\n  issue-flow worktree cleanup [--path <dir>]\n  issue-flow worktree prune [--only <dir>] [--yes] [-R owner/repo]\n  issue-flow pr worktree <n> [--no-setup] [-R owner/repo] [-- [<command>...]]\n  issue-flow adapter setup [--only <step>] | issue [<url>] | archive [-R owner/repo]\n  issue-flow session\n  issue-flow hook worktree-create | worktree-remove\n  issue-flow init [--yes] [--recipe <name>,...] [--no-cloud] [--no-guard] [--no-skills]\n  issue-flow doctor\n  issue-flow upgrade [--to <version>] [--dry-run]\n\nThe slug comes from the issue's \"Slug de rama\" block, then from Claude, then from the title,\nand the branch from the repo's template (an older \"Rama sugerida\" block is used if it fits).\n--missing adds the slug block to every open issue without a block, after confirming.\n\nissue start makes the branch in a worktree (or, with --branch, in this checkout), the\nstart commit, the push, the draft PR and the assignment, after confirming, and opens\nClaude: in auto mode if the repo has claude-repo-guard, with your settings with\n--ask-permissions, and with no sandbox nor questions with --free. --plan prints the branch\nand the prompt as JSON and changes nothing.\n\n--cloud confirms here and opens a Claude cloud session that starts the issue there.\n--here, inside a cloud session, starts it in this checkout and opens nothing. --teleport\nbrings the cloud session noted in the PR to the worktree. --adopt starts it in the\nworktree another tool (Orca, Paseo) just made, without asking nor opening Claude.\n\nworktree runs the steps of \"worktrees\" in .agents/flow.json: setup prepares this worktree,\nteardown cleans it before it goes (steps, ports, Docker), ports prints or moves its block\nof ports, cleanup deletes the Docker of deleted worktrees, and prune deletes the worktrees\nwhose PR was merged or closed. session is the SessionStart hook of Claude Code.\n\npr worktree makes (or reuses) a worktree on a PR's own branch, to review and fix it; with\n--, it runs the command there (Claude if none). adapter is what Orca and Paseo run: setup\nwhen they make a worktree (its steps and, if it came from an issue, issue start --adopt),\nissue to start one by hand, and archive before they delete it. hook implements Claude\nCode's WorktreeCreate and WorktreeRemove for claude --worktree.\n\ninit sets the repo up: .agents/flow.json (with the recipes its files suggest), the dev\ndependencies and scripts, and the hooks; then, after asking, claude-cloud init,\nclaude-repo-guard and the skills menu. doctor checks it is set up at this version, and\nupgrade moves the CLI, the hooks and the flow's skills to the latest version (or --to).";

package/dist/usage.js

@@ -0,0 +1,54 @@
+/**
+ * @file The usage text of the CLI, printed with `--help` and after a usage error.
+ */
+/** Usage text. */
+export const USAGE = `Usage:
+  issue-flow issue branch <n>... [--namer claude|title] [--json] [-R owner/repo]
+  issue-flow issue branch --missing [--limit <n>] [--namer claude|title] [--dry-run | --yes] [--json] [-R owner/repo]
+  issue-flow issue start <n> [--branch] [--dry-run | --yes] [--resume <branch> | --new] [--no-launch]
+                             [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]
+  issue-flow issue start <n> --plan [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]
+  issue-flow issue start <n> --cloud | --here | --teleport | --adopt [...]
+  issue-flow worktree setup [--only <step>]
+  issue-flow worktree teardown [--path <dir>]
+  issue-flow worktree ports [--next]
+  issue-flow worktree cleanup [--path <dir>]
+  issue-flow worktree prune [--only <dir>] [--yes] [-R owner/repo]
+  issue-flow pr worktree <n> [--no-setup] [-R owner/repo] [-- [<command>...]]
+  issue-flow adapter setup [--only <step>] | issue [<url>] | archive [-R owner/repo]
+  issue-flow session
+  issue-flow hook worktree-create | worktree-remove
+  issue-flow init [--yes] [--recipe <name>,...] [--no-cloud] [--no-guard] [--no-skills]
+  issue-flow doctor
+  issue-flow upgrade [--to <version>] [--dry-run]
+
+The slug comes from the issue's "Slug de rama" block, then from Claude, then from the title,
+and the branch from the repo's template (an older "Rama sugerida" block is used if it fits).
+--missing adds the slug block to every open issue without a block, after confirming.
+
+issue start makes the branch in a worktree (or, with --branch, in this checkout), the
+start commit, the push, the draft PR and the assignment, after confirming, and opens
+Claude: in auto mode if the repo has claude-repo-guard, with your settings with
+--ask-permissions, and with no sandbox nor questions with --free. --plan prints the branch
+and the prompt as JSON and changes nothing.
+
+--cloud confirms here and opens a Claude cloud session that starts the issue there.
+--here, inside a cloud session, starts it in this checkout and opens nothing. --teleport
+brings the cloud session noted in the PR to the worktree. --adopt starts it in the
+worktree another tool (Orca, Paseo) just made, without asking nor opening Claude.
+
+worktree runs the steps of "worktrees" in .agents/flow.json: setup prepares this worktree,
+teardown cleans it before it goes (steps, ports, Docker), ports prints or moves its block
+of ports, cleanup deletes the Docker of deleted worktrees, and prune deletes the worktrees
+whose PR was merged or closed. session is the SessionStart hook of Claude Code.
+
+pr worktree makes (or reuses) a worktree on a PR's own branch, to review and fix it; with
+--, it runs the command there (Claude if none). adapter is what Orca and Paseo run: setup
+when they make a worktree (its steps and, if it came from an issue, issue start --adopt),
+issue to start one by hand, and archive before they delete it. hook implements Claude
+Code's WorktreeCreate and WorktreeRemove for claude --worktree.
+
+init sets the repo up: .agents/flow.json (with the recipes its files suggest), the dev
+dependencies and scripts, and the hooks; then, after asking, claude-cloud init,
+claude-repo-guard and the skills menu. doctor checks it is set up at this version, and
+upgrade moves the CLI, the hooks and the flow's skills to the latest version (or --to).`;

package/dist/work-state.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @file What an issue already has, from github-rest's `readWork`: its PRs, the branches it
+ * used and the live ones that can be resumed. Ported from `detect_existing` and
+ * `branch_pr` in Abastio's `scripts/start-issue.sh`.
+ */
+import type { IssueEntry, PrState } from "@ramon-sg/github-rest";
+/** A PR of the issue from this repo (not from a fork). */
+export interface IssuePr {
+    number: number;
+    branch: string;
+    state: PrState;
+    head: string;
+}
+/** The issue's work, ready to choose a branch. */
+export interface WorkState {
+    prs: IssuePr[];
+    forks: number[];
+    mergedPrs: number[];
+    mergedBranches: string[];
+    known: string[];
+    candidates: string[];
+}
+/**
+ * The issue's work. Branches of merged PRs do not count as live; a branch counts if it is
+ * in origin, local, or has an open PR. Without GitHub (offline) only local branches are
+ * seen.
+ * @param entry - The issue in `readWork`'s output.
+ * @returns The work.
+ * @example workState(output.issues[0]).candidates // ["feat/42-x"]
+ */
+export declare function workState(entry: IssueEntry): WorkState;
+/**
+ * The PR of a branch being resumed: the open one or, if there is none, the closed one
+ * that was never merged (it gets reopened).
+ * @param prs - The issue's PRs.
+ * @param branch - The branch.
+ * @returns Its number and state, or null if it has none.
+ * @example branchPr(prs, "feat/42-x") // { number: 7, state: "OPEN" }
+ */
+export declare function branchPr(prs: IssuePr[], branch: string): {
+    number: number;
+    state: "OPEN" | "CLOSED";
+} | null;
+/**
+ * The open PRs of the issue on other branches.
+ * @param prs - The issue's PRs.
+ * @param branch - The branch being worked on.
+ * @returns Their numbers.
+ * @example openPrsElsewhere(prs, "feat/42-x") // [150]
+ */
+export declare function openPrsElsewhere(prs: IssuePr[], branch: string): number[];

package/dist/work-state.js

@@ -0,0 +1,58 @@
+/**
+ * Sorted and without repeats, like jq's `unique`.
+ * @param names - The names.
+ * @returns The names.
+ */
+const unique = (names) => [...new Set(names)].sort();
+/**
+ * The issue's work. Branches of merged PRs do not count as live; a branch counts if it is
+ * in origin, local, or has an open PR. Without GitHub (offline) only local branches are
+ * seen.
+ * @param entry - The issue in `readWork`'s output.
+ * @returns The work.
+ * @example workState(output.issues[0]).candidates // ["feat/42-x"]
+ */
+export function workState(entry) {
+    const work = "work" in entry ? entry.work : { prs: [], branches: [] };
+    const local = "local" in entry ? entry.local : { branches: [], worktrees: [] };
+    const own = work.prs.filter((pr) => !pr.fork);
+    const merged = work.branches.filter((branch) => branch.merged).map((branch) => branch.name);
+    return {
+        prs: own.map(({ number, branch, state, head }) => ({ number, branch, state, head })),
+        forks: work.prs.filter((pr) => pr.fork).map((pr) => pr.number),
+        mergedPrs: own.filter((pr) => pr.state === "MERGED").map((pr) => pr.number),
+        mergedBranches: merged,
+        known: unique([...work.branches.map((branch) => branch.name), ...local.branches]),
+        candidates: unique([
+            ...work.branches.filter((branch) => !branch.merged && branch.remote).map((branch) => branch.name),
+            ...local.branches.filter((branch) => !merged.includes(branch)),
+            ...own.filter((pr) => pr.state === "OPEN").map((pr) => pr.branch),
+        ]),
+    };
+}
+/**
+ * The PR of a branch being resumed: the open one or, if there is none, the closed one
+ * that was never merged (it gets reopened).
+ * @param prs - The issue's PRs.
+ * @param branch - The branch.
+ * @returns Its number and state, or null if it has none.
+ * @example branchPr(prs, "feat/42-x") // { number: 7, state: "OPEN" }
+ */
+export function branchPr(prs, branch) {
+    const mine = prs.filter((pr) => pr.branch === branch);
+    const open = mine.find((pr) => pr.state === "OPEN");
+    if (open !== undefined)
+        return { number: open.number, state: "OPEN" };
+    const closed = mine.find((pr) => pr.state === "CLOSED");
+    return closed === undefined ? null : { number: closed.number, state: "CLOSED" };
+}
+/**
+ * The open PRs of the issue on other branches.
+ * @param prs - The issue's PRs.
+ * @param branch - The branch being worked on.
+ * @returns Their numbers.
+ * @example openPrsElsewhere(prs, "feat/42-x") // [150]
+ */
+export function openPrsElsewhere(prs, branch) {
+    return prs.filter((pr) => pr.state === "OPEN" && pr.branch !== branch).map((pr) => pr.number);
+}