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

package/dist/launch.js

@@ -0,0 +1,158 @@
+/**
+ * @file Opens Claude for an issue in the same terminal. The permission mode follows
+ * `claude-repo-guard` when the repo has it: auto mode with its classifier context by
+ * default, plain `claude` with `--ask-permissions`, and no sandbox nor questions with
+ * `--free`. Each branch keeps its session id, so starting the issue again resumes it.
+ * Ported from `launch_session` and `run_claude` in Abastio's `scripts/start-issue.sh`.
+ */
+import { randomUUID } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import { dirName, sessionName } from "./issue-text.js";
+/** The file `claude-repo-guard` writes with the auto mode's classifier context. */
+export const AUTO_MODE_FILE = ".claude/repo-guard.auto-mode.json";
+/** Folder, inside the shared `.git`, with one file per branch holding its session id. */
+export const SESSIONS_DIR = "issue-flow-sessions";
+/** Settings that turn the sandbox off for one session, as `claude:free` does. */
+const NO_SANDBOX = '{"sandbox":{"enabled":false}}';
+/**
+ * The arguments for the permission mode. By default, auto mode with the classifier context
+ * of `claude-repo-guard` if the repo has it (relative, from the folder where Claude runs,
+ * if it is there; or else by its full path in the main checkout), and plain `claude` if it
+ * does not.
+ * @param permissions - What the flags asked for.
+ * @param workDir - Where Claude runs, or null if that folder does not exist yet.
+ * @param mainRoot - The main checkout.
+ * @returns The arguments and their label.
+ * @example permissionArgs("default", wt, root).args // ["--settings", ".claude/repo-guard.auto-mode.json", "--permission-mode", "auto"]
+ */
+export function permissionArgs(permissions, workDir, mainRoot) {
+    if (permissions === "free")
+        return {
+            args: ["--settings", NO_SANDBOX, "--dangerously-skip-permissions"],
+            label: "none: no sandbox and no questions (--free)",
+        };
+    if (permissions === "ask")
+        return { args: [], label: "your settings (--ask-permissions)" };
+    const file = workDir !== null && existsSync(join(workDir, AUTO_MODE_FILE))
+        ? AUTO_MODE_FILE
+        : existsSync(join(mainRoot, AUTO_MODE_FILE))
+            ? join(mainRoot, AUTO_MODE_FILE)
+            : null;
+    if (file === null)
+        return { args: [], label: "your settings (claude-repo-guard is not installed)" };
+    return {
+        args: ["--settings", file, "--permission-mode", "auto"],
+        label: "auto mode, with claude-repo-guard's context",
+    };
+}
+/**
+ * Whether a program is in the PATH, without running it.
+ * @param name - The program.
+ * @returns True if it is.
+ * @example inPath("claude")
+ */
+export function inPath(name) {
+    return (process.env.PATH ?? "")
+        .split(delimiter)
+        .some((dir) => dir !== "" && existsSync(join(dir, name)));
+}
+/**
+ * The file that holds a branch's session id.
+ * @param commonDir - The shared `.git`.
+ * @param branch - The branch.
+ * @returns The path.
+ * @example sessionFile("/repo/.git", "feat/42-x") // "/repo/.git/issue-flow-sessions/feat+42-x"
+ */
+export function sessionFile(commonDir, branch) {
+    return join(commonDir, SESSIONS_DIR, dirName(branch));
+}
+/**
+ * Whether Claude Code has a saved session with that id.
+ * @param id - The id.
+ * @returns True if it does.
+ * @example sessionExists("11111111-2222-3333-4444-555555555555")
+ */
+export function sessionExists(id) {
+    const projects = join(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude"), "projects");
+    if (!existsSync(projects))
+        return false;
+    return readdirSync(projects).some((project) => existsSync(join(projects, project, `${id}.jsonl`)));
+}
+/**
+ * The saved session of a branch, if Claude still has it.
+ * @param commonDir - The shared `.git`.
+ * @param branch - The branch.
+ * @returns The id, or null.
+ * @example savedSession("/repo/.git", "feat/42-x")
+ */
+export function savedSession(commonDir, branch) {
+    const file = sessionFile(commonDir, branch);
+    if (!existsSync(file))
+        return null;
+    const id = readFileSync(file, "utf8").trim();
+    return id !== "" && sessionExists(id) ? id : null;
+}
+/**
+ * Forgets a branch's session id, once its work is gone.
+ * @param commonDir - The shared `.git`.
+ * @param branch - The branch.
+ * @example forgetSession("/repo/.git", "feat/42-x")
+ */
+export function forgetSession(commonDir, branch) {
+    rmSync(sessionFile(commonDir, branch), { force: true });
+}
+/**
+ * Runs Claude in the terminal; its exit code does not matter, what follows runs anyway.
+ * @param cwd - Where.
+ * @param args - The arguments.
+ */
+function runClaude(cwd, args) {
+    spawnSync("claude", args, { cwd, stdio: "inherit" });
+}
+/**
+ * Opens Claude: resumes the branch's saved session or creates one with its name, its color
+ * and the prompt. The color is set first with a `claude -p "/color …"` on the new session,
+ * because a session only takes it from a command.
+ * @param plan - Where, which branch and with what.
+ * @param warn - Where a warning goes.
+ * @example launchSession(plan, (text) => console.error(text))
+ */
+export function launchSession(plan, warn) {
+    const saved = savedSession(plan.commonDir, plan.branch);
+    if (saved !== null) {
+        runClaude(plan.workDir, [...plan.permissions, "--resume", saved, plan.prompt]);
+        return;
+    }
+    const id = randomUUID();
+    const file = sessionFile(plan.commonDir, plan.branch);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${id}\n`);
+    const name = sessionName(plan.branch, plan.mode);
+    if (plan.color !== null) {
+        const colored = spawnSync("claude", ["-p", "--session-id", id, "-n", name, `/color ${plan.color}`], {
+            cwd: plan.workDir,
+            stdio: "ignore",
+        });
+        if (colored.status !== 0)
+            warn("could not color the session; it opens without a color.");
+    }
+    if (sessionExists(id))
+        runClaude(plan.workDir, [...plan.permissions, "--resume", id, plan.prompt]);
+    else
+        runClaude(plan.workDir, [...plan.permissions, "--session-id", id, "-n", name, plan.prompt]);
+}
+/**
+ * Brings a cloud session to the folder with `claude --teleport`: the one noted in the PR,
+ * or the list of sessions to choose from if there is none. It keeps no session id: once
+ * brought, `claude --resume` finds it.
+ * @param workDir - Where.
+ * @param permissions - The arguments of the permission mode.
+ * @param id - The cloud session, or null for the list.
+ * @example teleportSession(wt, [], "session_01A")
+ */
+export function teleportSession(workDir, permissions, id) {
+    runClaude(workDir, [...permissions, "--teleport", ...(id === null ? [] : [id])]);
+}

package/dist/output.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file Where commands write, and the usage error. Commands get an `Output` instead of
+ * writing to `process` directly, so the entry point decides about the terminal.
+ */
+/** Usage error: exits 2 and prints the usage text. */
+export declare class UsageError extends Error {
+}
+/** Where a command writes, and whether someone can answer a question. */
+export interface Output {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    interactive: boolean;
+}
+/**
+ * The process's output; interactive when both stdin and stdout are a terminal.
+ * @returns The output.
+ * @example processOutput().interactive
+ */
+export declare function processOutput(): Output;
+/**
+ * Prints a warning on stderr with the program's name.
+ * @param out - Where to write.
+ * @param text - The warning.
+ * @example warn(out, "nothing written")
+ */
+export declare function warn(out: Output, text: string): void;
+/**
+ * Prints a value as one line of JSON on stdout.
+ * @param out - Where to write.
+ * @param value - The value.
+ * @example emitJson(out, { ok: true })
+ */
+export declare function emitJson(out: Output, value: unknown): void;

package/dist/output.js

@@ -0,0 +1,37 @@
+/**
+ * @file Where commands write, and the usage error. Commands get an `Output` instead of
+ * writing to `process` directly, so the entry point decides about the terminal.
+ */
+/** Usage error: exits 2 and prints the usage text. */
+export class UsageError extends Error {
+}
+/**
+ * The process's output; interactive when both stdin and stdout are a terminal.
+ * @returns The output.
+ * @example processOutput().interactive
+ */
+export function processOutput() {
+    return {
+        stdout: (text) => process.stdout.write(text),
+        stderr: (text) => process.stderr.write(text),
+        interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    };
+}
+/**
+ * Prints a warning on stderr with the program's name.
+ * @param out - Where to write.
+ * @param text - The warning.
+ * @example warn(out, "nothing written")
+ */
+export function warn(out, text) {
+    out.stderr(`issue-flow: ${text}\n`);
+}
+/**
+ * Prints a value as one line of JSON on stdout.
+ * @param out - Where to write.
+ * @param value - The value.
+ * @example emitJson(out, { ok: true })
+ */
+export function emitJson(out, value) {
+    out.stdout(`${JSON.stringify(value)}\n`);
+}

package/dist/package-edits.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @file The repo's `package.json` as the flow needs it: `issue-flow`, `github-rest` and
+ * `skills-manager` as exact dev dependencies (the skills call them with `npx`, which then
+ * uses the repo's copy), and the scripts to start an issue, prune worktrees and review a PR.
+ * A dependency or script the repo already has with another value stays as it is.
+ */
+import type { OwnVersions } from "./setup-files.js";
+/**
+ * The dependencies the flow pins, with their versions.
+ * @param versions - This package's versions.
+ * @returns Package to version.
+ * @example pinnedPackages(versions)["@ramon-sg/issue-flow"] // "0.1.0"
+ */
+export declare function pinnedPackages(versions: OwnVersions): Record<string, string>;
+/**
+ * The version of a package in the repo, as a dependency or a dev dependency.
+ * @param pkg - The package.json.
+ * @param name - The package.
+ * @returns Its version range, or null.
+ * @example dependencyVersion(pkg, "@ramon-sg/github-rest") // "0.2.1"
+ */
+export declare function dependencyVersion(pkg: Record<string, unknown> | null, name: string): string | null;
+/**
+ * Adds the flow's dev dependencies and scripts that are missing. With `move`, also moves the
+ * ones already there to these versions (what `upgrade` does).
+ * @param pkg - The package.json, or null if there is none.
+ * @param versions - The versions to pin.
+ * @param move - Whether to move the dependencies already there.
+ * @returns The new package.json and what changed or was kept.
+ * @example withFlowPackages(null, versions, false).changes // ["devDependencies: @ramon-sg/issue-flow 0.1.0", …]
+ */
+export declare function withFlowPackages(pkg: Record<string, unknown> | null, versions: OwnVersions, move: boolean): {
+    pkg: Record<string, unknown>;
+    changes: string[];
+};

package/dist/package-edits.js

@@ -0,0 +1,78 @@
+/** The scripts `init` adds. */
+const FLOW_SCRIPTS = {
+    "issue:start": "issue-flow issue start",
+    "worktree:prune": "issue-flow worktree prune",
+    "pr:worktree": "issue-flow pr worktree",
+};
+/**
+ * The dependencies the flow pins, with their versions.
+ * @param versions - This package's versions.
+ * @returns Package to version.
+ * @example pinnedPackages(versions)["@ramon-sg/issue-flow"] // "0.1.0"
+ */
+export function pinnedPackages(versions) {
+    return {
+        "@ramon-sg/issue-flow": versions.issueFlow,
+        "@ramon-sg/github-rest": versions.githubRest,
+        "@ramon-sg/skills-manager": versions.skillsManager,
+    };
+}
+/**
+ * Where a package is in the repo's package.json, and its version.
+ * @param pkg - The package.json.
+ * @param name - The package.
+ * @returns The field and the version range, or null if it is in neither.
+ */
+function dependencyOf(pkg, name) {
+    for (const field of ["dependencies", "devDependencies"]) {
+        const deps = pkg?.[field];
+        const version = typeof deps === "object" && deps !== null ? deps[name] : undefined;
+        if (typeof version === "string")
+            return { field, version };
+    }
+    return null;
+}
+/**
+ * The version of a package in the repo, as a dependency or a dev dependency.
+ * @param pkg - The package.json.
+ * @param name - The package.
+ * @returns Its version range, or null.
+ * @example dependencyVersion(pkg, "@ramon-sg/github-rest") // "0.2.1"
+ */
+export function dependencyVersion(pkg, name) {
+    return dependencyOf(pkg, name)?.version ?? null;
+}
+/**
+ * Adds the flow's dev dependencies and scripts that are missing. With `move`, also moves the
+ * ones already there to these versions (what `upgrade` does).
+ * @param pkg - The package.json, or null if there is none.
+ * @param versions - The versions to pin.
+ * @param move - Whether to move the dependencies already there.
+ * @returns The new package.json and what changed or was kept.
+ * @example withFlowPackages(null, versions, false).changes // ["devDependencies: @ramon-sg/issue-flow 0.1.0", …]
+ */
+export function withFlowPackages(pkg, versions, move) {
+    const next = pkg === null ? { private: true } : { ...pkg };
+    const scripts = { ...(next.scripts ?? {}) };
+    const changes = [];
+    for (const [name, version] of Object.entries(pinnedPackages(versions))) {
+        const current = dependencyOf(next, name);
+        if (current?.version === version)
+            continue;
+        if (current !== null && !move) {
+            changes.push(`kept ${name} ${current.version} (issue-flow ${versions.issueFlow} was tested with ${version})`);
+            continue;
+        }
+        const field = current?.field ?? "devDependencies";
+        next[field] = { ...(next[field] ?? {}), [name]: version };
+        changes.push(`${field}: ${name} ${current === null ? "" : `${current.version} → `}${version}`);
+    }
+    for (const [name, command] of Object.entries(FLOW_SCRIPTS)) {
+        if (scripts[name] !== undefined)
+            continue;
+        scripts[name] = command;
+        changes.push(`scripts: ${name}`);
+    }
+    next.scripts = scripts;
+    return { pkg: next, changes };
+}

package/dist/plan-doc.d.ts

@@ -0,0 +1,26 @@
+/** Where to look and what for. */
+export interface PlanQuery {
+    cwd: string;
+    base: string;
+    repo: string;
+    dirs: string[];
+}
+/**
+ * The plan of a branch being resumed: one its own commits touched or, if none, one in the
+ * base branch that names its PR.
+ * @param query - Where to look.
+ * @param branch - The branch.
+ * @param pr - Its PR, or null.
+ * @returns The plan's path, or null.
+ * @example findPlan(query, "feat/42-x", 7) // "docs/plans/2026-10-24-x.md"
+ */
+export declare function findPlan(query: PlanQuery, branch: string, pr: number | null): string | null;
+/**
+ * The plan an earlier round left open: a document of the base branch that names one of
+ * the merged PRs and is not in `applied/` nor `abandoned/`.
+ * @param query - Where to look.
+ * @param merged - The issue's merged PRs.
+ * @returns The plan's path, or null.
+ * @example findOpenPlan(query, [7]) // "docs/plans/2026-10-24-x.md"
+ */
+export declare function findOpenPlan(query: PlanQuery, merged: number[]): string | null;

package/dist/plan-doc.js

@@ -0,0 +1,93 @@
+/**
+ * @file Finds the plan of an issue, so a resumed session picks up from it: a plan the
+ * branch's own commits touched, or a plan in the base branch whose `prs:` names one of the
+ * issue's PRs. Ported from `find_plan` and `find_open_plan` in Abastio's
+ * `scripts/start-issue.sh`.
+ */
+import { gitLines, hasLocal, onOrigin } from "./git.js";
+/** Folders of finished and discarded plans, which never count as open. */
+const CLOSED_FOLDERS = /\/(applied|abandoned)\//;
+/** A PR in a `prs:` list: `12`, `#12` or `owner/repo#12`, with or without quotes. */
+const PR_REFERENCE = /(?:([\w.-]+\/[\w.-]+))?#?(\d+)/g;
+/**
+ * The first file in the order of the configured folders (plans before specs by default).
+ * @param files - The files found.
+ * @param dirs - The folders, in order of preference.
+ * @returns The file, or null.
+ */
+function preferred(files, dirs) {
+    for (const dir of dirs) {
+        const found = files.find((file) => file.startsWith(`${dir}/`));
+        if (found !== undefined)
+            return found;
+    }
+    return null;
+}
+/**
+ * Whether a `prs:` line names that PR of this repo. A reference to another repo does not
+ * count.
+ * @param line - The line.
+ * @param repo - `owner/repo`.
+ * @param number - The PR.
+ * @returns True if it names it.
+ */
+function namesPr(line, repo, number) {
+    for (const match of line.matchAll(PR_REFERENCE)) {
+        const [, other, digits] = match;
+        if (Number(digits) !== number)
+            continue;
+        if (other === undefined || other.toLowerCase() === repo.toLowerCase())
+            return true;
+    }
+    return false;
+}
+/**
+ * The documents of the base branch whose `prs:` names one of the PRs.
+ * @param query - Where to look.
+ * @param prs - The PRs.
+ * @returns The paths, relative to the repo.
+ */
+function documentsOf(query, prs) {
+    if (prs.length === 0)
+        return [];
+    const ref = `origin/${query.base}`;
+    const hits = gitLines(query.cwd, ["grep", "-E", "^prs:", ref, "--", ...query.dirs]);
+    const files = [];
+    for (const hit of hits) {
+        const [, path = "", line = ""] = /^[^:]+:([^:]+):(.*)$/.exec(hit) ?? [];
+        if (prs.some((pr) => namesPr(line.slice("prs:".length), query.repo, pr)))
+            files.push(path);
+    }
+    return [...new Set(files)];
+}
+/**
+ * The plan of a branch being resumed: one its own commits touched or, if none, one in the
+ * base branch that names its PR.
+ * @param query - Where to look.
+ * @param branch - The branch.
+ * @param pr - Its PR, or null.
+ * @returns The plan's path, or null.
+ * @example findPlan(query, "feat/42-x", 7) // "docs/plans/2026-10-24-x.md"
+ */
+export function findPlan(query, branch, pr) {
+    const ref = hasLocal(query.cwd, branch) ? branch : onOrigin(query.cwd, branch) ? `origin/${branch}` : null;
+    const touched = ref === null
+        ? []
+        : gitLines(query.cwd, ["log", "--format=", "--name-only", `origin/${query.base}..${ref}`, "--", ...query.dirs]);
+    const own = preferred([...new Set(touched)].sort(), query.dirs);
+    if (own !== null)
+        return own;
+    return preferred(documentsOf(query, pr === null ? [] : [pr]), query.dirs);
+}
+/**
+ * The plan an earlier round left open: a document of the base branch that names one of
+ * the merged PRs and is not in `applied/` nor `abandoned/`.
+ * @param query - Where to look.
+ * @param merged - The issue's merged PRs.
+ * @returns The plan's path, or null.
+ * @example findOpenPlan(query, [7]) // "docs/plans/2026-10-24-x.md"
+ */
+export function findOpenPlan(query, merged) {
+    const open = documentsOf(query, merged).filter((file) => !CLOSED_FOLDERS.test(`/${file}`));
+    return preferred(open.sort(), query.dirs);
+}

package/dist/ports.d.ts

@@ -0,0 +1,90 @@
+import type { PortsConfig } from "./worktree-config.js";
+/** File, in the worktree's own git dir, with the first port of its block. */
+export declare const PORT_BASE_FILE = "issue-flow-port-base";
+/**
+ * The sha256 of a text, in hex.
+ * @param value - The text.
+ * @returns The hash.
+ * @example sha256("a").slice(0, 6) // "ca9781"
+ */
+export declare function sha256(value: string): string;
+/**
+ * Where `issue-flow` keeps what belongs to the whole machine (which worktree took each
+ * block): `ISSUE_FLOW_STATE_DIR`, or `~/.issue-flow`.
+ * @returns The folder.
+ * @example stateDir() // "/Users/me/.issue-flow"
+ */
+export declare function stateDir(): string;
+/**
+ * A stable name of the machine, without its domain. On macOS the local host name, not
+ * `hostname()`: that one changes with the network, and every block would move.
+ * @returns The name.
+ * @example machineName() // "ramon-mbp"
+ */
+export declare function machineName(): string;
+/**
+ * The first port of the block a folder starts from on a machine. It is only the start:
+ * `claimPortBase` moves on if it is taken.
+ * @param ports - The range.
+ * @param machine - The machine's name.
+ * @param root - The worktree.
+ * @param system - The system (`os.platform()`).
+ * @returns The port.
+ * @example defaultPortBase(DEFAULT_PORTS, "mbp", "/repo/.claude/worktrees/feat+42-x", "darwin") // 20000 to 24990
+ */
+export declare function defaultPortBase(ports: PortsConfig, machine: string, root: string, system: string): number;
+/**
+ * The block after one, without leaving its half: after the half's last it goes back to
+ * the half's first.
+ * @param ports - The range.
+ * @param base - The first port of a block.
+ * @returns The next block's first port.
+ * @example nextPortBase(DEFAULT_PORTS, 24990) // 20000
+ */
+export declare function nextPortBase(ports: PortsConfig, base: number): number;
+/**
+ * Whether a value is the first port of a block of the range.
+ * @param ports - The range.
+ * @param value - The value.
+ * @returns True if it is.
+ * @example isPortBase(DEFAULT_PORTS, 20010) // true
+ */
+export declare function isPortBase(ports: PortsConfig, value: number): boolean;
+/**
+ * The first port of a worktree's block: the saved one, or the one it starts from. It only
+ * reads: `claimPortBase` writes it once, before the apps start.
+ * @param ports - The range.
+ * @param root - The worktree.
+ * @returns The port.
+ * @example portBase(DEFAULT_PORTS, wt) // 21430
+ */
+export declare function portBase(ports: PortsConfig, root: string): number;
+/**
+ * Whether a folder is still the root of a checkout, comparing resolved paths. An empty
+ * folder left by a deleted worktree inside the main checkout finds the main repo, so being
+ * inside git is not enough.
+ * @param path - The folder.
+ * @returns True if it is a root.
+ * @example isCheckoutRoot("/repo/.claude/worktrees/feat+42-x")
+ */
+export declare function isCheckoutRoot(path: string): boolean;
+/**
+ * Deletes the worktree's registrations, but the one of the block it keeps. Run when the
+ * worktree moves to another block or goes away.
+ * @param root - The worktree.
+ * @param keep - The block it keeps, or null for none.
+ * @example releasePortClaims(wt, null)
+ */
+export declare function releasePortClaims(root: string, keep: number | null): void;
+/**
+ * Fixes the worktree's block and returns it. A valid saved block stays. Otherwise, or with
+ * `start` (to move it), it looks from `start` (or the block it starts from) for the first
+ * free one of its half: nobody registered it and nothing listens in it. It registers that
+ * block, saves it and drops the ones it had.
+ * @param ports - The range.
+ * @param root - The worktree.
+ * @param start - Where to start looking, or null to keep the saved block.
+ * @returns The first port, or null if the whole half is taken.
+ * @example await claimPortBase(DEFAULT_PORTS, wt, null) // 21430
+ */
+export declare function claimPortBase(ports: PortsConfig, root: string, start: number | null): Promise<number | null>;