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

package/dist/cli.d.ts

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * @file `issue-flow` CLI. Warnings on stderr; exits 0 on success, 1 if GitHub, an edit or
+ * the start of an issue failed (or was declined) and 2 on bad usage or a bad
+ * `.agents/flow.json`.
+ */
+import { parseArgs } from "node:util";
+import { type FlowConfig } from "./config.js";
+import { type Output } from "./output.js";
+/** Options of the CLI. */
+declare const OPTIONS: {
+    readonly repo: {
+        readonly type: "string";
+        readonly short: "R";
+    };
+    readonly json: {
+        readonly type: "boolean";
+    };
+    readonly help: {
+        readonly type: "boolean";
+        readonly short: "h";
+    };
+    readonly missing: {
+        readonly type: "boolean";
+    };
+    readonly limit: {
+        readonly type: "string";
+    };
+    readonly namer: {
+        readonly type: "string";
+    };
+    readonly yes: {
+        readonly type: "boolean";
+        readonly short: "y";
+    };
+    readonly "dry-run": {
+        readonly type: "boolean";
+    };
+    readonly branch: {
+        readonly type: "boolean";
+    };
+    readonly resume: {
+        readonly type: "string";
+    };
+    readonly new: {
+        readonly type: "boolean";
+    };
+    readonly "no-launch": {
+        readonly type: "boolean";
+    };
+    readonly "ask-permissions": {
+        readonly type: "boolean";
+    };
+    readonly free: {
+        readonly type: "boolean";
+    };
+    readonly plan: {
+        readonly type: "boolean";
+    };
+    readonly cloud: {
+        readonly type: "boolean";
+    };
+    readonly here: {
+        readonly type: "boolean";
+    };
+    readonly teleport: {
+        readonly type: "boolean";
+    };
+    readonly adopt: {
+        readonly type: "boolean";
+    };
+    readonly only: {
+        readonly type: "string";
+    };
+    readonly path: {
+        readonly type: "string";
+    };
+    readonly next: {
+        readonly type: "boolean";
+    };
+    readonly "no-setup": {
+        readonly type: "boolean";
+    };
+    readonly recipe: {
+        readonly type: "string";
+    };
+    readonly "no-cloud": {
+        readonly type: "boolean";
+    };
+    readonly "no-guard": {
+        readonly type: "boolean";
+    };
+    readonly "no-skills": {
+        readonly type: "boolean";
+    };
+    readonly to: {
+        readonly type: "string";
+    };
+};
+/** The parsed flags. */
+export type Flags = ReturnType<typeof parseArgs<{
+    options: typeof OPTIONS;
+    allowPositionals: true;
+    strict: true;
+}>>["values"];
+/**
+ * The repo of the command: `-R`, then the config's `repo`, then `GH_REPO`, then origin.
+ * @param flag - The `-R` value.
+ * @param config - The config.
+ * @param cwd - Where the command runs.
+ * @returns `owner/repo`.
+ * @throws UsageError if `-R` or `GH_REPO` is malformed; GitHubError if there is no repo.
+ */
+export declare function repoOf(flag: string | undefined, config: FlowConfig, cwd: string): string;
+/**
+ * Checks that only the command's own flags were given.
+ * @param command - The command (`start`, `worktree prune`, `session`).
+ * @param flags - The flags.
+ * @throws UsageError if one belongs to another command.
+ * @example ownFlags("worktree ports", { next: true })
+ */
+export declare function ownFlags(command: string, flags: Flags): void;
+/**
+ * Runs the CLI.
+ * @param argv - Arguments without `node` or the script.
+ * @param out - Where to write.
+ * @param cwd - Where it runs.
+ * @returns The exit code.
+ * @throws UsageError, ConfigError or GitHubError, which the entry point handles.
+ */
+export declare function main(argv: string[], out: Output, cwd: string): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+/**
+ * @file `issue-flow` CLI. Warnings on stderr; exits 0 on success, 1 if GitHub, an edit or
+ * the start of an issue failed (or was declined) and 2 on bad usage or a bad
+ * `.agents/flow.json`.
+ */
+import { parseArgs } from "node:util";
+import { GitHubError, InvalidRepoEnvError, resolveRepo } from "@ramon-sg/github-rest";
+import { branchMissing, branchOf } from "./commands/issue-branch.js";
+import { issueStart } from "./commands/issue-start.js";
+import { ADAPTER_COMMANDS, HOOK_COMMANDS, runAdapter, runHook, runSession, runWorktree, WORKTREE_COMMANDS } from "./cli-worktree.js";
+import { runSetupCommand, SETUP_COMMANDS } from "./cli-setup.js";
+import { prWorktree } from "./commands/pr-worktree.js";
+import { ConfigError } from "./config-base.js";
+import { loadConfig } from "./config.js";
+import { processOutput, UsageError } from "./output.js";
+import { USAGE } from "./usage.js";
+/** Options of the CLI. */
+const OPTIONS = {
+    repo: { type: "string", short: "R" },
+    json: { type: "boolean" },
+    help: { type: "boolean", short: "h" },
+    missing: { type: "boolean" },
+    limit: { type: "string" },
+    namer: { type: "string" },
+    yes: { type: "boolean", short: "y" },
+    "dry-run": { type: "boolean" },
+    branch: { type: "boolean" },
+    resume: { type: "string" },
+    new: { type: "boolean" },
+    "no-launch": { type: "boolean" },
+    "ask-permissions": { type: "boolean" },
+    free: { type: "boolean" },
+    plan: { type: "boolean" },
+    cloud: { type: "boolean" },
+    here: { type: "boolean" },
+    teleport: { type: "boolean" },
+    adopt: { type: "boolean" },
+    only: { type: "string" },
+    path: { type: "string" },
+    next: { type: "boolean" },
+    "no-setup": { type: "boolean" },
+    recipe: { type: "string" },
+    "no-cloud": { type: "boolean" },
+    "no-guard": { type: "boolean" },
+    "no-skills": { type: "boolean" },
+    to: { type: "string" },
+};
+/** Flags each command takes, besides `--repo`, `--help` and `--namer`. */
+const COMMAND_FLAGS = {
+    branch: ["json", "missing", "limit", "yes", "dry-run"],
+    start: [
+        "yes",
+        "dry-run",
+        "branch",
+        "resume",
+        "new",
+        "no-launch",
+        "ask-permissions",
+        "free",
+        "plan",
+        "cloud",
+        "here",
+        "teleport",
+        "adopt",
+    ],
+    "worktree setup": ["only"],
+    "worktree teardown": ["path"],
+    "worktree ports": ["next"],
+    "worktree cleanup": ["path"],
+    "worktree prune": ["only", "yes"],
+    session: [],
+    "pr worktree": ["no-setup"],
+    "adapter setup": ["only"],
+    "adapter issue": [],
+    "adapter archive": [],
+    "hook worktree-create": [],
+    "hook worktree-remove": [],
+    init: ["yes", "recipe", "no-cloud", "no-guard", "no-skills"],
+    doctor: [],
+    upgrade: ["to", "dry-run"],
+};
+/** An issue number: digits only. */
+const NUMBER = /^\d+$/;
+/** A positive whole number. */
+const POSITIVE = /^[1-9]\d*$/;
+/** `owner/repo`. */
+const REPO = /^[^/\s]+\/[^/\s]+$/;
+/**
+ * The repo of the command: `-R`, then the config's `repo`, then `GH_REPO`, then origin.
+ * @param flag - The `-R` value.
+ * @param config - The config.
+ * @param cwd - Where the command runs.
+ * @returns `owner/repo`.
+ * @throws UsageError if `-R` or `GH_REPO` is malformed; GitHubError if there is no repo.
+ */
+export function repoOf(flag, config, cwd) {
+    if (flag !== undefined && !REPO.test(flag))
+        throw new UsageError(`-R expects owner/repo: ${flag}`);
+    let repo;
+    try {
+        repo = resolveRepo(flag ?? config.repo ?? undefined, cwd);
+    }
+    catch (error) {
+        if (error instanceof InvalidRepoEnvError)
+            throw new UsageError(error.message);
+        throw error;
+    }
+    if (repo === null)
+        throw new GitHubError("can't tell which repo this is: run inside a checkout whose origin is on GitHub, pass -R owner/repo, set GH_REPO or \"repo\" in .agents/flow.json.", 0);
+    return repo;
+}
+/**
+ * The `--namer` value.
+ * @param value - The flag, or undefined.
+ * @returns The namer, or undefined to use the config's.
+ * @throws UsageError if it is not claude or title.
+ */
+function namerOf(value) {
+    if (value === undefined || value === "claude" || value === "title")
+        return value;
+    throw new UsageError(`--namer expects claude or title: ${value}`);
+}
+/**
+ * Checks that only the command's own flags were given.
+ * @param command - The command (`start`, `worktree prune`, `session`).
+ * @param flags - The flags.
+ * @throws UsageError if one belongs to another command.
+ * @example ownFlags("worktree ports", { next: true })
+ */
+export function ownFlags(command, flags) {
+    const shared = command === "branch" || command === "start" ? ["repo", "help", "namer"] : ["repo", "help"];
+    const allowed = new Set([...shared, ...(COMMAND_FLAGS[command] ?? [])]);
+    const other = Object.keys(flags).find((flag) => !allowed.has(flag));
+    const name = command === "branch" || command === "start" ? `issue ${command}` : command;
+    if (other !== undefined)
+        throw new UsageError(`--${other} does not go with ${name}.`);
+}
+/**
+ * The permission mode of `issue start`.
+ * @param flags - The flags.
+ * @returns The mode.
+ * @throws UsageError if both were given.
+ */
+function permissionsOf(flags) {
+    if (flags["ask-permissions"] && flags.free)
+        throw new UsageError("use --ask-permissions or --free, not both.");
+    if (flags.free)
+        return "free";
+    return flags["ask-permissions"] ? "ask" : "default";
+}
+/**
+ * Checks the flags of `issue start`.
+ * @param flags - The flags.
+ * @param rest - The positionals after the command.
+ * @returns The issue number.
+ * @throws UsageError if they do not fit.
+ */
+function startArgs(flags, rest) {
+    const [text, ...extra] = rest;
+    if (text === undefined || extra.length > 0 || !NUMBER.test(text))
+        throw new UsageError("issue start needs one issue number.");
+    if (flags.resume !== undefined && flags.new)
+        throw new UsageError("--resume does not go with --new.");
+    const conflicting = flags.branch || flags["dry-run"] || flags.yes || flags.resume !== undefined || flags.new;
+    if (flags.plan && conflicting)
+        throw new UsageError("--plan does not go with --branch, --dry-run, --yes, --resume nor --new.");
+    cloudArgs(flags);
+    return Number(text);
+}
+/** The flags that do not go together with each way of starting, besides each other. */
+const EXCLUSIVE = {
+    cloud: ["branch", "plan", "ask-permissions", "free"],
+    here: ["branch", "plan", "ask-permissions", "free"],
+    teleport: ["plan", "new", "no-launch"],
+    adopt: ["branch", "plan", "resume", "new", "ask-permissions", "free"],
+};
+/**
+ * Checks `--cloud`, `--here`, `--teleport` and `--adopt`: at most one, and none with the
+ * flags it has no use for (only `--teleport` opens Claude here, and it needs a branch).
+ * @param flags - The flags.
+ * @throws UsageError if they do not fit.
+ */
+function cloudArgs(flags) {
+    const ways = Object.keys(EXCLUSIVE).filter((way) => flags[way] === true);
+    if (ways.length > 1)
+        throw new UsageError(`use one of --${ways.join(", --")}, not several.`);
+    const [way] = ways;
+    if (way === undefined)
+        return;
+    const other = EXCLUSIVE[way].find((flag) => flags[flag] !== undefined && flags[flag] !== false);
+    if (other !== undefined)
+        throw new UsageError(`--${way} does not go with --${other}.`);
+}
+/**
+ * Runs the CLI.
+ * @param argv - Arguments without `node` or the script.
+ * @param out - Where to write.
+ * @param cwd - Where it runs.
+ * @returns The exit code.
+ * @throws UsageError, ConfigError or GitHubError, which the entry point handles.
+ */
+export async function main(argv, out, cwd) {
+    const dashes = argv.indexOf("--");
+    const command = dashes === -1 ? null : argv.slice(dashes + 1);
+    let parsed;
+    try {
+        parsed = parseArgs({ args: dashes === -1 ? argv : argv.slice(0, dashes), options: OPTIONS, allowPositionals: true, strict: true });
+    }
+    catch (error) {
+        throw new UsageError(error instanceof Error ? error.message : String(error));
+    }
+    const { values: flags, positionals } = parsed;
+    if (flags.help) {
+        out.stdout(`${USAGE}\n`);
+        return 0;
+    }
+    const [group, sub, ...rest] = positionals;
+    if (command !== null && (group !== "pr" || sub !== "worktree"))
+        throw new UsageError("-- only goes with pr worktree.");
+    if (group === "pr")
+        return runPr(sub, rest, flags, { out, cwd, command });
+    if (group !== undefined && SETUP_COMMANDS.includes(group)) {
+        ownFlags(group, flags);
+        return runSetupCommand(group, flags, [sub, ...rest].filter((item) => item !== undefined), { out, cwd });
+    }
+    if (group === "adapter" || group === "hook") {
+        const commands = group === "adapter" ? ADAPTER_COMMANDS : HOOK_COMMANDS;
+        if (sub === undefined || !commands.includes(sub))
+            throw new UsageError(`${group} expects ${commands.join(", ")}.`);
+        ownFlags(`${group} ${sub}`, flags);
+        if (group === "hook") {
+            if (rest.length > 0)
+                throw new UsageError(`hook ${sub} takes no arguments.`);
+            return runHook(sub, { out, cwd });
+        }
+        return runAdapter(sub, flags, rest, { out, cwd, repo: () => repoOf(flags.repo, loadConfig(cwd), cwd) });
+    }
+    return runIssue(group, sub, rest, flags, { out, cwd });
+}
+/**
+ * Runs `issue-flow pr worktree <n>`.
+ * @param sub - The word after `pr`.
+ * @param rest - The positionals after it.
+ * @param flags - The flags.
+ * @param run - Where it writes and runs, and the command after `--` (null without `--`).
+ * @returns The exit code.
+ * @throws UsageError if the arguments do not fit.
+ */
+async function runPr(sub, rest, flags, run) {
+    if (sub !== "worktree")
+        throw new UsageError("pr expects worktree.");
+    ownFlags("pr worktree", flags);
+    const [text, ...extra] = rest;
+    if (text === undefined || extra.length > 0 || !NUMBER.test(text))
+        throw new UsageError("pr worktree needs one PR number.");
+    const config = loadConfig(run.cwd);
+    return prWorktree({ repo: repoOf(flags.repo, config, run.cwd), config, cwd: run.cwd, number: Number(text), setup: !(flags["no-setup"] ?? false), command: run.command }, run.out);
+}
+/**
+ * Runs the `issue`, `worktree` and `session` commands.
+ * @param group - The first word.
+ * @param command - The second word.
+ * @param rest - The positionals after them.
+ * @param flags - The flags.
+ * @param run - Where it writes and runs.
+ * @returns The exit code.
+ * @throws UsageError, ConfigError or GitHubError.
+ */
+async function runIssue(group, command, rest, flags, run) {
+    const { out, cwd } = run;
+    const positionals = [group, command, ...rest].filter((item) => item !== undefined);
+    if (group === "session") {
+        ownFlags("session", flags);
+        if (positionals.length > 1)
+            throw new UsageError("session takes no arguments.");
+        return runSession(out, cwd);
+    }
+    if (group === "worktree") {
+        if (command === undefined || !WORKTREE_COMMANDS.includes(command))
+            throw new UsageError(`worktree expects ${WORKTREE_COMMANDS.join(", ")}.`);
+        ownFlags(`worktree ${command}`, flags);
+        if (rest.length > 0)
+            throw new UsageError(`worktree ${command} takes no arguments.`);
+        const config = loadConfig(cwd);
+        return runWorktree(command, flags, { out, cwd, config, repo: () => repoOf(flags.repo, config, cwd) });
+    }
+    if (group !== "issue" || (command !== "branch" && command !== "start"))
+        throw new UsageError(group === undefined ? "missing the command." : `unknown command: ${positionals.join(" ")}`);
+    ownFlags(command, flags);
+    if (flags.yes && flags["dry-run"])
+        throw new UsageError("use --yes or --dry-run, not both.");
+    const namer = namerOf(flags.namer);
+    if (command === "start") {
+        const number = startArgs(flags, rest);
+        const permissions = permissionsOf(flags);
+        const config = loadConfig(cwd);
+        return issueStart({
+            repo: repoOf(flags.repo, config, cwd),
+            config,
+            cwd,
+            number,
+            ...(namer === undefined ? {} : { namer }),
+            dryRun: flags["dry-run"] ?? false,
+            yes: flags.yes ?? false,
+            resume: flags.resume ?? null,
+            forceNew: flags.new ?? false,
+            branchMode: flags.branch ?? false,
+            launch: !(flags["no-launch"] ?? false),
+            permissions,
+            plan: flags.plan ?? false,
+            cloud: flags.cloud ?? false,
+            here: flags.here ?? false,
+            teleport: flags.teleport ?? false,
+            adopt: flags.adopt ?? false,
+            remoteSession: process.env.CLAUDE_CODE_REMOTE_SESSION_ID || null,
+        }, out);
+    }
+    if (flags.limit !== undefined && !POSITIVE.test(flags.limit))
+        throw new UsageError(`--limit expects a positive number: ${flags.limit}`);
+    if (flags.missing && rest.length > 0)
+        throw new UsageError("--missing takes no issue numbers.");
+    if (!flags.missing && (rest.length === 0 || !rest.every((text) => NUMBER.test(text))))
+        throw new UsageError("issue branch needs issue numbers, or --missing.");
+    if (!flags.missing && (flags.yes || flags["dry-run"] || flags.limit !== undefined))
+        throw new UsageError("--yes, --dry-run and --limit go with --missing.");
+    const config = loadConfig(cwd);
+    const options = {
+        repo: repoOf(flags.repo, config, cwd),
+        config,
+        cwd,
+        ...(namer === undefined ? {} : { namer }),
+        json: flags.json ?? false,
+        ...(flags.limit === undefined ? {} : { limit: Number(flags.limit) }),
+        yes: flags.yes ?? false,
+        dryRun: flags["dry-run"] ?? false,
+    };
+    return flags.missing ? branchMissing(options, out) : branchOf(rest.map(Number), options, out);
+}
+const out = processOutput();
+main(process.argv.slice(2), out, process.cwd()).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    const usage = error instanceof UsageError;
+    const config = error instanceof ConfigError;
+    out.stderr(`issue-flow: ${error instanceof Error ? error.message : String(error)}\n${usage ? `${USAGE}\n` : ""}`);
+    process.exitCode = usage || config ? 2 : 1;
+});

package/dist/commands/adapter.d.ts

@@ -0,0 +1,49 @@
+import { type FlowConfig } from "../config.js";
+import { type Output } from "../output.js";
+/** Orca's CLI, which knows which issue a workspace came from; `ISSUE_FLOW_ORCA_CLI` changes it. */
+export declare const ORCA_CLI = "orca";
+/** Options of `issue-flow adapter`. */
+export interface AdapterOptions {
+    config: FlowConfig;
+    cwd: string;
+    only: string | null;
+    url: string | null;
+    repo: () => string;
+}
+/**
+ * The number of an issue of the repo by its URL; a slash, an anchor or a query may follow.
+ * @param url - The URL.
+ * @param repo - `owner/repo`.
+ * @returns The number, or null if it is not an issue of the repo.
+ * @example issueOfUrl("https://github.com/acme/widgets/issues/214#top", "acme/widgets") // 214
+ */
+export declare function issueOfUrl(url: string, repo: string): number | null;
+/**
+ * `adapter setup [--only <step>]`.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns Always 0.
+ * @throws StartError outside git; UsageError if `--only` names no step.
+ * @example await adapterSetup(options, out)
+ */
+export declare function adapterSetup(options: AdapterOptions, out: Output): Promise<number>;
+/**
+ * `adapter issue [<url>]`.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns The code of `issue start` with a URL, 0 without one.
+ * @throws StartError outside git or if the URL is not an issue of the repo.
+ * @example await adapterIssue({ ...options, url: "https://github.com/acme/widgets/issues/214" }, out)
+ */
+export declare function adapterIssue(options: AdapterOptions, out: Output): Promise<number>;
+/**
+ * `adapter archive`. With git's link broken (the main checkout moved, or its record of the
+ * worktree was deleted) it cannot tell a worktree, but it still frees the ports and the
+ * Docker of the folder, with the config of the main checkout Orca or Paseo name: without
+ * git it cannot be the main checkout, which they never archive.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns Always 0.
+ * @example await adapterArchive(options, out)
+ */
+export declare function adapterArchive(options: AdapterOptions, out: Output): Promise<number>;