@ramon-sg/issue-flow 0.2.7 → 0.3.1

package/README.md

@@ -6,7 +6,7 @@ Flujo de trabajo de issue a PR para cualquier repo, en local y en las sesiones d
 
 ## 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 apply` 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: `@ramon-sg/issue-flow`, los hooks y el `$schema`. `github-rest` y `skills-manager` solo suben si no llegan a la versión con que se probó issue-flow: una versión igual o más nueva, un rango que la permite (`^1.2.0` para 1.3.0, no `^0.1.0` para 0.3.0) o una fuente como `workspace:*` se deja como está y se avisa (`kept …`). 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. */
+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/commands/pr-worktree.js

@@ -13,7 +13,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { getPr } from "@ramon-sg/github-rest";
 import { canonicalPath } from "../docker.js";
-import { checkedOutAt, git, hasLocal, locateRepo, worktrees } from "../git.js";
+import { checkedOutAt, git, hasLocal, locateRepo, trackOrigin, untracked, worktrees } from "../git.js";
 import { permissionArgs } from "../launch.js";
 import { warn } from "../output.js";
 import { copyWorktreeIncludes } from "../start-place.js";
@@ -45,7 +45,7 @@ function mustGit(cwd, args, message) {
 }
 /**
  * Makes the worktree on the PR's branch: the local branch if there is one (moved forward to
- * origin's when it can be), or a new one tracking origin's.
+ * origin's when it can be), or a new one; either way tracking origin's when it can.
  * @param mainRoot - The main checkout.
  * @param branch - The PR's branch.
  * @param path - The worktree.
@@ -57,14 +57,14 @@ function addWorktree(mainRoot, branch, path, out) {
     const elsewhere = checkedOutAt(mainRoot, branch);
     if (elsewhere !== null)
         throw new StartError(`${branch} is checked out in ${elsewhere}; review it there, or switch that checkout to another branch.`);
-    if (!hasLocal(mainRoot, branch)) {
-        mustGit(mainRoot, ["worktree", "add", "-q", "--track", "-b", branch, path, `origin/${branch}`], `could not make the worktree of ${branch}`);
-        return;
-    }
-    mustGit(mainRoot, ["worktree", "add", "-q", path, branch], `could not make the worktree of ${branch}`);
-    if (!git(path, ["branch", "-q", "--set-upstream-to", `origin/${branch}`]).ok)
-        warn(out, `could not make ${branch} track origin/${branch}.`);
-    if (!git(path, ["merge", "-q", "--ff-only", `origin/${branch}`]).ok)
+    // NOTE: the tracking goes apart, after the worktree: it writes .git/config, which Claude
+    // Code's sandbox forbids, and the worktree is still useful without it.
+    const local = hasLocal(mainRoot, branch);
+    const args = local ? [path, branch] : ["--no-track", "-b", branch, path, `origin/${branch}`];
+    mustGit(mainRoot, ["worktree", "add", "-q", ...args], `could not make the worktree of ${branch}`);
+    if (!trackOrigin(path, branch))
+        warn(out, untracked(branch));
+    if (local && !git(path, ["merge", "-q", "--ff-only", `origin/${branch}`]).ok)
         warn(out, `the local ${branch} does not move forward to origin/${branch}: you see other commits than the PR's.`);
 }
 /**

package/dist/git.d.ts

@@ -28,6 +28,22 @@ export declare function gitLines(cwd: string, args: string[]): string[];
  * @example hasRef("/repo", "refs/heads/main")
  */
 export declare function hasRef(cwd: string, ref: string): boolean;
+/**
+ * Makes a branch track origin's of the same name, unless it already does. The upstream lives
+ * in `.git/config`, which Claude Code's sandbox forbids writing, so this is the only step that
+ * writes it: branches are made with `--no-track` and pushed without `-u`.
+ * @param cwd - The checkout.
+ * @param branch - The branch.
+ * @returns True if it tracks `origin/<branch>` now; false if git could not write it.
+ * @example trackOrigin("/repo", "feat/42-x")
+ */
+export declare function trackOrigin(cwd: string, branch: string): boolean;
+/**
+ * The warning when a branch cannot track origin's.
+ * @param branch - The branch.
+ * @returns The warning.
+ */
+export declare function untracked(branch: string): string;
 /**
  * Whether the branch exists locally.
  * @param cwd - The checkout.

package/dist/git.js

@@ -41,6 +41,29 @@ export function gitLines(cwd, args) {
 export function hasRef(cwd, ref) {
     return git(cwd, ["rev-parse", "-q", "--verify", ref]).ok;
 }
+/**
+ * Makes a branch track origin's of the same name, unless it already does. The upstream lives
+ * in `.git/config`, which Claude Code's sandbox forbids writing, so this is the only step that
+ * writes it: branches are made with `--no-track` and pushed without `-u`.
+ * @param cwd - The checkout.
+ * @param branch - The branch.
+ * @returns True if it tracks `origin/<branch>` now; false if git could not write it.
+ * @example trackOrigin("/repo", "feat/42-x")
+ */
+export function trackOrigin(cwd, branch) {
+    const upstream = git(cwd, ["rev-parse", "-q", "--symbolic-full-name", `${branch}@{u}`]);
+    if (upstream.ok && upstream.out === `refs/remotes/origin/${branch}`)
+        return true;
+    return git(cwd, ["branch", "-q", `--set-upstream-to=origin/${branch}`, branch]).ok;
+}
+/**
+ * The warning when a branch cannot track origin's.
+ * @param branch - The branch.
+ * @returns The warning.
+ */
+export function untracked(branch) {
+    return `could not make ${branch} track origin/${branch} (is .git/config read-only, as in a sandbox?); push with 'git push origin HEAD'.`;
+}
 /**
  * Whether the branch exists locally.
  * @param cwd - The checkout.