@ramon-sg/issue-flow 0.2.6 → 0.3.0

package/README.md

@@ -2,11 +2,11 @@
 
 Flujo de trabajo de issue a PR para cualquier repo, en local y en las sesiones de Claude en la nube: nombra la rama de cada issue, crea su worktree con puertos y Docker propios, abre el PR en draft y limpia cuando se mergea. Trae las skills que usan ese flujo.
 
-> **Instalar en un repo:** `npx agent-kitchen`, que instala este flujo con sus skills, las skills generales, `claude-cloud` y `claude-repo-guard`, y los actualiza ([agent-kitchen](https://github.com/ramon-sg/agent-kitchen)). El paquete es `@ramon-sg/issue-flow` y el comando, `issue-flow`; sin el scope, `issue-flow` en npm es otro paquete.
+> **Instalar en un repo:** `npx agent-kitchen apply`, que instala este flujo con sus skills, las skills generales, `claude-cloud` y `claude-repo-guard`, y los actualiza ([agent-kitchen](https://github.com/ramon-sg/agent-kitchen)). El paquete es `@ramon-sg/issue-flow` y el comando, `issue-flow`; sin el scope, `issue-flow` en npm es otro paquete.
 
 ## Qué va a tener
 
-- **`issue-flow init|doctor|upgrade`:** escribe, revisa y mueve a su versión lo que el flujo deja en el repo: `.agents/flow.json` con sus recetas, las dependencias y los hooks. Los corre `agent-kitchen`.
+- **`issue-flow apply|doctor`:** deja como lo pide su versión, y revisa, lo que el flujo deja en el repo: `.agents/flow.json` con sus recetas, las dependencias y los hooks. Los corre `agent-kitchen`.
 - **`issue-flow issue branch <n>`:** propone la rama de una issue (con Claude por defecto, o desde el título). Con `--missing`, agrega el slug de rama a todas las issues abiertas que no lo tienen.
 - **`issue-flow labels sync`:** crea en GitHub los labels que el flujo espera y le faltan al repo: los de tipo y `P1` a `P4`, con los mismos colores en todos los repos.
 - **`issue-flow issue start <n>`:** crea la rama y el worktree, hace el commit inicial, abre el PR en draft, asigna la issue y abre Claude. Con `--cloud`, lo hace en una sesión en la nube.
@@ -181,30 +181,33 @@ Es el hook `SessionStart` de Claude Code. Lo que imprime le llega a Claude como
 4. Borra el Docker de los worktrees que ya no existen: Claude Code no llama al hook `WorktreeRemove` de los worktrees que no hizo un hook `WorktreeCreate`.
 5. Si hay `.envrc` y `direnv`, agrega su entorno a `CLAUDE_ENV_FILE`, para que los comandos de la sesión lo tengan.
 
-## Lo que el flujo deja en el repo: `issue-flow init`
+## Lo que el flujo deja en el repo: `issue-flow apply`
 
-`npx agent-kitchen` corre estos tres comandos en la versión que corresponde. Correrlos a mano sirve para probar el flujo en un repo sin lo demás.
+`npx agent-kitchen apply` corre `apply` en la versión que elige y después mueve las skills del flujo a la misma tag. Correrlo a mano sirve para probar el flujo en un repo sin lo demás.
 
 ```sh
-npx @ramon-sg/issue-flow init           # pregunta cada receta y pide el OK
-npx @ramon-sg/issue-flow init --yes     # sin preguntas, con las recetas que sugiere el repo
-npx @ramon-sg/issue-flow doctor         # revisa que el repo esté como lo deja init (--json para agent-kitchen)
-npx @ramon-sg/issue-flow@<versión> upgrade  # mueve el repo a esa versión (--dry-run)
+npx @ramon-sg/issue-flow@<versión> apply          # deja el repo como lo pide esa versión
+npx @ramon-sg/issue-flow@<versión> apply --yes    # sin preguntas, con las recetas que sugiere el repo
+npx @ramon-sg/issue-flow apply --recipe docker-compose   # suma una receta más tarde
+npx @ramon-sg/issue-flow apply --dry-run          # solo dice qué cambiaría (--json para agent-kitchen)
+npx @ramon-sg/issue-flow doctor                   # revisa que el repo esté como lo deja apply (--json)
 ```
 
-`init` muestra lo que va a escribir y pide el OK; correrlo otra vez solo completa lo que falta.
+`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. Suma las recetas que elijas.
-2. **`package.json`:** `@ramon-sg/issue-flow`, `@ramon-sg/github-rest` y `@ramon-sg/skills-manager` como dependencias de desarrollo con versión exacta, y los scripts `issue:start`, `worktree:prune` y `pr:worktree`. Lo que el repo ya tiene con otro valor se queda, con un aviso.
+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.
 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.
 
-**`doctor`** no cambia nada. Revisa la config, las dependencias y que los hooks estén en esta versión. Cada problema dice qué lo arregla.
+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.
 
-**`upgrade`** mueve el repo a la versión que corre: las dependencias a las que fija, los hooks y el `$schema`. No consulta npm, así que se corre con la versión: `npx @ramon-sg/issue-flow@<versión> upgrade`. Nunca baja de versión: si el repo ya tiene una más nueva (por ejemplo, una copia local vieja en `node_modules`), se detiene y dice qué correr. Las skills del flujo llaman a la CLI, así que tienen que ir a la misma tag: `agent-kitchen` las mueve después. `--dry-run` solo dice qué cambiaría.
+**`doctor`** no cambia nada. Revisa la config y su `$schema`, las dependencias y que los hooks estén en esta versión. Cada problema dice qué lo arregla: `npx agent-kitchen apply` si el repo fija otra issue-flow (también mueve las skills), y `npx @ramon-sg/issue-flow apply` si la versión es esta pero sus archivos quedaron atrás.
+
+**`init` y `upgrade`** siguen funcionando hasta la 0.4.0, con un aviso: `init` es `apply`, y `upgrade` es `apply --yes` sin recetas, porque nunca preguntaba.
 
 ### Recetas
 
-Piezas de `flow.json` para lo que muchos repos comparten. `init` ofrece las que sugieren los archivos del repo; `--recipe a,b` elige otras. Una receta solo agrega lo que falta: un paso con el mismo nombre o una clave que el repo ya tiene no se tocan.
+Piezas de `flow.json` para lo que muchos repos comparten. `apply` ofrece, la primera vez, las que sugieren los archivos del repo; `--recipe a,b` elige otras. Una receta solo agrega lo que falta: un paso con el mismo nombre o una clave que el repo ya tiene no se tocan.
 
 | Receta | La sugiere | Qué agrega |
 |---|---|---|

package/dist/cli-setup.d.ts

@@ -1,13 +1,15 @@
 /**
- * @file The `init`, `doctor` and `upgrade` commands of the CLI: their flags turned into
- * options.
+ * @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 Output } from "./output.js";
 /** The setup commands. */
 export declare const SETUP_COMMANDS: string[];
 /**
- * Runs `issue-flow init`, `doctor` or `upgrade`.
+ * Runs `issue-flow apply` or `doctor`. `init` is `apply` with its flags; `upgrade` is
+ * `apply --yes` without recipes, as it never asked, so an `agent-kitchen` that still calls
+ * it keeps working.
  * @param command - The command.
  * @param flags - The flags, already checked to be the command's own.
  * @param rest - The positionals after it.

package/dist/cli-setup.js

@@ -1,11 +1,20 @@
+import { apply } from "./commands/apply.js";
 import { doctor } from "./commands/doctor.js";
-import { init } from "./commands/init.js";
-import { upgrade } from "./commands/upgrade.js";
-import { UsageError } from "./output.js";
+import { UsageError, warn } from "./output.js";
 /** The setup commands. */
-export const SETUP_COMMANDS = ["init", "doctor", "upgrade"];
+export const SETUP_COMMANDS = ["apply", "init", "upgrade", "doctor"];
 /**
- * Runs `issue-flow init`, `doctor` or `upgrade`.
+ * The names given with `--recipe`.
+ * @param value - The flag.
+ * @returns The names, or null without the flag.
+ */
+function recipesOf(value) {
+    return value === undefined ? null : value.split(",").map((name) => name.trim()).filter((name) => name !== "");
+}
+/**
+ * Runs `issue-flow apply` or `doctor`. `init` is `apply` with its flags; `upgrade` is
+ * `apply --yes` without recipes, as it never asked, so an `agent-kitchen` that still calls
+ * it keeps working.
  * @param command - The command.
  * @param flags - The flags, already checked to be the command's own.
  * @param rest - The positionals after it.
@@ -19,8 +28,9 @@ export async function runSetupCommand(command, flags, rest, run) {
         throw new UsageError(`${command} takes no arguments.`);
     if (command === "doctor")
         return doctor(run.cwd, flags.json ?? false, run.out);
+    if (command === "init" || command === "upgrade")
+        warn(run.out, `${command} is now apply: run 'issue-flow apply'. ${command} goes away in 0.4.0.`);
     if (command === "upgrade")
-        return upgrade({ cwd: run.cwd, dryRun: flags["dry-run"] ?? false }, run.out);
-    const recipes = flags.recipe === undefined ? null : flags.recipe.split(",").map((name) => name.trim()).filter((name) => name !== "");
-    return init({ cwd: run.cwd, yes: flags.yes ?? false, recipes }, run.out);
+        return apply({ cwd: run.cwd, yes: true, dryRun: flags["dry-run"] ?? false, json: false, recipes: [] }, run.out);
+    return apply({ cwd: run.cwd, yes: flags.yes ?? false, dryRun: flags["dry-run"] ?? false, json: flags.json ?? false, recipes: recipesOf(flags.recipe) }, run.out);
 }

package/dist/cli.js

@@ -74,6 +74,7 @@ const COMMAND_FLAGS = {
     "adapter archive": [],
     "hook worktree-create": [],
     "hook worktree-remove": [],
+    apply: ["yes", "dry-run", "json", "recipe"],
     init: ["yes", "recipe"],
     doctor: ["json"],
     upgrade: ["dry-run"],

package/dist/commands/apply.d.ts

@@ -0,0 +1,21 @@
+import { type Output } from "../output.js";
+/** Options of `issue-flow apply`. */
+export interface ApplyOptions {
+    cwd: string;
+    /** Takes the recipes the repo's files suggest without asking. */
+    yes: boolean;
+    dryRun: boolean;
+    json: boolean;
+    /** The recipes named with `--recipe`, or null to pick them the first time. */
+    recipes: string[] | null;
+}
+/**
+ * Applies the flow to the repo; see the file's header.
+ * @param options - The options.
+ * @param out - Where to write and ask.
+ * @returns 0 when applied or already there, 1 when it had to ask and could not.
+ * @throws SetupError outside the main checkout, with a broken file, or when it refuses the
+ * version; ConfigError if the config would be invalid; UsageError for an unknown recipe.
+ * @example await apply({ cwd, yes: true, dryRun: false, json: false, recipes: null }, out)
+ */
+export declare function apply(options: ApplyOptions, out: Output): Promise<number>;

package/dist/commands/apply.js

@@ -0,0 +1,231 @@
+/**
+ * @file `issue-flow apply [--yes] [--dry-run] [--json] [--recipe <name>,...]`: leaves the
+ * repo as the version that runs needs it, and running it again changes nothing. It writes
+ * `.agents/flow.json` the first time (from `paseo.json` if the repo has one, plus the recipes
+ * it picks), runs the config's migrations, pins `@ramon-sg/issue-flow` to this version, adds
+ * `github-rest` and the scripts if they are missing, and moves the hooks and the `$schema`
+ * to this version. It changes no other version: who updates picks the version by picking
+ * which one to run (`npx @ramon-sg/issue-flow@<version> apply`). It refuses when the repo
+ * already has a newer issue-flow, or a range, since the hooks need an exact one. The skills,
+ * `claude-cloud` and `claude-repo-guard` are `agent-kitchen`'s, which runs this command.
+ */
+import { confirm } from "../ask.js";
+import { CONFIG_PATH, isObject } from "../config-base.js";
+import { parseConfig } from "../config.js";
+import { checkoutRoot, locateRepo } from "../git.js";
+import { emitJson, UsageError, warn } from "../output.js";
+import { dependencyVersion, isNewer, KEPT, withFlowPackages } from "../package-edits.js";
+import { applyRecipe, detectedRecipes, loadRecipes, projectPrefix } from "../recipes.js";
+import { hookVersions, registerHooks } from "../settings-hooks.js";
+import { isStaleSchema, ownVersions, PACKAGE, packageManager, readJson, schemaUrl, SETTINGS_FILE, SetupError, writeJson } from "../setup-files.js";
+/** An exact version, as the hooks need one (a leading `=` means the same). */
+const EXACT = /^=?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+/**
+ * The config's migrations, oldest first. Each one sees the config as the earlier ones left
+ * it and returns the new config, or null when there is nothing to do, so running them twice
+ * changes nothing. A key the flow renames goes here.
+ */
+const MIGRATIONS = [];
+/**
+ * Runs the migrations and moves the `$schema` to this version (a `$schema` that is not the
+ * flow's stays).
+ * @param raw - The config.
+ * @param version - This package's version.
+ * @returns The config and what changed.
+ */
+function migrate(raw, version) {
+    let next = raw;
+    const changes = [];
+    for (const migration of MIGRATIONS) {
+        const moved = migration.run(next);
+        if (moved === null)
+            continue;
+        next = moved;
+        changes.push(migration.name);
+    }
+    if (isStaleSchema(next.$schema, version)) {
+        next = { ...next, $schema: schemaUrl(version) };
+        changes.push(`$schema at v${version}`);
+    }
+    return { raw: next, changes };
+}
+/**
+ * A new config: the schema, and the branch rules of `paseo.json` if the repo has one.
+ * @param root - The repo.
+ * @param version - This package's version.
+ * @returns The config and what it took from `paseo.json`.
+ */
+function freshConfig(root, version) {
+    const raw = { $schema: schemaUrl(version) };
+    const issues = readJson(root, "paseo.json")?.project;
+    const paseo = isObject(issues) && isObject(issues.issues) ? issues.issues : null;
+    if (paseo === null)
+        return { raw, changes: ["new"] };
+    const branch = {};
+    if (typeof paseo.branchTemplate === "string")
+        branch.template = paseo.branchTemplate;
+    if (isObject(paseo.types))
+        branch.types = paseo.types;
+    if (Object.keys(branch).length > 0)
+        raw.branch = branch;
+    return { raw, changes: ["new, with the branch rules of paseo.json"] };
+}
+/**
+ * The recipes to apply: the ones named with `--recipe`; with no config yet, each one the
+ * repo's files suggest, after asking (all of them with `--yes`); otherwise none.
+ * @param root - The repo.
+ * @param options - The options.
+ * @param fresh - Whether the config is new.
+ * @param out - Where to ask.
+ * @returns The recipes, or null when it would have to ask and cannot.
+ * @throws UsageError if `--recipe` names one that does not exist.
+ */
+async function pickRecipes(root, options, fresh, out) {
+    const recipes = loadRecipes();
+    if (options.recipes !== null) {
+        const unknown = options.recipes.find((name) => !recipes.some((recipe) => recipe.name === name));
+        if (unknown !== undefined)
+            throw new UsageError(`unknown recipe ${unknown}; there are ${recipes.map((recipe) => recipe.name).join(", ")}.`);
+        return recipes.filter((recipe) => options.recipes?.includes(recipe.name));
+    }
+    if (!fresh)
+        return [];
+    const detected = detectedRecipes(root, recipes);
+    const suggested = recipes.filter((item) => detected.includes(item.name));
+    // NOTE: a dry run shows what --yes would write, so the first apply can be previewed.
+    if (options.yes || options.dryRun || suggested.length === 0)
+        return suggested;
+    if (!out.interactive)
+        return null;
+    const picked = [];
+    for (const recipe of suggested)
+        if (await confirm(out, `Recipe ${recipe.name}: ${recipe.description} Add it?`))
+            picked.push(recipe);
+    return picked;
+}
+/**
+ * Refuses to move the repo back, or to pin over a range: package.json must have an exact
+ * issue-flow, and neither it nor any hook may be newer than this one.
+ * @param root - The repo.
+ * @param versions - This package's versions.
+ * @throws SetupError if the repo has a newer issue-flow or one that is not exact.
+ */
+function checkVersion(root, versions) {
+    const pinned = dependencyVersion(readJson(root, "package.json"), PACKAGE);
+    if (pinned !== null && !EXACT.test(pinned))
+        throw new SetupError(`package.json has issue-flow ${pinned}, not an exact version: the hooks need one. Pin one (such as ${versions.issueFlow}) and run 'npx ${PACKAGE}@<that version> apply'.`);
+    const found = [
+        ...(pinned === null ? [] : [{ where: "package.json", version: pinned.replace(/^=/, "") }]),
+        ...Object.values(hookVersions(readJson(root, SETTINGS_FILE)))
+            .filter((version) => version !== null)
+            .map((version) => ({ where: `a hook of ${SETTINGS_FILE}`, version })),
+    ];
+    const newer = found.find((item) => isNewer(item.version, versions.issueFlow));
+    if (newer !== undefined)
+        throw new SetupError(`${newer.where} has issue-flow ${newer.version}, newer than this ${versions.issueFlow}; run 'npx ${PACKAGE}@${newer.version} apply', or install first if package.json was bumped by hand.`);
+}
+/**
+ * What `apply` would write: the config, `package.json` and the settings' hooks.
+ * @param root - The repo.
+ * @param versions - This package's versions.
+ * @param options - The options.
+ * @param out - Where to ask about the recipes.
+ * @returns The files, or null if it had to ask about the recipes and could not.
+ * @throws ConfigError if the resulting config is invalid; SetupError if a file is broken.
+ */
+async function plan(root, versions, options, out) {
+    const existing = readJson(root, CONFIG_PATH);
+    const recipes = await pickRecipes(root, options, existing === null, out);
+    if (recipes === null)
+        return null;
+    const start = existing === null ? freshConfig(root, versions.issueFlow) : migrate(existing, versions.issueFlow);
+    let { raw } = start;
+    const configChanges = [...start.changes];
+    for (const recipe of recipes) {
+        const applied = applyRecipe(raw, recipe, projectPrefix(root));
+        raw = applied.raw;
+        configChanges.push(...applied.changes.map((change) => (change.startsWith(KEPT) ? `${change} (${recipe.name})` : `${recipe.name}: ${change}`)));
+    }
+    parseConfig(raw);
+    const pkg = withFlowPackages(readJson(root, "package.json"), versions);
+    const hooks = registerHooks(readJson(root, SETTINGS_FILE), versions.issueFlow);
+    const file = (path, value, lines) => ({
+        path,
+        value,
+        changes: lines.filter((line) => !line.startsWith(KEPT)).map((line) => `${path}: ${line}`),
+        kept: lines.filter((line) => line.startsWith(KEPT)).map((line) => `${path}: ${line}`),
+    });
+    // NOTE: the settings go first: the sandbox of claude-repo-guard is likeliest to block them,
+    // and then nothing else has been written.
+    return [file(SETTINGS_FILE, hooks.settings, hooks.changes), file(CONFIG_PATH, raw, configChanges), file("package.json", pkg.pkg, pkg.changes)];
+}
+/**
+ * Writes a file, saying what to do if the sandbox of `claude-repo-guard` blocks it.
+ * @param root - The repo.
+ * @param file - The file.
+ * @param done - The files already written, to say so if this one fails.
+ * @throws SetupError if it cannot be written for lack of permission.
+ */
+function write(root, file, done) {
+    try {
+        writeJson(root, file.path, file.value);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "EPERM" && code !== "EACCES")
+            throw error;
+        const already = done.length === 0 ? "" : ` It already wrote ${done.join(" and ")}; running it again finishes the rest.`;
+        throw new SetupError(`could not write ${file.path} (${code}): inside a Claude session the sandbox blocks it; run apply from your terminal.${already}`);
+    }
+}
+/**
+ * Applies the flow to the repo; see the file's header.
+ * @param options - The options.
+ * @param out - Where to write and ask.
+ * @returns 0 when applied or already there, 1 when it had to ask and could not.
+ * @throws SetupError outside the main checkout, with a broken file, or when it refuses the
+ * version; ConfigError if the config would be invalid; UsageError for an unknown recipe.
+ * @example await apply({ cwd, yes: true, dryRun: false, json: false, recipes: null }, out)
+ */
+export async function apply(options, out) {
+    const located = locateRepo(options.cwd);
+    if (located === null)
+        throw new SetupError("run apply inside a checkout of the repo.");
+    if (checkoutRoot(options.cwd) !== located.mainRoot)
+        throw new SetupError(`run apply in the main checkout, ${located.mainRoot}, not in a worktree.`);
+    const root = located.mainRoot;
+    const versions = ownVersions();
+    checkVersion(root, versions);
+    const planned = await plan(root, versions, options, out);
+    if (planned === null) {
+        warn(out, "nothing written: the repo's files suggest recipes; pass --yes to take them, or --recipe to pick.");
+        if (options.json)
+            emitJson(out, { version: versions.issueFlow, changes: [], kept: [], written: false, next: ["pass --yes or --recipe"] });
+        return 1;
+    }
+    const files = planned.filter((file) => file.changes.length > 0);
+    const changes = files.flatMap((file) => file.changes);
+    const kept = planned.flatMap((file) => file.kept);
+    for (const line of kept)
+        warn(out, line);
+    const written = !options.dryRun && files.length > 0;
+    const done = [];
+    if (written)
+        for (const file of files) {
+            write(root, file, done);
+            done.push(file.path);
+        }
+    const pkgChanged = files.some((file) => file.path === "package.json");
+    const next = files.length === 0 ? [] : [...(pkgChanged ? [`${packageManager(root, readJson(root, "package.json"))} install`] : []), "review the diff and commit it"];
+    if (options.json) {
+        emitJson(out, { version: versions.issueFlow, changes, kept, written, next });
+        return 0;
+    }
+    if (changes.length === 0)
+        out.stdout(`Already at issue-flow ${versions.issueFlow}.\n`);
+    else
+        out.stdout(`issue-flow ${versions.issueFlow}${options.dryRun ? " would write" : ""}:\n${changes.map((line) => `  ${line}\n`).join("")}`);
+    if (written)
+        out.stdout(`Next: ${pkgChanged ? `run '${next[0]}', ` : ""}review the diff and commit it.\n`);
+    return 0;
+}

package/dist/commands/doctor.js

@@ -1,60 +1,79 @@
 /**
- * @file `issue-flow doctor [--json]`: whether the repo's flow files are as `init` leaves
- * them, at this version: the config, the dev dependencies and the hooks. It changes nothing;
- * each problem says what fixes it. `--json` prints the checks for `agent-kitchen`,
+ * @file `issue-flow doctor [--json]`: whether the repo's flow files are as `apply` leaves
+ * them, at this version: the config and its `$schema`, the dev dependencies and the hooks.
+ * It changes nothing; each problem says what fixes it: `npx agent-kitchen apply` when the
+ * repo pins another issue-flow (it also moves the skills), and `issue-flow apply` when the
+ * version is this one but its files fell behind. `--json` prints the checks for `agent-kitchen`,
  * which adds those of the skills and the other tools.
  */
-import { ConfigError } from "../config-base.js";
+import { CONFIG_PATH, ConfigError } from "../config-base.js";
 import { loadConfig } from "../config.js";
 import { locateRepo } from "../git.js";
-import { dependencyVersion } from "../package-edits.js";
+import { dependencyVersion, GITHUB_REST, reaches } from "../package-edits.js";
 import { hookVersions } from "../settings-hooks.js";
-import { ownVersions, PACKAGE, readJson, SETTINGS_FILE, SetupError } from "../setup-files.js";
-/** What fixes every problem: it runs init or upgrade at the right version. */
-const RUN_AGENT_KITCHEN = "run npx agent-kitchen";
+import { isStaleSchema, ownVersions, PACKAGE, readJson, SETTINGS_FILE, SetupError } from "../setup-files.js";
+/** What fixes a repo at another version: it runs apply at the right one and moves the skills. */
+const RUN_AGENT_KITCHEN = "run npx agent-kitchen apply";
+/** What fixes the files of a repo already at this version. */
+const RUN_APPLY = `run npx ${PACKAGE} apply`;
 /**
- * Checks the config.
+ * What fixes a problem: `issue-flow apply` if the repo pins this version, else agent-kitchen.
+ * @param pinned - The issue-flow the repo pins, or null.
+ * @param version - This package's version.
+ * @returns The hint.
+ */
+function fix(pinned, version) {
+    return pinned === version ? RUN_APPLY : RUN_AGENT_KITCHEN;
+}
+/**
+ * Checks the config, and that its `$schema` (if it is the flow's) is at this version.
  * @param root - The repo.
+ * @param hint - What fixes a stale `$schema`.
+ * @param version - This package's version.
  * @returns The check.
  */
-function configCheck(root) {
+function configCheck(root, hint, version) {
     try {
         loadConfig(root);
-        return { name: ".agents/flow.json", ok: true, detail: "valid" };
     }
     catch (error) {
         if (!(error instanceof ConfigError))
             throw error;
-        return { name: ".agents/flow.json", ok: false, detail: error.message };
+        return { name: CONFIG_PATH, ok: false, detail: error.message };
     }
+    const stale = isStaleSchema(readJson(root, CONFIG_PATH)?.$schema, version);
+    return stale ? { name: CONFIG_PATH, ok: false, detail: `valid, but its $schema is not at v${version}: ${hint}` } : { name: CONFIG_PATH, ok: true, detail: "valid" };
 }
 /**
  * Checks the dev dependencies: `issue-flow` at this version and `github-rest`, which the
- * skills call.
+ * skills call, at the version the flow needs or newer.
  * @param root - The repo.
- * @param version - This package's version.
+ * @param versions - This package's version and the lowest github-rest.
  * @returns The checks.
  */
-function packageChecks(root, version) {
+function packageChecks(root, versions) {
     const pkg = readJson(root, "package.json");
     const flow = dependencyVersion(pkg, PACKAGE);
-    const rest = dependencyVersion(pkg, "@ramon-sg/github-rest");
+    const rest = dependencyVersion(pkg, GITHUB_REST);
+    const version = versions.issueFlow;
+    const restDetail = rest === null ? `not in package.json, and the skills call it: ${fix(flow, version)}` : reaches(rest, versions.githubRest) ? rest : `${rest}, and the skills need ${versions.githubRest} or newer: raise it in package.json`;
     return [
         { name: PACKAGE, ok: flow === version, detail: flow === null ? `not in package.json: ${RUN_AGENT_KITCHEN}` : flow === version ? version : `package.json has ${flow}, this is ${version}: ${RUN_AGENT_KITCHEN}` },
-        { name: "@ramon-sg/github-rest", ok: rest !== null, detail: rest ?? `not in package.json, and the skills call it: ${RUN_AGENT_KITCHEN}` },
+        { name: GITHUB_REST, ok: rest !== null && reaches(rest, versions.githubRest), detail: restDetail },
     ];
 }
 /**
  * Checks that each hook is there at this version.
  * @param root - The repo.
  * @param version - This package's version.
+ * @param hint - What fixes a missing or stale hook.
  * @returns The checks.
  */
-function hookChecks(root, version) {
+function hookChecks(root, version, hint) {
     return Object.entries(hookVersions(readJson(root, SETTINGS_FILE))).map(([event, found]) => ({
         name: `${event} hook`,
         ok: found === version,
-        detail: found === null ? `not in ${SETTINGS_FILE}: ${RUN_AGENT_KITCHEN}` : found === version ? version : `at ${found}, this is ${version}: ${RUN_AGENT_KITCHEN}`,
+        detail: found === null ? `not in ${SETTINGS_FILE}: ${hint}` : found === version ? version : `at ${found}, this is ${version}: ${hint}`,
     }));
 }
 /**
@@ -71,10 +90,11 @@ export function doctor(cwd, json, out) {
     if (located === null)
         throw new SetupError("run doctor inside a checkout of the repo.");
     const root = located.mainRoot;
-    const { issueFlow } = ownVersions();
+    const versions = ownVersions();
     let checks;
     try {
-        checks = [configCheck(root), ...packageChecks(root, issueFlow), ...hookChecks(root, issueFlow)];
+        const hint = fix(dependencyVersion(readJson(root, "package.json"), PACKAGE), versions.issueFlow);
+        checks = [configCheck(root, hint, versions.issueFlow), ...packageChecks(root, versions), ...hookChecks(root, versions.issueFlow, hint)];
     }
     catch (error) {
         if (!(error instanceof SetupError))

package/dist/package-edits.d.ts

@@ -1,17 +1,36 @@
 /**
- * @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.
+ * @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";
+import { type OwnVersions } from "./setup-files.js";
 /**
- * The dependencies the flow pins, with their versions.
- * @param versions - This package's versions.
- * @returns Package to version.
- * @example pinnedPackages(versions)["@ramon-sg/issue-flow"] // "0.1.0"
+ * Whether a version is newer than another; false if either is not a version. A leading
+ * range sign is dropped, so `^0.3.0` reads as 0.3.0.
+ * @param version - The version, maybe with a range sign.
+ * @param than - The other.
+ * @returns True if it is newer.
+ * @example isNewer("1.10.0", "1.9.0") // true
+ */
+export declare function isNewer(version: string, than: string): boolean;
+/**
+ * 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 needs.
+ * @returns True if it reaches it.
+ * @example reaches("1.3.0", "1.2.0") // true
  */
-export declare function pinnedPackages(versions: OwnVersions): Record<string, string>;
+export declare function reaches(current: string, tested: string): boolean;
+/** How a change that keeps what the repo had starts. */
+export declare const KEPT = "kept ";
+/** 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.
@@ -21,15 +40,15 @@ export declare function pinnedPackages(versions: OwnVersions): Record<string, st
  */
 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[];
 };

package/dist/package-edits.js

@@ -1,22 +1,111 @@
-/** The scripts `init` adds. */
+/**
+ * @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. */
+const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+/** A range this file understands: a sign (`^`, `~`, `>=`, `=`) before a version. */
+const SIMPLE_RANGE = /^(\^|~|>=|=)\s*(\S+)$/;
+/**
+ * Parses a version.
+ * @param text - The version, without a range sign.
+ * @returns It, or null if it is not one.
+ */
+function parse(text) {
+    const match = VERSION.exec(text);
+    if (match === null)
+        return null;
+    return { parts: [Number(match[1]), Number(match[2]), Number(match[3])], pre: match[4] ?? null };
+}
+/**
+ * Compares two versions, semver-style: by the numbers, then a pre-release before its release.
+ * @param left - One.
+ * @param right - The other.
+ * @returns Negative if left is older, 0 if equal, positive if newer.
+ */
+function compare(left, right) {
+    for (let index = 0; index < 3; index += 1) {
+        const diff = left.parts[index] - right.parts[index];
+        if (diff !== 0)
+            return diff;
+    }
+    if (left.pre === right.pre)
+        return 0;
+    if (left.pre === null)
+        return 1;
+    if (right.pre === null)
+        return -1;
+    return left.pre.localeCompare(right.pre, "en", { numeric: true });
+}
+/**
+ * Whether a version is newer than another; false if either is not a version. A leading
+ * range sign is dropped, so `^0.3.0` reads as 0.3.0.
+ * @param version - The version, maybe with a range sign.
+ * @param than - The other.
+ * @returns True if it is newer.
+ * @example isNewer("1.10.0", "1.9.0") // true
+ */
+export function isNewer(version, than) {
+    const [left, right] = [parse(version.replace(/^[\^~=]/, "")), parse(than.replace(/^[\^~=]/, ""))];
+    return left !== null && right !== null && compare(left, right) > 0;
+}
+/**
+ * The first version a simple range leaves out, or null if it has no ceiling (`>=`).
+ * @param sign - `^`, `~` or `>=`.
+ * @param floor - Its version.
+ * @returns The ceiling.
+ */
+function ceiling(sign, floor) {
+    const [major, minor, patch] = floor.parts;
+    if (sign === ">=")
+        return null;
+    if (sign === "~")
+        return { parts: [major, minor + 1, 0], pre: null };
+    if (major > 0)
+        return { parts: [major + 1, 0, 0], pre: null };
+    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 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 needs.
+ * @returns True if it reaches it.
+ * @example reaches("1.3.0", "1.2.0") // true
+ */
+export function reaches(current, tested) {
+    const wanted = parse(tested);
+    if (wanted === null)
+        return true;
+    const exact = parse(current);
+    if (exact !== null)
+        return compare(exact, wanted) >= 0;
+    const range = SIMPLE_RANGE.exec(current.trim());
+    const floor = range === null ? null : parse(range[2]);
+    if (range === null || floor === null)
+        return true;
+    if (range[1] === "=")
+        return compare(floor, wanted) >= 0;
+    const top = ceiling(range[1], floor);
+    return top === null || compare(wanted, top) < 0;
+}
+/** How a change that keeps what the repo had starts. */
+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 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.
- * @param versions - This package's versions.
- * @returns Package to version.
- * @example pinnedPackages(versions)["@ramon-sg/issue-flow"] // "0.1.0"
- */
-export function pinnedPackages(versions) {
-    return {
-        "@ramon-sg/issue-flow": versions.issueFlow,
-        "@ramon-sg/github-rest": versions.githubRest,
-        "@ramon-sg/skills-manager": versions.skillsManager,
-    };
-}
 /**
  * Where a package is in the repo's package.json, and its version.
  * @param pkg - The package.json.
@@ -43,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] of Object.entries(pinnedPackages(versions))) {
-        const current = dependencyOf(next, name);
-        if (current?.version === version)
-            continue;
-        if (current !== null && !move) {
-            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/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 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 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.6",
+  "version": "0.3.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",
@@ -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>;

package/dist/commands/init.js

@@ -1,136 +0,0 @@
-/**
- * @file `issue-flow init`: sets a repo up for the flow, and can run again to fill in what
- * is missing. It writes `.agents/flow.json` (from `paseo.json` if the repo has one, plus the
- * recipes it picks), the flow's dev dependencies and scripts in `package.json`, and the
- * `SessionStart`, `WorktreeCreate` and `WorktreeRemove` hooks. Only the flow's own files:
- * the skills, `claude-cloud` and `claude-repo-guard` are installed by `agent-kitchen`,
- * which runs this command.
- */
-import { confirm } from "../ask.js";
-import { CONFIG_PATH, isObject } from "../config-base.js";
-import { parseConfig } from "../config.js";
-import { checkoutRoot, locateRepo } from "../git.js";
-import { UsageError, warn } from "../output.js";
-import { withFlowPackages } from "../package-edits.js";
-import { applyRecipe, detectedRecipes, loadRecipes, projectPrefix } from "../recipes.js";
-import { registerHooks } from "../settings-hooks.js";
-import { FLOW_REPO, ownVersions, packageManager, readJson, SETTINGS_FILE, SetupError, writeJson } from "../setup-files.js";
-/**
- * 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 `https://raw.githubusercontent.com/${FLOW_REPO}/v${version}/schema.json`;
-}
-/**
- * A new config: the schema, and the branch rules of `paseo.json` if the repo has one.
- * @param root - The repo.
- * @param version - This package's version.
- * @returns The config and what it took from `paseo.json`.
- */
-function freshConfig(root, version) {
-    const raw = { $schema: schemaUrl(version) };
-    const issues = readJson(root, "paseo.json")?.project;
-    const paseo = isObject(issues) && isObject(issues.issues) ? issues.issues : null;
-    if (paseo === null)
-        return { raw, changes: ["new"] };
-    const branch = {};
-    if (typeof paseo.branchTemplate === "string")
-        branch.template = paseo.branchTemplate;
-    if (isObject(paseo.types))
-        branch.types = paseo.types;
-    if (Object.keys(branch).length > 0)
-        raw.branch = branch;
-    return { raw, changes: ["new, with the branch rules of paseo.json"] };
-}
-/**
- * The recipes to apply: the ones named with `--recipe`, or each one the repo's files
- * suggest, after asking (all of them with `--yes`).
- * @param root - The repo.
- * @param options - The options.
- * @param out - Where to ask.
- * @returns The recipes.
- * @throws UsageError if `--recipe` names one that does not exist.
- */
-async function pickRecipes(root, options, out) {
-    const recipes = loadRecipes();
-    if (options.recipes !== null) {
-        const unknown = options.recipes.find((name) => !recipes.some((recipe) => recipe.name === name));
-        if (unknown !== undefined)
-            throw new UsageError(`unknown recipe ${unknown}; there are ${recipes.map((recipe) => recipe.name).join(", ")}.`);
-        return recipes.filter((recipe) => options.recipes?.includes(recipe.name));
-    }
-    const picked = [];
-    for (const recipe of recipes.filter((item) => detectedRecipes(root, recipes).includes(item.name)))
-        if (options.yes || (await confirm(out, `Recipe ${recipe.name}: ${recipe.description} Add it?`)))
-            picked.push(recipe);
-    return picked;
-}
-/** How a line of a change that keeps what the repo had starts. */
-const KEPT = "kept ";
-/**
- * What `init` would write: the config, `package.json` and the settings' hooks.
- * @param root - The repo.
- * @param versions - This package's versions.
- * @param recipes - The recipes to apply.
- * @returns The files that change.
- * @throws ConfigError if the resulting config is invalid; SetupError if a file is broken.
- */
-function plan(root, versions, recipes) {
-    const existing = readJson(root, CONFIG_PATH);
-    const start = existing === null ? freshConfig(root, versions.issueFlow) : { raw: existing, changes: [] };
-    let { raw } = start;
-    const configChanges = [...start.changes];
-    for (const recipe of recipes) {
-        const applied = applyRecipe(raw, recipe, projectPrefix(root));
-        raw = applied.raw;
-        configChanges.push(...applied.changes.map((change) => (change.startsWith(KEPT) ? `${change} (${recipe.name})` : `${recipe.name}: ${change}`)));
-    }
-    parseConfig(raw);
-    const pkg = withFlowPackages(readJson(root, "package.json"), versions, false);
-    const hooks = registerHooks(readJson(root, SETTINGS_FILE), versions.issueFlow);
-    const file = (path, value, lines) => ({
-        path,
-        value,
-        changes: lines.filter((line) => !line.startsWith(KEPT)).map((line) => `${path}: ${line}`),
-        kept: lines.filter((line) => line.startsWith(KEPT)).map((line) => `${path}: ${line}`),
-    });
-    return [file(CONFIG_PATH, raw, configChanges), file("package.json", pkg.pkg, pkg.changes), file(SETTINGS_FILE, hooks.settings, hooks.changes)];
-}
-/**
- * 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 async function init(options, out) {
-    const located = locateRepo(options.cwd);
-    if (located === null)
-        throw new SetupError("run init inside a checkout of the repo.");
-    if (checkoutRoot(options.cwd) !== located.mainRoot)
-        throw new SetupError(`run init in the main checkout, ${located.mainRoot}, not in a worktree.`);
-    const root = located.mainRoot;
-    const versions = ownVersions();
-    const files = plan(root, versions, await pickRecipes(root, options, out)).filter((file) => file.changes.length > 0 || file.kept.length > 0);
-    for (const line of files.flatMap((file) => file.kept))
-        warn(out, line);
-    const lines = files.flatMap((file) => file.changes);
-    if (lines.length === 0)
-        out.stdout("The config, package.json and the hooks are already set up.\n");
-    else
-        out.stdout(`issue-flow ${versions.issueFlow} will write:\n${lines.map((line) => `  ${line}\n`).join("")}`);
-    if (lines.length > 0 && !options.yes && !(await confirm(out, "Write it?"))) {
-        warn(out, "nothing written.");
-        return 1;
-    }
-    for (const file of files.filter((item) => item.changes.length > 0))
-        writeJson(root, file.path, file.value);
-    const manager = packageManager(root, readJson(root, "package.json"));
-    out.stdout(`Next: run '${manager} install', and commit .agents/, .claude/ and package.json.\n`);
-    return 0;
-}

package/dist/commands/upgrade.d.ts

@@ -1,16 +0,0 @@
-import type { Output } from "../output.js";
-/** Options of `issue-flow upgrade`. */
-export interface UpgradeOptions {
-    cwd: string;
-    dryRun: boolean;
-}
-/**
- * Moves the repo's flow files to this version; see the file's header.
- * @param options - The options.
- * @param out - Where to write.
- * @returns 0.
- * @throws SetupError outside the main checkout, if a file is broken, or if the repo is
- * already at a newer version (a stale local copy must not move it back).
- * @example upgrade({ cwd, dryRun: false }, out)
- */
-export declare function upgrade(options: UpgradeOptions, out: Output): number;

package/dist/commands/upgrade.js

@@ -1,85 +0,0 @@
-/**
- * @file `issue-flow upgrade [--dry-run]`: moves the repo's flow files to the version that
- * runs: the dev dependencies to the ones it pins, and the hooks and the config's schema to
- * it. `agent-kitchen` runs it as `npx @ramon-sg/issue-flow@<version> upgrade` and then
- * moves the flow's skills to the same tag, because the skills call this CLI.
- */
-import { CONFIG_PATH } from "../config-base.js";
-import { checkoutRoot, locateRepo } from "../git.js";
-import { dependencyVersion, withFlowPackages } from "../package-edits.js";
-import { hookVersions, registerHooks } from "../settings-hooks.js";
-import { FLOW_REPO, ownVersions, PACKAGE, packageManager, readJson, SETTINGS_FILE, SetupError, writeJson } from "../setup-files.js";
-import { schemaUrl } from "./init.js";
-/** The start of the schema URL `init` writes, at any version. */
-const SCHEMA_PREFIX = `https://raw.githubusercontent.com/${FLOW_REPO}/`;
-/** A release version, after an optional range sign. */
-const RELEASE = /^[\^~=]?(\d+)\.(\d+)\.(\d+)$/;
-/**
- * Whether a version is newer than another; false if either is not a release.
- * @param version - The version, maybe with a range sign.
- * @param than - The other.
- * @returns True if it is newer.
- */
-function isNewer(version, than) {
-    const [left, right] = [RELEASE.exec(version), RELEASE.exec(than)];
-    if (left === null || right === null)
-        return false;
-    for (let index = 1; index <= 3; index += 1) {
-        const diff = Number(left[index]) - Number(right[index]);
-        if (diff !== 0)
-            return diff > 0;
-    }
-    return false;
-}
-/**
- * The newest version of the flow the repo already has, in package.json or a hook.
- * @param root - The repo.
- * @returns The version, or null if it has none.
- */
-function repoVersion(root) {
-    const found = [dependencyVersion(readJson(root, "package.json"), PACKAGE), ...Object.values(hookVersions(readJson(root, SETTINGS_FILE)))];
-    return found.filter((version) => version !== null).reduce((newest, version) => (newest === null || isNewer(version, newest) ? version : newest), null);
-}
-/**
- * Moves the repo's flow files to this version; see the file's header.
- * @param options - The options.
- * @param out - Where to write.
- * @returns 0.
- * @throws SetupError outside the main checkout, if a file is broken, or if the repo is
- * already at a newer version (a stale local copy must not move it back).
- * @example upgrade({ cwd, dryRun: false }, out)
- */
-export function upgrade(options, out) {
-    const located = locateRepo(options.cwd);
-    if (located === null)
-        throw new SetupError("run upgrade inside a checkout of the repo.");
-    const root = located.mainRoot;
-    if (checkoutRoot(options.cwd) !== root)
-        throw new SetupError(`run upgrade in the main checkout, ${root}, not in a worktree.`);
-    const versions = ownVersions();
-    const current = repoVersion(root);
-    if (current !== null && isNewer(current, versions.issueFlow))
-        throw new SetupError(`the repo is at issue-flow ${current}, newer than this ${versions.issueFlow}; run 'npx ${PACKAGE}@${current.replace(/^[\^~=]/, "")} upgrade' or 'npx agent-kitchen'.`);
-    const writes = [];
-    const lines = [];
-    const pkg = withFlowPackages(readJson(root, "package.json"), versions, true);
-    if (pkg.changes.length > 0)
-        writes.push({ path: "package.json", value: pkg.pkg });
-    lines.push(...pkg.changes.map((change) => `package.json: ${change}`));
-    const hooks = registerHooks(readJson(root, SETTINGS_FILE), versions.issueFlow);
-    if (hooks.changes.length > 0)
-        writes.push({ path: SETTINGS_FILE, value: hooks.settings });
-    lines.push(...hooks.changes.map((change) => `${SETTINGS_FILE}: ${change}`));
-    const config = readJson(root, CONFIG_PATH);
-    if (config !== null && typeof config.$schema === "string" && config.$schema.startsWith(SCHEMA_PREFIX) && config.$schema !== schemaUrl(versions.issueFlow)) {
-        writes.push({ path: CONFIG_PATH, value: { ...config, $schema: schemaUrl(versions.issueFlow) } });
-        lines.push(`${CONFIG_PATH}: $schema at v${versions.issueFlow}`);
-    }
-    out.stdout(lines.length === 0 ? `Already at issue-flow ${versions.issueFlow}.\n` : `To issue-flow ${versions.issueFlow}:\n${lines.map((line) => `  ${line}\n`).join("")}`);
-    if (options.dryRun || writes.length === 0)
-        return 0;
-    for (const write of writes)
-        writeJson(root, write.path, write.value);
-    out.stdout(`Next: run '${packageManager(root, readJson(root, "package.json"))} install', review the diff and commit it.\n`);
-    return 0;
-}