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

package/dist/ports.js

@@ -0,0 +1,257 @@
+/**
+ * @file The block of ports of each worktree, so two worktrees never take the same ports.
+ * A block starts from a hash of the machine and the folder (stable: the same worktree
+ * always gets the same block), moves on if something listens in it or another worktree of
+ * the machine registered it, and once chosen is saved in the worktree's git dir. macOS uses
+ * the first half of the range and the rest the second, so a laptop worktree and a server's
+ * never share a block when Orca forwards the server's ports with the same numbers. Ported
+ * from `wt_claim_port_base` and its helpers in Abastio's `scripts/lib/worktree.sh`.
+ */
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { connect } from "node:net";
+import { homedir, hostname, platform } from "node:os";
+import { join } from "node:path";
+import { checkoutRoot, git } from "./git.js";
+/** File, in the worktree's own git dir, with the first port of its block. */
+export const PORT_BASE_FILE = "issue-flow-port-base";
+/** Hex digits of the hash that pick the block: seven fit in a safe integer. */
+const HASH_DIGITS = 7;
+/** How long a port gets to answer before it counts as free. */
+const CONNECT_TIMEOUT_MS = 300;
+/**
+ * The sha256 of a text, in hex.
+ * @param value - The text.
+ * @returns The hash.
+ * @example sha256("a").slice(0, 6) // "ca9781"
+ */
+export function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+/**
+ * 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 function stateDir() {
+    return process.env.ISSUE_FLOW_STATE_DIR ?? join(homedir(), ".issue-flow");
+}
+/**
+ * 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 function machineName() {
+    const local = platform() === "darwin" ? spawnSync("scutil", ["--get", "LocalHostName"], { encoding: "utf8" }) : null;
+    const name = local?.status === 0 && local.stdout.trim() !== "" ? local.stdout.trim() : hostname();
+    return name.split(".")[0] ?? name;
+}
+/**
+ * The first block of the half of the range that belongs to a system.
+ * @param ports - The range.
+ * @param system - The system, as `os.platform()` names it.
+ * @returns The block's index.
+ */
+function firstBlock(ports, system) {
+    return system === "darwin" ? 0 : ports.blocks / 2;
+}
+/**
+ * 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 function defaultPortBase(ports, machine, root, system) {
+    const hash = Number.parseInt(sha256(`${machine}:${root}`).slice(0, HASH_DIGITS), 16);
+    const half = ports.blocks / 2;
+    return ports.start + (firstBlock(ports, system) + (hash % half)) * ports.blockSize;
+}
+/**
+ * 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 function nextPortBase(ports, base) {
+    const half = ports.blocks / 2;
+    const block = (base - ports.start) / ports.blockSize;
+    const first = Math.floor(block / half) * half;
+    const next = block + 1 < first + half ? block + 1 : first;
+    return ports.start + next * ports.blockSize;
+}
+/**
+ * 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 function isPortBase(ports, value) {
+    const end = ports.start + ports.blocks * ports.blockSize;
+    return Number.isInteger(value) && value >= ports.start && value < end && (value - ports.start) % ports.blockSize === 0;
+}
+/**
+ * The file with a worktree's block.
+ * @param root - The worktree.
+ * @returns The path, or null outside git.
+ */
+function baseFile(root) {
+    const dir = git(root, ["rev-parse", "--path-format=absolute", "--git-dir"]);
+    return dir.ok ? join(dir.out, PORT_BASE_FILE) : null;
+}
+/**
+ * The block saved for a worktree, if it is valid for the range.
+ * @param ports - The range.
+ * @param root - The worktree.
+ * @returns The first port, or null.
+ */
+function savedBase(ports, root) {
+    const file = baseFile(root);
+    if (file === null || !existsSync(file))
+        return null;
+    const value = Number(readFileSync(file, "utf8").trim());
+    return isPortBase(ports, value) ? value : null;
+}
+/**
+ * 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 function portBase(ports, root) {
+    return savedBase(ports, root) ?? defaultPortBase(ports, machineName(), root, platform());
+}
+/**
+ * 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 function isCheckoutRoot(path) {
+    return path !== "" && existsSync(path) && checkoutRoot(path) === realpathSync(path);
+}
+/**
+ * The folder that records which worktree of the machine took a block.
+ * @param base - The block's first port.
+ * @returns The folder.
+ */
+function claimDir(base) {
+    return join(stateDir(), "ports", String(base));
+}
+/**
+ * The worktree that registered a block, if it still exists and is not this one.
+ * @param root - This worktree.
+ * @param base - The block.
+ * @returns True if another live worktree has it.
+ */
+function takenByOther(root, base) {
+    const file = join(claimDir(base), "path");
+    if (!existsSync(file))
+        return false;
+    const owner = readFileSync(file, "utf8").trim();
+    return owner !== "" && owner !== root && isCheckoutRoot(owner);
+}
+/**
+ * Whether something listens on a port, over IPv4 or IPv6.
+ * @param port - The port.
+ * @returns True if a connection opens.
+ */
+async function listening(port) {
+    const tryHost = (host) => new Promise((resolve) => {
+        const socket = connect({ host, port });
+        const done = (open) => {
+            socket.destroy();
+            resolve(open);
+        };
+        socket.setTimeout(CONNECT_TIMEOUT_MS, () => done(false));
+        socket.once("connect", () => done(true));
+        socket.once("error", () => done(false));
+    });
+    return (await tryHost("127.0.0.1")) || (await tryHost("::1"));
+}
+/**
+ * Whether something listens on any port of a block.
+ * @param ports - The range.
+ * @param base - The block.
+ * @returns True if one is busy.
+ */
+async function blockBusy(ports, base) {
+    const checks = Array.from({ length: ports.blockSize }, (_, offset) => listening(base + offset));
+    return (await Promise.all(checks)).some(Boolean);
+}
+/**
+ * Registers a block for the worktree.
+ * @param root - The worktree.
+ * @param base - The block.
+ * @returns False if another live worktree registered it first.
+ */
+function takeClaim(root, base) {
+    if (takenByOther(root, base))
+        return false;
+    mkdirSync(claimDir(base), { recursive: true });
+    writeFileSync(join(claimDir(base), "path"), `${root}\n`);
+    return true;
+}
+/**
+ * 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 function releasePortClaims(root, keep) {
+    const dir = join(stateDir(), "ports");
+    if (!existsSync(dir))
+        return;
+    for (const name of readdirSync(dir)) {
+        const file = join(dir, name, "path");
+        if (name === String(keep) || !existsSync(file))
+            continue;
+        if (readFileSync(file, "utf8").trim() === root)
+            rmSync(join(dir, name), { recursive: true, force: true });
+    }
+}
+/**
+ * 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 async function claimPortBase(ports, root, start) {
+    const saved = savedBase(ports, root);
+    if (start === null && saved !== null) {
+        takeClaim(root, saved);
+        return saved;
+    }
+    const file = baseFile(root);
+    if (file === null)
+        return null;
+    let candidate = start ?? defaultPortBase(ports, machineName(), root, platform());
+    for (let tries = 0; tries < ports.blocks / 2; tries += 1) {
+        if (!takenByOther(root, candidate) && !(await blockBusy(ports, candidate)) && takeClaim(root, candidate)) {
+            writeFileSync(file, `${candidate}\n`);
+            releasePortClaims(root, candidate);
+            return candidate;
+        }
+        candidate = nextPortBase(ports, candidate);
+    }
+    return null;
+}

package/dist/propose.d.ts

@@ -0,0 +1,42 @@
+import type { FlowConfig, Namer } from "./config.js";
+/** What is read of an issue to name its branch. */
+export interface IssueInfo {
+    number: number;
+    title: string;
+    body: string;
+    labels: string[];
+}
+/** Where a proposed branch came from. */
+export type BranchSource = "slug" | "suggested" | "claude" | "title";
+/** The branch proposed for an issue, with the slug and type it was made from. */
+export interface Proposal {
+    number: number;
+    branch: string;
+    slug: string;
+    type: string | null;
+    source: BranchSource;
+    warnings: string[];
+}
+/** How to propose: the namer (the config's by default), where to run Claude and whether
+ * a type Claude picks for an issue without one is used. */
+export interface ProposeOptions {
+    namer?: Namer;
+    cwd: string;
+    claudeType?: boolean;
+}
+/**
+ * Proposes a branch for each issue. Claude is called once, for every issue without a
+ * usable block, and only if the namer is `claude`; if it fails or skips an issue, that
+ * issue falls back to the title, with a warning.
+ * @param issues - The issues.
+ * @param config - The repo's config.
+ * @param options - The namer, where to run Claude and whether Claude's type is used
+ *   (true by default; false when only the slug will be written to the issue).
+ * @returns One proposal per issue, in the same order, and the warnings of the whole batch
+ *   (Claude not answering).
+ * @example proposeBranches([issue], config, { cwd: process.cwd() }).proposals[0]?.branch
+ */
+export declare function proposeBranches(issues: IssueInfo[], config: FlowConfig, options: ProposeOptions): {
+    proposals: Proposal[];
+    warnings: string[];
+};

package/dist/propose.js

@@ -0,0 +1,111 @@
+/**
+ * @file Proposes the branch of each issue, in this order: its "Slug de rama" block, its
+ * older "Rama sugerida" block if it fits the issue, a slug from Claude (one call for every
+ * issue that needs one), or the title's slug. Except for the older block, the branch is
+ * always the repo's template. Ported from `propose_branch` in Abastio's
+ * `scripts/start-issue.sh`, with the slug block and Claude as new steps.
+ */
+import { branchProblem, branchType, isSlug, renderBranch, suggestedBranch, suggestedSlug, titleSlug, typeNames, } from "./branch-name.js";
+import { nameWithClaude } from "./claude-namer.js";
+/**
+ * The proposal from the issue's own blocks: the slug block, or else the older block if it
+ * fits the issue (used as is, with a warning if its prefix is not the issue's type).
+ * @param issue - The issue.
+ * @param type - Its type, or null.
+ * @param template - The repo's template.
+ * @returns The proposal, or the notes on why the blocks were not used.
+ */
+function fromBlocks(issue, type, template) {
+    const { number } = issue;
+    const slug = suggestedSlug(issue.body);
+    if (isSlug(slug))
+        return { number, branch: renderBranch(template, type, number, slug), slug, type, source: "slug", warnings: [] };
+    if (slug !== null)
+        return { notes: [`#${number}: "${slug}" in "Slug de rama" is not a valid slug; proposing another.`] };
+    const branch = suggestedBranch(issue.body);
+    const problem = branchProblem(branch, number);
+    if (branch === null)
+        return { notes: [] };
+    if (problem !== null)
+        return { notes: [`#${number}: ${problem}; proposing another.`] };
+    const prefix = branch.includes("/") ? branch.slice(0, branch.indexOf("/")) : null;
+    const warnings = type !== null && prefix !== null && prefix !== type
+        ? [`#${number}: the suggested branch ${branch} does not start with ${type}/, the issue's type; using it anyway.`]
+        : [];
+    const own = branch.slice(branch.lastIndexOf("/") + 1).slice(`${number}-`.length);
+    return { number, branch, slug: own, type, source: "suggested", warnings };
+}
+/**
+ * Proposes a branch for each issue. Claude is called once, for every issue without a
+ * usable block, and only if the namer is `claude`; if it fails or skips an issue, that
+ * issue falls back to the title, with a warning.
+ * @param issues - The issues.
+ * @param config - The repo's config.
+ * @param options - The namer, where to run Claude and whether Claude's type is used
+ *   (true by default; false when only the slug will be written to the issue).
+ * @returns One proposal per issue, in the same order, and the warnings of the whole batch
+ *   (Claude not answering).
+ * @example proposeBranches([issue], config, { cwd: process.cwd() }).proposals[0]?.branch
+ */
+export function proposeBranches(issues, config, options) {
+    const { template, types: rules } = config.branch;
+    const typeOf = new Map(issues.map((issue) => [issue.number, branchType(rules, issue.labels, issue.title)]));
+    const proposals = new Map();
+    const pending = [];
+    const notes = new Map();
+    for (const issue of issues) {
+        const found = fromBlocks(issue, typeOf.get(issue.number) ?? null, template);
+        if ("branch" in found) {
+            proposals.set(issue.number, found);
+            continue;
+        }
+        notes.set(issue.number, found.notes);
+        pending.push(issue);
+    }
+    const namer = options.namer ?? config.branch.namer;
+    const asked = pending.map((issue) => ({
+        number: issue.number,
+        title: issue.title,
+        body: issue.body,
+        type: typeOf.get(issue.number) ?? null,
+    }));
+    const answer = namer === "claude" && asked.length > 0
+        ? nameWithClaude(asked, typeNames(rules), config.branch.claudeModel, options.cwd)
+        : null;
+    const prefixes = Object.keys(rules.titlePrefixes);
+    for (const issue of pending) {
+        const { number } = issue;
+        const warnings = notes.get(number) ?? [];
+        const own = typeOf.get(number) ?? null;
+        const named = answer !== null && "names" in answer ? answer.names.get(number) : undefined;
+        if (named !== undefined) {
+            const type = options.claudeType === false ? own : named.type;
+            proposals.set(number, {
+                number,
+                branch: renderBranch(template, type, number, named.slug),
+                slug: named.slug,
+                type,
+                source: "claude",
+                warnings,
+            });
+            continue;
+        }
+        if (answer !== null && "names" in answer)
+            warnings.push(`#${number}: Claude gave no valid name; using the title.`);
+        const slug = titleSlug(issue.title, prefixes);
+        proposals.set(number, {
+            number,
+            branch: renderBranch(template, own, number, slug),
+            slug,
+            type: own,
+            source: "title",
+            warnings,
+        });
+    }
+    return {
+        proposals: issues.map((issue) => proposals.get(issue.number)),
+        warnings: answer !== null && "error" in answer
+            ? [`${answer.error}; naming ${pending.length} issue(s) from the title.`]
+            : [],
+    };
+}

package/dist/recipes.d.ts

@@ -0,0 +1,43 @@
+/** A recipe. */
+export interface Recipe {
+    name: string;
+    description: string;
+    detect: string[];
+    config: Record<string, unknown>;
+}
+/**
+ * Every recipe, by name.
+ * @returns The recipes.
+ * @throws SetupError if a recipe file is broken.
+ * @example loadRecipes().map((recipe) => recipe.name) // ["bun", "direnv", …]
+ */
+export declare function loadRecipes(): Recipe[];
+/**
+ * The recipes the repo's files suggest: a lockfile, a compose file, an `.envrc`.
+ * @param root - The repo.
+ * @param recipes - The recipes.
+ * @returns Their names.
+ * @example detectedRecipes(root, loadRecipes()) // ["pnpm", "docker-compose"]
+ */
+export declare function detectedRecipes(root: string, recipes: Recipe[]): string[];
+/**
+ * The prefix of the repo's Docker projects: its folder name, in lowercase letters, digits
+ * and dashes.
+ * @param root - The repo.
+ * @returns The prefix.
+ * @example projectPrefix("/code/Acme Shop") // "acme-shop"
+ */
+export declare function projectPrefix(root: string): string;
+/**
+ * Applies a recipe to the repo's raw config: adds its missing steps and keys, and keeps
+ * every key the repo already set.
+ * @param raw - The repo's config, as JSON.
+ * @param recipe - The recipe.
+ * @param prefix - The repo's Docker project prefix, for `{project}`.
+ * @returns The new config and what changed, one line each.
+ * @example applyRecipe({}, npmRecipe, "acme").changes // ['worktrees.setup: added "deps"']
+ */
+export declare function applyRecipe(raw: Record<string, unknown>, recipe: Recipe, prefix: string): {
+    raw: Record<string, unknown>;
+    changes: string[];
+};

package/dist/recipes.js

@@ -0,0 +1,123 @@
+/**
+ * @file Recipes: pieces of `.agents/flow.json` for what many repos share (installing with
+ * npm, pnpm or bun, a Docker Compose project per worktree, direnv, a staging branch). Each
+ * one is a JSON file in `recipes/` with a description, the files that suggest it and its
+ * config. Applying one adds what is missing and never overwrites what the repo chose:
+ * steps go in by name, and a key already set stays as it is.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isObject } from "./config-base.js";
+import { SetupError } from "./setup-files.js";
+/** Where the recipes are, next to `dist`. */
+const RECIPES_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "recipes");
+/** What a recipe's strings say instead of the repo's Docker project prefix. */
+const PROJECT_PLACEHOLDER = "{project}";
+/** The worktree lists a recipe adds steps to. */
+const STEP_LISTS = ["setup", "teardown"];
+/**
+ * Every recipe, by name.
+ * @returns The recipes.
+ * @throws SetupError if a recipe file is broken.
+ * @example loadRecipes().map((recipe) => recipe.name) // ["bun", "direnv", …]
+ */
+export function loadRecipes() {
+    return readdirSync(RECIPES_DIR).filter((file) => file.endsWith(".json")).sort().map((file) => {
+        const raw = JSON.parse(readFileSync(join(RECIPES_DIR, file), "utf8"));
+        if (!isObject(raw) || typeof raw.description !== "string" || !Array.isArray(raw.detect) || !isObject(raw.config))
+            throw new SetupError(`recipe ${file} is broken.`);
+        return { name: basename(file, ".json"), description: raw.description, detect: raw.detect.map(String), config: raw.config };
+    });
+}
+/**
+ * The recipes the repo's files suggest: a lockfile, a compose file, an `.envrc`.
+ * @param root - The repo.
+ * @param recipes - The recipes.
+ * @returns Their names.
+ * @example detectedRecipes(root, loadRecipes()) // ["pnpm", "docker-compose"]
+ */
+export function detectedRecipes(root, recipes) {
+    return recipes.filter((recipe) => recipe.detect.some((file) => existsSync(join(root, file)))).map((recipe) => recipe.name);
+}
+/**
+ * The prefix of the repo's Docker projects: its folder name, in lowercase letters, digits
+ * and dashes.
+ * @param root - The repo.
+ * @returns The prefix.
+ * @example projectPrefix("/code/Acme Shop") // "acme-shop"
+ */
+export function projectPrefix(root) {
+    const slug = basename(root).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return slug === "" ? "app" : slug;
+}
+/**
+ * Adds a recipe's steps to a list, those whose name is not there yet.
+ * @param current - The repo's steps, or undefined.
+ * @param added - The recipe's steps.
+ * @returns The list, the names added and the names it already had.
+ */
+function mergeSteps(current, added) {
+    const steps = Array.isArray(current) ? [...current] : [];
+    const names = new Set(steps.filter(isObject).map((step) => step.name));
+    const recipeSteps = (Array.isArray(added) ? added : []).filter(isObject);
+    const fresh = recipeSteps.filter((step) => !names.has(step.name));
+    const taken = recipeSteps.filter((step) => names.has(step.name)).map((step) => String(step.name));
+    return { steps: [...steps, ...fresh], names: fresh.map((step) => String(step.name)), taken };
+}
+/**
+ * Merges a recipe's `worktrees` into the repo's.
+ * @param current - The repo's `worktrees`, or undefined.
+ * @param added - The recipe's.
+ * @param changes - Where to note what changed.
+ * @returns The merged `worktrees`.
+ */
+function mergeWorktrees(current, added, changes) {
+    const merged = isObject(current) ? { ...current } : {};
+    for (const [key, value] of Object.entries(added)) {
+        if (STEP_LISTS.includes(key)) {
+            const { steps, names, taken } = mergeSteps(merged[key], value);
+            merged[key] = steps;
+            for (const name of names)
+                changes.push(`worktrees.${key}: added "${name}"`);
+            for (const name of taken)
+                changes.push(`kept the "${name}" step of worktrees.${key}`);
+        }
+        else if (key === "dockerProjects") {
+            const projects = [...new Set([...(Array.isArray(merged[key]) ? merged[key] : []), ...(Array.isArray(value) ? value : [])])];
+            if (projects.length !== (Array.isArray(merged[key]) ? merged[key].length : 0))
+                changes.push(`worktrees.dockerProjects: ${projects.join(", ")}`);
+            merged[key] = projects;
+        }
+        else if (merged[key] === undefined) {
+            merged[key] = value;
+            changes.push(`worktrees.${key}: ${JSON.stringify(value)}`);
+        }
+    }
+    return merged;
+}
+/**
+ * Applies a recipe to the repo's raw config: adds its missing steps and keys, and keeps
+ * every key the repo already set.
+ * @param raw - The repo's config, as JSON.
+ * @param recipe - The recipe.
+ * @param prefix - The repo's Docker project prefix, for `{project}`.
+ * @returns The new config and what changed, one line each.
+ * @example applyRecipe({}, npmRecipe, "acme").changes // ['worktrees.setup: added "deps"']
+ */
+export function applyRecipe(raw, recipe, prefix) {
+    const config = JSON.parse(JSON.stringify(recipe.config).split(PROJECT_PLACEHOLDER).join(prefix));
+    const next = { ...raw };
+    const changes = [];
+    for (const [key, value] of Object.entries(config)) {
+        if (key === "worktrees" && isObject(value))
+            next.worktrees = mergeWorktrees(next.worktrees, value, changes);
+        else if (next[key] === undefined) {
+            next[key] = value;
+            changes.push(`${key}: ${JSON.stringify(value)}`);
+        }
+        else if (JSON.stringify(next[key]) !== JSON.stringify(value))
+            changes.push(`kept ${key} ${JSON.stringify(next[key])} (the recipe says ${JSON.stringify(value)})`);
+    }
+    return { raw: next, changes };
+}

package/dist/session-lock.d.ts

@@ -0,0 +1,32 @@
+/** Start of the lock reason. */
+export declare const LOCK_REASON = "claude session issue-flow";
+/** How the lock went. */
+export interface Lock {
+    mine: boolean;
+    shared: boolean;
+}
+/**
+ * Whether a lock is from an `issue-flow` whose process is gone (a `kill -9`).
+ * @param reason - The lock reason.
+ * @returns True if it is stale.
+ * @example isStale("claude session issue-flow 99999999") // true
+ */
+export declare function isStale(reason: string): boolean;
+/**
+ * Locks the worktree. A stale lock of `issue-flow` is taken over; any other lock is left
+ * alone, and then the session counts as shared, so nothing offers to delete the worktree.
+ * @param mainRoot - The main checkout.
+ * @param workDir - The worktree.
+ * @param say - Where to say what happened.
+ * @returns Whether this process holds the lock and whether another session does.
+ * @example lockWorktree(root, wt, console.error)
+ */
+export declare function lockWorktree(mainRoot: string, workDir: string, say: (text: string) => void): Lock;
+/**
+ * Unlocks the worktree if this process locked it.
+ * @param mainRoot - The main checkout.
+ * @param workDir - The worktree.
+ * @param lock - The lock.
+ * @example unlockWorktree(root, wt, lock)
+ */
+export declare function unlockWorktree(mainRoot: string, workDir: string, lock: Lock): void;

package/dist/session-lock.js

@@ -0,0 +1,69 @@
+/**
+ * @file Locks the worktree while Claude runs (`git worktree lock`), so cleaning worktrees
+ * from another terminal does not delete one in use. The reason starts like the one of
+ * `claude --worktree`, so tools that respect it respect this one too, and ends with the
+ * pid: a lock left by a process that died is taken over. Ported from `lock_worktree` in
+ * Abastio's `scripts/start-issue.sh`.
+ */
+import { git, worktreeLock } from "./git.js";
+/** Start of the lock reason. */
+export const LOCK_REASON = "claude session issue-flow";
+/**
+ * Whether a process is alive.
+ * @param pid - The pid.
+ * @returns True if it is (or it cannot be told: another user's).
+ */
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/**
+ * Whether a lock is from an `issue-flow` whose process is gone (a `kill -9`).
+ * @param reason - The lock reason.
+ * @returns True if it is stale.
+ * @example isStale("claude session issue-flow 99999999") // true
+ */
+export function isStale(reason) {
+    if (!reason.startsWith(`${LOCK_REASON} `))
+        return false;
+    const pid = reason.slice(LOCK_REASON.length + 1);
+    return /^\d+$/.test(pid) && !alive(Number(pid));
+}
+/**
+ * Locks the worktree. A stale lock of `issue-flow` is taken over; any other lock is left
+ * alone, and then the session counts as shared, so nothing offers to delete the worktree.
+ * @param mainRoot - The main checkout.
+ * @param workDir - The worktree.
+ * @param say - Where to say what happened.
+ * @returns Whether this process holds the lock and whether another session does.
+ * @example lockWorktree(root, wt, console.error)
+ */
+export function lockWorktree(mainRoot, workDir, say) {
+    const reason = worktreeLock(mainRoot, workDir);
+    if (reason !== null && isStale(reason)) {
+        say(`Taking over the lock of a session that is gone (${reason}).`);
+        git(mainRoot, ["worktree", "unlock", workDir]);
+    }
+    if (git(mainRoot, ["worktree", "lock", "--reason", `${LOCK_REASON} ${process.pid}`, workDir]).ok)
+        return { mine: true, shared: false };
+    say("the worktree is already locked (is another session open?); going on without locking it.");
+    return { mine: false, shared: true };
+}
+/**
+ * Unlocks the worktree if this process locked it.
+ * @param mainRoot - The main checkout.
+ * @param workDir - The worktree.
+ * @param lock - The lock.
+ * @example unlockWorktree(root, wt, lock)
+ */
+export function unlockWorktree(mainRoot, workDir, lock) {
+    if (!lock.mine)
+        return;
+    git(mainRoot, ["worktree", "unlock", workDir]);
+    lock.mine = false;
+}