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

package/dist/commands/issue-start.js

@@ -0,0 +1,361 @@
+/**
+ * @file `issue-flow issue start <n>`: starts or resumes the work on an issue and opens
+ * Claude in the same terminal. It reads the issue and its work, picks the branch (the one
+ * it has, or a new one named like `issue branch`), shows a summary and asks, then creates
+ * what is missing (worktree or branch, start commit, push, draft PR, assignment) and opens
+ * Claude with the repo's permission mode. With `--plan` it only prints the branch and the
+ * prompt as one line of JSON. `--adopt`, `--here`, `--cloud` and `--teleport` are in
+ * `start-modes.ts`. Ported from Abastio's `scripts/start-issue.sh`.
+ */
+import { existsSync } from "node:fs";
+import { readWork, resolveRepo, viewIssue } from "@ramon-sg/github-rest";
+import { ask, confirm, forgetTypedAhead } from "../ask.js";
+import { branchType } from "../branch-name.js";
+import { checkedOutAt, checkoutRoot, git, gitLines, locateRepo, onOrigin, ownCommits } from "../git.js";
+import { fill, issueColor, nextBranch } from "../issue-text.js";
+import { inPath, launchSession, permissionArgs, teleportSession } from "../launch.js";
+import { emitJson, warn } from "../output.js";
+import { findOpenPlan, findPlan } from "../plan-doc.js";
+import { proposeBranches } from "../propose.js";
+import { lockWorktree, unlockWorktree } from "../session-lock.js";
+import { afterSession, choosePlace, copyWorktreeIncludes, prepareBranch, publish } from "../start-place.js";
+import { chooseAdopted, fetchOrigin, finishHere, launchCloud, placeAdopted, placeCloud, placeHere, prCloudSession, prepareHere, readAdopted, renameAdopted, withoutFresh, } from "../start-modes.js";
+import { again, StartError } from "../start-state.js";
+import { describeBranch, stepPlaceOf, summary } from "../start-summary.js";
+import { runSetup } from "../worktree-steps.js";
+import { branchPr, workState } from "../work-state.js";
+/**
+ * Adds a warning: prints it and keeps it for `--plan`'s output.
+ * @param context - The start.
+ * @param text - The warning.
+ */
+function note(context, text) {
+    context.warnings.push(text);
+    warn(context.out, text);
+}
+/**
+ * Reads the issue and its work: stops if the checkout's origin is not the repo (the branch
+ * would be pushed to one repo and the PR opened in another), or the issue is missing or
+ * closed; fetches origin
+ * (stops if it fails, because the new branch comes from it) and reads the PRs and branches
+ * with github-rest. A branch of `claude --worktree` stops it too: that session has its
+ * own flow. With `--adopt` it reads the worktree's branch, and a fresh one is not counted
+ * as the issue's work.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns What was read.
+ * @throws StartError if something stops the start; GitHubError if GitHub fails.
+ */
+async function readContext(options, out) {
+    const located = locateRepo(options.cwd);
+    const startRoot = checkoutRoot(options.cwd);
+    if (located === null || startRoot === null)
+        throw new StartError("run this inside a checkout of the repo.");
+    const { number, repo, config } = options;
+    const origin = resolveRepo(undefined, located.mainRoot, {});
+    if (origin === null || origin.toLowerCase() !== repo.toLowerCase())
+        throw new StartError(`this checkout's origin is ${origin ?? "not on GitHub"}, not ${repo}: the branch would be pushed to another repo. Run it in a checkout of ${repo}.`);
+    const issue = await viewIssue(repo, number);
+    if (issue === null)
+        throw new StartError(`issue #${number} does not exist in ${repo}.`);
+    if (issue.state !== "OPEN")
+        throw new StartError(`issue #${number} is ${issue.state}; not starting it.`);
+    const warnings = [];
+    const labels = issue.labels.map(({ name }) => name);
+    if (branchType(config.branch.types, labels, issue.title) === null)
+        note({ out, warnings }, `issue #${number} has no type label.`);
+    if (!fetchOrigin(located.mainRoot, options.here))
+        throw new StartError("could not fetch origin.");
+    const read = await readWork(repo, [number], { cwd: located.mainRoot });
+    for (const text of read.warnings)
+        note({ out, warnings }, text);
+    const entry = read.output.issues[0];
+    if (entry === undefined || "error" in entry)
+        throw new StartError(`issue #${number} does not exist in ${repo}.`);
+    const claudeBranches = gitLines(located.mainRoot, ["for-each-ref", "--format=%(refname:short)", "refs/heads"])
+        .filter((name) => new RegExp(`^worktree-[a-z]+\\+${number}-`).test(name));
+    if (claudeBranches.length > 0)
+        throw new StartError(`the issue has a 'claude --worktree' branch (${claudeBranches.join(", ")}): open that session instead.`);
+    const base = config.baseBranch ?? read.output.defaultBranch ?? "main";
+    const adopted = options.adopt ? readAdopted(startRoot, located.mainRoot, base) : null;
+    const work = adopted === null ? workState(entry) : withoutFresh(workState(entry), adopted);
+    if (work.forks.length > 0)
+        note({ out, warnings }, `the issue has PRs from a fork (${work.forks.map((pr) => `#${pr}`).join(", ")}): they are not resumed from here.`);
+    return { options, out, ...located, startRoot, base, issue, labels, work, warnings, adopted };
+}
+/**
+ * The new branch: named like `issue branch` (the slug block, Claude or the title), with
+ * `-2`, `-3`… if the issue already used that name.
+ * @param context - The start.
+ * @returns The branch.
+ */
+function proposeNew(context) {
+    const { issue, options } = context;
+    const info = { number: issue.number, title: issue.title, body: issue.body, labels: context.labels };
+    const { proposals, warnings } = proposeBranches([info], options.config, {
+        cwd: context.mainRoot,
+        ...(options.namer === undefined ? {} : { namer: options.namer }),
+    });
+    const [proposal] = proposals;
+    if (proposal === undefined)
+        throw new StartError("could not propose a branch.");
+    for (const text of [...warnings, ...proposal.warnings])
+        note(context, text);
+    return nextBranch(proposal.branch, context.work.known);
+}
+/**
+ * Asks in the terminal which live branch to continue, or whether to make another.
+ * @param context - The start.
+ * @param describe - Describes a branch.
+ * @param proposed - The new branch.
+ * @returns The chosen branch, or null for a new one.
+ * @throws StartError if the answer is none of the options.
+ */
+async function pickBranch(context, describe, proposed) {
+    const { candidates } = context.work;
+    const lines = candidates.map((branch, index) => `  ${index + 1}) ${describe(branch)}\n`);
+    context.out.stderr(`Issue #${context.issue.number} already has ${candidates.length} branches:\n${lines.join("")}  n) another new branch: ${proposed}\n`);
+    const answer = await ask(context.out, `Which one? [1-${candidates.length}/n] `);
+    if (/^n$/i.test(answer))
+        return null;
+    const chosen = /^\d+$/.test(answer) ? candidates[Number(answer) - 1] : undefined;
+    if (chosen === undefined)
+        throw new StartError("did nothing.");
+    return chosen;
+}
+/**
+ * The live branch to resume, or null to create a new one. `--new` creates; `--resume`
+ * takes that one if it is the issue's. No branches creates and one is resumed. With
+ * several: `--dry-run` and `--plan` propose a new one and warn, `--yes` stops, and the
+ * terminal asks.
+ * @param context - The start.
+ * @param proposed - Gives the new branch, only when it is needed.
+ * @returns The branch, or null.
+ * @throws StartError if `--resume` is not the issue's, or there are several with `--yes`.
+ */
+async function chooseExisting(context, proposed) {
+    const { options, work } = context;
+    const list = work.candidates.join(", ");
+    if (options.forceNew)
+        return null;
+    if (options.resume !== null) {
+        if (!work.candidates.includes(options.resume))
+            throw new StartError(`branch ${options.resume} is not one of issue #${options.number}'s. Its branches: ${list || "none"}`);
+        return options.resume;
+    }
+    if (work.candidates.length <= 1)
+        return work.candidates[0] ?? null;
+    const count = work.candidates.length;
+    if (options.plan || options.dryRun) {
+        note(context, `the issue already has ${count} branches (${list}): proposing a new one. To resume one: ${again(options.number, "--resume <branch>")}.`);
+        return null;
+    }
+    if (options.yes)
+        throw new StartError(`the issue has ${count} branches (${list}): choose with --resume <branch> or --new.`);
+    const partial = { ...context, found: null, branch: "", pr: null, kind: "closes", mode: "worktree", workDir: "", plan: null, cloudSession: null };
+    return pickBranch(context, (branch) => describeBranch(partial, branch, true), proposed());
+}
+/**
+ * The PR of the branch being resumed. Stops if the branch is neither local nor in origin:
+ * with an open PR, it says how to recreate it; otherwise the local refs of origin are
+ * stale.
+ * @param context - The start.
+ * @param branch - The branch.
+ * @returns The PR, or null.
+ * @throws StartError if the branch is gone.
+ */
+function resumedPr(context, branch) {
+    const pr = branchPr(context.work.prs, branch);
+    const exists = git(context.mainRoot, ["rev-parse", "-q", "--verify", `refs/heads/${branch}`]).ok || onOrigin(context.mainRoot, branch);
+    if (exists)
+        return pr;
+    if (pr?.state === "OPEN")
+        throw new StartError(`PR #${pr.number} is still open and points to branch ${branch}, which is gone locally and in origin. Recreate it with 'git fetch origin pull/${pr.number}/head:${branch}' or close that PR and start again.`);
+    throw new StartError(`branch ${branch} is on GitHub but not in the local refs of origin, which look stale: run 'git fetch origin' and try again.`);
+}
+/**
+ * Where plans are looked for.
+ * @param context - The start.
+ * @returns The query.
+ */
+function planQuery(context) {
+    return { cwd: context.mainRoot, base: context.base, repo: context.options.repo, dirs: context.options.config.plans.dirs };
+}
+/**
+ * The prompt Claude opens with, or `--plan` gives.
+ * @param context - The start.
+ * @param plan - The issue's plan, or null.
+ * @param onlySummary - Whether it only summarizes and waits (`--plan`).
+ * @returns The prompt.
+ */
+function promptFor(context, plan, onlySummary) {
+    const { start } = context.options.config;
+    const template = onlySummary
+        ? plan === null ? start.summaryPrompt : start.summaryPlanPrompt
+        : plan === null ? start.prompt : start.resumePrompt;
+    return fill(template, { number: String(context.issue.number), title: context.issue.title, plan: plan ?? "" });
+}
+/**
+ * `--plan`: prints the branch and the prompt as one line of JSON, without changing
+ * anything. A branch already checked out stops it, because the caller would make a second
+ * checkout. A local branch with no commits, PR nor push is what an earlier attempt left:
+ * it counts as `new`.
+ * @param context - The start.
+ * @param found - The branch being resumed, or null.
+ * @param branch - The branch.
+ * @param pr - Its PR.
+ * @returns The exit code.
+ * @throws StartError if the branch is checked out.
+ */
+function printPlan(context, found, branch, pr) {
+    const at = checkedOutAt(context.mainRoot, branch);
+    if (at !== null)
+        throw new StartError(`the issue already has branch ${branch} (at ${at}): continue there with '${again(context.options.number)}'.`);
+    const empty = found !== null && pr === null && !onOrigin(context.mainRoot, branch) && ownCommits(context.mainRoot, branch, context.base) === 0;
+    const resumed = found !== null && !empty;
+    const plan = resumed
+        ? findPlan(planQuery(context), branch, pr?.number ?? null)
+        : findOpenPlan(planQuery(context), context.work.mergedPrs);
+    emitJson(context.out, {
+        action: resumed ? "resume" : "new",
+        branch,
+        prompt: promptFor(context, plan, true),
+        url: context.issue.url,
+        title: context.issue.title,
+        warnings: context.warnings,
+        claudeArgs: permissionArgs(context.options.permissions, null, context.mainRoot).args,
+    });
+    return 0;
+}
+/**
+ * The question before acting, and what to say if the answer is no.
+ * @param state - The start.
+ * @returns The question and the message.
+ */
+function question(state) {
+    const { work, found } = state;
+    if (found !== null)
+        return { text: "Continue with this work?", declined: "did nothing." };
+    if (work.candidates.length > 0)
+        return { text: "Create another branch for the issue?", declined: "did nothing." };
+    if (work.mergedPrs.length > 0)
+        return {
+            text: `The issue already has merged PR ${work.mergedPrs.map((pr) => `#${pr}`).join(", ")}. Start a new round?`,
+            declined: "did nothing. If the issue is done, close it.",
+        };
+    return { text: "Start the issue?", declined: "did nothing." };
+}
+/**
+ * Opens Claude in the place, locking a worktree meanwhile, and then offers the cleanup.
+ * Without `claude` or with `--no-launch`, says how to open it.
+ * @param state - The start.
+ * @returns The exit code.
+ */
+async function openSession(state) {
+    const { options, out } = state;
+    if (!options.launch || !inPath("claude")) {
+        out.stdout(`Ready. To open the Claude session: ${again(options.number)}\n`);
+        return 0;
+    }
+    const lock = state.mode === "worktree"
+        ? lockWorktree(state.mainRoot, state.workDir, (text) => warn(out, text))
+        : { mine: false, shared: false };
+    const release = () => unlockWorktree(state.mainRoot, state.workDir, lock);
+    process.once("exit", release);
+    forgetTypedAhead();
+    const permissions = permissionArgs(options.permissions, state.workDir, state.mainRoot).args;
+    if (options.teleport) {
+        out.stdout(`Bringing the cloud session${state.cloudSession === null ? "" : ` (${state.cloudSession})`}. To resume it later: claude --resume\n`);
+        teleportSession(state.workDir, permissions, state.cloudSession);
+    }
+    else
+        launchSession({
+            workDir: state.workDir,
+            commonDir: state.commonDir,
+            branch: state.branch,
+            mode: state.mode,
+            prompt: promptFor(state, state.plan, false),
+            color: issueColor(state.labels, options.config.colors)?.color ?? null,
+            permissions,
+        }, (text) => warn(out, text));
+    release();
+    process.off("exit", release);
+    await afterSession(state, lock);
+    return 0;
+}
+/**
+ * `issue start <n>`.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns The exit code.
+ * @throws StartError if something stops the start; GitHubError if GitHub fails.
+ * @example await issueStart(options, processOutput())
+ */
+export async function issueStart(options, out) {
+    const context = await readContext(options, out);
+    let proposed = null;
+    const propose = () => (proposed ??= proposeNew(context));
+    const chosen = context.adopted === null
+        ? { found: await chooseExisting(context, propose), named: null }
+        : chooseAdopted(context.mainRoot, context.work, context.adopted, options.number);
+    const { found } = chosen;
+    const branch = found ?? chosen.named ?? propose();
+    const pr = found === null ? null : resumedPr(context, branch);
+    const kind = context.work.candidates.some((other) => other !== branch) ? "part" : "closes";
+    if (options.plan)
+        return printPlan(context, found, branch, pr);
+    if (options.teleport && found === null)
+        throw new StartError(`issue #${options.number} has no branch: start it with '${again(options.number, "--cloud")}' (or without flags).`);
+    const plan = found !== null
+        ? findPlan(planQuery(context), branch, pr?.number ?? null)
+        : findOpenPlan(planQuery(context), context.work.mergedPrs);
+    const cloudSession = await prCloudSession(options.repo, pr?.number ?? null);
+    const state = { ...context, found, branch, pr, kind, ...placeOf(context, branch, found), plan, cloudSession };
+    out.stdout(summary(state, permissionArgs(options.permissions, existsSync(state.workDir) ? state.workDir : null, context.mainRoot)));
+    if (options.dryRun)
+        return 0;
+    const asked = question(state);
+    if (!options.yes && state.adopted === null && !(await confirm(out, asked.text)))
+        throw new StartError(asked.declined);
+    if (state.mode === "cloud")
+        return launchCloud(state, out);
+    if (state.adopted !== null)
+        renameAdopted(state);
+    else if (state.mode === "here")
+        prepareHere(state);
+    else
+        prepareBranch(state);
+    const prNumber = await publish(state);
+    if (state.mode === "here") {
+        await finishHere(state, prNumber, promptFor(state, plan, false));
+        return 0;
+    }
+    if (state.adopted !== null) {
+        out.stdout(`Ready: issue #${options.number} is on branch ${branch}, with its draft PR.\n${plan === null ? "" : `Open plan of this issue, to resume: ${plan}\n`}`);
+        return 0;
+    }
+    if (state.mode === "worktree") {
+        copyWorktreeIncludes(context.mainRoot, state.workDir, out);
+        await runSetup(stepPlaceOf(state), null);
+    }
+    return openSession(state);
+}
+/**
+ * Where the work goes, by the flags: the adopted worktree, this checkout (`--here`), the
+ * cloud (`--cloud`), or a worktree or the main checkout.
+ * @param context - The start.
+ * @param branch - The branch.
+ * @param found - The branch being resumed, or null.
+ * @returns The mode and the folder.
+ * @throws StartError if the place is taken.
+ */
+function placeOf(context, branch, found) {
+    const { options, mainRoot, adopted } = context;
+    if (adopted !== null)
+        return placeAdopted({ branch, startRoot: context.startRoot, adopted });
+    if (options.here)
+        return placeHere(mainRoot, context.startRoot, branch, options.number);
+    if (options.cloud)
+        return placeCloud(mainRoot, branch, found, options.number);
+    return choosePlace(mainRoot, branch, options.branchMode, options.config.worktrees.dir);
+}

package/dist/commands/pr-worktree.d.ts

@@ -0,0 +1,31 @@
+import type { FlowConfig } from "../config.js";
+import { type Output } from "../output.js";
+/** Options of `issue-flow pr worktree`. */
+export interface PrWorktreeOptions {
+    repo: string;
+    config: FlowConfig;
+    cwd: string;
+    number: number;
+    setup: boolean;
+    command: string[] | null;
+}
+/**
+ * The folder of a PR's worktree: `pr-<n>` in the config's worktrees folder.
+ * @param mainRoot - The main checkout.
+ * @param config - The config.
+ * @param number - The PR.
+ * @returns The path.
+ * @example prWorktreePath("/repo", config, 7) // "/repo/.claude/worktrees/pr-7"
+ */
+export declare function prWorktreePath(mainRoot: string, config: FlowConfig, number: number): string;
+/**
+ * `pr worktree <n> [--no-setup] [-- <command>]`: makes or reuses the PR's worktree and
+ * prints where it is; with `--`, runs the command there (Claude, with the repo's permission
+ * mode, if it names none) and exits with its code.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns The exit code.
+ * @throws StartError if the PR does not exist, comes from a fork or cannot be checked out.
+ * @example await prWorktree({ ...options, number: 7 }, out)
+ */
+export declare function prWorktree(options: PrWorktreeOptions, out: Output): Promise<number>;

package/dist/commands/pr-worktree.js

@@ -0,0 +1,122 @@
+/**
+ * @file `issue-flow pr worktree <n>`: a PR in its own worktree, to review it without
+ * leaving what you are doing. The worktree is on the PR's branch, tracking origin, so what
+ * you commit and push updates the PR. It copies `.worktreeinclude` and runs the setup
+ * steps, but a `trusted` step (an install) is skipped, because the PR's code is not in the
+ * base branch yet: it says what to run once you checked it. It never touches the main
+ * checkout, and a PR from a fork is refused, since its branch is not in origin. Cleaning up
+ * is `worktree prune`, like every other worktree. Ported from Clean Queen's
+ * `scripts/pr-worktree.sh`.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { getPr } from "@ramon-sg/github-rest";
+import { canonicalPath } from "../docker.js";
+import { checkedOutAt, git, hasLocal, locateRepo, worktrees } from "../git.js";
+import { permissionArgs } from "../launch.js";
+import { warn } from "../output.js";
+import { copyWorktreeIncludes } from "../start-place.js";
+import { StartError } from "../start-state.js";
+import { runSetup } from "../worktree-steps.js";
+import { baseBranch } from "./worktree.js";
+/**
+ * The folder of a PR's worktree: `pr-<n>` in the config's worktrees folder.
+ * @param mainRoot - The main checkout.
+ * @param config - The config.
+ * @param number - The PR.
+ * @returns The path.
+ * @example prWorktreePath("/repo", config, 7) // "/repo/.claude/worktrees/pr-7"
+ */
+export function prWorktreePath(mainRoot, config, number) {
+    return join(mainRoot, config.worktrees.dir, `pr-${number}`);
+}
+/**
+ * Runs git and stops with the message if it fails.
+ * @param cwd - Where.
+ * @param args - The arguments.
+ * @param message - What failed, for the error.
+ * @throws StartError if git fails.
+ */
+function mustGit(cwd, args, message) {
+    const result = git(cwd, args);
+    if (!result.ok)
+        throw new StartError(`${message}: ${result.err || result.out}`);
+}
+/**
+ * Makes the worktree on the PR's branch: the local branch if there is one (moved forward to
+ * origin's when it can be), or a new one tracking origin's.
+ * @param mainRoot - The main checkout.
+ * @param branch - The PR's branch.
+ * @param path - The worktree.
+ * @param out - Where a warning goes.
+ * @throws StartError if git cannot make it, or the branch is checked out somewhere else.
+ */
+function addWorktree(mainRoot, branch, path, out) {
+    mustGit(mainRoot, ["fetch", "-q", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`], `could not fetch ${branch} from origin`);
+    const elsewhere = checkedOutAt(mainRoot, branch);
+    if (elsewhere !== null)
+        throw new StartError(`${branch} is checked out in ${elsewhere}; review it there, or switch that checkout to another branch.`);
+    if (!hasLocal(mainRoot, branch)) {
+        mustGit(mainRoot, ["worktree", "add", "-q", "--track", "-b", branch, path, `origin/${branch}`], `could not make the worktree of ${branch}`);
+        return;
+    }
+    mustGit(mainRoot, ["worktree", "add", "-q", path, branch], `could not make the worktree of ${branch}`);
+    if (!git(path, ["branch", "-q", "--set-upstream-to", `origin/${branch}`]).ok)
+        warn(out, `could not make ${branch} track origin/${branch}.`);
+    if (!git(path, ["merge", "-q", "--ff-only", `origin/${branch}`]).ok)
+        warn(out, `the local ${branch} does not move forward to origin/${branch}: you see other commits than the PR's.`);
+}
+/**
+ * `pr worktree <n> [--no-setup] [-- <command>]`: makes or reuses the PR's worktree and
+ * prints where it is; with `--`, runs the command there (Claude, with the repo's permission
+ * mode, if it names none) and exits with its code.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns The exit code.
+ * @throws StartError if the PR does not exist, comes from a fork or cannot be checked out.
+ * @example await prWorktree({ ...options, number: 7 }, out)
+ */
+export async function prWorktree(options, out) {
+    const located = locateRepo(options.cwd);
+    if (located === null)
+        throw new StartError("run this inside a checkout of the repo.");
+    const { mainRoot } = located;
+    const pr = await getPr(options.repo, options.number);
+    if (pr === null)
+        throw new StartError(`${options.repo} has no PR #${options.number}.`);
+    if (pr.fork)
+        throw new StartError(`PR #${pr.number} comes from a fork and its branch is not in origin; check it out by hand in a worktree with 'gh pr checkout ${pr.number}'.`);
+    out.stdout(`PR #${pr.number}: ${pr.url}\n`);
+    if (pr.state !== "OPEN")
+        warn(out, `the PR is ${pr.state.toLowerCase()}.`);
+    const path = canonicalPath(prWorktreePath(mainRoot, options.config, pr.number));
+    const existing = worktrees(mainRoot).find((entry) => entry.path === path);
+    if (existing !== undefined && existing.branch !== pr.branch)
+        throw new StartError(`${path} is on ${existing.branch ?? "a detached HEAD"}, not on the PR's branch ${pr.branch}; delete it with 'git worktree remove ${path}'.`);
+    if (existing === undefined && existsSync(path))
+        throw new StartError(`${path} exists and is not a worktree of this repo.`);
+    if (existing === undefined) {
+        addWorktree(mainRoot, pr.branch, path, out);
+        copyWorktreeIncludes(mainRoot, path, out);
+        out.stdout(`Worktree on ${pr.branch}: what you commit and push updates the PR.\n`);
+    }
+    else
+        out.stdout(`The worktree already exists; reusing it.\n`);
+    const place = { root: path, mainRoot, base: baseBranch(options.config, mainRoot), config: options.config, out, remote: false };
+    if (options.setup)
+        await runSetup(place, null);
+    if (options.command === null) {
+        out.stdout(`Ready. To go in: cd ${path}\n`);
+        return 0;
+    }
+    const [command, ...args] = options.command.length > 0
+        ? options.command
+        : ["claude", ...permissionArgs("default", path, mainRoot).args];
+    if (command === undefined)
+        return 0;
+    const result = spawnSync(command, args, { cwd: path, stdio: "inherit" });
+    if (result.error !== undefined)
+        throw new StartError(`could not run ${command}: ${result.error.message}`);
+    return result.status ?? 1;
+}

package/dist/commands/session.d.ts

@@ -0,0 +1,15 @@
+import type { FlowConfig } from "../config.js";
+import type { Output } from "../output.js";
+/** Where the cloud environment's setup leaves the `claude-cloud` command. */
+export declare const CLAUDE_CLOUD_BIN = "/opt/claude-cloud/bin/claude-cloud";
+/**
+ * `issue-flow session`.
+ * @param options - The config and the session's folder.
+ * @param out - Where to write; stdout reaches Claude.
+ * @returns Always 0.
+ * @example await session({ config, cwd }, out)
+ */
+export declare function session(options: {
+    config: FlowConfig;
+    cwd: string;
+}, out: Output): Promise<number>;

package/dist/commands/session.js

@@ -0,0 +1,102 @@
+/**
+ * @file `issue-flow session`: the `SessionStart` hook of Claude Code. What it prints on
+ * stdout reaches Claude as the session's context, so every warning goes there. Its steps:
+ * in a cloud session, `claude-cloud session` (tools, Docker, the full history and the
+ * repo's session steps); in a worktree (or the cloud's checkout), the setup steps; in a
+ * local worktree whose issue branch is not published, a warning to run `start-issue`; the
+ * cleanup of the Docker of deleted worktrees (Claude Code does not call `WorktreeRemove`
+ * for worktrees made with git); and the environment of `direnv` in `CLAUDE_ENV_FILE`,
+ * which Claude Code reads before each command. It never makes the session fail. Ported
+ * from Abastio's `scripts/claude-session-env.sh`.
+ */
+import { spawnSync } from "node:child_process";
+import { appendFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { dockerCleanup } from "../docker.js";
+import { currentBranch, onOrigin } from "../git.js";
+import { issueOfBranch } from "../issue-text.js";
+import { inPath } from "../launch.js";
+import { runSetup } from "../worktree-steps.js";
+import { stepPlace } from "./worktree.js";
+/** Where the cloud environment's setup leaves the `claude-cloud` command. */
+export const CLAUDE_CLOUD_BIN = "/opt/claude-cloud/bin/claude-cloud";
+/** The package that prepares the cloud, for the message of what to set in claude.ai. */
+const CLAUDE_CLOUD_PACKAGE = "@ramon-sg/claude-cloud";
+/**
+ * In a cloud session, runs `claude-cloud session` (`CLAUDE_CLOUD_BIN` changes where it is
+ * looked for). Its output goes to stderr, as its steps print their own.
+ * @param root - The checkout.
+ * @param say - Where a message for Claude goes.
+ */
+function cloudSession(root, say) {
+    const bin = process.env.CLAUDE_CLOUD_BIN ?? CLAUDE_CLOUD_BIN;
+    if (!existsSync(bin)) {
+        say(`the environment setup did not run (there is no ${bin}). In claude.ai, set the environment's setup script to: npx -y ${CLAUDE_CLOUD_PACKAGE}@1 setup. It applies to new sessions.`);
+        return;
+    }
+    if (spawnSync(bin, ["session"], { cwd: root, stdio: ["ignore", 2, 2] }).status !== 0)
+        say(`claude-cloud session failed; run '${bin} session' in ${root} to see why.`);
+}
+/**
+ * The issue of a local worktree whose branch has the issue's number and is not in origin:
+ * it was never published, so the issue has no draft PR (a tool's setup may have failed
+ * quietly). Its upstream does not tell: a worktree made from `origin/main` tracks it.
+ * @param root - The worktree.
+ * @returns The issue, or null.
+ */
+function unstartedIssue(root) {
+    const branch = currentBranch(root);
+    if (branch === null || onOrigin(root, branch))
+        return null;
+    return issueOfBranch(branch);
+}
+/**
+ * Appends the environment of `direnv` to `CLAUDE_ENV_FILE`, so the session's commands get
+ * what the `.envrc` loads (they run in shells that do not go through direnv's hook). A
+ * failed export is not appended: with the `.envrc` blocked it still prints the unload of
+ * the earlier environment, which would take from the session what it inherited.
+ * @param root - The checkout.
+ * @param say - Where a message for Claude goes.
+ */
+function direnvExport(root, say) {
+    const file = process.env.CLAUDE_ENV_FILE;
+    if (file === undefined || file === "" || !existsSync(join(root, ".envrc")) || !inPath("direnv"))
+        return;
+    const result = spawnSync("direnv", ["export", "bash"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    if (result.status !== 0) {
+        say("could not load the .envrc with direnv; the session keeps the environment it inherited.");
+        return;
+    }
+    appendFileSync(file, `${result.stdout}\n`);
+}
+/**
+ * `issue-flow session`.
+ * @param options - The config and the session's folder.
+ * @param out - Where to write; stdout reaches Claude.
+ * @returns Always 0.
+ * @example await session({ config, cwd }, out)
+ */
+export async function session(options, out) {
+    const say = (text) => out.stdout(`issue-flow session: ${text}\n`);
+    const toClaude = { ...out, stderr: (text) => out.stdout(text) };
+    let place;
+    try {
+        place = stepPlace({ config: options.config, cwd: options.cwd }, toClaude);
+    }
+    catch {
+        return 0;
+    }
+    const { root, mainRoot, remote } = place;
+    if (remote)
+        cloudSession(root, say);
+    if (root !== mainRoot || remote)
+        await runSetup(place, null);
+    const unstarted = !remote && root !== mainRoot ? unstartedIssue(root) : null;
+    if (unstarted !== null)
+        say(`issue #${unstarted} was not started: its branch is not published and has no draft PR. Before working, run the start-issue skill (${unstarted}).`);
+    const docker = dockerCleanup(options.config.worktrees.dockerProjects, null);
+    if (docker.failed.length > 0)
+        say(`could not delete the Docker of deleted worktrees (${docker.failed.join(", ")}); run 'issue-flow worktree cleanup' to see why.`);
+    direnvExport(root, say);
+    return 0;
+}

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,16 @@
+import type { Output } from "../output.js";
+/** Options of `issue-flow upgrade`. */
+export interface UpgradeOptions {
+    cwd: string;
+    to: string | null;
+    dryRun: boolean;
+}
+/**
+ * Moves the repo to another version of the flow; see the file's header.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns 0, or 1 if `skills-manager` failed.
+ * @throws SetupError outside the main checkout, if npm cannot tell the version or a file is broken.
+ * @example upgrade({ cwd, to: null, dryRun: false }, out)
+ */
+export declare function upgrade(options: UpgradeOptions, out: Output): number;