@ramon-sg/issue-flow 0.3.1 → 0.3.2

package/README.md

@@ -75,7 +75,7 @@ Qué hace, en orden:
    - Si el PR se mergeó y no queda trabajo sin pushear, ofrece borrar el worktree y la rama.
    - Si no, dice cómo retomar.
 
-**Permisos:** si el repo tiene [`claude-repo-guard`](https://github.com/ramon-sg/claude-repo-guard), Claude se abre en modo auto con su contexto (lo mismo que `claude:auto`). Con `--ask-permissions` se abre con tus settings, y con `--free` sin sandbox ni preguntas (como `claude:free`). Sin `claude-repo-guard`, se abre con tus settings. `--plan` devuelve esos mismos argumentos en `claudeArgs`.
+**Permisos:** si el repo tiene [`claude-repo-guard`](https://github.com/ramon-sg/claude-repo-guard), Claude se abre en modo auto con su contexto (lo mismo que `claude:auto`). Con `--ask-permissions` se abre con tus settings, y con `--free` sin sandbox ni preguntas (como `claude:free`). Sin `claude-repo-guard`, se abre con tus settings. `--plan` devuelve esos mismos argumentos en `claudeArgs`. El atajo es `npm run issue:start:free 42`. Con npm, las opciones van después de `--` (`npm run issue:start -- 42 --free`); con pnpm, bun o yarn no hace falta. La tabla de cada administrador está en [Flujos](docs/flujos.md#administradores). `issue-flow issue start --help` explica cada opción.
 
 ### Con la nube y con otras herramientas
 
@@ -196,7 +196,7 @@ npx @ramon-sg/issue-flow doctor                   # revisa que el repo esté com
 `apply` deja el repo como lo pide la versión que corre, y correrlo otra vez no cambia nada. La versión la elige quien actualiza, al elegir cuál correr: `apply` no cambia la versión de ningún otro paquete.
 
 1. **`.agents/flow.json`:** si no existe, lo crea con el `$schema` de esta versión y, si el repo tiene `paseo.json`, con su plantilla de rama y sus tipos. Esa primera vez propone las recetas que sugieren los archivos del repo (con `--yes`, todas; sin terminal y sin `--yes`, no escribe nada y lo dice). Si ya existe, no pregunta: corre las migraciones de esta versión, mueve el `$schema` y suma las recetas de `--recipe`.
-2. **`package.json`:** `@ramon-sg/issue-flow` en esta versión, exacta. `@ramon-sg/github-rest` y los scripts `issue:start`, `worktree:prune` y `pr:worktree` solo si faltan: un `github-rest` que el repo ya tiene se queda, con un aviso si no llega a la versión que necesitan las skills.
+2. **`package.json`:** `@ramon-sg/issue-flow` en esta versión, exacta. `@ramon-sg/github-rest` y los scripts `issue:start`, `issue:start:free`, `worktree:prune` y `pr:worktree` solo si faltan (`issue:start:free` no se agrega si el repo tiene su propio `issue:start`, que se saltaría): un `github-rest` que el repo ya tiene se queda, con un aviso si no llega a la versión que necesitan las skills.
 3. **`.claude/settings.json`:** los hooks `SessionStart`, `WorktreeCreate` y `WorktreeRemove`, fijados a esta versión y con 600 segundos. El de `SessionStart` corre `claude-cloud session` en la nube, así que un hook propio de `claude-cloud` se quita para que no corra dos veces.
 
 No consulta npm, y nunca baja de versión: si el repo ya tiene una issue-flow más nueva (por ejemplo, `package.json` subido a mano antes del `install`), o un rango como `^0.2.6`, se detiene y dice qué correr. `--json` da `{ version, changes, kept, written, next }`. Sale con 0 si aplicó o no había nada que hacer, y con 1 si se negó o tenía que preguntar y no pudo.

package/dist/cli-flags.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @file The CLI's flags and which command takes each one, apart from cli.ts (which runs on
+ * import) so the tests can check the usage text against them.
+ */
+import type { parseArgs } from "node:util";
+/** Options of the CLI. */
+export 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 update: {
+        readonly type: "boolean";
+    };
+};
+/** The parsed flags. */
+export type Flags = ReturnType<typeof parseArgs<{
+    options: typeof OPTIONS;
+    allowPositionals: true;
+    strict: true;
+}>>["values"];
+/** Flags each command takes, besides `--repo`, `--help` and `--namer`. */
+export declare const COMMAND_FLAGS: Record<string, (keyof Flags)[]>;

package/dist/cli-flags.js

@@ -0,0 +1,64 @@
+/** Options of the CLI. */
+export 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" },
+    update: { type: "boolean" },
+};
+/** Flags each command takes, besides `--repo`, `--help` and `--namer`. */
+export 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": [],
+    apply: ["yes", "dry-run", "json", "recipe"],
+    init: ["yes", "recipe"],
+    doctor: ["json"],
+    upgrade: ["dry-run"],
+    "labels sync": ["update", "dry-run", "json"],
+};

package/dist/cli-setup.d.ts

@@ -2,7 +2,7 @@
  * @file The `apply` and `doctor` commands of the CLI, and `init` and `upgrade`, which run
  * `apply` now and say so: their flags turned into options.
  */
-import type { Flags } from "./cli.js";
+import type { Flags } from "./cli-flags.js";
 import { type Output } from "./output.js";
 /** The setup commands. */
 export declare const SETUP_COMMANDS: string[];

package/dist/cli-worktree.d.ts

@@ -2,7 +2,7 @@
  * @file The `worktree`, `session`, `adapter` and `hook` commands of the CLI: their flags
  * turned into options.
  */
-import type { Flags } from "./cli.js";
+import type { Flags } from "./cli-flags.js";
 import { type FlowConfig } from "./config.js";
 import { type Output } from "./output.js";
 /** The commands of `issue-flow worktree`. */

package/dist/cli.d.ts

@@ -1,99 +1,7 @@
 #!/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 Flags } from "./cli-flags.js";
 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 update: {
-        readonly type: "boolean";
-    };
-};
-/** 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.
@@ -111,6 +19,19 @@ export declare function repoOf(flag: string | undefined, config: FlowConfig, cwd
  * @example ownFlags("worktree ports", { next: true })
  */
 export declare function ownFlags(command: string, flags: Flags): void;
+/**
+ * Splits the arguments from the command that `pr worktree` runs after `--`. Anywhere else
+ * a `--` is dropped, since pnpm passes it on as it is (`pnpm issue:start -- 42` runs
+ * `issue start -- 42`), and so is one right after `pr worktree` with no PR number before it
+ * (`pnpm pr:worktree -- 5`).
+ * @param argv - The arguments.
+ * @returns The arguments for issue-flow, and the command, or null if there is none.
+ * @example splitArgs(["pr", "worktree", "5", "--", "npm", "test"]) // { args: ["pr", "worktree", "5"], command: ["npm", "test"] }
+ */
+export declare function splitArgs(argv: string[]): {
+    args: string[];
+    command: string[] | null;
+};
 /**
  * Runs the CLI.
  * @param argv - Arguments without `node` or the script.
@@ -120,4 +41,3 @@ export declare function ownFlags(command: string, flags: Flags): void;
  * @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

@@ -5,6 +5,7 @@
  * `.agents/flow.json`.
  */
 import { parseArgs } from "node:util";
+import { COMMAND_FLAGS, OPTIONS } from "./cli-flags.js";
 import { GitHubError, InvalidRepoEnvError, resolveRepo } from "@ramon-sg/github-rest";
 import { branchMissing, branchOf } from "./commands/issue-branch.js";
 import { issueStart } from "./commands/issue-start.js";
@@ -15,71 +16,7 @@ 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" },
-    update: { type: "boolean" },
-};
-/** 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": [],
-    apply: ["yes", "dry-run", "json", "recipe"],
-    init: ["yes", "recipe"],
-    doctor: ["json"],
-    upgrade: ["dry-run"],
-    "labels sync": ["update", "dry-run", "json"],
-};
+import { usageOf } from "./usage.js";
 /** An issue number: digits only. */
 const NUMBER = /^\d+$/;
 /** A positive whole number. */
@@ -192,6 +129,41 @@ function cloudArgs(flags) {
     if (other !== undefined)
         throw new UsageError(`--${way} does not go with --${other}.`);
 }
+/**
+ * The positionals of some arguments, with each flag's value left out (`-R o/r` is a flag).
+ * @param args - The arguments.
+ * @returns The positionals.
+ */
+function positionalsOf(args) {
+    return parseArgs({ args, options: OPTIONS, allowPositionals: true, strict: false }).positionals;
+}
+/**
+ * Splits the arguments from the command that `pr worktree` runs after `--`. Anywhere else
+ * a `--` is dropped, since pnpm passes it on as it is (`pnpm issue:start -- 42` runs
+ * `issue start -- 42`), and so is one right after `pr worktree` with no PR number before it
+ * (`pnpm pr:worktree -- 5`).
+ * @param argv - The arguments.
+ * @returns The arguments for issue-flow, and the command, or null if there is none.
+ * @example splitArgs(["pr", "worktree", "5", "--", "npm", "test"]) // { args: ["pr", "worktree", "5"], command: ["npm", "test"] }
+ */
+export function splitArgs(argv) {
+    let args = argv;
+    for (let dashes = args.indexOf("--"); dashes !== -1; dashes = args.indexOf("--")) {
+        const words = positionalsOf(args.slice(0, dashes));
+        if (words[0] === "pr" && words[1] === "worktree" && words.length > 2)
+            return { args: args.slice(0, dashes), command: args.slice(dashes + 1) };
+        args = args.filter((_, index) => index !== dashes);
+    }
+    return { args, command: null };
+}
+/**
+ * The command's words, as `usageOf` takes them.
+ * @param argv - The arguments.
+ * @returns The positionals, without the flags nor their values.
+ */
+function commandWords(argv) {
+    return positionalsOf(splitArgs(argv).args);
+}
 /**
  * Runs the CLI.
  * @param argv - Arguments without `node` or the script.
@@ -201,23 +173,20 @@ function cloudArgs(flags) {
  * @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);
+    const { args, command } = splitArgs(argv);
     let parsed;
     try {
-        parsed = parseArgs({ args: dashes === -1 ? argv : argv.slice(0, dashes), options: OPTIONS, allowPositionals: true, strict: true });
+        parsed = parseArgs({ args, 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`);
+        out.stdout(`${usageOf(positionals)}\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 === "labels")
@@ -363,6 +332,6 @@ main(process.argv.slice(2), out, process.cwd()).then((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` : ""}`);
+    out.stderr(`issue-flow: ${error instanceof Error ? error.message : String(error)}\n${usage ? `${usageOf(commandWords(process.argv.slice(2)))}\n` : ""}`);
     process.exitCode = usage || config ? 2 : 1;
 });

package/dist/package-edits.js

@@ -100,9 +100,13 @@ export function reaches(current, tested) {
 export const KEPT = "kept ";
 /** The package the skills call, which the repo gets if it lacks it. */
 export const GITHUB_REST = "@ramon-sg/github-rest";
+/** The script that starts an issue, and its shortcut with `--free`. */
+const START_SCRIPT = "issue:start";
+const FREE_SCRIPT = "issue:start:free";
 /** The scripts `apply` adds. */
 const FLOW_SCRIPTS = {
     "issue:start": "issue-flow issue start",
+    "issue:start:free": "issue-flow issue start --free",
     "worktree:prune": "issue-flow worktree prune",
     "pr:worktree": "issue-flow pr worktree",
 };
@@ -156,8 +160,13 @@ export function withFlowPackages(pkg, versions) {
         pin(GITHUB_REST, versions.githubRest, "devDependencies", null);
     else if (!reaches(rest.version, versions.githubRest))
         changes.push(`${KEPT}${GITHUB_REST} ${rest.version} (the skills need ${versions.githubRest} or newer: raise it)`);
+    // NOTE: with its own issue:start (a wrapper), issue:start:free would skip it: it is not
+    // added, and the flow's one gets a note.
+    const ownStart = scripts[START_SCRIPT] !== undefined && scripts[START_SCRIPT] !== FLOW_SCRIPTS[START_SCRIPT];
+    if (ownStart && scripts[FREE_SCRIPT] === FLOW_SCRIPTS[FREE_SCRIPT])
+        changes.push(`${KEPT}scripts: ${FREE_SCRIPT}, which skips the repo's own ${START_SCRIPT}: make it run that one with --free, or delete it`);
     for (const [name, command] of Object.entries(FLOW_SCRIPTS)) {
-        if (scripts[name] !== undefined)
+        if (scripts[name] !== undefined || (name === FREE_SCRIPT && ownStart))
             continue;
         scripts[name] = command;
         changes.push(`scripts: ${name}`);

package/dist/usage.d.ts

@@ -2,4 +2,13 @@
  * @file The usage text of the CLI, printed with `--help` and after a usage error.
  */
 /** Usage text. */
-export declare const USAGE = "Usage:\n  issue-flow issue branch <n>... [--namer claude|title] [--json] [-R owner/repo]\n  issue-flow issue branch --missing [--limit <n>] [--namer claude|title] [--dry-run | --yes] [--json] [-R owner/repo]\n  issue-flow issue start <n> [--branch] [--dry-run | --yes] [--resume <branch> | --new] [--no-launch]\n                             [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --plan [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --cloud | --here | --teleport | --adopt [...]\n  issue-flow worktree setup [--only <step>]\n  issue-flow worktree teardown [--path <dir>]\n  issue-flow worktree ports [--next]\n  issue-flow worktree cleanup [--path <dir>]\n  issue-flow worktree prune [--only <dir>] [--yes] [-R owner/repo]\n  issue-flow pr worktree <n> [--no-setup] [-R owner/repo] [-- [<command>...]]\n  issue-flow adapter setup [--only <step>] | issue [<url>] | archive [-R owner/repo]\n  issue-flow session\n  issue-flow hook worktree-create | worktree-remove\n  issue-flow apply [--yes] [--dry-run] [--json] [--recipe <name>,...]\n  issue-flow doctor [--json]\n  issue-flow labels sync [--update] [--dry-run] [--json] [-R owner/repo]\n\nThe slug comes from the issue's \"Slug de rama\" block, then from Claude, then from the title,\nand the branch from the repo's template (an older \"Rama sugerida\" block is used if it fits).\n--missing adds the slug block to every open issue without a block, after confirming.\n\nissue start makes the branch in a worktree (or, with --branch, in this checkout), the\nstart commit, the push, the draft PR and the assignment, after confirming, and opens\nClaude: in auto mode if the repo has claude-repo-guard, with your settings with\n--ask-permissions, and with no sandbox nor questions with --free. --plan prints the branch\nand the prompt as JSON and changes nothing.\n\n--cloud confirms here and opens a Claude cloud session that starts the issue there.\n--here, inside a cloud session, starts it in this checkout and opens nothing. --teleport\nbrings the cloud session noted in the PR to the worktree. --adopt starts it in the\nworktree another tool (Orca, Paseo) just made, without asking nor opening Claude.\n\nworktree runs the steps of \"worktrees\" in .agents/flow.json: setup prepares this worktree,\nteardown cleans it before it goes (steps, ports, Docker), ports prints or moves its block\nof ports, cleanup deletes the Docker of deleted worktrees, and prune deletes the worktrees\nwhose PR was merged or closed. session is the SessionStart hook of Claude Code.\n\npr worktree makes (or reuses) a worktree on a PR's own branch, to review and fix it; with\n--, it runs the command there (Claude if none). adapter is what Orca and Paseo run: setup\nwhen they make a worktree (its steps and, if it came from an issue, issue start --adopt),\nissue to start one by hand, and archive before they delete it. hook implements Claude\nCode's WorktreeCreate and WorktreeRemove for claude --worktree.\n\napply leaves the repo as this version needs it: .agents/flow.json (the first time, with\nthe recipes its files suggest), issue-flow at this version and github-rest and the scripts\nif missing in package.json, and the hooks; it changes no other version, and refuses a newer\nissue-flow or a range. doctor checks them. npx agent-kitchen apply runs apply at the version\nit picks, along with the skills, claude-cloud and claude-repo-guard. init and upgrade still\nrun apply, with a warning, until 0.4.0.\n\nlabels sync makes in GitHub the labels the flow wants (\"labels\" in .agents/flow.json: the\nissue types and P1 to P4 by default) that the repo lacks. Names ignore case and are never\nrenamed nor deleted; --update also fixes the color and description of those that differ.";
+export declare const USAGE = "Usage:\n  issue-flow issue branch <n>... [--namer claude|title] [--json] [-R owner/repo]\n  issue-flow issue branch --missing [--limit <n>] [--namer claude|title] [--dry-run | --yes] [--json] [-R owner/repo]\n  issue-flow issue start <n> [--branch] [--dry-run | --yes] [--resume <branch> | --new] [--no-launch]\n                             [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --plan [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --cloud | --here | --teleport | --adopt [...]\n  issue-flow worktree setup [--only <step>]\n  issue-flow worktree teardown [--path <dir>]\n  issue-flow worktree ports [--next]\n  issue-flow worktree cleanup [--path <dir>]\n  issue-flow worktree prune [--only <dir>] [--yes] [-R owner/repo]\n  issue-flow pr worktree <n> [--no-setup] [-R owner/repo] [-- [<command>...]]\n  issue-flow adapter setup [--only <step>] | issue [<url>] | archive [-R owner/repo]\n  issue-flow session\n  issue-flow hook worktree-create | worktree-remove\n  issue-flow apply [--yes] [--dry-run] [--json] [--recipe <name>,...]\n  issue-flow doctor [--json]\n  issue-flow labels sync [--update] [--dry-run] [--json] [-R owner/repo]\n\nThe slug comes from the issue's \"Slug de rama\" block, then from Claude, then from the title,\nand the branch from the repo's template (an older \"Rama sugerida\" block is used if it fits).\n--missing adds the slug block to every open issue without a block, after confirming.\n\nissue start makes the branch in a worktree (or, with --branch, in this checkout), the\nstart commit, the push, the draft PR and the assignment, after confirming, and opens\nClaude: in auto mode if the repo has claude-repo-guard, with your settings with\n--ask-permissions, and with no sandbox nor questions with --free. --plan prints the branch\nand the prompt as JSON and changes nothing. issue start --help explains each flag.\n\n--cloud confirms here and opens a Claude cloud session that starts the issue there.\n--here, inside a cloud session, starts it in this checkout and opens nothing. --teleport\nbrings the cloud session noted in the PR to the worktree. --adopt starts it in the\nworktree another tool (Orca, Paseo) just made, without asking nor opening Claude.\n\nworktree runs the steps of \"worktrees\" in .agents/flow.json: setup prepares this worktree,\nteardown cleans it before it goes (steps, ports, Docker), ports prints or moves its block\nof ports, cleanup deletes the Docker of deleted worktrees, and prune deletes the worktrees\nwhose PR was merged or closed. session is the SessionStart hook of Claude Code.\n\npr worktree makes (or reuses) a worktree on a PR's own branch, to review and fix it; with\n--, it runs the command there (Claude if none). adapter is what Orca and Paseo run: setup\nwhen they make a worktree (its steps and, if it came from an issue, issue start --adopt),\nissue to start one by hand, and archive before they delete it. hook implements Claude\nCode's WorktreeCreate and WorktreeRemove for claude --worktree.\n\napply leaves the repo as this version needs it: .agents/flow.json (the first time, with\nthe recipes its files suggest), issue-flow at this version and github-rest and the scripts\nif missing in package.json, and the hooks; it changes no other version, and refuses a newer\nissue-flow or a range. doctor checks them. npx agent-kitchen apply runs apply at the version\nit picks, along with the skills, claude-cloud and claude-repo-guard. init and upgrade still\nrun apply, with a warning, until 0.4.0.\n\nlabels sync makes in GitHub the labels the flow wants (\"labels\" in .agents/flow.json: the\nissue types and P1 to P4 by default) that the repo lacks. Names ignore case and are never\nrenamed nor deleted; --update also fixes the color and description of those that differ.";
+/** Usage text of `issue start`, printed with `issue start --help`. */
+export declare const START_USAGE = "Usage: issue-flow issue start <n> [flags]\n\nStarts issue <n>: the branch (in a worktree, or in this checkout with --branch), the empty\nstart commit, the push, the draft PR and the assignment, after confirming; then it opens\nClaude there.\n\nFlags:\n  --dry-run            show what it would do and change nothing\n  -y, --yes            do it without asking\n  --branch             in this checkout instead of a worktree\n  --resume <branch>    take that branch of the issue\n  --new                make another branch, even if the issue has one\n  --no-launch          leave everything ready and do not open Claude\n  --namer claude|title who names the branch when the issue has no slug block\n  -R owner/repo        another repo than the checkout's\n  --plan               print the branch and the prompt as JSON, and change nothing\n  --cloud              open a Claude cloud session that starts the issue there\n  --here               inside a cloud session, start it in this checkout\n  --teleport           bring the cloud session noted in the PR to the worktree\n  --adopt              start it in the worktree Orca or Paseo just made\n  -h, --help           this help\n\nPermissions of the Claude it opens (one at most):\n  (none)               auto mode if the repo has claude-repo-guard, else your settings\n  --ask-permissions    your settings: Claude asks before what they do not allow\n  --free               no sandbox and no questions, as claude:free\n\nFrom the repo's scripts (issue:start, and issue:start:free, which adds --free):\n  npm run issue:start:free 42           npm passes a number on as it is\n  npm run issue:start -- 42 --free      but keeps the flags for itself, unless after --\n  pnpm issue:start 42 --free            pnpm, bun and yarn pass everything on\n  bun run issue:start 42 --free\n  yarn issue:start 42 --free\nA -- does no harm with any of them: issue-flow drops it.\n\nissue:start:free does not go with --ask-permissions, --cloud, --here nor --adopt: use\nissue:start for those.";
+/**
+ * The usage text for a command: its own if it has one, else the whole CLI's.
+ * @param words - The command's words, as given (`["issue", "start", "42"]`).
+ * @returns The text.
+ * @example usageOf(["issue", "start"]) === START_USAGE
+ */
+export declare function usageOf(words: string[]): string;

package/dist/usage.js

@@ -30,7 +30,7 @@ issue start makes the branch in a worktree (or, with --branch, in this checkout)
 start commit, the push, the draft PR and the assignment, after confirming, and opens
 Claude: in auto mode if the repo has claude-repo-guard, with your settings with
 --ask-permissions, and with no sandbox nor questions with --free. --plan prints the branch
-and the prompt as JSON and changes nothing.
+and the prompt as JSON and changes nothing. issue start --help explains each flag.
 
 --cloud confirms here and opens a Claude cloud session that starts the issue there.
 --here, inside a cloud session, starts it in this checkout and opens nothing. --teleport
@@ -58,3 +58,52 @@ run apply, with a warning, until 0.4.0.
 labels sync makes in GitHub the labels the flow wants ("labels" in .agents/flow.json: the
 issue types and P1 to P4 by default) that the repo lacks. Names ignore case and are never
 renamed nor deleted; --update also fixes the color and description of those that differ.`;
+/** Usage text of `issue start`, printed with `issue start --help`. */
+export const START_USAGE = `Usage: issue-flow issue start <n> [flags]
+
+Starts issue <n>: the branch (in a worktree, or in this checkout with --branch), the empty
+start commit, the push, the draft PR and the assignment, after confirming; then it opens
+Claude there.
+
+Flags:
+  --dry-run            show what it would do and change nothing
+  -y, --yes            do it without asking
+  --branch             in this checkout instead of a worktree
+  --resume <branch>    take that branch of the issue
+  --new                make another branch, even if the issue has one
+  --no-launch          leave everything ready and do not open Claude
+  --namer claude|title who names the branch when the issue has no slug block
+  -R owner/repo        another repo than the checkout's
+  --plan               print the branch and the prompt as JSON, and change nothing
+  --cloud              open a Claude cloud session that starts the issue there
+  --here               inside a cloud session, start it in this checkout
+  --teleport           bring the cloud session noted in the PR to the worktree
+  --adopt              start it in the worktree Orca or Paseo just made
+  -h, --help           this help
+
+Permissions of the Claude it opens (one at most):
+  (none)               auto mode if the repo has claude-repo-guard, else your settings
+  --ask-permissions    your settings: Claude asks before what they do not allow
+  --free               no sandbox and no questions, as claude:free
+
+From the repo's scripts (issue:start, and issue:start:free, which adds --free):
+  npm run issue:start:free 42           npm passes a number on as it is
+  npm run issue:start -- 42 --free      but keeps the flags for itself, unless after --
+  pnpm issue:start 42 --free            pnpm, bun and yarn pass everything on
+  bun run issue:start 42 --free
+  yarn issue:start 42 --free
+A -- does no harm with any of them: issue-flow drops it.
+
+issue:start:free does not go with --ask-permissions, --cloud, --here nor --adopt: use
+issue:start for those.`;
+/** The usage text of each command that has its own, by its words. */
+const OWN_USAGE = { "issue start": START_USAGE };
+/**
+ * The usage text for a command: its own if it has one, else the whole CLI's.
+ * @param words - The command's words, as given (`["issue", "start", "42"]`).
+ * @returns The text.
+ * @example usageOf(["issue", "start"]) === START_USAGE
+ */
+export function usageOf(words) {
+    return OWN_USAGE[words.slice(0, 2).join(" ")] ?? USAGE;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramon-sg/issue-flow",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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",