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

package/dist/config.js

@@ -0,0 +1,230 @@
+/**
+ * @file The repo's config, `.agents/flow.json`. Every key is optional: without the file,
+ * or with a key missing, the default applies. An unknown key or a value of the wrong kind
+ * is an error that names the key, so a typo never silently falls back to the default.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { locateRepo } from "./git.js";
+import { CONFIG_PATH, ConfigError, isObject, onlyKeys, text } from "./config-base.js";
+import { worktreesSection } from "./worktree-config.js";
+/** The defaults, the same rules Abastio uses. */
+export const DEFAULT_CONFIG = {
+    repo: null,
+    baseBranch: null,
+    branch: {
+        template: "{type}/{number}-{slug}",
+        namer: "claude",
+        claudeModel: "haiku",
+        types: {
+            labels: {
+                bug: "fix",
+                enhancement: "feat",
+                documentation: "docs",
+                spike: "spike",
+            },
+            titlePrefixes: {
+                "bug:": "fix",
+                "mejora:": "feat",
+                "docs:": "docs",
+                "spike:": "spike",
+            },
+        },
+    },
+    worktrees: { dir: ".claude/worktrees", setup: [], teardown: [], ports: null, dockerProjects: [] },
+    start: {
+        commitMessage: "chore: empieza el trabajo en la issue #{number} [skip ci]",
+        prBody: "{keyword} #{number}\n\nEn progreso.",
+        prompt: "Issue #{number}. Lee la issue con `npx @ramon-sg/github-rest issue view {number}`, resúmela en lenguaje llano y sigue la skill start-issue para elegir el flujo.",
+        resumePrompt: "Issue #{number}. Lee la issue con `npx @ramon-sg/github-rest issue view {number}`, resúmela en lenguaje llano y retoma el trabajo según {plan}: revisa qué tareas quedan.",
+        summaryPrompt: "Issue #{number}. Lee la issue con `npx @ramon-sg/github-rest issue view {number}` y resúmela en lenguaje llano. No empieces a trabajar ni a planificar: espera mi pedido.",
+        summaryPlanPrompt: "Issue #{number}. Lee la issue con `npx @ramon-sg/github-rest issue view {number}` y resúmela en lenguaje llano. Tiene un plan abierto en {plan}: di en una línea qué tareas quedan. No empieces a trabajar ni a planificar: espera mi pedido.",
+        cloudPrompt: "/start-issue {number} --yes{flags}",
+    },
+    plans: { dirs: ["docs/plans", "docs/specs"] },
+    colors: {
+        "critical-path": "red",
+        "P1:": "red",
+        "P2:": "orange",
+        "P3:": "yellow",
+        "P4:": "cyan",
+    },
+};
+/** The colors a Claude session takes with `/color`. */
+export const SESSION_COLORS = ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"];
+/** Placeholders the branch template must have. */
+const TEMPLATE_PLACEHOLDERS = ["{number}", "{slug}"];
+/** `owner/repo`. */
+const REPO = /^[^/\s]+\/[^/\s]+$/;
+/** A branch type: lowercase, as it goes in the branch name. */
+const TYPE = /^[a-z0-9][a-z0-9._-]*$/;
+/**
+ * A map of name to branch type (`{"bug": "fix"}`), merged over nothing: when the repo
+ * gives one, it replaces the default whole, so a label can be dropped.
+ * @param value - The value, or undefined.
+ * @param where - Its path, for the error.
+ * @param fallback - The default map.
+ * @returns The map.
+ * @throws ConfigError if it is not an object of valid types.
+ */
+function typeMap(value, where, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!isObject(value))
+        throw new ConfigError(`${CONFIG_PATH}: "${where}" must be an object.`);
+    for (const [key, type] of Object.entries(value)) {
+        if (typeof type !== "string" || !TYPE.test(type))
+            throw new ConfigError(`${CONFIG_PATH}: "${where}.${key}" must be a lowercase branch type such as "feat".`);
+    }
+    return value;
+}
+/**
+ * The `branch` section, with its defaults.
+ * @param value - The section, or undefined.
+ * @returns The section.
+ * @throws ConfigError if something is invalid.
+ */
+function branchSection(value) {
+    const fallback = DEFAULT_CONFIG.branch;
+    if (value === undefined)
+        return fallback;
+    if (!isObject(value))
+        throw new ConfigError(`${CONFIG_PATH}: "branch" must be an object.`);
+    onlyKeys(value, ["template", "namer", "claudeModel", "types"], "branch");
+    const template = text(value.template, "branch.template", fallback.template);
+    const missing = TEMPLATE_PLACEHOLDERS.filter((part) => !template.includes(part));
+    if (missing.length > 0)
+        throw new ConfigError(`${CONFIG_PATH}: "branch.template" needs ${missing.join(" and ")}.`);
+    const namer = value.namer ?? fallback.namer;
+    if (namer !== "claude" && namer !== "title")
+        throw new ConfigError(`${CONFIG_PATH}: "branch.namer" must be "claude" or "title".`);
+    const types = value.types;
+    if (types !== undefined && !isObject(types))
+        throw new ConfigError(`${CONFIG_PATH}: "branch.types" must be an object.`);
+    if (types !== undefined)
+        onlyKeys(types, ["labels", "titlePrefixes"], "branch.types");
+    return {
+        template,
+        namer,
+        claudeModel: text(value.claudeModel, "branch.claudeModel", fallback.claudeModel),
+        types: {
+            labels: typeMap(types?.labels, "branch.types.labels", fallback.types.labels),
+            titlePrefixes: typeMap(types?.titlePrefixes, "branch.types.titlePrefixes", fallback.types.titlePrefixes),
+        },
+    };
+}
+/**
+ * A section made only of optional strings (`start`).
+ * @param value - The section, or undefined.
+ * @param name - Its key.
+ * @param fallback - Its defaults.
+ * @returns The section.
+ * @throws ConfigError if something is invalid.
+ */
+function textSection(value, name, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!isObject(value))
+        throw new ConfigError(`${CONFIG_PATH}: "${name}" must be an object.`);
+    onlyKeys(value, Object.keys(fallback), name);
+    const out = {};
+    for (const [key, standard] of Object.entries(fallback))
+        out[key] = text(value[key], `${name}.${key}`, standard);
+    return out;
+}
+/**
+ * The `plans` section: the folders where an issue's plan is looked for, in order of
+ * preference.
+ * @param value - The section, or undefined.
+ * @returns The section.
+ * @throws ConfigError if something is invalid.
+ */
+function plansSection(value) {
+    if (value === undefined)
+        return DEFAULT_CONFIG.plans;
+    if (!isObject(value))
+        throw new ConfigError(`${CONFIG_PATH}: "plans" must be an object.`);
+    onlyKeys(value, ["dirs"], "plans");
+    const dirs = value.dirs ?? DEFAULT_CONFIG.plans.dirs;
+    const valid = Array.isArray(dirs) &&
+        dirs.length > 0 &&
+        dirs.every((dir) => typeof dir === "string" && dir.trim() !== "" && !dir.startsWith("/"));
+    if (!valid)
+        throw new ConfigError(`${CONFIG_PATH}: "plans.dirs" must be a non-empty list of folders relative to the repo.`);
+    return { dirs: dirs.map((dir) => dir.replace(/\/+$/, "")) };
+}
+/**
+ * The `colors` map: label prefix to session color. When the repo gives one, it replaces the
+ * default whole.
+ * @param value - The map, or undefined.
+ * @returns The map.
+ * @throws ConfigError if a color is not one Claude knows.
+ */
+function colorsSection(value) {
+    if (value === undefined)
+        return DEFAULT_CONFIG.colors;
+    if (!isObject(value))
+        throw new ConfigError(`${CONFIG_PATH}: "colors" must be an object.`);
+    for (const [prefix, color] of Object.entries(value)) {
+        if (typeof color !== "string" || !SESSION_COLORS.includes(color))
+            throw new ConfigError(`${CONFIG_PATH}: "colors.${prefix}" must be one of ${SESSION_COLORS.join(", ")}.`);
+    }
+    return value;
+}
+/**
+ * Validates a parsed config and fills in the defaults.
+ * @param raw - The parsed JSON.
+ * @returns The config.
+ * @throws ConfigError if something is invalid.
+ * @example parseConfig({ branch: { namer: "title" } }).branch.template // "{type}/{number}-{slug}"
+ */
+export function parseConfig(raw) {
+    if (!isObject(raw))
+        throw new ConfigError(`${CONFIG_PATH} must be a JSON object.`);
+    onlyKeys(raw, ["repo", "baseBranch", "branch", "worktrees", "start", "plans", "colors"], "");
+    const repo = text(raw.repo, "repo", null);
+    if (repo !== null && !REPO.test(repo))
+        throw new ConfigError(`${CONFIG_PATH}: "repo" must be owner/repo.`);
+    return {
+        repo,
+        baseBranch: text(raw.baseBranch, "baseBranch", null),
+        branch: branchSection(raw.branch),
+        worktrees: worktreesSection(raw.worktrees, DEFAULT_CONFIG.worktrees),
+        start: textSection(raw.start, "start", DEFAULT_CONFIG.start),
+        plans: plansSection(raw.plans),
+        colors: colorsSection(raw.colors),
+    };
+}
+/**
+ * The main checkout of the repo that holds a directory, or null outside git. The config
+ * is always the main checkout's, also from a worktree: a branch cannot change the steps
+ * its own worktree runs.
+ * @param cwd - The directory.
+ * @returns The root.
+ * @example repoRoot("/repo/.claude/worktrees/feat+42-x") // "/repo"
+ */
+export function repoRoot(cwd) {
+    return locateRepo(cwd)?.mainRoot ?? null;
+}
+/**
+ * Reads the config of the main checkout of the repo that holds `cwd`. Outside git, or
+ * without the file, every default applies.
+ * @param cwd - A directory inside the checkout.
+ * @returns The config.
+ * @throws ConfigError if the file is not valid JSON or something in it is invalid.
+ * @example loadConfig(process.cwd()).branch.namer // "claude"
+ */
+export function loadConfig(cwd) {
+    const root = repoRoot(cwd);
+    const file = root === null ? null : join(root, CONFIG_PATH);
+    if (file === null || !existsSync(file))
+        return DEFAULT_CONFIG;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new ConfigError(`${CONFIG_PATH} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return parseConfig(raw);
+}

package/dist/docker.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A DNS label, like portless makes them: lowercase, `[a-z0-9-]`, no repeated dashes nor at
+ * the edges, and over 63 characters cut with a hash of 6.
+ * @param value - The text.
+ * @returns The label.
+ * @example sanitizeLabel("feat+214_Odoo") // "feat-214-odoo"
+ */
+export declare function sanitizeLabel(value: string): string;
+/**
+ * The Compose project of a worktree: the prefix, the folder's name and a hash of its path,
+ * so two clones with a worktree of the same name never share containers.
+ * @param prefix - The project prefix (`abastio-dev`).
+ * @param root - The worktree.
+ * @returns The project name.
+ * @example dockerProject("acme-dev", "/repo/.claude/worktrees/feat+42-x") // "acme-dev-feat-42-x-1a2b3c"
+ */
+export declare function dockerProject(prefix: string, root: string): string;
+/**
+ * A path to compare with a container's folder: no trailing slash, and its parent resolved
+ * (symlinks too) even if the path itself is gone, as a just-deleted worktree is.
+ * @param path - The path.
+ * @returns The path.
+ * @example canonicalPath("/tmp/x/") // "/private/tmp/x"
+ */
+export declare function canonicalPath(path: string): string;
+/**
+ * Whether a project's folder still belongs to a checkout. Compose's folder is the compose
+ * file's, maybe a subfolder (`infra/`), so being inside a checkout is enough, as long as the
+ * folder has something: a deleted worktree inside the main checkout leaves its folder
+ * empty, and that one finds the main repo.
+ * @param dir - The project's folder.
+ * @returns True if it is alive.
+ * @example projectAlive("/repo/.claude/worktrees/feat+42-x/infra")
+ */
+export declare function projectAlive(dir: string): boolean;
+/** What the cleanup did. */
+export interface CleanupResult {
+    dockerRunning: boolean;
+    removed: string[];
+    failed: string[];
+}
+/**
+ * Deletes the Docker of worktrees that no longer exist: projects with one of the prefixes
+ * and a suffix, whose folder no longer belongs to a checkout. With a path, the
+ * projects of that folder, whether it exists or not, including the volumes and networks
+ * left without containers (their names come from the path). `docker ps -a`, so a deleted
+ * worktree with stopped containers counts too.
+ * @param prefixes - The project prefixes of the config.
+ * @param path - Only this worktree's, or null for every orphan.
+ * @returns What was deleted, what failed, and whether Docker runs at all.
+ * @example dockerCleanup(["acme-dev"], null)
+ */
+export declare function dockerCleanup(prefixes: string[], path: string | null): CleanupResult;

package/dist/docker.js

@@ -0,0 +1,153 @@
+/**
+ * @file The Docker of worktrees: the Compose project name of each one, and the cleanup of
+ * the containers, volumes and networks of worktrees that no longer exist. There is no
+ * registry of its own: each Compose container carries its project and its folder
+ * (`com.docker.compose.project.working_dir`), and a project whose folder is no longer the
+ * root of a checkout is an orphan. Only projects with a prefix of the config are ever
+ * deleted, and never one without a suffix (the main checkout's). Ported from
+ * `wt_project_name` in Abastio's `scripts/lib/worktree.sh` and its
+ * `scripts/worktree-cleanup.sh`; the names come out the same, so its existing projects
+ * are found.
+ */
+import { spawnSync } from "node:child_process";
+import { basename, dirname, join } from "node:path";
+import { existsSync, readdirSync, realpathSync } from "node:fs";
+import { checkoutRoot } from "./git.js";
+import { sha256 } from "./ports.js";
+/** Longest DNS label, as portless cuts them (the names were born with portless). */
+const MAX_LABEL = 63;
+/** Hex digits of the hashes in names. */
+const HASH_LENGTH = 6;
+/** How long `docker info` may take: a hung Docker cannot hold a hook up. */
+const DOCKER_INFO_TIMEOUT_MS = 20_000;
+/** Compose's label with the project. */
+const PROJECT_LABEL = "com.docker.compose.project";
+/**
+ * A DNS label, like portless makes them: lowercase, `[a-z0-9-]`, no repeated dashes nor at
+ * the edges, and over 63 characters cut with a hash of 6.
+ * @param value - The text.
+ * @returns The label.
+ * @example sanitizeLabel("feat+214_Odoo") // "feat-214-odoo"
+ */
+export function sanitizeLabel(value) {
+    const clean = value.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+    if (clean.length <= MAX_LABEL)
+        return clean;
+    const trimmed = clean.slice(0, MAX_LABEL - HASH_LENGTH - 1).replace(/-+$/, "");
+    return `${trimmed}-${sha256(clean).slice(0, HASH_LENGTH)}`;
+}
+/**
+ * The Compose project of a worktree: the prefix, the folder's name and a hash of its path,
+ * so two clones with a worktree of the same name never share containers.
+ * @param prefix - The project prefix (`abastio-dev`).
+ * @param root - The worktree.
+ * @returns The project name.
+ * @example dockerProject("acme-dev", "/repo/.claude/worktrees/feat+42-x") // "acme-dev-feat-42-x-1a2b3c"
+ */
+export function dockerProject(prefix, root) {
+    return `${prefix}-${sanitizeLabel(basename(root))}-${sha256(root).slice(0, HASH_LENGTH)}`;
+}
+/**
+ * A path to compare with a container's folder: no trailing slash, and its parent resolved
+ * (symlinks too) even if the path itself is gone, as a just-deleted worktree is.
+ * @param path - The path.
+ * @returns The path.
+ * @example canonicalPath("/tmp/x/") // "/private/tmp/x"
+ */
+export function canonicalPath(path) {
+    const clean = path.replace(/\/+$/, "") || "/";
+    try {
+        return join(realpathSync(dirname(clean)), basename(clean));
+    }
+    catch {
+        return clean;
+    }
+}
+/**
+ * Runs docker and returns its output, or null if it failed.
+ * @param args - The arguments.
+ * @param timeout - Milliseconds before giving up, or undefined.
+ * @returns The output, trimmed.
+ */
+function docker(args, timeout) {
+    const result = spawnSync("docker", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...(timeout === undefined ? {} : { timeout }) });
+    return result.status === 0 ? result.stdout.trim() : null;
+}
+/**
+ * Deletes a project's containers, volumes and networks. It tries all three even if one
+ * fails (a container Docker cannot kill yet).
+ * @param project - The project.
+ * @returns Whether it had nothing, was deleted, or something failed.
+ */
+function removeProject(project) {
+    const filter = ["--filter", `label=${PROJECT_LABEL}=${project}`];
+    let ok = true;
+    let found = false;
+    for (const [list, remove] of [
+        [["ps", "-aq"], ["rm", "-f"]],
+        [["volume", "ls", "-q"], ["volume", "rm"]],
+        [["network", "ls", "-q"], ["network", "rm"]],
+    ]) {
+        const ids = docker([...list, ...filter]);
+        if (ids === null)
+            ok = false;
+        if (ids === null || ids === "")
+            continue;
+        found = true;
+        if (docker([...remove, ...ids.split("\n")]) === null)
+            ok = false;
+    }
+    if (!ok)
+        return "failed";
+    return found ? "removed" : "none";
+}
+/**
+ * Whether a project's folder still belongs to a checkout. Compose's folder is the compose
+ * file's, maybe a subfolder (`infra/`), so being inside a checkout is enough, as long as the
+ * folder has something: a deleted worktree inside the main checkout leaves its folder
+ * empty, and that one finds the main repo.
+ * @param dir - The project's folder.
+ * @returns True if it is alive.
+ * @example projectAlive("/repo/.claude/worktrees/feat+42-x/infra")
+ */
+export function projectAlive(dir) {
+    return dir !== "" && existsSync(dir) && readdirSync(dir).length > 0 && checkoutRoot(dir) !== null;
+}
+/**
+ * Deletes the Docker of worktrees that no longer exist: projects with one of the prefixes
+ * and a suffix, whose folder no longer belongs to a checkout. With a path, the
+ * projects of that folder, whether it exists or not, including the volumes and networks
+ * left without containers (their names come from the path). `docker ps -a`, so a deleted
+ * worktree with stopped containers counts too.
+ * @param prefixes - The project prefixes of the config.
+ * @param path - Only this worktree's, or null for every orphan.
+ * @returns What was deleted, what failed, and whether Docker runs at all.
+ * @example dockerCleanup(["acme-dev"], null)
+ */
+export function dockerCleanup(prefixes, path) {
+    const result = { dockerRunning: false, removed: [], failed: [] };
+    if (prefixes.length === 0)
+        return { ...result, dockerRunning: true };
+    if (docker(["info"], DOCKER_INFO_TIMEOUT_MS) === null)
+        return result;
+    result.dockerRunning = true;
+    const forced = path === null ? null : canonicalPath(path);
+    const listed = docker(["ps", "-a", "--filter", `label=${PROJECT_LABEL}`, "--format", `{{.Label "${PROJECT_LABEL}"}}\t{{.Label "${PROJECT_LABEL}.working_dir"}}`]) ?? "";
+    const projects = new Set();
+    for (const line of listed.split("\n")) {
+        const [project = "", dir = ""] = line.split("\t");
+        if (!prefixes.some((prefix) => project.startsWith(`${prefix}-`)))
+            continue;
+        if (forced !== null ? canonicalPath(dir) === forced : !projectAlive(dir))
+            projects.add(project);
+    }
+    if (forced !== null)
+        for (const prefix of prefixes)
+            projects.add(dockerProject(prefix, forced));
+    for (const project of projects) {
+        const outcome = removeProject(project);
+        if (outcome !== "none")
+            result[outcome].push(project);
+    }
+    return result;
+}

package/dist/git.d.ts

@@ -0,0 +1,130 @@
+/** What a git command gave. */
+export interface GitResult {
+    ok: boolean;
+    out: string;
+    err: string;
+}
+/**
+ * Runs git and returns whether it worked, with its output trimmed at the end.
+ * @param cwd - Where to run it.
+ * @param args - The arguments.
+ * @returns The result.
+ * @example git("/repo", ["rev-parse", "HEAD"]).out
+ */
+export declare function git(cwd: string, args: string[]): GitResult;
+/**
+ * The non-empty lines of a git command's output (none if it failed).
+ * @param cwd - Where to run it.
+ * @param args - The arguments.
+ * @returns The lines.
+ * @example gitLines("/repo", ["branch", "--format=%(refname:short)"])
+ */
+export declare function gitLines(cwd: string, args: string[]): string[];
+/**
+ * Whether a ref exists.
+ * @param cwd - The checkout.
+ * @param ref - The full ref (`refs/heads/x`).
+ * @returns True if it does.
+ * @example hasRef("/repo", "refs/heads/main")
+ */
+export declare function hasRef(cwd: string, ref: string): boolean;
+/**
+ * Whether the branch exists locally.
+ * @param cwd - The checkout.
+ * @param branch - The branch.
+ * @returns True if it does.
+ * @example hasLocal("/repo", "feat/42-x")
+ */
+export declare const hasLocal: (cwd: string, branch: string) => boolean;
+/**
+ * Whether the branch exists in origin, as of the last fetch.
+ * @param cwd - The checkout.
+ * @param branch - The branch.
+ * @returns True if it does.
+ * @example onOrigin("/repo", "feat/42-x")
+ */
+export declare const onOrigin: (cwd: string, branch: string) => boolean;
+/**
+ * Commits of the branch (local, or else in origin) that are not in `origin/<base>`.
+ * @param cwd - The checkout.
+ * @param branch - The branch.
+ * @param base - The base branch.
+ * @returns How many, 0 if the branch does not exist.
+ * @example ownCommits("/repo", "feat/42-x", "main") // 0
+ */
+export declare function ownCommits(cwd: string, branch: string, base: string): number;
+/** A worktree as `git worktree list --porcelain` gives it. */
+export interface WorktreeEntry {
+    path: string;
+    branch: string | null;
+    lock: string | null;
+}
+/**
+ * The worktrees of the repo, the main checkout first.
+ * @param cwd - Any checkout of the repo.
+ * @returns Path, branch and lock reason of each.
+ * @example worktrees("/repo")[0].path // "/repo"
+ */
+export declare function worktrees(cwd: string): WorktreeEntry[];
+/**
+ * Where the branch is checked out: the main checkout or a worktree.
+ * @param cwd - Any checkout of the repo.
+ * @param branch - The branch.
+ * @returns The path, or null if it is not checked out.
+ * @example checkedOutAt("/repo", "feat/42-x")
+ */
+export declare function checkedOutAt(cwd: string, branch: string): string | null;
+/**
+ * Why the worktree is locked.
+ * @param cwd - Any checkout of the repo.
+ * @param path - The worktree.
+ * @returns The reason (empty if it has none), or null if it is not locked.
+ * @example worktreeLock("/repo", "/repo/.claude/worktrees/feat+42-x")
+ */
+export declare function worktreeLock(cwd: string, path: string): string | null;
+/**
+ * Whether the checkout has no changes. Untracked files count unless told otherwise.
+ * @param cwd - The checkout.
+ * @param untracked - Whether untracked files count.
+ * @returns True if it is clean.
+ * @example isClean("/repo")
+ */
+export declare function isClean(cwd: string, untracked?: boolean): boolean;
+/**
+ * The branch the checkout is on.
+ * @param cwd - The checkout.
+ * @returns The branch, or null on a detached HEAD.
+ * @example currentBranch("/repo") // "main"
+ */
+export declare function currentBranch(cwd: string): string | null;
+/**
+ * Where a directory's repo lives: its shared `.git` and the main checkout, the same from
+ * any worktree. The main checkout is the first one git lists, which also holds in a
+ * submodule or with `--separate-git-dir`, where the shared `.git` is not inside it.
+ * @param cwd - A directory inside the repo.
+ * @returns The common git dir and the main checkout, or null outside git.
+ * @example locateRepo(process.cwd())?.mainRoot
+ */
+export declare function locateRepo(cwd: string): {
+    commonDir: string;
+    mainRoot: string;
+} | null;
+/**
+ * The root of the checkout a directory is in (the main one or a worktree), with its
+ * symlinks resolved like the other paths here.
+ * @param cwd - A directory inside the checkout.
+ * @returns The root, or null outside git.
+ * @example checkoutRoot("/repo/.claude/worktrees/feat+42-x/src") // "/repo/.claude/worktrees/feat+42-x"
+ */
+export declare function checkoutRoot(cwd: string): string | null;
+/**
+ * Whether deleting the branch loses no work: all its commits are in some branch of
+ * origin, or it does not go past the PR's head (the branch already deleted on GitHub, or
+ * a squash merge).
+ * @param cwd - The checkout.
+ * @param branch - The branch.
+ * @param head - The merged PR's head.
+ * @returns True if it is safe.
+ * @example safeToDelete("/repo", "feat/42-x", "")
+ */
+export declare function safeToDelete(cwd: string, branch: string, head: string): boolean;