@ramon-sg/issue-flow 0.2.5 → 0.2.7

package/README.md

@@ -2,12 +2,13 @@
 
 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 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.
 - **`issue-flow worktree setup|teardown|ports|cleanup|prune`:** prepara y limpia cada worktree con los pasos del repo, le da un bloque de puertos y borra los worktrees con el PR cerrado.
 - **`issue-flow pr worktree <n>`:** abre un PR en su propio worktree, en la rama del PR, para revisarlo sin soltar lo que estás haciendo.
@@ -182,7 +183,7 @@ Es el hook `SessionStart` de Claude Code. Lo que imprime le llega a Claude como
 
 ## Lo que el flujo deja en el repo: `issue-flow init`
 
-`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 estos tres comandos en la versión que corresponde. Correrlos 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
@@ -199,7 +200,7 @@ npx @ramon-sg/issue-flow@<versión> upgrade  # mueve el repo a esa versión (--d
 
 **`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.
 
-**`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.
+**`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.
 
 ### Recetas
 
@@ -270,6 +271,40 @@ Todo es opcional; sin el archivo valen los valores por defecto. Una clave descon
 | `start.cloudPrompt` | `/start-issue {number} --yes{flags}` | Lo que `--cloud` le pide a la sesión; `{flags}` es `--new` o `--resume <rama>` |
 | `plans.dirs` | `docs/plans`, `docs/specs` | Dónde buscar el plan de la issue: lo que tocó la rama, o el documento cuyo `prs:` nombra su PR |
 | `colors` | `critical-path` y `P1:` rojo, `P2:` naranjo, `P3:` amarillo, `P4:` cian | Color de la sesión por prefijo de label; gana el primero que calce |
+| `labels` | Los 8 de abajo | Labels que crea `labels sync`; lo del repo se suma al default (ver abajo) |
+
+## Labels: `issue-flow labels sync`
+
+```sh
+npx @ramon-sg/issue-flow labels sync --dry-run   # qué haría
+npx @ramon-sg/issue-flow labels sync             # crea los que faltan
+npx @ramon-sg/issue-flow labels sync --update    # también corrige color y descripción
+```
+
+Crea en GitHub los labels de `labels` que el repo no tiene. Los nombres se comparan sin mayúsculas, como en GitHub: un `Bug` cuenta como `bug` y nunca se renombra. Uno que existe con otro color o descripción solo se avisa, salvo con `--update`. Nunca borra. `--json` da la lista con el estado de cada uno: `created`, `updated`, `ok`, `differs`, o `to-create` y `to-update` con `--dry-run`. Si GitHub rechaza uno, sigue con los demás, lo marca `failed` y sale con 1.
+
+| Label | Color | Descripción |
+|---|---|---|
+| `bug` | `d73a4a` | Something isn't working |
+| `enhancement` | `a2eeef` | New feature or request |
+| `documentation` | `0075ca` | Improvements or additions to documentation |
+| `spike` | `fbca04` | Time-boxed research before building |
+| `P1: urgent` | `B60205` | Breaks production or blocks work |
+| `P2: important` | `F9D0C4` | Real impact, with some slack |
+| `P3: minor` | `FEF2C0` | Default when in doubt |
+| `P4: low` | `BFDADC` | Nice-to-have |
+
+Los tres primeros son los de GitHub, con sus colores y textos. A diferencia de `branch.types` y `colors`, lo que pone el repo **se suma** al default: un nombre reemplaza al de por defecto con ese nombre, y `null` lo quita. La taxonomía del repo va acá y no en el `project.md` de `github-issues`, porque con `claude-repo-guard` el agente no puede escribir en `.agents/skills/`:
+
+```json
+{
+  "labels": {
+    "area:api": { "color": "1d76db", "description": "packages/api" },
+    "size:S": { "color": "c5def5", "description": "Menos de 1 día" },
+    "spike": null
+  }
+}
+```
 
 ## Desarrollo
 

package/dist/cli.d.ts

@@ -84,6 +84,9 @@ declare const OPTIONS: {
     readonly recipe: {
         readonly type: "string";
     };
+    readonly update: {
+        readonly type: "boolean";
+    };
 };
 /** The parsed flags. */
 export type Flags = ReturnType<typeof parseArgs<{

package/dist/cli.js

@@ -8,6 +8,7 @@ import { parseArgs } from "node:util";
 import { GitHubError, InvalidRepoEnvError, resolveRepo } from "@ramon-sg/github-rest";
 import { branchMissing, branchOf } from "./commands/issue-branch.js";
 import { issueStart } from "./commands/issue-start.js";
+import { labelsSync } from "./commands/labels.js";
 import { ADAPTER_COMMANDS, HOOK_COMMANDS, runAdapter, runHook, runSession, runWorktree, WORKTREE_COMMANDS } from "./cli-worktree.js";
 import { runSetupCommand, SETUP_COMMANDS } from "./cli-setup.js";
 import { prWorktree } from "./commands/pr-worktree.js";
@@ -41,6 +42,7 @@ const OPTIONS = {
     next: { type: "boolean" },
     "no-setup": { type: "boolean" },
     recipe: { type: "string" },
+    update: { type: "boolean" },
 };
 /** Flags each command takes, besides `--repo`, `--help` and `--namer`. */
 const COMMAND_FLAGS = {
@@ -75,6 +77,7 @@ const COMMAND_FLAGS = {
     init: ["yes", "recipe"],
     doctor: ["json"],
     upgrade: ["dry-run"],
+    "labels sync": ["update", "dry-run", "json"],
 };
 /** An issue number: digits only. */
 const NUMBER = /^\d+$/;
@@ -216,6 +219,8 @@ export async function main(argv, out, cwd) {
         throw new UsageError("-- only goes with pr worktree.");
     if (group === "pr")
         return runPr(sub, rest, flags, { out, cwd, command });
+    if (group === "labels")
+        return runLabels(sub, rest, flags, { out, cwd });
     if (group !== undefined && SETUP_COMMANDS.includes(group)) {
         ownFlags(group, flags);
         return runSetupCommand(group, flags, [sub, ...rest].filter((item) => item !== undefined), { out, cwd });
@@ -253,6 +258,24 @@ async function runPr(sub, rest, flags, run) {
     const config = loadConfig(run.cwd);
     return prWorktree({ repo: repoOf(flags.repo, config, run.cwd), config, cwd: run.cwd, number: Number(text), setup: !(flags["no-setup"] ?? false), command: run.command }, run.out);
 }
+/**
+ * Runs `issue-flow labels sync`.
+ * @param sub - The word after `labels`.
+ * @param rest - The positionals after it.
+ * @param flags - The flags.
+ * @param run - Where it writes and runs.
+ * @returns The exit code.
+ * @throws UsageError if the arguments do not fit; GitHubError if GitHub fails.
+ */
+async function runLabels(sub, rest, flags, run) {
+    if (sub !== "sync")
+        throw new UsageError("labels expects sync.");
+    ownFlags("labels sync", flags);
+    if (rest.length > 0)
+        throw new UsageError("labels sync takes no arguments.");
+    const config = loadConfig(run.cwd);
+    return labelsSync({ repo: repoOf(flags.repo, config, run.cwd), labels: config.labels, update: flags.update ?? false, dryRun: flags["dry-run"] ?? false, json: flags.json ?? false }, run.out);
+}
 /**
  * Runs the `issue`, `worktree` and `session` commands.
  * @param group - The first word.

package/dist/commands/doctor.js

@@ -11,7 +11,7 @@ import { dependencyVersion } 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";
+const RUN_AGENT_KITCHEN = "run npx agent-kitchen apply";
 /**
  * Checks the config.
  * @param root - The repo.

package/dist/commands/init.js

@@ -11,7 +11,7 @@ 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 { KEPT, 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";
@@ -68,8 +68,6 @@ async function pickRecipes(root, options, out) {
             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.

package/dist/commands/labels.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file `issue-flow labels sync [--update] [--dry-run] [--json]`: makes in GitHub the labels
+ * of `labels` in `.agents/flow.json` that the repo lacks. Names compare ignoring case, as
+ * GitHub does, so `Bug` counts as `bug` and is never renamed. A label that exists with
+ * another color or description is only reported, unless `--update`. It never deletes. A
+ * write that fails does not stop the rest: every label is reported, and it exits 1.
+ */
+import { type Label } from "@ramon-sg/github-rest";
+import type { LabelSpec } from "../config.js";
+import { type Output } from "../output.js";
+/**
+ * What happened to one label: with `--dry-run`, `to-create` and `to-update` instead of
+ * `created` and `updated`; `failed` when GitHub refused the write.
+ */
+export type LabelStatus = "created" | "updated" | "ok" | "differs" | "to-create" | "to-update" | "failed";
+/** One label of the result. */
+export interface LabelResult {
+    name: string;
+    status: LabelStatus;
+    color: string;
+    description: string;
+    /** What GitHub has, when it differs. */
+    found?: {
+        color: string;
+        description: string;
+    };
+    /** Why the write failed. */
+    error?: string;
+}
+/** The options of `labels sync`. */
+export interface LabelsSyncOptions {
+    repo: string;
+    labels: Record<string, LabelSpec>;
+    update: boolean;
+    dryRun: boolean;
+    json: boolean;
+}
+/**
+ * What to do with each label, before writing anything.
+ * @param wanted - The labels of the config.
+ * @param existing - The labels in GitHub.
+ * @param update - Whether to fix the ones that differ.
+ * @returns Each label with its status, as if every write worked, and its name in GitHub if it exists.
+ */
+export declare function planLabels(wanted: Record<string, LabelSpec>, existing: Label[], update: boolean): LabelResult[];
+/**
+ * Runs `labels sync`; see the file's header.
+ * @param options - The repo, the labels and the flags.
+ * @param out - Where to write.
+ * @returns 0 when done; 1 if GitHub's list came back cut short (nothing is written then) or a write failed.
+ * @throws GitHubError if GitHub fails to list the labels.
+ * @example await labelsSync({ repo: "acme/widgets", labels, update: false, dryRun: true, json: false }, out)
+ */
+export declare function labelsSync(options: LabelsSyncOptions, out: Output): Promise<number>;

package/dist/commands/labels.js

@@ -0,0 +1,113 @@
+/**
+ * @file `issue-flow labels sync [--update] [--dry-run] [--json]`: makes in GitHub the labels
+ * of `labels` in `.agents/flow.json` that the repo lacks. Names compare ignoring case, as
+ * GitHub does, so `Bug` counts as `bug` and is never renamed. A label that exists with
+ * another color or description is only reported, unless `--update`. It never deletes. A
+ * write that fails does not stop the rest: every label is reported, and it exits 1.
+ */
+import { createLabel, listLabels } from "@ramon-sg/github-rest";
+import { emitJson } from "../output.js";
+/** Width of the status column in the text output. */
+const STATUS_WIDTH = 10;
+/**
+ * Whether a label in GitHub has the wanted color and description (colors ignore case).
+ * @param found - The label in GitHub.
+ * @param spec - The wanted one.
+ * @returns True if they match.
+ */
+function matches(found, spec) {
+    return found.color.toLowerCase() === spec.color.toLowerCase() && found.description === spec.description;
+}
+/**
+ * What to do with each label, before writing anything.
+ * @param wanted - The labels of the config.
+ * @param existing - The labels in GitHub.
+ * @param update - Whether to fix the ones that differ.
+ * @returns Each label with its status, as if every write worked, and its name in GitHub if it exists.
+ */
+export function planLabels(wanted, existing, update) {
+    const byName = new Map(existing.map((label) => [label.name.toLowerCase(), label]));
+    return Object.entries(wanted).map(([name, spec]) => {
+        const found = byName.get(name.toLowerCase());
+        const base = { name, color: spec.color, description: spec.description };
+        if (found === undefined)
+            return { ...base, status: "created" };
+        if (matches(found, spec))
+            return { ...base, name: found.name, status: "ok" };
+        return { ...base, name: found.name, status: update ? "updated" : "differs", found: { color: found.color, description: found.description } };
+    });
+}
+/** The word of each status in the text output. */
+const WORDS = {
+    created: "created",
+    updated: "updated",
+    ok: "ok",
+    differs: "differs",
+    "to-create": "to create",
+    "to-update": "to update",
+    failed: "failed",
+};
+/**
+ * One line of the text output.
+ * @param result - The label.
+ * @returns The line.
+ */
+function line(result) {
+    const head = `${WORDS[result.status].padEnd(STATUS_WIDTH)}${result.name}`;
+    if (result.error !== undefined)
+        return `${head}: ${result.error}`;
+    if (result.found === undefined)
+        return head;
+    const was = `${result.found.color} "${result.found.description}"`;
+    const wanted = `${result.color} "${result.description}"`;
+    return result.status === "differs" ? `${head}: has ${was}, the flow wants ${wanted} (--update fixes it)` : `${head}: ${was} → ${wanted}`;
+}
+/**
+ * Writes one label and says how it went. A label that appeared in GitHub after the list
+ * was read fails without `--update`, with a message that says to run it again.
+ * @param repo - `owner/repo`.
+ * @param result - The label, as planned.
+ * @returns The label with its final status.
+ */
+async function write(repo, result) {
+    try {
+        await createLabel(repo, { name: result.name, color: result.color, description: result.description, force: result.status === "updated" });
+        return result;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const appeared = result.status === "created" && message.includes("already exists");
+        return { ...result, status: "failed", error: appeared ? "it appeared in GitHub meanwhile: run labels sync again" : message };
+    }
+}
+/**
+ * Runs `labels sync`; see the file's header.
+ * @param options - The repo, the labels and the flags.
+ * @param out - Where to write.
+ * @returns 0 when done; 1 if GitHub's list came back cut short (nothing is written then) or a write failed.
+ * @throws GitHubError if GitHub fails to list the labels.
+ * @example await labelsSync({ repo: "acme/widgets", labels, update: false, dryRun: true, json: false }, out)
+ */
+export async function labelsSync(options, out) {
+    const { labels: existing, truncated } = await listLabels(options.repo);
+    if (truncated) {
+        out.stderr(`issue-flow: could not read every label of ${options.repo}; nothing written, so no label is made twice.\n`);
+        return 1;
+    }
+    const results = [];
+    for (const item of planLabels(options.labels, existing, options.update)) {
+        const writes = item.status === "created" || item.status === "updated";
+        // NOTE: one at a time, as GitHub asks of writes, to stay clear of its secondary rate limit.
+        if (!writes)
+            results.push(item);
+        else if (options.dryRun)
+            results.push({ ...item, status: item.status === "created" ? "to-create" : "to-update" });
+        else
+            results.push(await write(options.repo, item));
+    }
+    if (options.json)
+        emitJson(out, { repo: options.repo, dryRun: options.dryRun, labels: results });
+    else
+        out.stdout(`${results.map(line).join("\n")}\n`);
+    return results.some((result) => result.status === "failed") ? 1 : 0;
+}

package/dist/commands/upgrade.d.ts

@@ -1,4 +1,4 @@
-import type { Output } from "../output.js";
+import { type Output } from "../output.js";
 /** Options of `issue-flow upgrade`. */
 export interface UpgradeOptions {
     cwd: string;

package/dist/commands/upgrade.js

@@ -1,36 +1,19 @@
 /**
  * @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
+ * runs: `@ramon-sg/issue-flow`, the hooks and the config's schema to it, and `github-rest`
+ * and `skills-manager` up to the versions it was tested with only if they fall short (a
+ * newer one, or a range that allows it, is kept and reported). `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 { warn } from "../output.js";
+import { dependencyVersion, isNewer, KEPT, 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.
@@ -59,13 +42,17 @@ export function upgrade(options, out) {
     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'.`);
+        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 apply'.`);
     const writes = [];
     const lines = [];
     const pkg = withFlowPackages(readJson(root, "package.json"), versions, true);
-    if (pkg.changes.length > 0)
+    const kept = pkg.changes.filter((change) => change.startsWith(KEPT));
+    const moved = pkg.changes.filter((change) => !change.startsWith(KEPT));
+    for (const change of kept)
+        warn(out, `package.json: ${change}`);
+    if (moved.length > 0)
         writes.push({ path: "package.json", value: pkg.pkg });
-    lines.push(...pkg.changes.map((change) => `package.json: ${change}`));
+    lines.push(...moved.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 });

package/dist/config.d.ts

@@ -6,6 +6,11 @@ export interface TypeRules {
     labels: Record<string, string>;
     titlePrefixes: Record<string, string>;
 }
+/** A label the flow wants in the repo: its color (hex, no `#`) and description. */
+export interface LabelSpec {
+    color: string;
+    description: string;
+}
 /** The whole config, with every default applied. */
 export interface FlowConfig {
     repo: string | null;
@@ -30,6 +35,7 @@ export interface FlowConfig {
         dirs: string[];
     };
     colors: Record<string, string>;
+    labels: Record<string, LabelSpec>;
 }
 /** The defaults, the same rules Abastio uses. */
 export declare const DEFAULT_CONFIG: FlowConfig;

package/dist/config.js

@@ -49,6 +49,16 @@ export const DEFAULT_CONFIG = {
         "P3:": "yellow",
         "P4:": "cyan",
     },
+    labels: {
+        bug: { color: "d73a4a", description: "Something isn't working" },
+        enhancement: { color: "a2eeef", description: "New feature or request" },
+        documentation: { color: "0075ca", description: "Improvements or additions to documentation" },
+        spike: { color: "fbca04", description: "Time-boxed research before building" },
+        "P1: urgent": { color: "B60205", description: "Breaks production or blocks work" },
+        "P2: important": { color: "F9D0C4", description: "Real impact, with some slack" },
+        "P3: minor": { color: "FEF2C0", description: "Default when in doubt" },
+        "P4: low": { color: "BFDADC", description: "Nice-to-have" },
+    },
 };
 /** The colors a Claude session takes with `/color`. */
 export const SESSION_COLORS = ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"];
@@ -171,6 +181,55 @@ function colorsSection(value) {
     }
     return value;
 }
+/** A label color: six hex digits, without `#`. */
+const LABEL_COLOR = /^[0-9a-fA-F]{6}$/;
+/** A label name: no spaces at the ends, since GitHub trims them. */
+const LABEL_NAME = /^\S(?:.*\S)?$/;
+/** GitHub's limits for a label's name and description, in characters. */
+const LABEL_NAME_MAX = 50;
+const LABEL_DESCRIPTION_MAX = 100;
+/**
+ * The `labels` map: the labels `labels sync` makes in the repo. Unlike the other maps, it
+ * merges over the default, because a repo usually adds labels: a name replaces the default
+ * of the same name (ignoring case, as GitHub does) and `null` drops it.
+ * @param value - The map, or undefined.
+ * @returns The labels.
+ * @throws ConfigError if a label is invalid.
+ * @example labelsSection({ spike: null, "area:api": { color: "1d76db" } })["area:api"].description // ""
+ */
+function labelsSection(value) {
+    if (value === undefined)
+        return DEFAULT_CONFIG.labels;
+    if (!isObject(value))
+        throw new ConfigError(`${CONFIG_PATH}: "labels" must be an object.`);
+    // NOTE: a Map, so a "__proto__" key from JSON.parse stays a label and not the prototype.
+    const labels = new Map(Object.entries(DEFAULT_CONFIG.labels));
+    const seen = new Set();
+    for (const [name, spec] of Object.entries(value)) {
+        const where = `labels.${name}`;
+        if (!LABEL_NAME.test(name) || [...name].length > LABEL_NAME_MAX)
+            throw new ConfigError(`${CONFIG_PATH}: "${where}" needs a name of 1 to ${LABEL_NAME_MAX} characters, without spaces at the ends.`);
+        const key = name.toLowerCase();
+        if (seen.has(key))
+            throw new ConfigError(`${CONFIG_PATH}: "labels" has "${name}" twice (names ignore case).`);
+        seen.add(key);
+        for (const known of [...labels.keys()])
+            if (known.toLowerCase() === key)
+                labels.delete(known);
+        if (spec === null)
+            continue;
+        if (!isObject(spec))
+            throw new ConfigError(`${CONFIG_PATH}: "${where}" must be an object or null.`);
+        onlyKeys(spec, ["color", "description"], where);
+        if (typeof spec.color !== "string" || !LABEL_COLOR.test(spec.color))
+            throw new ConfigError(`${CONFIG_PATH}: "${where}.color" must be six hex digits, without #, such as "1d76db".`);
+        const description = spec.description ?? "";
+        if (typeof description !== "string" || [...description].length > LABEL_DESCRIPTION_MAX)
+            throw new ConfigError(`${CONFIG_PATH}: "${where}.description" must be a string of up to ${LABEL_DESCRIPTION_MAX} characters.`);
+        labels.set(name, { color: spec.color, description });
+    }
+    return Object.fromEntries(labels);
+}
 /**
  * Validates a parsed config and fills in the defaults.
  * @param raw - The parsed JSON.
@@ -181,7 +240,7 @@ function colorsSection(value) {
 export function parseConfig(raw) {
     if (!isObject(raw))
         throw new ConfigError(`${CONFIG_PATH} must be a JSON object.`);
-    onlyKeys(raw, ["repo", "baseBranch", "branch", "worktrees", "start", "plans", "colors"], "");
+    onlyKeys(raw, ["repo", "baseBranch", "branch", "worktrees", "start", "plans", "colors", "labels"], "");
     const repo = text(raw.repo, "repo", null);
     if (repo !== null && !REPO.test(repo))
         throw new ConfigError(`${CONFIG_PATH}: "repo" must be owner/repo.`);
@@ -193,6 +252,7 @@ export function parseConfig(raw) {
         start: textSection(raw.start, "start", DEFAULT_CONFIG.start),
         plans: plansSection(raw.plans),
         colors: colorsSection(raw.colors),
+        labels: labelsSection(raw.labels),
     };
 }
 /**

package/dist/package-edits.d.ts

@@ -2,16 +2,46 @@
  * @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.
+ * A dependency or script the repo already has with another value stays as it is, except
+ * that `upgrade` moves `issue-flow` to the version that runs and raises the other two only
+ * when they fall short of it: a newer version or a range that allows it is never moved back.
  */
-import type { OwnVersions } from "./setup-files.js";
+import { type OwnVersions } from "./setup-files.js";
 /**
- * The dependencies the flow pins, with their versions.
+ * 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 was tested with, so
+ * `upgrade` keeps it: an exact version as new or newer, a range that allows it or newer
+ * (`^1.2.0` for 1.3.0, not `^0.1.0` for 0.3.0), or a source it cannot read (`workspace:*`,
+ * `github:…`, `latest`), which the repo chose on purpose.
+ * @param current - The repo's version or range.
+ * @param tested - The version the flow was tested with.
+ * @returns True to keep it.
+ * @example reaches("1.3.0", "1.2.0") // true
+ */
+export declare function reaches(current: string, tested: string): boolean;
+/** A dependency the flow pins: its version, and whether `upgrade` keeps one that reaches it. */
+interface Pin {
+    version: string;
+    keepsReaching: boolean;
+}
+/** How a change that keeps what the repo had starts. */
+export declare const KEPT = "kept ";
+/**
+ * The dependencies the flow pins, with their versions. `issue-flow` always follows the
+ * version that runs; the other two are a floor, so `upgrade` keeps what reaches it.
  * @param versions - This package's versions.
- * @returns Package to version.
- * @example pinnedPackages(versions)["@ramon-sg/issue-flow"] // "0.1.0"
+ * @returns Package to pin.
+ * @example pinnedPackages(versions)["@ramon-sg/issue-flow"].version // "0.1.0"
  */
-export declare function pinnedPackages(versions: OwnVersions): Record<string, string>;
+export declare function pinnedPackages(versions: OwnVersions): Record<string, Pin>;
 /**
  * The version of a package in the repo, as a dependency or a dev dependency.
  * @param pkg - The package.json.
@@ -33,3 +63,4 @@ export declare function withFlowPackages(pkg: Record<string, unknown> | null, ve
     pkg: Record<string, unknown>;
     changes: string[];
 };
+export {};

package/dist/package-edits.js

@@ -1,3 +1,103 @@
+/**
+ * @file The repo's `package.json` as the flow needs it: `issue-flow`, `github-rest` and
+ * `skills-manager` as exact dev dependencies (the skills call them with `npx`, which then
+ * uses the repo's copy), and the scripts to start an issue, prune worktrees and review a PR.
+ * A dependency or script the repo already has with another value stays as it is, except
+ * that `upgrade` moves `issue-flow` to the version that runs and raises the other two only
+ * when they fall short of it: a newer version or a range that allows it is never moved back.
+ */
+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 was tested with, so
+ * `upgrade` keeps it: an exact version as new or newer, a range that allows it or newer
+ * (`^1.2.0` for 1.3.0, not `^0.1.0` for 0.3.0), or a source it cannot read (`workspace:*`,
+ * `github:…`, `latest`), which the repo chose on purpose.
+ * @param current - The repo's version or range.
+ * @param tested - The version the flow was tested with.
+ * @returns True to keep it.
+ * @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 scripts `init` adds. */
 const FLOW_SCRIPTS = {
     "issue:start": "issue-flow issue start",
@@ -5,16 +105,17 @@ const FLOW_SCRIPTS = {
     "pr:worktree": "issue-flow pr worktree",
 };
 /**
- * The dependencies the flow pins, with their versions.
+ * The dependencies the flow pins, with their versions. `issue-flow` always follows the
+ * version that runs; the other two are a floor, so `upgrade` keeps what reaches it.
  * @param versions - This package's versions.
- * @returns Package to version.
- * @example pinnedPackages(versions)["@ramon-sg/issue-flow"] // "0.1.0"
+ * @returns Package to pin.
+ * @example pinnedPackages(versions)["@ramon-sg/issue-flow"].version // "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,
+        [PACKAGE]: { version: versions.issueFlow, keepsReaching: false },
+        "@ramon-sg/github-rest": { version: versions.githubRest, keepsReaching: true },
+        "@ramon-sg/skills-manager": { version: versions.skillsManager, keepsReaching: true },
     };
 }
 /**
@@ -55,12 +156,12 @@ export function withFlowPackages(pkg, versions, move) {
     const next = pkg === null ? { private: true } : { ...pkg };
     const scripts = { ...(next.scripts ?? {}) };
     const changes = [];
-    for (const [name, version] of Object.entries(pinnedPackages(versions))) {
+    for (const [name, { version, keepsReaching }] 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})`);
+        if (current !== null && (!move || (keepsReaching && reaches(current.version, version)))) {
+            changes.push(`${KEPT}${name} ${current.version} (issue-flow ${versions.issueFlow} was tested with ${version})`);
             continue;
         }
         const field = current?.field ?? "devDependencies";

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\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.";
+export declare const USAGE = "Usage:\n  issue-flow issue branch <n>... [--namer claude|title] [--json] [-R owner/repo]\n  issue-flow issue branch --missing [--limit <n>] [--namer claude|title] [--dry-run | --yes] [--json] [-R owner/repo]\n  issue-flow issue start <n> [--branch] [--dry-run | --yes] [--resume <branch> | --new] [--no-launch]\n                             [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --plan [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --cloud | --here | --teleport | --adopt [...]\n  issue-flow worktree setup [--only <step>]\n  issue-flow worktree teardown [--path <dir>]\n  issue-flow worktree ports [--next]\n  issue-flow worktree cleanup [--path <dir>]\n  issue-flow worktree prune [--only <dir>] [--yes] [-R owner/repo]\n  issue-flow pr worktree <n> [--no-setup] [-R owner/repo] [-- [<command>...]]\n  issue-flow adapter setup [--only <step>] | issue [<url>] | archive [-R owner/repo]\n  issue-flow session\n  issue-flow hook worktree-create | worktree-remove\n  issue-flow init [--yes] [--recipe <name>,...]\n  issue-flow doctor [--json]\n  issue-flow upgrade [--dry-run]\n  issue-flow labels sync [--update] [--dry-run] [--json] [-R owner/repo]\n\nThe slug comes from the issue's \"Slug de rama\" block, then from Claude, then from the title,\nand the branch from the repo's template (an older \"Rama sugerida\" block is used if it fits).\n--missing adds the slug block to every open issue without a block, after confirming.\n\nissue start makes the branch in a worktree (or, with --branch, in this checkout), the\nstart commit, the push, the draft PR and the assignment, after confirming, and opens\nClaude: in auto mode if the repo has claude-repo-guard, with your settings with\n--ask-permissions, and with no sandbox nor questions with --free. --plan prints the branch\nand the prompt as JSON and changes nothing.\n\n--cloud confirms here and opens a Claude cloud session that starts the issue there.\n--here, inside a cloud session, starts it in this checkout and opens nothing. --teleport\nbrings the cloud session noted in the PR to the worktree. --adopt starts it in the\nworktree another tool (Orca, Paseo) just made, without asking nor opening Claude.\n\nworktree runs the steps of \"worktrees\" in .agents/flow.json: setup prepares this worktree,\nteardown cleans it before it goes (steps, ports, Docker), ports prints or moves its block\nof ports, cleanup deletes the Docker of deleted worktrees, and prune deletes the worktrees\nwhose PR was merged or closed. session is the SessionStart hook of Claude Code.\n\npr worktree makes (or reuses) a worktree on a PR's own branch, to review and fix it; with\n--, it runs the command there (Claude if none). adapter is what Orca and Paseo run: setup\nwhen they make a worktree (its steps and, if it came from an issue, issue start --adopt),\nissue to start one by hand, and archive before they delete it. hook implements Claude\nCode's WorktreeCreate and WorktreeRemove for claude --worktree.\n\ninit sets the flow up in the repo: .agents/flow.json (with the recipes its files suggest),\nthe dev dependencies and scripts, and the hooks. doctor checks them at this version, and\nupgrade moves them to this version. npx agent-kitchen apply runs the three, along with the\nskills, claude-cloud and claude-repo-guard.\n\nlabels sync makes in GitHub the labels the flow wants (\"labels\" in .agents/flow.json: the\nissue types and P1 to P4 by default) that the repo lacks. Names ignore case and are never\nrenamed nor deleted; --update also fixes the color and description of those that differ.";

package/dist/usage.js

@@ -21,6 +21,7 @@ export const USAGE = `Usage:
   issue-flow init [--yes] [--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,
 and the branch from the repo's template (an older "Rama sugerida" block is used if it fits).
@@ -50,5 +51,9 @@ 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.`;
+upgrade moves them to this version. npx agent-kitchen apply runs the three, along with the
+skills, claude-cloud and claude-repo-guard.
+
+labels sync makes in GitHub the labels the flow wants ("labels" in .agents/flow.json: the
+issue types and P1 to P4 by default) that the repo lacks. Names ignore case and are never
+renamed nor deleted; --update also fixes the color and description of those that differ.`;

package/package.json

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

package/schema.json

@@ -267,6 +267,50 @@
         "P3:": "yellow",
         "P4:": "cyan"
       }
+    },
+    "labels": {
+      "description": "Labels that `issue-flow labels sync` makes in GitHub when the repo lacks them. Merges over the default: a name replaces the default of the same name (ignoring case) and null drops it.",
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^\\S(?:.*\\S)?$",
+        "maxLength": 50
+      },
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "type": "null"
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "color"
+            ],
+            "properties": {
+              "color": {
+                "description": "Six hex digits, without #.",
+                "type": "string",
+                "pattern": "^[0-9a-fA-F]{6}$"
+              },
+              "description": {
+                "type": "string",
+                "maxLength": 100,
+                "default": ""
+              }
+            }
+          }
+        ]
+      },
+      "default": {
+        "bug": { "color": "d73a4a", "description": "Something isn't working" },
+        "enhancement": { "color": "a2eeef", "description": "New feature or request" },
+        "documentation": { "color": "0075ca", "description": "Improvements or additions to documentation" },
+        "spike": { "color": "fbca04", "description": "Time-boxed research before building" },
+        "P1: urgent": { "color": "B60205", "description": "Breaks production or blocks work" },
+        "P2: important": { "color": "F9D0C4", "description": "Real impact, with some slack" },
+        "P3: minor": { "color": "FEF2C0", "description": "Default when in doubt" },
+        "P4: low": { "color": "BFDADC", "description": "Nice-to-have" }
+      }
     }
   },
   "$defs": {