@ramon-sg/issue-flow 0.2.7 → 0.3.1

package/dist/package-edits.d.ts

@@ -1,10 +1,10 @@
 /**
- * @file The repo's `package.json` as the flow needs it: `issue-flow`, `github-rest` and
- * `skills-manager` as exact dev dependencies (the skills call them with `npx`, which then
- * uses the repo's copy), and the scripts to start an issue, prune worktrees and review a PR.
- * A dependency or script the repo already has with another value stays as it is, except
- * that `upgrade` moves `issue-flow` to the version that runs and raises the other two only
- * when they fall short of it: a newer version or a range that allows it is never moved back.
+ * @file The repo's `package.json` as the flow needs it: `issue-flow` at the version that
+ * runs and `github-rest` as exact dev dependencies (the skills call them with `npx`, which
+ * then uses the repo's copy), and the scripts to start an issue, prune worktrees and review
+ * a PR. `apply` adds `github-rest` only if it is missing: its version is the repo's to pick,
+ * and `doctor` says when it falls short of what the flow needs. A script the repo already
+ * has with another value stays as it is.
  */
 import { type OwnVersions } from "./setup-files.js";
 /**
@@ -17,31 +17,20 @@ import { type OwnVersions } from "./setup-files.js";
  */
 export declare function isNewer(version: string, than: string): boolean;
 /**
- * Whether the repo's version of a package reaches the one the flow was tested with, so
- * `upgrade` keeps it: an exact version as new or newer, a range that allows it or newer
+ * Whether the repo's version of a package reaches the one the flow needs, so `apply` and
+ * `doctor` accept it: an exact version as new or newer, a range that allows it or newer
  * (`^1.2.0` for 1.3.0, not `^0.1.0` for 0.3.0), or a source it cannot read (`workspace:*`,
  * `github:…`, `latest`), which the repo chose on purpose.
  * @param current - The repo's version or range.
- * @param tested - The version the flow was tested with.
- * @returns True to keep it.
+ * @param tested - The version the flow needs.
+ * @returns True if it reaches it.
  * @example reaches("1.3.0", "1.2.0") // true
  */
 export declare function reaches(current: string, tested: string): boolean;
-/** A dependency the flow pins: its version, and whether `upgrade` keeps one that reaches it. */
-interface Pin {
-    version: string;
-    keepsReaching: boolean;
-}
 /** How a change that keeps what the repo had starts. */
 export declare const KEPT = "kept ";
-/**
- * The dependencies the flow pins, with their versions. `issue-flow` always follows the
- * version that runs; the other two are a floor, so `upgrade` keeps what reaches it.
- * @param versions - This package's versions.
- * @returns Package to pin.
- * @example pinnedPackages(versions)["@ramon-sg/issue-flow"].version // "0.1.0"
- */
-export declare function pinnedPackages(versions: OwnVersions): Record<string, Pin>;
+/** The package the skills call, which the repo gets if it lacks it. */
+export declare const GITHUB_REST = "@ramon-sg/github-rest";
 /**
  * The version of a package in the repo, as a dependency or a dev dependency.
  * @param pkg - The package.json.
@@ -51,16 +40,15 @@ export declare function pinnedPackages(versions: OwnVersions): Record<string, Pi
  */
 export declare function dependencyVersion(pkg: Record<string, unknown> | null, name: string): string | null;
 /**
- * Adds the flow's dev dependencies and scripts that are missing. With `move`, also moves the
- * ones already there to these versions (what `upgrade` does).
+ * Pins `issue-flow` to the version that runs, adds `github-rest` if it is missing and the
+ * scripts that are missing. Nothing else changes: a `github-rest` the repo has stays, with a
+ * note if it falls short of the version the flow needs.
  * @param pkg - The package.json, or null if there is none.
- * @param versions - The versions to pin.
- * @param move - Whether to move the dependencies already there.
+ * @param versions - This package's versions.
  * @returns The new package.json and what changed or was kept.
- * @example withFlowPackages(null, versions, false).changes // ["devDependencies: @ramon-sg/issue-flow 0.1.0", …]
+ * @example withFlowPackages(null, versions).changes // ["devDependencies: @ramon-sg/issue-flow 0.1.0", …]
  */
-export declare function withFlowPackages(pkg: Record<string, unknown> | null, versions: OwnVersions, move: boolean): {
+export declare function withFlowPackages(pkg: Record<string, unknown> | null, versions: OwnVersions): {
     pkg: Record<string, unknown>;
     changes: string[];
 };
-export {};

package/dist/package-edits.js

@@ -1,10 +1,10 @@
 /**
- * @file The repo's `package.json` as the flow needs it: `issue-flow`, `github-rest` and
- * `skills-manager` as exact dev dependencies (the skills call them with `npx`, which then
- * uses the repo's copy), and the scripts to start an issue, prune worktrees and review a PR.
- * A dependency or script the repo already has with another value stays as it is, except
- * that `upgrade` moves `issue-flow` to the version that runs and raises the other two only
- * when they fall short of it: a newer version or a range that allows it is never moved back.
+ * @file The repo's `package.json` as the flow needs it: `issue-flow` at the version that
+ * runs and `github-rest` as exact dev dependencies (the skills call them with `npx`, which
+ * then uses the repo's copy), and the scripts to start an issue, prune worktrees and review
+ * a PR. `apply` adds `github-rest` only if it is missing: its version is the repo's to pick,
+ * and `doctor` says when it falls short of what the flow needs. A script the repo already
+ * has with another value stays as it is.
  */
 import { PACKAGE } from "./setup-files.js";
 /** A version: X.Y.Z, with an optional pre-release and build. */
@@ -71,13 +71,13 @@ function ceiling(sign, floor) {
     return minor > 0 ? { parts: [0, minor + 1, 0], pre: null } : { parts: [0, 0, patch + 1], pre: null };
 }
 /**
- * Whether the repo's version of a package reaches the one the flow was tested with, so
- * `upgrade` keeps it: an exact version as new or newer, a range that allows it or newer
+ * Whether the repo's version of a package reaches the one the flow needs, so `apply` and
+ * `doctor` accept it: an exact version as new or newer, a range that allows it or newer
  * (`^1.2.0` for 1.3.0, not `^0.1.0` for 0.3.0), or a source it cannot read (`workspace:*`,
  * `github:…`, `latest`), which the repo chose on purpose.
  * @param current - The repo's version or range.
- * @param tested - The version the flow was tested with.
- * @returns True to keep it.
+ * @param tested - The version the flow needs.
+ * @returns True if it reaches it.
  * @example reaches("1.3.0", "1.2.0") // true
  */
 export function reaches(current, tested) {
@@ -98,26 +98,14 @@ export function reaches(current, tested) {
 }
 /** How a change that keeps what the repo had starts. */
 export const KEPT = "kept ";
-/** The scripts `init` adds. */
+/** The package the skills call, which the repo gets if it lacks it. */
+export const GITHUB_REST = "@ramon-sg/github-rest";
+/** The scripts `apply` adds. */
 const FLOW_SCRIPTS = {
     "issue:start": "issue-flow issue start",
     "worktree:prune": "issue-flow worktree prune",
     "pr:worktree": "issue-flow pr worktree",
 };
-/**
- * The dependencies the flow pins, with their versions. `issue-flow` always follows the
- * version that runs; the other two are a floor, so `upgrade` keeps what reaches it.
- * @param versions - This package's versions.
- * @returns Package to pin.
- * @example pinnedPackages(versions)["@ramon-sg/issue-flow"].version // "0.1.0"
- */
-export function pinnedPackages(versions) {
-    return {
-        [PACKAGE]: { version: versions.issueFlow, keepsReaching: false },
-        "@ramon-sg/github-rest": { version: versions.githubRest, keepsReaching: true },
-        "@ramon-sg/skills-manager": { version: versions.skillsManager, keepsReaching: true },
-    };
-}
 /**
  * Where a package is in the repo's package.json, and its version.
  * @param pkg - The package.json.
@@ -144,30 +132,30 @@ export function dependencyVersion(pkg, name) {
     return dependencyOf(pkg, name)?.version ?? null;
 }
 /**
- * Adds the flow's dev dependencies and scripts that are missing. With `move`, also moves the
- * ones already there to these versions (what `upgrade` does).
+ * Pins `issue-flow` to the version that runs, adds `github-rest` if it is missing and the
+ * scripts that are missing. Nothing else changes: a `github-rest` the repo has stays, with a
+ * note if it falls short of the version the flow needs.
  * @param pkg - The package.json, or null if there is none.
- * @param versions - The versions to pin.
- * @param move - Whether to move the dependencies already there.
+ * @param versions - This package's versions.
  * @returns The new package.json and what changed or was kept.
- * @example withFlowPackages(null, versions, false).changes // ["devDependencies: @ramon-sg/issue-flow 0.1.0", …]
+ * @example withFlowPackages(null, versions).changes // ["devDependencies: @ramon-sg/issue-flow 0.1.0", …]
  */
-export function withFlowPackages(pkg, versions, move) {
+export function withFlowPackages(pkg, versions) {
     const next = pkg === null ? { private: true } : { ...pkg };
     const scripts = { ...(next.scripts ?? {}) };
     const changes = [];
-    for (const [name, { version, keepsReaching }] of Object.entries(pinnedPackages(versions))) {
-        const current = dependencyOf(next, name);
-        if (current?.version === version)
-            continue;
-        if (current !== null && (!move || (keepsReaching && reaches(current.version, version)))) {
-            changes.push(`${KEPT}${name} ${current.version} (issue-flow ${versions.issueFlow} was tested with ${version})`);
-            continue;
-        }
-        const field = current?.field ?? "devDependencies";
+    const pin = (name, version, field, from) => {
         next[field] = { ...(next[field] ?? {}), [name]: version };
-        changes.push(`${field}: ${name} ${current === null ? "" : `${current.version} → `}${version}`);
-    }
+        changes.push(`${field}: ${name} ${from === null ? "" : `${from} → `}${version}`);
+    };
+    const flow = dependencyOf(next, PACKAGE);
+    if (flow?.version !== versions.issueFlow)
+        pin(PACKAGE, versions.issueFlow, flow?.field ?? "devDependencies", flow?.version ?? null);
+    const rest = dependencyOf(next, GITHUB_REST);
+    if (rest === null)
+        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)`);
     for (const [name, command] of Object.entries(FLOW_SCRIPTS)) {
         if (scripts[name] !== undefined)
             continue;

package/dist/settings-hooks.d.ts

@@ -1,4 +1,4 @@
-/** The hook events `init` registers. */
+/** The hook events `apply` registers. */
 export declare const HOOK_EVENTS: string[];
 /**
  * The command of one of the hooks, at a version.

package/dist/settings-hooks.js

@@ -1,8 +1,8 @@
 /**
- * @file The Claude Code hooks `init` registers in `.claude/settings.json`: `SessionStart`
+ * @file The Claude Code hooks `apply` 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`
+ * `apply` twice changes nothing, and a new version 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.
@@ -19,7 +19,7 @@ const HOOK_COMMANDS = {
     WorktreeCreate: { sub: "hook worktree-create", note: "" },
     WorktreeRemove: { sub: "hook worktree-remove", note: "" },
 };
-/** The hook events `init` registers. */
+/** The hook events `apply` registers. */
 export const HOOK_EVENTS = Object.keys(HOOK_COMMANDS);
 /**
  * The command of one of the hooks, at a version.

package/dist/setup-files.d.ts

@@ -2,20 +2,37 @@
 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";
+/** The start of the config's schema URL, at any version. */
+export declare const SCHEMA_PREFIX = "https://raw.githubusercontent.com/ramon-sg/issue-flow/";
+/**
+ * The URL of the config's schema at a version.
+ * @param version - This package's version.
+ * @returns The URL.
+ * @example schemaUrl("0.1.0") // "https://raw.githubusercontent.com/ramon-sg/issue-flow/v0.1.0/schema.json"
+ */
+export declare function schemaUrl(version: string): string;
+/**
+ * Whether a config's `$schema` is the flow's at another version (one that is not the
+ * flow's is the repo's choice and never stale).
+ * @param schema - The config's `$schema`.
+ * @param version - This package's version.
+ * @returns True if `apply` would move it.
+ */
+export declare function isStaleSchema(schema: unknown, version: string): boolean;
 /** 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. */
+/** Error of `apply` or `doctor`: exits 1 with the message. */
 export declare class SetupError extends Error {
 }
 /** The versions this package pins in the repo. */
 export interface OwnVersions {
     issueFlow: string;
+    /** The lowest `github-rest` the flow works with: the floor of its own dependency. */
     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`.
+ * This package's version and the lowest `github-rest` it works with, from its own
+ * `package.json` (`"^0.3.0"` gives 0.3.0).
  * @returns The versions.
  * @throws SetupError if the package.json does not have them.
  * @example ownVersions().issueFlow // "0.1.0"

package/dist/setup-files.js

@@ -1,5 +1,5 @@
 /**
- * @file What `init`, `doctor` and `upgrade` share: this package's own versions, the JSON
+ * @file What `apply` and `doctor` 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.
@@ -12,14 +12,35 @@ import { isObject } from "./config-base.js";
 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";
+/** The start of the config's schema URL, at any version. */
+export const SCHEMA_PREFIX = `https://raw.githubusercontent.com/${FLOW_REPO}/`;
+/**
+ * The URL of the config's schema at a version.
+ * @param version - This package's version.
+ * @returns The URL.
+ * @example schemaUrl("0.1.0") // "https://raw.githubusercontent.com/ramon-sg/issue-flow/v0.1.0/schema.json"
+ */
+export function schemaUrl(version) {
+    return `${SCHEMA_PREFIX}v${version}/schema.json`;
+}
+/**
+ * Whether a config's `$schema` is the flow's at another version (one that is not the
+ * flow's is the repo's choice and never stale).
+ * @param schema - The config's `$schema`.
+ * @param version - This package's version.
+ * @returns True if `apply` would move it.
+ */
+export function isStaleSchema(schema, version) {
+    return typeof schema === "string" && schema.startsWith(SCHEMA_PREFIX) && schema !== schemaUrl(version);
+}
 /** 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. */
+/** Error of `apply` or `doctor`: 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`.
+ * This package's version and the lowest `github-rest` it works with, from its own
+ * `package.json` (`"^0.3.0"` gives 0.3.0).
  * @returns The versions.
  * @throws SetupError if the package.json does not have them.
  * @example ownVersions().issueFlow // "0.1.0"
@@ -27,11 +48,10 @@ export class SetupError extends Error {
 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 };
+    const githubRest = pkg.dependencies?.["@ramon-sg/github-rest"]?.replace(/^[\^~]/, "");
+    if (pkg.version === undefined || githubRest === undefined)
+        throw new SetupError(`${file} lacks the version of issue-flow or github-rest.`);
+    return { issueFlow: pkg.version, githubRest };
 }
 /**
  * Reads a JSON object of the repo.

package/dist/start-modes.js

@@ -188,7 +188,8 @@ export function prepareHere(state) {
         throw new StartError(`branch ${branch} is only local (on another machine or checkout): push it from there and run this again.`);
     if (hasLocal(mainRoot, branch) && git(mainRoot, ["rev-list", "--count", branch, "--not", `origin/${branch}`]).out !== "0")
         throw new StartError(`the local branch ${branch} has commits that are not in origin; push them or sort it out by hand.`);
-    checkout(["-B", branch, `origin/${branch}`]);
+    // NOTE: --no-track: publish sets the upstream when it can (see trackOrigin).
+    checkout(["--no-track", "-B", branch, `origin/${branch}`]);
 }
 /**
  * The cloud session noted in the PR's body, or null (no PR, none noted, or the PR cannot

package/dist/start-place.js

@@ -9,7 +9,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:f
 import { dirname, join, relative } from "node:path";
 import { assign, createPr, findPr, getPr, updatePr } from "@ramon-sg/github-rest";
 import { confirm } from "./ask.js";
-import { checkedOutAt, currentBranch, git, gitLines, hasLocal, isClean, onOrigin, safeToDelete } from "./git.js";
+import { checkedOutAt, currentBranch, git, gitLines, hasLocal, isClean, onOrigin, safeToDelete, trackOrigin, untracked } from "./git.js";
 import { bodyToPartOf, dirName, fill, prBody } from "./issue-text.js";
 import { forgetSession } from "./launch.js";
 import { warn } from "./output.js";
@@ -75,7 +75,9 @@ export function prepareBranch(state) {
     if (state.mode === "worktree") {
         if (existsSync(state.workDir))
             return;
-        const args = found === null ? ["-b", branch, `origin/${base}`] : [branch];
+        // NOTE: --no-track, since tracking writes .git/config, which Claude Code's sandbox
+        // forbids; publish sets the branch's upstream when it can (see trackOrigin).
+        const args = found === null ? ["--no-track", "-b", branch, `origin/${base}`] : hasLocal(mainRoot, branch) ? [branch] : ["--no-track", "-b", branch, `origin/${branch}`];
         const result = git(mainRoot, ["worktree", "add", "-q", state.workDir, ...args]);
         if (!result.ok)
             throw new StartError(`could not create the worktree: ${result.err}. If a sandbox stopped it, run in a terminal: ${again(state.options.number, "--yes")}`);
@@ -85,8 +87,10 @@ export function prepareBranch(state) {
         return;
     if (!isClean(mainRoot))
         throw new StartError("the main checkout has uncommitted changes; commit or stash them first. No stash is made.");
-    if (found !== null)
-        return mustGit(mainRoot, ["checkout", "-q", branch], `could not check out ${branch}`);
+    if (found !== null) {
+        const args = hasLocal(mainRoot, branch) ? [branch] : ["--no-track", "-b", branch, `origin/${branch}`];
+        return mustGit(mainRoot, ["checkout", "-q", ...args], `could not check out ${branch}`);
+    }
     if (currentBranch(mainRoot) !== base)
         throw new StartError(`the main checkout is not on ${base}.`);
     if (git(mainRoot, ["rev-list", "--count", `origin/${base}..${base}`]).out !== "0")
@@ -133,9 +137,9 @@ export async function publish(state) {
         mustGit(workDir, ["commit", "-q", "--allow-empty", "--only", "-m", message], "could not make the start commit");
     }
     if (commit || !onOrigin(workDir, branch))
-        mustGit(workDir, ["push", "-q", "-u", "origin", branch], `could not push ${branch}`);
-    if (!git(workDir, ["rev-parse", "-q", "--verify", "@{u}"]).ok)
-        git(workDir, ["branch", "-q", `--set-upstream-to=origin/${branch}`, branch]);
+        mustGit(workDir, ["push", "-q", "origin", branch], `could not push ${branch}`);
+    if (!trackOrigin(workDir, branch))
+        warn(state.out, untracked(branch));
     let number = state.pr?.number ?? null;
     if (number === null) {
         const created = await createPr(options.repo, {

package/dist/start-summary.d.ts

@@ -22,7 +22,7 @@ export declare function describeBranch(state: StartState, branch: string, withPr
  * The actions it will take, joined with " + ".
  * @param state - The start.
  * @returns The text.
- * @example plannedActions(state) // "create the branch from origin/main + empty commit + push -u + …"
+ * @example plannedActions(state) // "create the branch from origin/main + empty commit + push + …"
  */
 export declare function plannedActions(state: StartState): string;
 /**

package/dist/start-summary.js

@@ -53,7 +53,7 @@ export function describeBranch(state, branch, withPr) {
  * The actions it will take, joined with " + ".
  * @param state - The start.
  * @returns The text.
- * @example plannedActions(state) // "create the branch from origin/main + empty commit + push -u + …"
+ * @example plannedActions(state) // "create the branch from origin/main + empty commit + push + …"
  */
 export function plannedActions(state) {
     if (state.mode === "cloud")
@@ -65,7 +65,7 @@ export function plannedActions(state) {
     if (commit)
         actions.push("empty commit");
     if (commit || !onOrigin(mainRoot, branch))
-        actions.push("push -u");
+        actions.push("push");
     if (state.pr === null) {
         const first = prBody(state.options.config.start.prBody, number, state.kind, state.issue.url).split("\n")[0];
         actions.push(`draft PR (${first})`);

package/dist/usage.d.ts

@@ -2,4 +2,4 @@
  * @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 init [--yes] [--recipe <name>,...]\n  issue-flow doctor [--json]\n  issue-flow upgrade [--dry-run]\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\ninit sets the flow up in the repo: .agents/flow.json (with the recipes its files suggest),\nthe dev dependencies and scripts, and the hooks. doctor checks them at this version, and\nupgrade moves them to this version. npx agent-kitchen apply runs the three, along with the\nskills, claude-cloud and claude-repo-guard.\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.\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.";

package/dist/usage.js

@@ -18,9 +18,8 @@ export const USAGE = `Usage:
   issue-flow adapter setup [--only <step>] | issue [<url>] | archive [-R owner/repo]
   issue-flow session
   issue-flow hook worktree-create | worktree-remove
-  issue-flow init [--yes] [--recipe <name>,...]
+  issue-flow apply [--yes] [--dry-run] [--json] [--recipe <name>,...]
   issue-flow doctor [--json]
-  issue-flow upgrade [--dry-run]
   issue-flow labels sync [--update] [--dry-run] [--json] [-R owner/repo]
 
 The slug comes from the issue's "Slug de rama" block, then from Claude, then from the title,
@@ -49,10 +48,12 @@ when they make a worktree (its steps and, if it came from an issue, issue start
 issue to start one by hand, and archive before they delete it. hook implements Claude
 Code's WorktreeCreate and WorktreeRemove for claude --worktree.
 
-init sets the flow up in the repo: .agents/flow.json (with the recipes its files suggest),
-the dev dependencies and scripts, and the hooks. doctor checks them at this version, and
-upgrade moves them to this version. npx agent-kitchen apply runs the three, along with the
-skills, claude-cloud and claude-repo-guard.
+apply leaves the repo as this version needs it: .agents/flow.json (the first time, with
+the recipes its files suggest), issue-flow at this version and github-rest and the scripts
+if missing in package.json, and the hooks; it changes no other version, and refuses a newer
+issue-flow or a range. doctor checks them. npx agent-kitchen apply runs apply at the version
+it picks, along with the skills, claude-cloud and claude-repo-guard. init and upgrade still
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramon-sg/issue-flow",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "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",
@@ -17,6 +17,6 @@
     "test": "tsc && node --test test/*.test.mjs",
     "prepublishOnly": "npm test"
   },
-  "dependencies": { "@ramon-sg/github-rest": "0.3.0" },
+  "dependencies": { "@ramon-sg/github-rest": "^0.3.0" },
   "devDependencies": { "@ramon-sg/skills-manager": "1.2.0", "@types/node": "^24.0.0", "typescript": "^5.9.3" }
 }

package/dist/commands/init.d.ts

@@ -1,24 +0,0 @@
-import { type Output } from "../output.js";
-/** Options of `issue-flow init`. */
-export interface InitOptions {
-    cwd: string;
-    yes: boolean;
-    recipes: string[] | null;
-}
-/**
- * The URL of the config's schema at a version.
- * @param version - This package's version.
- * @returns The URL.
- * @example schemaUrl("0.1.0") // "https://raw.githubusercontent.com/ramon-sg/issue-flow/v0.1.0/schema.json"
- */
-export declare function schemaUrl(version: string): string;
-/**
- * Sets the repo up for the flow; see the file's header.
- * @param options - The options.
- * @param out - Where to write and ask.
- * @returns 0, or 1 if the files were not written.
- * @throws SetupError outside the main checkout or with a broken file; ConfigError if the
- * config would be invalid; UsageError for an unknown recipe.
- * @example await init({ cwd, yes: true, recipes: null }, out)
- */
-export declare function init(options: InitOptions, out: Output): Promise<number>;