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

package/dist/worktree-config.d.ts

@@ -0,0 +1,35 @@
+/** A command of the setup or the teardown of a worktree. */
+export interface Step {
+    name: string;
+    run: string;
+    trusted: boolean;
+    once: boolean;
+}
+/** The range of ports split in blocks, one block per worktree. */
+export interface PortsConfig {
+    start: number;
+    blockSize: number;
+    blocks: number;
+}
+/** The `worktrees` section, with its defaults. */
+export interface WorktreesConfig {
+    dir: string;
+    setup: Step[];
+    teardown: Step[];
+    ports: PortsConfig | null;
+    dockerProjects: string[];
+}
+/**
+ * The ports with `"ports": true`: 1000 blocks of 10 from 20000, far from the usual ones
+ * (3000, 9000), from Docker's ephemeral ones (from 32768) and the same as Abastio's.
+ */
+export declare const DEFAULT_PORTS: PortsConfig;
+/**
+ * The `worktrees` section, with its defaults.
+ * @param value - The section, or undefined.
+ * @param fallback - The defaults.
+ * @returns The section.
+ * @throws ConfigError if something is invalid.
+ * @example worktreesSection({ ports: true }, defaults).ports // { start: 20000, blockSize: 10, blocks: 1000 }
+ */
+export declare function worktreesSection(value: unknown, fallback: WorktreesConfig): WorktreesConfig;

package/dist/worktree-config.js

@@ -0,0 +1,139 @@
+/**
+ * @file The `worktrees` section of `.agents/flow.json`: where worktrees go, the steps that
+ * prepare one and clean it before deleting it, its block of ports, and the prefixes of its
+ * Docker Compose projects. Everything that belongs to one project (installing, a database,
+ * Docker) is a step here; `issue-flow` only runs them.
+ */
+import { CONFIG_PATH, ConfigError, isObject, onlyKeys, text } from "./config-base.js";
+/**
+ * The ports with `"ports": true`: 1000 blocks of 10 from 20000, far from the usual ones
+ * (3000, 9000), from Docker's ephemeral ones (from 32768) and the same as Abastio's.
+ */
+export const DEFAULT_PORTS = { start: 20000, blockSize: 10, blocks: 1000 };
+/** The first port a block can use: below it, ports need root. */
+const MIN_PORT = 1024;
+/** One past the last port. */
+const PORT_LIMIT = 65536;
+/** A step's name: lowercase, for `--only` and the marker of `once`. */
+const STEP_NAME = /^[a-z0-9][a-z0-9-]*$/;
+/** A Docker Compose project prefix, as Compose accepts project names. */
+const PROJECT = /^[a-z0-9][a-z0-9_-]*$/;
+/**
+ * An optional boolean of a step.
+ * @param value - The value, or undefined.
+ * @param where - Its path, for the error.
+ * @returns The value, false if missing.
+ * @throws ConfigError if it is not a boolean.
+ */
+function flag(value, where) {
+    if (value === undefined)
+        return false;
+    if (typeof value !== "boolean")
+        throw new ConfigError(`${CONFIG_PATH}: "${where}" must be true or false.`);
+    return value;
+}
+/**
+ * A list of steps. A teardown step has no `trusted` nor `once`: it cleans up, whatever the
+ * code.
+ * @param value - The list, or undefined.
+ * @param where - Its path (`worktrees.setup`).
+ * @param teardown - Whether these are teardown steps.
+ * @returns The steps.
+ * @throws ConfigError if a step is invalid or two share a name.
+ */
+function steps(value, where, teardown) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new ConfigError(`${CONFIG_PATH}: "${where}" must be a list of steps.`);
+    const names = new Set();
+    return value.map((raw, index) => {
+        const at = `${where}[${index}]`;
+        if (!isObject(raw))
+            throw new ConfigError(`${CONFIG_PATH}: "${at}" must be an object with "name" and "run".`);
+        onlyKeys(raw, teardown ? ["name", "run"] : ["name", "run", "trusted", "once"], at);
+        const name = text(raw.name, `${at}.name`, null);
+        if (name === null || !STEP_NAME.test(name))
+            throw new ConfigError(`${CONFIG_PATH}: "${at}.name" must be lowercase letters, digits and dashes.`);
+        if (names.has(name))
+            throw new ConfigError(`${CONFIG_PATH}: "${where}" has two steps named "${name}".`);
+        names.add(name);
+        const run = text(raw.run, `${at}.run`, null);
+        if (run === null)
+            throw new ConfigError(`${CONFIG_PATH}: "${at}.run" must be a non-empty string.`);
+        return { name, run, trusted: flag(raw.trusted, `${at}.trusted`), once: flag(raw.once, `${at}.once`) };
+    });
+}
+/**
+ * A whole number of the ports.
+ * @param value - The value, or undefined.
+ * @param key - Its key.
+ * @returns The number, or the default's.
+ * @throws ConfigError if it is not a positive whole number.
+ */
+function count(value, key) {
+    if (value === undefined)
+        return DEFAULT_PORTS[key];
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1)
+        throw new ConfigError(`${CONFIG_PATH}: "worktrees.ports.${key}" must be a positive whole number.`);
+    return value;
+}
+/**
+ * The ports: off (absent or false), the defaults (true), or a range. Its blocks are split
+ * in two halves, one for macOS and one for the rest, so they must be even.
+ * @param value - The value, or undefined.
+ * @returns The ports, or null if off.
+ * @throws ConfigError if the range does not fit.
+ */
+function ports(value) {
+    if (value === undefined || value === false)
+        return null;
+    if (value === true)
+        return DEFAULT_PORTS;
+    if (!isObject(value))
+        throw new ConfigError(`${CONFIG_PATH}: "worktrees.ports" must be true, false or an object.`);
+    onlyKeys(value, ["start", "blockSize", "blocks"], "worktrees.ports");
+    const range = { start: count(value.start, "start"), blockSize: count(value.blockSize, "blockSize"), blocks: count(value.blocks, "blocks") };
+    if (range.blocks % 2 !== 0)
+        throw new ConfigError(`${CONFIG_PATH}: "worktrees.ports.blocks" must be even.`);
+    if (range.start < MIN_PORT || range.start + range.blockSize * range.blocks > PORT_LIMIT)
+        throw new ConfigError(`${CONFIG_PATH}: "worktrees.ports" must stay between ${MIN_PORT} and ${PORT_LIMIT - 1}.`);
+    return range;
+}
+/**
+ * The Docker Compose project prefixes of a worktree (each worktree's project is
+ * `<prefix>-<folder>-<hash>`); the cleanup only ever deletes projects that start with one.
+ * @param value - The list, or undefined.
+ * @returns The prefixes.
+ * @throws ConfigError if one is not a valid project name.
+ */
+function dockerProjects(value) {
+    if (value === undefined)
+        return [];
+    const valid = Array.isArray(value) && value.every((item) => typeof item === "string" && PROJECT.test(item));
+    if (!valid)
+        throw new ConfigError(`${CONFIG_PATH}: "worktrees.dockerProjects" must be a list of Compose project prefixes (lowercase letters, digits, - and _).`);
+    return value;
+}
+/**
+ * The `worktrees` section, with its defaults.
+ * @param value - The section, or undefined.
+ * @param fallback - The defaults.
+ * @returns The section.
+ * @throws ConfigError if something is invalid.
+ * @example worktreesSection({ ports: true }, defaults).ports // { start: 20000, blockSize: 10, blocks: 1000 }
+ */
+export function worktreesSection(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!isObject(value))
+        throw new ConfigError(`${CONFIG_PATH}: "worktrees" must be an object.`);
+    onlyKeys(value, ["dir", "setup", "teardown", "ports", "dockerProjects"], "worktrees");
+    return {
+        dir: text(value.dir, "worktrees.dir", fallback.dir),
+        setup: steps(value.setup, "worktrees.setup", false),
+        teardown: steps(value.teardown, "worktrees.teardown", true),
+        ports: ports(value.ports),
+        dockerProjects: dockerProjects(value.dockerProjects),
+    };
+}

package/dist/worktree-steps.d.ts

@@ -0,0 +1,53 @@
+import type { FlowConfig } from "./config.js";
+import { type Output } from "./output.js";
+/** Folder, in the worktree's git dir, with a mark per `once` step that worked. */
+export declare const SETUP_MARKS_DIR = "issue-flow-setup";
+/** Where the steps run, and with what. */
+export interface StepPlace {
+    root: string;
+    mainRoot: string;
+    base: string;
+    config: FlowConfig;
+    out: Output;
+    remote: boolean;
+}
+/**
+ * Whether the worktree's code can run an install: its HEAD is in `origin/<base>` and it has
+ * no changes to tracked files. A branch of someone else could put anything in the scripts
+ * an install runs.
+ * @param root - The worktree.
+ * @param base - The base branch.
+ * @returns True if it is trusted.
+ * @example trustedCode(wt, "main")
+ */
+export declare function trustedCode(root: string, base: string): boolean;
+/**
+ * The environment of a step: the worktree, the main checkout, the first port of its block
+ * (if the config has ports) and the suffix of its Docker projects (`<prefix>-<suffix>`).
+ * @param place - Where.
+ * @param port - The block's first port, or null.
+ * @returns The variables.
+ * @example stepEnv(place, 21430).ISSUE_FLOW_PORT_BASE // "21430"
+ */
+export declare function stepEnv(place: StepPlace, port: number | null): Record<string, string>;
+/**
+ * Prepares a worktree with the setup steps: one (`only`) or all, in order. In the main
+ * checkout it does nothing, except in a cloud session, whose checkout is not a worktree. It
+ * fixes the block of ports first, so the steps (and the apps after them) agree on it.
+ * Never stops on a failed step: it says what to run and goes on.
+ * @param place - Where.
+ * @param only - The step to run, or null for all.
+ * @returns True if every step that ran worked.
+ * @example await runSetup(place, null)
+ */
+export declare function runSetup(place: StepPlace, only: string | null): Promise<boolean>;
+/**
+ * Cleans a worktree before it is deleted: its apps and then its teardown steps (if the
+ * folder still exists), so a step that drops a database finds nobody connected; then its
+ * block of ports and its Docker. Never stops: a step or a Docker that
+ * fails gets a warning, because a cleanup cannot block the deletion.
+ * @param place - Where; the folder may be gone already.
+ * @returns True if nothing failed.
+ * @example await teardownWorktree(place)
+ */
+export declare function teardownWorktree(place: StepPlace): Promise<boolean>;

package/dist/worktree-steps.js

@@ -0,0 +1,210 @@
+/**
+ * @file Runs the steps of `worktrees.setup` and `worktrees.teardown` in a worktree. The
+ * steps come from the main checkout's config, not the worktree's, so a branch cannot add
+ * commands to its own setup. A `trusted` step (an install, which runs the lifecycle scripts
+ * of `package.json`) runs only if the worktree's code is in `origin/<base>` and has no
+ * changes; a `once` step leaves a mark when it works and is not repeated. Two setups of one
+ * worktree at a time (the tool's and the session hook's) take turns with a lock. Each step
+ * gets the worktree, the main checkout, its block of ports and its Docker suffix in the
+ * environment. Ported from Abastio's `scripts/worktree-setup.sh` and `worktree-cleanup.sh`.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { dockerCleanup, sanitizeLabel } from "./docker.js";
+import { git, isClean } from "./git.js";
+import { warn } from "./output.js";
+import { claimPortBase, portBase, releasePortClaims, sha256 } from "./ports.js";
+import { stopApps } from "./stop-apps.js";
+/** Folder, in the worktree's git dir, with a mark per `once` step that worked. */
+export const SETUP_MARKS_DIR = "issue-flow-setup";
+/** The lock of the setup, in the worktree's git dir. */
+const LOCK_NAME = "issue-flow-setup.lock";
+/** How old a lock without a pid must be to count as left by a process that died at once. */
+const LOCK_NO_PID_MS = 10_000;
+/** Seconds a setup waits for another one of the same worktree. */
+const LOCK_WAIT_SECONDS = 600;
+/** Hex digits of the hash in the Docker suffix, as in `dockerProject`. */
+const SUFFIX_HASH = 6;
+/**
+ * The worktree's own git dir.
+ * @param root - The worktree.
+ * @returns The path.
+ */
+function gitDir(root) {
+    return git(root, ["rev-parse", "--path-format=absolute", "--git-dir"]).out;
+}
+/**
+ * Whether the worktree's code can run an install: its HEAD is in `origin/<base>` and it has
+ * no changes to tracked files. A branch of someone else could put anything in the scripts
+ * an install runs.
+ * @param root - The worktree.
+ * @param base - The base branch.
+ * @returns True if it is trusted.
+ * @example trustedCode(wt, "main")
+ */
+export function trustedCode(root, base) {
+    return git(root, ["merge-base", "--is-ancestor", "HEAD", `origin/${base}`]).ok && isClean(root, false);
+}
+/**
+ * The environment of a step: the worktree, the main checkout, the first port of its block
+ * (if the config has ports) and the suffix of its Docker projects (`<prefix>-<suffix>`).
+ * @param place - Where.
+ * @param port - The block's first port, or null.
+ * @returns The variables.
+ * @example stepEnv(place, 21430).ISSUE_FLOW_PORT_BASE // "21430"
+ */
+export function stepEnv(place, port) {
+    return {
+        ISSUE_FLOW_WORKTREE: place.root,
+        ISSUE_FLOW_MAIN_ROOT: place.mainRoot,
+        ISSUE_FLOW_DOCKER_SUFFIX: `${sanitizeLabel(basename(place.root))}-${sha256(place.root).slice(0, SUFFIX_HASH)}`,
+        ...(port === null ? {} : { ISSUE_FLOW_PORT_BASE: String(port) }),
+    };
+}
+/**
+ * Runs one step with `sh -c` in the worktree. Its output goes to stderr, so the stdout of
+ * the session hook stays for what Claude must read.
+ * @param place - Where.
+ * @param step - The step.
+ * @param env - The step's variables.
+ * @returns True if it worked.
+ */
+function runStep(place, step, env) {
+    const result = spawnSync("sh", ["-c", step.run], { cwd: place.root, env: { ...process.env, ...env }, stdio: ["ignore", 2, 2] });
+    if (result.status === 0)
+        return true;
+    warn(place.out, `step "${step.name}" failed${result.status === null ? "" : ` (exit ${result.status})`}; run '${step.run}' in ${place.root}.`);
+    return false;
+}
+/**
+ * Takes the setup's lock: a folder with the pid. A lock of a process that is gone is taken
+ * over, and so is one without a pid that is some seconds old (its process died before
+ * writing it); another one is waited for.
+ * @param lock - The folder.
+ * @param out - Where the wait is said.
+ * @returns True if it was taken, false if it waited too long.
+ */
+async function takeLock(lock, out) {
+    for (let waited = 0; waited < LOCK_WAIT_SECONDS; waited += 1) {
+        try {
+            mkdirSync(lock);
+            writeFileSync(join(lock, "pid"), `${process.pid}\n`);
+            return true;
+        }
+        catch {
+            const pidFile = join(lock, "pid");
+            const owner = Number(existsSync(pidFile) ? readFileSync(pidFile, "utf8").trim() : "");
+            const orphan = !existsSync(pidFile) && existsSync(lock) && Date.now() - statSync(lock).mtimeMs > LOCK_NO_PID_MS;
+            if (orphan || (Number.isInteger(owner) && owner > 0 && !alive(owner))) {
+                rmSync(lock, { recursive: true, force: true });
+                continue;
+            }
+            if (waited === 0)
+                warn(out, "another setup is preparing this worktree; waiting for it…");
+            await sleep(1000);
+        }
+    }
+    return false;
+}
+/**
+ * Whether a process is alive.
+ * @param pid - The pid.
+ * @returns True if it is (or it is another user's).
+ */
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/**
+ * Prepares a worktree with the setup steps: one (`only`) or all, in order. In the main
+ * checkout it does nothing, except in a cloud session, whose checkout is not a worktree. It
+ * fixes the block of ports first, so the steps (and the apps after them) agree on it.
+ * Never stops on a failed step: it says what to run and goes on.
+ * @param place - Where.
+ * @param only - The step to run, or null for all.
+ * @returns True if every step that ran worked.
+ * @example await runSetup(place, null)
+ */
+export async function runSetup(place, only) {
+    const { root, mainRoot, config, out } = place;
+    if (root === mainRoot && !place.remote)
+        return true;
+    const chosen = config.worktrees.setup.filter((step) => only === null || step.name === only);
+    const ports = config.worktrees.ports;
+    const port = ports === null ? null : await claimPortBase(ports, root, null);
+    if (ports !== null && port === null)
+        warn(out, "no block of ports is free on this machine; delete worktrees you no longer use.");
+    if (chosen.length === 0)
+        return true;
+    const lock = join(gitDir(root), LOCK_NAME);
+    if (!(await takeLock(lock, out))) {
+        warn(out, `another setup has been running for over ${LOCK_WAIT_SECONDS} s; nothing ran. Run 'issue-flow worktree setup' in ${root} when it ends.`);
+        return false;
+    }
+    try {
+        return chosen.map((step) => setupStep(place, step, stepEnv(place, port))).every(Boolean);
+    }
+    finally {
+        rmSync(lock, { recursive: true, force: true });
+    }
+}
+/**
+ * One setup step: skipped if it is `once` and already worked, or `trusted` and the code is
+ * not; run otherwise, leaving its mark if it is `once`.
+ * @param place - Where.
+ * @param step - The step.
+ * @param env - Its variables.
+ * @returns True unless it ran and failed.
+ */
+function setupStep(place, step, env) {
+    const mark = join(gitDir(place.root), SETUP_MARKS_DIR, step.name);
+    if (step.once && existsSync(mark))
+        return true;
+    if (step.trusted && !place.remote && !trustedCode(place.root, place.base)) {
+        warn(place.out, `skipped "${step.name}": this worktree has code that is not in origin/${place.base}. Check it and run '${step.run}' in ${place.root} if you trust it.`);
+        return true;
+    }
+    if (!runStep(place, step, env))
+        return false;
+    if (step.once) {
+        mkdirSync(join(gitDir(place.root), SETUP_MARKS_DIR), { recursive: true });
+        writeFileSync(mark, "");
+    }
+    return true;
+}
+/**
+ * Cleans a worktree before it is deleted: its apps and then its teardown steps (if the
+ * folder still exists), so a step that drops a database finds nobody connected; then its
+ * block of ports and its Docker. Never stops: a step or a Docker that
+ * fails gets a warning, because a cleanup cannot block the deletion.
+ * @param place - Where; the folder may be gone already.
+ * @returns True if nothing failed.
+ * @example await teardownWorktree(place)
+ */
+export async function teardownWorktree(place) {
+    const { root, config, out } = place;
+    const ports = config.worktrees.ports;
+    let ok = true;
+    if (existsSync(root)) {
+        const base = ports === null ? null : portBase(ports, root);
+        if (ports !== null && base !== null)
+            await stopApps(ports, base, root, out);
+        const env = stepEnv(place, base);
+        for (const step of config.worktrees.teardown)
+            ok = runStep(place, step, env) && ok;
+    }
+    releasePortClaims(root, null);
+    const docker = dockerCleanup(config.worktrees.dockerProjects, root);
+    if (!docker.dockerRunning)
+        warn(out, "Docker is not running; the worktree's containers stay. Start Docker and run 'issue-flow worktree cleanup'.");
+    if (docker.failed.length > 0)
+        warn(out, `could not delete the Docker projects ${docker.failed.join(", ")}; see what holds them with 'docker ps -a --filter label=com.docker.compose.project=<project>'.`);
+    return ok && docker.dockerRunning && docker.failed.length === 0;
+}

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@ramon-sg/issue-flow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Issue-to-PR workflow for any repo: names each issue's branch, creates its worktree, opens the draft PR and launches Claude Code, locally and in Claude's cloud.",
+  "license": "MIT",
+  "type": "module",
+  "bin": { "issue-flow": "dist/cli.js" },
+  "files": ["dist", "schema.json", "recipes"],
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public", "provenance": true },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ramon-sg/issue-flow.git"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test test/*.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": { "@ramon-sg/github-rest": "0.2.1" },
+  "devDependencies": { "@ramon-sg/skills-manager": "1.1.0", "@types/node": "^24.0.0", "typescript": "^5.9.3" }
+}

package/recipes/bun.json

@@ -0,0 +1,5 @@
+{
+  "description": "Installs the dependencies with bun in each worktree, only when its code is in the base branch.",
+  "detect": ["bun.lock", "bun.lockb"],
+  "config": { "worktrees": { "setup": [{ "name": "deps", "run": "bun install --frozen-lockfile", "trusted": true }] } }
+}

package/recipes/direnv.json

@@ -0,0 +1,17 @@
+{
+  "description": "Allows the .envrc of each worktree whose code is in the base branch, so direnv (and the secrets it loads, Infisical for example) works there.",
+  "detect": [
+    ".envrc"
+  ],
+  "config": {
+    "worktrees": {
+      "setup": [
+        {
+          "name": "direnv",
+          "run": "command -v direnv >/dev/null || { echo 'direnv is not installed: .envrc not allowed'; exit 0; }; direnv allow",
+          "trusted": true
+        }
+      ]
+    }
+  }
+}

package/recipes/docker-compose.json

@@ -0,0 +1,30 @@
+{
+  "description": "Gives each worktree its own Docker Compose project and block of ports: up on setup (only when its code is in the base branch), down with its volumes on teardown. The compose file takes its ports from ISSUE_FLOW_PORT_BASE.",
+  "detect": [
+    "compose.yaml",
+    "compose.yml",
+    "docker-compose.yml",
+    "docker-compose.yaml"
+  ],
+  "config": {
+    "worktrees": {
+      "setup": [
+        {
+          "name": "docker",
+          "run": "docker compose -p {project}-$ISSUE_FLOW_DOCKER_SUFFIX up -d",
+          "trusted": true
+        }
+      ],
+      "teardown": [
+        {
+          "name": "docker",
+          "run": "docker compose -p {project}-$ISSUE_FLOW_DOCKER_SUFFIX down -v"
+        }
+      ],
+      "ports": true,
+      "dockerProjects": [
+        "{project}"
+      ]
+    }
+  }
+}

package/recipes/npm.json

@@ -0,0 +1,5 @@
+{
+  "description": "Installs the dependencies with npm ci in each worktree, only when its code is in the base branch.",
+  "detect": ["package-lock.json"],
+  "config": { "worktrees": { "setup": [{ "name": "deps", "run": "npm ci", "trusted": true }] } }
+}

package/recipes/pnpm.json

@@ -0,0 +1,5 @@
+{
+  "description": "Installs the dependencies with pnpm in each worktree, only when its code is in the base branch.",
+  "detect": ["pnpm-lock.yaml"],
+  "config": { "worktrees": { "setup": [{ "name": "deps", "run": "pnpm install --frozen-lockfile", "trusted": true }] } }
+}

package/recipes/staging-main.json

@@ -0,0 +1,5 @@
+{
+  "description": "Work starts from staging and PRs go there; main only gets releases.",
+  "detect": [],
+  "config": { "baseBranch": "staging" }
+}