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

package/dist/settings-hooks.d.ts

@@ -0,0 +1,31 @@
+/** The hook events `init` registers. */
+export declare const HOOK_EVENTS: string[];
+/**
+ * The command of one of the hooks, at a version.
+ * @param event - The hook event.
+ * @param version - This package's version.
+ * @returns The command.
+ * @example hookCommand("WorktreeCreate", "0.1.0") // "npx --yes @ramon-sg/issue-flow@0.1.0 hook worktree-create"
+ */
+export declare function hookCommand(event: string, version: string): string;
+/**
+ * Registers our hooks at a version: moves the version of the ones already there and adds
+ * the missing ones. In `SessionStart` it drops a `claude-cloud session` hook that is not
+ * ours.
+ * @param settings - The settings, or null if there is no file.
+ * @param version - This package's version.
+ * @returns The new settings and what changed, one line each.
+ * @throws SetupError if `hooks` or an event of it is not what Claude Code expects.
+ * @example registerHooks(null, "0.1.0").changes // ["added the SessionStart hook", …]
+ */
+export declare function registerHooks(settings: Record<string, unknown> | null, version: string): {
+    settings: Record<string, unknown>;
+    changes: string[];
+};
+/**
+ * The version of each of our hooks in the settings.
+ * @param settings - The settings, or null.
+ * @returns Event to version, or null if the hook is missing.
+ * @example hookVersions(settings).SessionStart // "0.1.0"
+ */
+export declare function hookVersions(settings: Record<string, unknown> | null): Record<string, string | null>;

package/dist/settings-hooks.js

@@ -0,0 +1,133 @@
+/**
+ * @file The Claude Code hooks `init` registers in `.claude/settings.json`: `SessionStart`
+ * (`issue-flow session`) and `WorktreeCreate` and `WorktreeRemove` (`issue-flow hook …`), each
+ * pinned to this package's version. They are found again by their command, so running
+ * `init` twice changes nothing and `upgrade` only moves the version. The `SessionStart`
+ * command names `claude-cloud session`, which `issue-flow session` runs in the cloud: that
+ * way `claude-cloud init` sees it and does not add its own, and a hook of `claude-cloud`
+ * already there is dropped, so it does not run twice.
+ */
+import { isObject } from "./config-base.js";
+import { PACKAGE, SETTINGS_FILE, SetupError } from "./setup-files.js";
+/** Seconds each hook may take: the setup steps can install dependencies. */
+const HOOK_TIMEOUT_SECONDS = 600;
+/** What `claude-cloud init` looks for in a `SessionStart` command. */
+const CLOUD_MARKER = "claude-cloud session";
+/** The subcommand of each hook, and what follows it. */
+const HOOK_COMMANDS = {
+    SessionStart: { sub: "session", note: ` # runs ${CLOUD_MARKER} in the cloud` },
+    WorktreeCreate: { sub: "hook worktree-create", note: "" },
+    WorktreeRemove: { sub: "hook worktree-remove", note: "" },
+};
+/** The hook events `init` registers. */
+export const HOOK_EVENTS = Object.keys(HOOK_COMMANDS);
+/**
+ * The command of one of the hooks, at a version.
+ * @param event - The hook event.
+ * @param version - This package's version.
+ * @returns The command.
+ * @example hookCommand("WorktreeCreate", "0.1.0") // "npx --yes @ramon-sg/issue-flow@0.1.0 hook worktree-create"
+ */
+export function hookCommand(event, version) {
+    const hook = HOOK_COMMANDS[event];
+    if (hook === undefined)
+        throw new SetupError(`unknown hook event ${event}.`);
+    return `npx --yes ${PACKAGE}@${version} ${hook.sub}${hook.note}`;
+}
+/**
+ * The version of our hook in a command, or null if the command is not ours for that event.
+ * @param command - The command.
+ * @param event - The event.
+ * @returns The version.
+ */
+function ourVersion(command, event) {
+    const sub = HOOK_COMMANDS[event]?.sub;
+    if (typeof command !== "string" || sub === undefined)
+        return null;
+    const match = new RegExp(`${PACKAGE.replace("/", "\\/")}@(\\S+) ${sub}(?:\\s|$)`).exec(command);
+    return match?.[1] ?? null;
+}
+/**
+ * The entries of an event in the settings, checked.
+ * @param hooks - The `hooks` object.
+ * @param event - The event.
+ * @returns Its entries (a new array if there were none).
+ * @throws SetupError if they are not a list of objects.
+ */
+function entriesOf(hooks, event) {
+    const entries = hooks[event] ?? [];
+    if (!Array.isArray(entries) || !entries.every(isObject))
+        throw new SetupError(`${SETTINGS_FILE}: hooks.${event} is not a list of entries; fix it and run again.`);
+    return entries;
+}
+/**
+ * The hooks of an entry.
+ * @param entry - The entry.
+ * @returns Its hooks, or an empty list.
+ */
+function hooksOf(entry) {
+    return Array.isArray(entry.hooks) ? entry.hooks.filter(isObject) : [];
+}
+/**
+ * Registers our hooks at a version: moves the version of the ones already there and adds
+ * the missing ones. In `SessionStart` it drops a `claude-cloud session` hook that is not
+ * ours.
+ * @param settings - The settings, or null if there is no file.
+ * @param version - This package's version.
+ * @returns The new settings and what changed, one line each.
+ * @throws SetupError if `hooks` or an event of it is not what Claude Code expects.
+ * @example registerHooks(null, "0.1.0").changes // ["added the SessionStart hook", …]
+ */
+export function registerHooks(settings, version) {
+    const next = { ...(settings ?? {}) };
+    const hooks = next.hooks ?? {};
+    if (!isObject(hooks))
+        throw new SetupError(`${SETTINGS_FILE}: "hooks" is not an object; fix it and run again.`);
+    next.hooks = { ...hooks };
+    const changes = [];
+    for (const event of HOOK_EVENTS) {
+        const entries = entriesOf(hooks, event);
+        const command = hookCommand(event, version);
+        let found = false;
+        const kept = entries.map((entry) => {
+            const inner = hooksOf(entry).flatMap((hook) => {
+                const current = ourVersion(hook.command, event);
+                if (current !== null) {
+                    found = true;
+                    if (hook.command === command)
+                        return [hook];
+                    changes.push(`moved the ${event} hook from ${current} to ${version}`);
+                    return [{ ...hook, command }];
+                }
+                if (event === "SessionStart" && typeof hook.command === "string" && hook.command.includes(CLOUD_MARKER)) {
+                    changes.push(`dropped the ${CLOUD_MARKER} SessionStart hook: issue-flow session runs it`);
+                    return [];
+                }
+                return [hook];
+            });
+            return Array.isArray(entry.hooks) ? { ...entry, hooks: inner } : entry;
+        }).filter((entry) => !Array.isArray(entry.hooks) || entry.hooks.length > 0);
+        if (!found) {
+            kept.push({ hooks: [{ type: "command", command, timeout: HOOK_TIMEOUT_SECONDS }] });
+            changes.push(`added the ${event} hook`);
+        }
+        next.hooks[event] = kept;
+    }
+    return { settings: next, changes };
+}
+/**
+ * The version of each of our hooks in the settings.
+ * @param settings - The settings, or null.
+ * @returns Event to version, or null if the hook is missing.
+ * @example hookVersions(settings).SessionStart // "0.1.0"
+ */
+export function hookVersions(settings) {
+    const hooks = isObject(settings?.hooks) ? settings.hooks : {};
+    const versions = {};
+    for (const event of HOOK_EVENTS) {
+        const entries = Array.isArray(hooks[event]) ? hooks[event].filter(isObject) : [];
+        const commands = entries.flatMap((entry) => hooksOf(entry).map((hook) => hook.command));
+        versions[event] = commands.map((command) => ourVersion(command, event)).find((found) => found !== null) ?? null;
+    }
+    return versions;
+}

package/dist/setup-files.d.ts

@@ -0,0 +1,48 @@
+/** This package's name on npm. */
+export declare const PACKAGE = "@ramon-sg/issue-flow";
+/** The GitHub repo of this package, whose tags hold the config's schema of each version. */
+export declare const FLOW_REPO = "ramon-sg/issue-flow";
+/** Claude Code's settings of the repo. */
+export declare const SETTINGS_FILE = ".claude/settings.json";
+/** Error of `init`, `doctor` or `upgrade`: exits 1 with the message. */
+export declare class SetupError extends Error {
+}
+/** The versions this package pins in the repo. */
+export interface OwnVersions {
+    issueFlow: string;
+    githubRest: string;
+    skillsManager: string;
+}
+/**
+ * This package's version and the exact versions of `github-rest` and `skills-manager` it
+ * was built and tested with, from its own `package.json`.
+ * @returns The versions.
+ * @throws SetupError if the package.json does not have them.
+ * @example ownVersions().issueFlow // "0.1.0"
+ */
+export declare function ownVersions(): OwnVersions;
+/**
+ * Reads a JSON object of the repo.
+ * @param root - The repo.
+ * @param path - The file, relative to the repo.
+ * @returns The object, or null if the file does not exist.
+ * @throws SetupError if it is not valid JSON or not an object: it is never overwritten then.
+ * @example readJson(root, ".claude/settings.json")
+ */
+export declare function readJson(root: string, path: string): Record<string, unknown> | null;
+/**
+ * Writes a JSON file of the repo, indented by two spaces, creating its folder.
+ * @param root - The repo.
+ * @param path - The file, relative to the repo.
+ * @param value - What to write.
+ * @example writeJson(root, ".agents/flow.json", { baseBranch: "main" })
+ */
+export declare function writeJson(root: string, path: string, value: unknown): void;
+/**
+ * The repo's package manager: the `packageManager` field, then its lockfile, then npm.
+ * @param root - The repo.
+ * @param pkg - Its package.json, or null.
+ * @returns `npm`, `pnpm`, `bun` or `yarn`.
+ * @example packageManager(root, { packageManager: "pnpm@9.0.0" }) // "pnpm"
+ */
+export declare function packageManager(root: string, pkg: Record<string, unknown> | null): string;

package/dist/setup-files.js

@@ -0,0 +1,91 @@
+/**
+ * @file What `init`, `doctor` and `upgrade` share: this package's own versions, the JSON
+ * files of the repo they read and write, and its package manager. Every package goes by its
+ * scoped name: the unscoped `issue-flow`, `github-rest` and `skills-manager` on npm belong
+ * to other people.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isObject } from "./config-base.js";
+/** This package's name on npm. */
+export const PACKAGE = "@ramon-sg/issue-flow";
+/** The GitHub repo of this package, whose tags hold the config's schema of each version. */
+export const FLOW_REPO = "ramon-sg/issue-flow";
+/** Claude Code's settings of the repo. */
+export const SETTINGS_FILE = ".claude/settings.json";
+/** Error of `init`, `doctor` or `upgrade`: exits 1 with the message. */
+export class SetupError extends Error {
+}
+/**
+ * This package's version and the exact versions of `github-rest` and `skills-manager` it
+ * was built and tested with, from its own `package.json`.
+ * @returns The versions.
+ * @throws SetupError if the package.json does not have them.
+ * @example ownVersions().issueFlow // "0.1.0"
+ */
+export function ownVersions() {
+    const file = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    const pkg = JSON.parse(readFileSync(file, "utf8"));
+    const githubRest = pkg.dependencies?.["@ramon-sg/github-rest"];
+    const skillsManager = pkg.devDependencies?.["@ramon-sg/skills-manager"];
+    if (pkg.version === undefined || githubRest === undefined || skillsManager === undefined)
+        throw new SetupError(`${file} lacks the version of issue-flow, github-rest or skills-manager.`);
+    return { issueFlow: pkg.version, githubRest, skillsManager };
+}
+/**
+ * Reads a JSON object of the repo.
+ * @param root - The repo.
+ * @param path - The file, relative to the repo.
+ * @returns The object, or null if the file does not exist.
+ * @throws SetupError if it is not valid JSON or not an object: it is never overwritten then.
+ * @example readJson(root, ".claude/settings.json")
+ */
+export function readJson(root, path) {
+    const file = join(root, path);
+    if (!existsSync(file))
+        return null;
+    let value;
+    try {
+        value = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new SetupError(`${path} is not valid JSON (${error instanceof Error ? error.message : String(error)}); fix it and run again.`);
+    }
+    if (!isObject(value))
+        throw new SetupError(`${path} is not a JSON object; fix it and run again.`);
+    return value;
+}
+/**
+ * Writes a JSON file of the repo, indented by two spaces, creating its folder.
+ * @param root - The repo.
+ * @param path - The file, relative to the repo.
+ * @param value - What to write.
+ * @example writeJson(root, ".agents/flow.json", { baseBranch: "main" })
+ */
+export function writeJson(root, path, value) {
+    const file = join(root, path);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+/** The lockfile of each package manager, in the order they are looked for. */
+const LOCKFILES = [
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"],
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["package-lock.json", "npm"],
+];
+/**
+ * The repo's package manager: the `packageManager` field, then its lockfile, then npm.
+ * @param root - The repo.
+ * @param pkg - Its package.json, or null.
+ * @returns `npm`, `pnpm`, `bun` or `yarn`.
+ * @example packageManager(root, { packageManager: "pnpm@9.0.0" }) // "pnpm"
+ */
+export function packageManager(root, pkg) {
+    const field = typeof pkg?.packageManager === "string" ? pkg.packageManager.split("@")[0] : undefined;
+    if (field !== undefined && field !== "")
+        return field;
+    return LOCKFILES.find(([file]) => existsSync(join(root, file)))?.[1] ?? "npm";
+}

package/dist/start-modes.d.ts

@@ -0,0 +1,162 @@
+import { type StartMode } from "./issue-text.js";
+import { type Output } from "./output.js";
+import { type Adopted, type StartState } from "./start-state.js";
+import type { WorkState } from "./work-state.js";
+/**
+ * The fetch of origin. In a cloud session the clone has one branch, so `--here` passes
+ * the refspec: without it neither the base nor the issue's branch would come.
+ * @param mainRoot - The main checkout.
+ * @param here - Whether it runs with `--here`.
+ * @returns True if it worked.
+ * @example fetchOrigin(root, false)
+ */
+export declare function fetchOrigin(mainRoot: string, here: boolean): boolean;
+/**
+ * The branch of the worktree `--adopt` runs in, and whether it is fresh: not in origin and
+ * with no commits of its own, so the tool that made the worktree just made it.
+ * @param startRoot - The checkout where it runs.
+ * @param mainRoot - The main checkout.
+ * @param base - The base branch.
+ * @returns The branch and whether it is fresh.
+ * @throws StartError in the main checkout or on a detached HEAD.
+ * @example readAdopted(wt, root, "main") // { current: "ramon/x", fresh: true }
+ */
+export declare function readAdopted(startRoot: string, mainRoot: string, base: string): Adopted;
+/**
+ * The issue's work without the adopted branch when it is fresh: it is neither earlier work
+ * nor a used name.
+ * @param work - The work.
+ * @param adopted - The adopted branch.
+ * @returns The work.
+ * @example withoutFresh(work, { current: "ramon/x", fresh: true })
+ */
+export declare function withoutFresh(work: WorkState, adopted: Adopted): WorkState;
+/**
+ * Which branch `--adopt` takes. A live branch of the issue that the worktree is on is
+ * resumed. A fresh branch with the issue's number is the new branch as it is, with other
+ * branches or without (Paseo lets you edit the name; Orca makes one without the number).
+ * Otherwise, with no live branches the branch is renamed to the proposed one, and with
+ * some it stops: the issue goes on elsewhere.
+ * @param mainRoot - The main checkout.
+ * @param work - The issue's work.
+ * @param adopted - The adopted branch.
+ * @param number - The issue.
+ * @returns The branch resumed, or the new one already named, or neither (propose one).
+ * @throws StartError if the issue has live branches elsewhere.
+ * @example chooseAdopted(root, work, adopted, 214) // { found: null, named: "fix/214-x" }
+ */
+export declare function chooseAdopted(mainRoot: string, work: WorkState, adopted: Adopted, number: number): {
+    found: string | null;
+    named: string | null;
+};
+/**
+ * The place of `--adopt`: the worktree where it runs. If it is already on the branch there
+ * is nothing to check (an `--adopt` repeated or resumed); if not, it must be fresh and
+ * without uncommitted changes, so a branch with other work is never renamed. Untracked
+ * files do not count: the tool may leave its own.
+ * @param state - What it knows: the branch, the start checkout and the adopted branch.
+ * @returns The mode and the folder.
+ * @throws StartError if the worktree is not fresh.
+ * @example placeAdopted({ branch, startRoot, adopted })
+ */
+export declare function placeAdopted(state: {
+    branch: string;
+    startRoot: string;
+    adopted: Adopted;
+}): {
+    mode: StartMode;
+    workDir: string;
+};
+/**
+ * Renames the adopted worktree's branch to the issue's (to the same name, it does
+ * nothing). The tool that made the worktree knows it by its path, so the rename does not
+ * unlink it.
+ * @param state - The start.
+ * @throws StartError if git cannot.
+ * @example renameAdopted(state)
+ */
+export declare function renameAdopted(state: StartState): void;
+/**
+ * The place of `--here`: the checkout where it runs. Stops if the branch is checked out in
+ * another one, or this one has uncommitted changes (untracked files do not count: the
+ * cloud's hook leaves its own, and git says if one is in the way).
+ * @param mainRoot - The main checkout.
+ * @param startRoot - The checkout where it runs.
+ * @param branch - The branch.
+ * @param number - The issue.
+ * @returns The mode and the folder.
+ * @throws StartError if the place is taken.
+ * @example placeHere(root, root, "feat/42-x", 42)
+ */
+export declare function placeHere(mainRoot: string, startRoot: string, branch: string, number: number): {
+    mode: StartMode;
+    workDir: string;
+};
+/**
+ * The place of `--cloud`: the cloud session does the work, launched from the main
+ * checkout. Stops if the branch is checked out, or exists only locally, where the cloud
+ * would not see it.
+ * @param mainRoot - The main checkout.
+ * @param branch - The branch.
+ * @param found - The branch being resumed, or null.
+ * @param number - The issue.
+ * @returns The mode and the folder.
+ * @throws StartError if the cloud cannot take the branch.
+ * @example placeCloud(root, "feat/42-x", null, 42)
+ */
+export declare function placeCloud(mainRoot: string, branch: string, found: string | null, number: number): {
+    mode: StartMode;
+    workDir: string;
+};
+/**
+ * With `--here`, leaves the checkout on the branch without needing a local base: a new one
+ * comes from `origin/<base>`, an existing one from `origin/<branch>` (the fetch of every
+ * branch already brought it). A branch missing from origin is only local, somewhere else;
+ * a local branch with commits origin lacks stops it, so `-B` does not overwrite them.
+ * @param state - The start.
+ * @throws StartError if git cannot or the branch cannot be brought.
+ * @example prepareHere(state)
+ */
+export declare function prepareHere(state: StartState): void;
+/**
+ * The cloud session noted in the PR's body, or null (no PR, none noted, or the PR cannot
+ * be read).
+ * @param repo - The repo.
+ * @param pr - The PR, or null.
+ * @returns The id, or null.
+ * @example await prCloudSession("acme/widgets", 7)
+ */
+export declare function prCloudSession(repo: string, pr: number | null): Promise<string | null>;
+/**
+ * The end of `--here`: notes this cloud session in the PR (if it runs in one and the PR
+ * does not have it yet), so `--teleport` finds it from any machine, and prints the
+ * `Prompt:` line the skill follows. It does not open Claude: it already runs in one.
+ * @param state - The start.
+ * @param pr - The PR.
+ * @param prompt - What the session goes on with.
+ * @example await finishHere(state, 900, prompt)
+ */
+export declare function finishHere(state: StartState, pr: number, prompt: string): Promise<void>;
+/**
+ * The flags with which the cloud session picks the branch: `--new` if the issue has live
+ * branches and a new one was chosen here (`--new`, or `n` in the terminal), `--resume
+ * <branch>` if one of several was chosen. With one live branch resumed, none: the session
+ * resumes it.
+ * @param state - The start.
+ * @returns The flags, with a space before each.
+ * @throws StartError if the branch has characters a shell would read (anyone who can push
+ * names branches).
+ * @example cloudFlags(state) // " --resume fix/214-old"
+ */
+export declare function cloudFlags(state: StartState): string;
+/**
+ * `--cloud` after the yes: opens the cloud session with the skill that starts the issue
+ * there, in the foreground and with the terminal (`claude --cloud` needs one), from the
+ * main checkout. Without `claude` or with `--no-launch`, says how to open it.
+ * @param state - The start.
+ * @param out - Where to write.
+ * @returns The exit code.
+ * @throws StartError if the session does not open.
+ * @example launchCloud(state, out)
+ */
+export declare function launchCloud(state: StartState, out: Output): number;