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

package/dist/git.js

@@ -0,0 +1,192 @@
+/**
+ * @file Small git queries over `spawnSync`, for starting an issue: refs, commits that are
+ * not in the base, where a branch is checked out and worktree locks.
+ */
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * 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 function git(cwd, args) {
+    const run = spawnSync("git", args, { cwd, encoding: "utf8" });
+    return {
+        ok: run.status === 0,
+        out: (run.stdout ?? "").trimEnd(),
+        err: (run.stderr ?? "").trim(),
+    };
+}
+/**
+ * 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 function gitLines(cwd, args) {
+    const result = git(cwd, args);
+    return result.ok ? result.out.split("\n").filter((line) => line !== "") : [];
+}
+/**
+ * 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 function hasRef(cwd, ref) {
+    return git(cwd, ["rev-parse", "-q", "--verify", ref]).ok;
+}
+/**
+ * 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 const hasLocal = (cwd, branch) => hasRef(cwd, `refs/heads/${branch}`);
+/**
+ * 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 const onOrigin = (cwd, branch) => hasRef(cwd, `refs/remotes/origin/${branch}`);
+/**
+ * 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 function ownCommits(cwd, branch, base) {
+    const ref = hasLocal(cwd, branch) ? branch : `origin/${branch}`;
+    const result = git(cwd, ["rev-list", "--count", `origin/${base}..${ref}`]);
+    return result.ok ? Number(result.out) : 0;
+}
+/**
+ * A path with its symlinks resolved, so paths from git and from the system compare
+ * equal (on macOS `/var` is `/private/var`).
+ * @param path - The path.
+ * @returns The real path, or the path itself if it does not exist.
+ */
+function real(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * 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 function worktrees(cwd) {
+    const found = [];
+    for (const line of git(cwd, ["worktree", "list", "--porcelain"]).out.split("\n")) {
+        if (line.startsWith("worktree "))
+            found.push({ path: real(line.slice(9)), branch: null, lock: null });
+        const current = found.at(-1);
+        if (current === undefined)
+            continue;
+        if (line.startsWith("branch refs/heads/"))
+            current.branch = line.slice(18);
+        if (line === "locked")
+            current.lock = "";
+        if (line.startsWith("locked "))
+            current.lock = line.slice(7);
+    }
+    return found;
+}
+/**
+ * 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 function checkedOutAt(cwd, branch) {
+    return worktrees(cwd).find((entry) => entry.branch === branch)?.path ?? 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 function worktreeLock(cwd, path) {
+    return worktrees(cwd).find((entry) => entry.path === real(path))?.lock ?? 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 function isClean(cwd, untracked = true) {
+    const args = ["status", "--porcelain", ...(untracked ? [] : ["--untracked-files=no"])];
+    const result = git(cwd, args);
+    return result.ok && result.out === "";
+}
+/**
+ * The branch the checkout is on.
+ * @param cwd - The checkout.
+ * @returns The branch, or null on a detached HEAD.
+ * @example currentBranch("/repo") // "main"
+ */
+export function currentBranch(cwd) {
+    const result = git(cwd, ["symbolic-ref", "-q", "--short", "HEAD"]);
+    return result.ok ? result.out : 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 function locateRepo(cwd) {
+    const result = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+    if (!result.ok)
+        return null;
+    const commonDir = real(result.out);
+    return { commonDir, mainRoot: worktrees(cwd)[0]?.path ?? dirname(commonDir) };
+}
+/**
+ * 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 function checkoutRoot(cwd) {
+    const result = git(cwd, ["rev-parse", "--show-toplevel"]);
+    return result.ok ? real(result.out) : 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 function safeToDelete(cwd, branch, head) {
+    if (git(cwd, ["rev-list", "--count", branch, "--not", "--remotes=origin"]).out === "0")
+        return true;
+    return head !== "" && git(cwd, ["merge-base", "--is-ancestor", branch, head]).ok;
+}

package/dist/issue-text.d.ts

@@ -0,0 +1,128 @@
+/** Lines of the issue's header shown before confirming. */
+export declare const HEADER_MAX_LINES = 6;
+/** Width the header is wrapped to. */
+export declare const HEADER_WIDTH = 80;
+/** Prefix of the session's name when it works in a worktree. */
+export declare const WORKTREE_SESSION_PREFIX = "w-";
+/**
+ * Where the work happens: a worktree of its own, the main checkout, the checkout where it
+ * runs inside a cloud session (`--here`), or a cloud session it opens (`--cloud`).
+ */
+export type StartMode = "worktree" | "branch" | "here" | "cloud";
+/** Label of the PR body's line with the link of its cloud session. */
+export declare const CLOUD_SESSION_LABEL = "Cloud session:";
+/** Whether the PR closes the issue, or is only part of it (the issue has another branch). */
+export type PrKind = "closes" | "part";
+/**
+ * The issue's header for the summary: its first paragraph, before any branch block,
+ * wrapped and cut to `HEADER_MAX_LINES` lines.
+ * @param body - The issue body.
+ * @returns The lines, maybe none.
+ * @example issueHeader("Qué se pide.\n\nDetalle.") // ["Qué se pide."]
+ */
+export declare function issueHeader(body: string): string[];
+/**
+ * The session's color and the label that gives it: the first entry of the config's map
+ * whose key starts some label, in the map's order (so `critical-path` can win over `P3:`).
+ * @param labels - The issue's labels.
+ * @param colors - Label prefix to color.
+ * @returns The label and color, or null if no label matches.
+ * @example issueColor(["P1: urgent"], { "P1:": "red" }) // { label: "P1: urgent", color: "red" }
+ */
+export declare function issueColor(labels: string[], colors: Record<string, string>): {
+    label: string;
+    color: string;
+} | null;
+/**
+ * The Claude session's name: the branch, with `w-` in front in a worktree.
+ * @param branch - The branch.
+ * @param mode - Where the work happens.
+ * @returns The name.
+ * @example sessionName("feat/42-x", "worktree") // "w-feat/42-x"
+ */
+export declare function sessionName(branch: string, mode: StartMode): string;
+/**
+ * The folder name of a branch's worktree and session file: the branch with every `/` as
+ * `+`, like `claude --worktree`, so it is one folder.
+ * @param branch - The branch.
+ * @returns The name.
+ * @example dirName("feat/42-x") // "feat+42-x"
+ */
+export declare function dirName(branch: string): string;
+/**
+ * The branch for a new round of the issue: the proposed one if the issue never used it,
+ * or with `-2`, `-3`… until one is free.
+ * @param proposed - The proposed branch.
+ * @param used - Every branch the issue already used.
+ * @returns The branch.
+ * @example nextBranch("feat/42-x", ["feat/42-x"]) // "feat/42-x-2"
+ */
+export declare function nextBranch(proposed: string, used: string[]): string;
+/**
+ * Fills `{name}` placeholders in one pass, so a value that holds `{plan}` is not filled
+ * again. Unknown placeholders are left as they are.
+ * @param template - The text.
+ * @param values - The values.
+ * @returns The text.
+ * @example fill("#{number}", { number: "4" }) // "#4"
+ */
+export declare function fill(template: string, values: Record<string, string>): string;
+/**
+ * The draft PR's body from the config's template.
+ * @param template - The template, with `{keyword}` and `{number}`.
+ * @param number - The issue.
+ * @param kind - Whether the PR closes the issue or is part of it.
+ * @returns The body.
+ * @example prBody("{keyword} #{number}", 4, "part") // "Part of #4"
+ */
+export declare function prBody(template: string, number: number, kind: PrKind): string;
+/**
+ * The body of a PR with the words that close the issue (`Closes`, `Fixes`, `Resolves` and
+ * their forms, with or without `:`) changed to `Part of`, because the issue now has more
+ * than one branch. Other numbers that start the same (`#2140`) are left alone.
+ * @param body - The PR body.
+ * @param number - The issue.
+ * @returns The new body.
+ * @example bodyToPartOf("Closes #4\n\nx", 4) // "Part of #4\n\nx"
+ */
+export declare function bodyToPartOf(body: string, number: number): string;
+/**
+ * The claude.ai link of a cloud session. The link uses `session_` even when the id comes
+ * as `cse_`.
+ * @param id - The id.
+ * @returns The link.
+ * @example cloudSessionUrl("cse_01A") // "https://claude.ai/code/session_01A"
+ */
+export declare function cloudSessionUrl(id: string): string;
+/**
+ * Whether two ids are the same cloud session (`cse_…` and `session_…` lead to one link).
+ * @param one - An id, or null.
+ * @param other - The other id.
+ * @returns True if they are.
+ * @example sameCloudSession("cse_01A", "session_01A") // true
+ */
+export declare function sameCloudSession(one: string | null, other: string): boolean;
+/**
+ * The cloud session noted in a PR body, so `--teleport` finds it from any machine.
+ * @param body - The PR body.
+ * @returns The id, or null.
+ * @example cloudSessionOf("Closes #4\n\nCloud session: https://claude.ai/code/session_01A") // "session_01A"
+ */
+export declare function cloudSessionOf(body: string): string | null;
+/**
+ * The PR body with the line of a cloud session: it replaces the line of an earlier
+ * session (one line stays, the last session that took the issue) or goes at the end.
+ * @param body - The PR body.
+ * @param id - The session.
+ * @returns The new body.
+ * @example withCloudSession("Closes #4", "cse_01A") // "Closes #4\n\nCloud session: https://claude.ai/code/session_01A"
+ */
+export declare function withCloudSession(body: string, id: string): string;
+/**
+ * The issue a branch belongs to, by its `<n>-` at the start or after a `/` (`feat/214-x`,
+ * `214-x`, `ramon/sub/214-x`).
+ * @param branch - The branch.
+ * @returns The number, or null.
+ * @example issueOfBranch("feat/214-x") // 214
+ */
+export declare function issueOfBranch(branch: string): number | null;

package/dist/issue-text.js

@@ -0,0 +1,210 @@
+/**
+ * @file Text about an issue for starting it, with no git, GitHub nor Claude: its header for
+ * the summary, the session's color and name, the next free branch, the PR body and the
+ * prompt Claude opens with. Ported from Abastio's `scripts/lib/issue.sh`.
+ */
+import { BRANCH_HEADING, SLUG_HEADING } from "./branch-name.js";
+/** Lines of the issue's header shown before confirming. */
+export const HEADER_MAX_LINES = 6;
+/** Width the header is wrapped to. */
+export const HEADER_WIDTH = 80;
+/** Prefix of the session's name when it works in a worktree. */
+export const WORKTREE_SESSION_PREFIX = "w-";
+/** Label of the PR body's line with the link of its cloud session. */
+export const CLOUD_SESSION_LABEL = "Cloud session:";
+/** Labels of that line that are still read (Abastio's), never written. */
+const LEGACY_CLOUD_SESSION_LABELS = ["Sesión en la nube:"];
+/** A cloud session id: `session_…`, or `cse_…` as the session sees itself. */
+const CLOUD_SESSION_ID = /\b(?:session|cse)_[A-Za-z0-9]+/;
+/** The issue number in a branch: `<n>-` at the start or after a `/`. */
+const BRANCH_NUMBER = /(?:^|\/)(\d+)-/;
+/**
+ * Wraps a line at spaces, like `fold -s`.
+ * @param line - The line.
+ * @param width - The width.
+ * @returns The wrapped lines.
+ */
+function wrap(line, width) {
+    const out = [];
+    let current = "";
+    for (const word of line.split(" ")) {
+        const next = current === "" ? word : `${current} ${word}`;
+        if (next.length > width && current !== "") {
+            out.push(current);
+            current = word;
+            continue;
+        }
+        current = next;
+    }
+    out.push(current);
+    return out;
+}
+/**
+ * The issue's header for the summary: its first paragraph, before any branch block,
+ * wrapped and cut to `HEADER_MAX_LINES` lines.
+ * @param body - The issue body.
+ * @returns The lines, maybe none.
+ * @example issueHeader("Qué se pide.\n\nDetalle.") // ["Qué se pide."]
+ */
+export function issueHeader(body) {
+    const lines = [];
+    for (const line of body.replace(/\r/g, "").split("\n")) {
+        if (line.startsWith(SLUG_HEADING) || line.startsWith(BRANCH_HEADING))
+            break;
+        if (line.trim() === "" && lines.length > 0)
+            break;
+        if (line.trim() !== "")
+            lines.push(...wrap(line.trimEnd(), HEADER_WIDTH));
+    }
+    return lines.slice(0, HEADER_MAX_LINES);
+}
+/**
+ * The session's color and the label that gives it: the first entry of the config's map
+ * whose key starts some label, in the map's order (so `critical-path` can win over `P3:`).
+ * @param labels - The issue's labels.
+ * @param colors - Label prefix to color.
+ * @returns The label and color, or null if no label matches.
+ * @example issueColor(["P1: urgent"], { "P1:": "red" }) // { label: "P1: urgent", color: "red" }
+ */
+export function issueColor(labels, colors) {
+    for (const [prefix, color] of Object.entries(colors)) {
+        const label = labels.find((name) => name.startsWith(prefix));
+        if (label !== undefined)
+            return { label, color };
+    }
+    return null;
+}
+/**
+ * The Claude session's name: the branch, with `w-` in front in a worktree.
+ * @param branch - The branch.
+ * @param mode - Where the work happens.
+ * @returns The name.
+ * @example sessionName("feat/42-x", "worktree") // "w-feat/42-x"
+ */
+export function sessionName(branch, mode) {
+    return mode === "worktree" ? `${WORKTREE_SESSION_PREFIX}${branch}` : branch;
+}
+/**
+ * The folder name of a branch's worktree and session file: the branch with every `/` as
+ * `+`, like `claude --worktree`, so it is one folder.
+ * @param branch - The branch.
+ * @returns The name.
+ * @example dirName("feat/42-x") // "feat+42-x"
+ */
+export function dirName(branch) {
+    return branch.replaceAll("/", "+");
+}
+/**
+ * The branch for a new round of the issue: the proposed one if the issue never used it,
+ * or with `-2`, `-3`… until one is free.
+ * @param proposed - The proposed branch.
+ * @param used - Every branch the issue already used.
+ * @returns The branch.
+ * @example nextBranch("feat/42-x", ["feat/42-x"]) // "feat/42-x-2"
+ */
+export function nextBranch(proposed, used) {
+    let candidate = proposed;
+    for (let round = 2; used.includes(candidate); round += 1)
+        candidate = `${proposed}-${round}`;
+    return candidate;
+}
+/**
+ * Fills `{name}` placeholders in one pass, so a value that holds `{plan}` is not filled
+ * again. Unknown placeholders are left as they are.
+ * @param template - The text.
+ * @param values - The values.
+ * @returns The text.
+ * @example fill("#{number}", { number: "4" }) // "#4"
+ */
+export function fill(template, values) {
+    return template.replace(/\{(\w+)\}/g, (whole, name) => values[name] ?? whole);
+}
+/**
+ * The draft PR's body from the config's template.
+ * @param template - The template, with `{keyword}` and `{number}`.
+ * @param number - The issue.
+ * @param kind - Whether the PR closes the issue or is part of it.
+ * @returns The body.
+ * @example prBody("{keyword} #{number}", 4, "part") // "Part of #4"
+ */
+export function prBody(template, number, kind) {
+    return fill(template, { keyword: kind === "part" ? "Part of" : "Closes", number: String(number) });
+}
+/**
+ * The body of a PR with the words that close the issue (`Closes`, `Fixes`, `Resolves` and
+ * their forms, with or without `:`) changed to `Part of`, because the issue now has more
+ * than one branch. Other numbers that start the same (`#2140`) are left alone.
+ * @param body - The PR body.
+ * @param number - The issue.
+ * @returns The new body.
+ * @example bodyToPartOf("Closes #4\n\nx", 4) // "Part of #4\n\nx"
+ */
+export function bodyToPartOf(body, number) {
+    const closing = new RegExp(`(^|[^\\w])(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?):?\\s+#${number}(?!\\d)`, "gi");
+    return body.replace(closing, `$1Part of #${number}`);
+}
+/**
+ * The claude.ai link of a cloud session. The link uses `session_` even when the id comes
+ * as `cse_`.
+ * @param id - The id.
+ * @returns The link.
+ * @example cloudSessionUrl("cse_01A") // "https://claude.ai/code/session_01A"
+ */
+export function cloudSessionUrl(id) {
+    return `https://claude.ai/code/${id.replace(/^cse_/, "session_")}`;
+}
+/**
+ * Whether two ids are the same cloud session (`cse_…` and `session_…` lead to one link).
+ * @param one - An id, or null.
+ * @param other - The other id.
+ * @returns True if they are.
+ * @example sameCloudSession("cse_01A", "session_01A") // true
+ */
+export function sameCloudSession(one, other) {
+    return one !== null && cloudSessionUrl(one) === cloudSessionUrl(other);
+}
+/**
+ * Whether a line of a PR body is the one with the cloud session.
+ * @param text - The line.
+ * @returns True if it is.
+ */
+function isSessionLine(text) {
+    return [CLOUD_SESSION_LABEL, ...LEGACY_CLOUD_SESSION_LABELS].some((label) => text.includes(label));
+}
+/**
+ * The cloud session noted in a PR body, so `--teleport` finds it from any machine.
+ * @param body - The PR body.
+ * @returns The id, or null.
+ * @example cloudSessionOf("Closes #4\n\nCloud session: https://claude.ai/code/session_01A") // "session_01A"
+ */
+export function cloudSessionOf(body) {
+    const found = body.split("\n").find(isSessionLine);
+    return found === undefined ? null : (CLOUD_SESSION_ID.exec(found)?.[0] ?? null);
+}
+/**
+ * The PR body with the line of a cloud session: it replaces the line of an earlier
+ * session (one line stays, the last session that took the issue) or goes at the end.
+ * @param body - The PR body.
+ * @param id - The session.
+ * @returns The new body.
+ * @example withCloudSession("Closes #4", "cse_01A") // "Closes #4\n\nCloud session: https://claude.ai/code/session_01A"
+ */
+export function withCloudSession(body, id) {
+    const note = `${CLOUD_SESSION_LABEL} ${cloudSessionUrl(id)}`;
+    const lines = body.split("\n");
+    const first = lines.findIndex(isSessionLine);
+    if (first === -1)
+        return body === "" ? note : `${body.replace(/\n+$/, "")}\n\n${note}`;
+    return lines.flatMap((text, index) => (index === first ? [note] : isSessionLine(text) ? [] : [text])).join("\n");
+}
+/**
+ * The issue a branch belongs to, by its `<n>-` at the start or after a `/` (`feat/214-x`,
+ * `214-x`, `ramon/sub/214-x`).
+ * @param branch - The branch.
+ * @returns The number, or null.
+ * @example issueOfBranch("feat/214-x") // 214
+ */
+export function issueOfBranch(branch) {
+    const found = BRANCH_NUMBER.exec(branch);
+    return found?.[1] === undefined ? null : Number(found[1]);
+}

package/dist/launch.d.ts

@@ -0,0 +1,90 @@
+import { type StartMode } from "./issue-text.js";
+/** The file `claude-repo-guard` writes with the auto mode's classifier context. */
+export declare 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 declare const SESSIONS_DIR = "issue-flow-sessions";
+/** How Claude asks for permissions: chosen by the flags, or the default. */
+export type Permissions = "default" | "ask" | "free";
+/** The arguments of the permission mode, and how the summary names it. */
+export interface PermissionArgs {
+    args: string[];
+    label: string;
+}
+/**
+ * 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 declare function permissionArgs(permissions: Permissions, workDir: string | null, mainRoot: string): PermissionArgs;
+/**
+ * Whether a program is in the PATH, without running it.
+ * @param name - The program.
+ * @returns True if it is.
+ * @example inPath("claude")
+ */
+export declare function inPath(name: string): boolean;
+/**
+ * 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 declare function sessionFile(commonDir: string, branch: string): string;
+/**
+ * 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 declare function sessionExists(id: string): boolean;
+/**
+ * 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 declare function savedSession(commonDir: string, branch: string): string | 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 declare function forgetSession(commonDir: string, branch: string): void;
+/** What opening Claude needs. */
+export interface LaunchPlan {
+    workDir: string;
+    commonDir: string;
+    branch: string;
+    mode: StartMode;
+    prompt: string;
+    color: string | null;
+    permissions: string[];
+}
+/**
+ * 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 declare function launchSession(plan: LaunchPlan, warn: (text: string) => void): void;
+/**
+ * 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 declare function teleportSession(workDir: string, permissions: string[], id: string | null): void;