agent-kitchen 0.9.0 → 0.10.0

package/README.md

@@ -26,7 +26,7 @@ Al arrancar revisa si npm tiene una versión más nueva de sí mismo. Si la hay,
 |---|---|---|---|---|---|
 | `skills-manager` | La versión de [`@ramon-sg/skills-manager`](https://github.com/ramon-sg/skills-manager) que corre `agent-kitchen`: como mínimo 1.2.0. Si falta la agrega y si es menor la sube; nunca la baja. Un rango o `workspace:` no se toca, y avisa si la versión que corre queda bajo el mínimo. Solo en repos que usan skills y tienen `package.json`, o donde issue-flow se instala en la misma corrida: entonces crea el `package.json` | `package.json` | — | La agrega `agent-kitchen` | La sube `agent-kitchen` |
 | `issue-flow` | Flujo de issues ([`@ramon-sg/issue-flow`](https://github.com/ramon-sg/issue-flow)): rama, worktree y PR en draft por issue, y sus 5 skills | `package.json` | npm | `issue-flow apply` (`init` antes de 0.3.0), y sus skills a la misma tag | `issue-flow apply` en la versión nueva (`upgrade` antes de 0.3.0), y sus skills a la misma tag. Desde 0.3.0, si su doctor ve hooks o el `$schema` atrás, `apply` en la versión del repo. Desde 0.3.0, si `github-rest` es una versión exacta bajo el mínimo que pide esa versión del flujo, la sube. Desde 0.2.6, si a GitHub le faltan labels del flujo (`spike`, `P1`–`P4`…), `issue-flow labels sync` los crea |
-| `claude-cloud` | Sesiones en la nube ([`@ramon-sg/claude-cloud`](https://github.com/ramon-sg/claude-cloud)): herramientas, Docker y el clone completo | `.claude/cloud.json` | npm | `claude-cloud init` | Cambia la versión que fija `.claude/cloud.json` |
+| `agent-cloud-kit` | Sesiones en la nube ([`agent-cloud-kit`](https://github.com/ramon-sg/agent-cloud-kit)): herramientas, Docker y el clone completo | `.claude/cloud.json`, `.agents/skills/cloud-ready/` | npm | `agent-cloud-kit init` | Cambia la versión que fija `.claude/cloud.json` y corre el `init` de la versión nueva, para que la skill `cloud-ready` quede igual. Al terminar `apply` sugiere `npx agent-cloud-kit prepare` |
 | `claude-repo-guard` | Barandas ([`claude-repo-guard`](https://github.com/ramon-sg/claude-repo-guard)): modo auto con sandbox, escribe solo en su worktree | `.claude/repo-guard.manifest.json` | Tags `vX.Y.Z` de GitHub | `apply` en esa tag (`install` antes de 0.5.0) | `apply` en la tag nueva |
 | `skills` | Skills con [`skills-manager`](https://github.com/ramon-sg/skills-manager): las del flujo y las de [`agent-skills`](https://github.com/ramon-sg/agent-skills) (planes, auditoría de código y de tests) | `.agents/skills.lock.json` | Tags del catálogo | `skills-manager init --select` con las elegidas | `skills-manager update` |
 | `agents-md` | Una línea en `AGENTS.md` que le pide al agente mirar la versión instalada de una biblioteca antes de usarla. Si el repo tiene `CLAUDE.md`, le agrega `@AGENTS.md`, porque si no Claude Code no lee `AGENTS.md`. Solo en repos con `package.json` | `AGENTS.md` | — | La escribe `agent-kitchen` | — |
@@ -51,7 +51,7 @@ npx agent-kitchen apply --yes                  # hace lo sugerido sin preguntar
 npx agent-kitchen apply --pr                   # en una copia de origin, y abre un PR en draft
 npx agent-kitchen apply --here                 # en tu copia, sin commit
 npx agent-kitchen apply --verbose              # muestra la salida de cada herramienta
-npx agent-kitchen apply --skip claude-cloud    # deja fuera una pieza (o varias, con comas)
+npx agent-kitchen apply --skip agent-cloud-kit    # deja fuera una pieza (o varias, con comas)
 npx agent-kitchen apply --pieces               # cambia qué piezas usa el repo (solo en una terminal)
 npx agent-kitchen doctor                       # revisa cada pieza con su propio doctor
 ```

package/dist/cli.js

@@ -14,7 +14,7 @@ import { KitError, processOutput, UsageError } from "./output.js";
 import { FLOW_PACKAGE, GENERAL_CATALOGS } from "./piece.js";
 import { PACKAGE as CLOUD_PACKAGE } from "./pieces/cloud.js";
 import { REPO as GUARD_REPO } from "./pieces/guard.js";
-import { compareVersions, isRelease, latestTag, npmLatest } from "./tools.js";
+import { compareVersions, isRelease, latestTag, npmLatest, npmLatestExact } from "./tools.js";
 /** This package on npm. */
 const PACKAGE = "agent-kitchen";
 /** Set in the run that a newer agent-kitchen was handed to, so it never hands over again. */
@@ -52,7 +52,7 @@ function ownVersion() {
  */
 function startLookups() {
     void npmLatest(FLOW_PACKAGE);
-    void npmLatest(CLOUD_PACKAGE);
+    void npmLatestExact(CLOUD_PACKAGE);
     void latestTag(GUARD_REPO);
     for (const catalog of GENERAL_CATALOGS)
         void latestTag(catalog);

package/dist/commands/sync.d.ts

@@ -17,7 +17,7 @@ export interface SyncOptions {
 /**
  * The names `--skip` takes.
  * @returns The pieces' names.
- * @example pieceNames() // ["skills-manager", "issue-flow", "claude-cloud", "claude-repo-guard", "skills", "agents-md"]
+ * @example pieceNames() // ["skills-manager", "issue-flow", "agent-cloud-kit", "claude-repo-guard", "skills", "agents-md"]
  */
 export declare function pieceNames(): string[];
 /**

package/dist/commands/sync.js

@@ -5,7 +5,7 @@
  * draft (see pr-clone.ts), `--here` in the person's checkout, leaving the changes uncommitted.
  * In a terminal, without either, it asks; with `--yes` or without a terminal, or without an
  * origin, it works here. Here it warns if the checkout has changes or is behind its upstream.
- * Then it looks at each piece (the version of skills-manager, the issue flow, claude-cloud,
+ * Then it looks at each piece (the version of skills-manager, the issue flow, agent-cloud-kit,
  * claude-repo-guard, the skills, the rule in AGENTS.md) with
  * every lookup at once, shows what the repo has, and offers the steps that install what is
  * missing or update what is behind. In a terminal it asks first, all in one go: everything
@@ -37,7 +37,7 @@ import { issueFlowStatus, NAME as FLOW } from "../pieces/issue-flow.js";
 import { keepOwn, NAME as SKILLS, ownInPick, skillsStatus } from "../pieces/skills.js";
 import { agentsMdStatus, NAME as AGENTS_MD } from "../pieces/agents-md.js";
 import { NAME as SKILLS_MANAGER, skillsManagerStatus } from "../pieces/skills-manager.js";
-import { mainCheckout, packageManager, packageText } from "../repo.js";
+import { mainCheckout, packageManager, packageText, readJson } from "../repo.js";
 import { download, failedOutput, runInstall, setVerbose } from "../tools.js";
 import { commitLine, DECISIONS_LINE } from "../commit-texts.js";
 import { progressFor } from "../progress.js";
@@ -47,7 +47,7 @@ const PIECES = [SKILLS_MANAGER, FLOW, CLOUD, GUARD, SKILLS, AGENTS_MD];
 /**
  * The names `--skip` takes.
  * @returns The pieces' names.
- * @example pieceNames() // ["skills-manager", "issue-flow", "claude-cloud", "claude-repo-guard", "skills", "agents-md"]
+ * @example pieceNames() // ["skills-manager", "issue-flow", "agent-cloud-kit", "claude-repo-guard", "skills", "agents-md"]
  */
 export function pieceNames() {
     return [...PIECES];
@@ -405,7 +405,13 @@ async function applyIn(work, options, out) {
     const steps = statuses.flatMap((status) => status.steps);
     const progress = progressFor(out, options.verbose);
     // In a clone, a run that only wrote the decisions file still ends in a PR.
-    const endWithoutSteps = async () => (work.kind === "pr" && wrote ? openPr(work, commitLabels([], true), [], progress, out) : 0);
+    const endWithoutSteps = async () => {
+        if (work.kind === "pr")
+            return wrote ? openPr(work, commitLabels([], true), [], progress, out) : 0;
+        if (!options.dryRun)
+            printCloudNext(root, skip, out);
+        return 0;
+    };
     if (steps.length === 0) {
         if (saves)
             wrote = saveDecisions(root, saved, statuses, [], pr, out) || wrote;
@@ -446,8 +452,20 @@ async function applyIn(work, options, out) {
     if (installFailed)
         failed.push(phrases({ kind: "install-deps", manager: packageManager(root) }).menu);
     out.stdout(`\n${ui.summary(failed)} ${ui.next(installFailed ? packageManager(root) : null)}\n`);
+    if (!options.dryRun)
+        printCloudNext(root, skip, out);
     return failed.length === 0 ? 0 : 1;
 }
+/**
+ * Says what to run next for the cloud, if agent-cloud-kit is installed and was not left out.
+ * @param root - The repo.
+ * @param skip - The pieces left out.
+ * @param out - Where to write.
+ */
+function printCloudNext(root, skip, out) {
+    if (!skip.includes(CLOUD) && readJson(root, ".claude/cloud.json") !== null)
+        out.stdout(`${ui.cloudNext}\n`);
+}
 /**
  * Runs the repo's install with the same progress as a step, and shows its output if it fails.
  * @param root - The repo.

package/dist/decisions.d.ts

@@ -24,7 +24,7 @@ export declare function readDecisions(root: string): Saved | null;
  * The decidable pieces with no decision yet.
  * @param saved - What was read, or null if there is no file.
  * @returns Their names; all of them without a file.
- * @example undecided(null) // ["issue-flow", "claude-cloud", ...]
+ * @example undecided(null) // ["issue-flow", "agent-cloud-kit", ...]
  */
 export declare function undecided(saved: Saved | null): string[];
 /**

package/dist/decisions.js

@@ -43,7 +43,7 @@ export function readDecisions(root) {
  * The decidable pieces with no decision yet.
  * @param saved - What was read, or null if there is no file.
  * @returns Their names; all of them without a file.
- * @example undecided(null) // ["issue-flow", "claude-cloud", ...]
+ * @example undecided(null) // ["issue-flow", "agent-cloud-kit", ...]
  */
 export function undecided(saved) {
     return DECIDABLE.filter((name) => saved?.pieces[name] === undefined);

package/dist/output.d.ts

@@ -24,6 +24,6 @@ export declare function processOutput(): Output;
  * Prints a warning on stderr with the program's name.
  * @param out - Where to write.
  * @param text - The warning.
- * @example warn(out, "claude-cloud init failed")
+ * @example warn(out, "agent-cloud-kit init failed")
  */
 export declare function warn(out: Output, text: string): void;

package/dist/output.js

@@ -24,7 +24,7 @@ export function processOutput() {
  * Prints a warning on stderr with the program's name.
  * @param out - Where to write.
  * @param text - The warning.
- * @example warn(out, "claude-cloud init failed")
+ * @example warn(out, "agent-cloud-kit init failed")
  */
 export function warn(out, text) {
     out.stderr(`agent-kitchen: ${text}\n`);

package/dist/piece.d.ts

@@ -1,6 +1,6 @@
 /**
  * @file What agent-kitchen knows of each piece it manages, and the names they share. A piece
- * (the version of skills-manager, the issue flow, claude-cloud, claude-repo-guard, the
+ * (the version of skills-manager, the issue flow, agent-cloud-kit, claude-repo-guard, the
  * skills, the rule in AGENTS.md) tells what the repo has and the steps that would install or
  * update it; agent-kitchen shows them, lets the person pick, and runs the picked ones in
  * order. Every step runs the piece's own tool, which owns its files: agent-kitchen only

package/dist/piece.js

@@ -1,6 +1,6 @@
 /**
  * @file What agent-kitchen knows of each piece it manages, and the names they share. A piece
- * (the version of skills-manager, the issue flow, claude-cloud, claude-repo-guard, the
+ * (the version of skills-manager, the issue flow, agent-cloud-kit, claude-repo-guard, the
  * skills, the rule in AGENTS.md) tells what the repo has and the steps that would install or
  * update it; agent-kitchen shows them, lets the person pick, and runs the picked ones in
  * order. Every step runs the piece's own tool, which owns its files: agent-kitchen only

package/dist/pieces/cloud.d.ts

@@ -1,17 +1,18 @@
 /**
- * @file Claude cloud sessions (`@ramon-sg/claude-cloud`). The repo's version is the one
+ * @file Claude cloud sessions (`agent-cloud-kit`). The repo's version is the one
  * `.claude/cloud.json` pins: the cloud machine runs exactly that one. Installing runs its
- * `init`; updating only moves that version (and a `$schema` pinned to a version), which is
- * how `claude-cloud` updates. Outside
- * the cloud its hook does nothing, so a repo nobody opens in the cloud loses nothing.
+ * `init`; updating moves that version (and a `$schema` pinned to a version) and then runs the
+ * new version's `init`, so the `cloud-ready` skill copied into the repo matches it (`init` is
+ * idempotent: it adds no second hook and keeps `.claude/cloud.json`). Outside the cloud its
+ * hook does nothing, so a repo nobody opens in the cloud loses nothing.
  */
 import type { Check, PieceStatus } from "../piece.js";
 /** The piece's name, as `--skip` takes it. */
-export declare const NAME = "claude-cloud";
+export declare const NAME = "agent-cloud-kit";
 /** The package on npm. */
-export declare const PACKAGE = "@ramon-sg/claude-cloud";
+export declare const PACKAGE = "agent-cloud-kit";
 /**
- * What the repo has of claude-cloud, and the step it needs.
+ * What the repo has of agent-cloud-kit, and the step it needs.
  * @param root - The repo.
  * @returns The piece's status.
  * @example (await cloudStatus(root)).state // "1.0.0, al día"

package/dist/pieces/cloud.js

@@ -1,18 +1,18 @@
 import { readJson, writeJson } from "../repo.js";
-import { compareVersions, isRelease, npmLatest, runNpx } from "../tools.js";
+import { compareSemver, isExactVersion, npmLatestExact, runNpx } from "../tools.js";
 /** The piece's name, as `--skip` takes it. */
-export const NAME = "claude-cloud";
+export const NAME = "agent-cloud-kit";
 /** The package on npm. */
-export const PACKAGE = "@ramon-sg/claude-cloud";
+export const PACKAGE = "agent-cloud-kit";
 /** Its config in the repo, which pins its version. */
 const CONFIG = ".claude/cloud.json";
 /**
- * The version `.claude/cloud.json` pins.
+ * The version `.claude/cloud.json` pins: exact semver, so a release candidate counts.
  * @param config - The config, or null.
  * @returns The version, or null if it has none.
  */
 function pinned(config) {
-    return typeof config?.version === "string" && isRelease(config.version) ? config.version : null;
+    return typeof config?.version === "string" && isExactVersion(config.version) ? config.version : null;
 }
 /**
  * The step the repo needs, if any.
@@ -33,35 +33,40 @@ function stepFor(config, latest) {
                 const run = await runNpx(context.root, [spec, "init"]);
                 if (run.ok)
                     return true;
-                context.fail(`claude-cloud init falló; corre 'npx ${spec} init'.`, run.output);
+                context.fail(`agent-cloud-kit init falló; corre 'npx ${spec} init'.`, run.output);
                 return false;
             },
         };
     }
-    if (latest === null || (version !== null && compareVersions(latest, version) <= 0))
+    if (latest === null || (version !== null && compareSemver(latest, version) <= 0))
         return null;
     return {
         piece: NAME,
         checked: true,
-        downloads: [],
+        downloads: [`${PACKAGE}@${latest}`],
         text: { kind: "cloud-update", from: version, to: latest, config: CONFIG },
         run: async (context) => {
             const current = readJson(context.root, CONFIG) ?? {};
-            const schema = typeof current.$schema === "string" ? current.$schema.replace(/@ramon-sg\/claude-cloud@[^/]+\//, `${PACKAGE}@${latest}/`) : undefined;
+            const schema = typeof current.$schema === "string" ? current.$schema.replace(/\/agent-cloud-kit@[^/]+\//, `/${PACKAGE}@${latest}/`) : undefined;
             writeJson(context.root, CONFIG, { ...current, ...(schema === undefined ? {} : { $schema: schema }), version: latest });
-            return true;
+            const spec = `${PACKAGE}@${latest}`;
+            const run = await runNpx(context.root, [spec, "init"]);
+            if (run.ok)
+                return true;
+            context.fail(`agent-cloud-kit init falló; corre 'npx ${spec} init'.`, run.output);
+            return false;
         },
     };
 }
 /**
- * What the repo has of claude-cloud, and the step it needs.
+ * What the repo has of agent-cloud-kit, and the step it needs.
  * @param root - The repo.
  * @returns The piece's status.
  * @example (await cloudStatus(root)).state // "1.0.0, al día"
  */
 export async function cloudStatus(root) {
     const config = readJson(root, CONFIG);
-    const latest = await npmLatest(PACKAGE);
+    const latest = await npmLatestExact(PACKAGE);
     const version = pinned(config);
     const step = stepFor(config, latest);
     const known = latest === null ? " (npm no responde)" : "";
@@ -79,10 +84,10 @@ export async function cloudChecks(root) {
     if (config === null)
         return [{ name: NAME, status: "info", detail: "no instalado" }];
     const version = pinned(config);
-    const latest = await npmLatest(PACKAGE);
+    const latest = await npmLatestExact(PACKAGE);
     if (version === null)
         return [{ name: NAME, status: "fail", detail: `${CONFIG} no fija una versión exacta: pon en "version" la que se usa, como "${latest ?? "1.0.0"}"` }];
-    if (latest !== null && compareVersions(latest, version) > 0)
+    if (latest !== null && compareSemver(latest, version) > 0)
         return [{ name: NAME, status: "info", detail: `${version}, hay ${latest}: corre npx agent-kitchen apply` }];
     return [{ name: NAME, status: "ok", detail: version }];
 }

package/dist/texts/catalog.d.ts

@@ -39,6 +39,8 @@ export interface Catalog {
     summary: (failed: string[]) => string;
     /** What is left to do by hand after the steps, in the checkout; with the manager if its install failed. */
     next: (failedInstall: string | null) => string;
+    /** The step after apply when agent-cloud-kit is installed. */
+    cloudNext: string;
     /** A new piece left out because no one was asked about it. */
     undecided: (names: string[]) => string;
     /** The repo's own skills left out of a pick. */

package/dist/texts/es.js

@@ -53,14 +53,14 @@ export const es = {
             done: `github-rest subido de ${from} a ${to}, el mínimo de issue-flow ${flow}`,
         }),
         "cloud-install": ({ version }) => ({
-            menu: `Instalar claude-cloud ${version ?? "1.x"}: prepara las sesiones en la nube de Claude`,
-            doing: `Instalando claude-cloud ${version ?? "1.x"}…`,
-            done: `claude-cloud ${version ?? "1.x"} instalado: prepara las sesiones en la nube de Claude`,
+            menu: `Instalar agent-cloud-kit ${version ?? "1.x"}: prepara las sesiones en la nube de Claude`,
+            doing: `Instalando agent-cloud-kit ${version ?? "1.x"}…`,
+            done: `agent-cloud-kit ${version ?? "1.x"} instalado: prepara las sesiones en la nube de Claude`,
         }),
         "cloud-update": ({ from, to, config }) => ({
-            menu: `Actualizar claude-cloud ${from ?? "?"} → ${to} (la versión que fija ${config})`,
-            doing: `Actualizando claude-cloud de ${from ?? "?"} a ${to}…`,
-            done: `claude-cloud actualizado de ${from ?? "?"} a ${to} en ${config}`,
+            menu: `Actualizar agent-cloud-kit ${from ?? "?"} → ${to} (la versión que fija ${config})`,
+            doing: `Actualizando agent-cloud-kit de ${from ?? "?"} a ${to}…`,
+            done: `agent-cloud-kit actualizado de ${from ?? "?"} a ${to} en ${config}`,
         }),
         "guard-install": ({ version }) => ({
             menu: `Instalar claude-repo-guard ${version ?? "(main)"}: modo auto con sandbox, y un documento de qué protege`,
@@ -128,6 +128,7 @@ export const es = {
     suggested: (dryRun) => `Pasos sugeridos${dryRun ? "" : " (para hacerlos, corre agent-kitchen apply en una terminal, o con --yes)"}:`,
     summary: (failed) => (failed.length === 0 ? "Listo." : `Terminó, pero fallaron: ${failed.join("; ")}.`),
     next: (failedInstall) => `Falta: ${failedInstall === null ? "" : `corre '${failedInstall} install', `}revisa el diff y haz commit.`,
+    cloudNext: "Siguiente paso para la nube: npx agent-cloud-kit prepare",
     undecided: (names) => `Pieza nueva sin decisión: ${list(names)}. Corre agent-kitchen apply en una terminal para elegir.`,
     ownSkillsKept: (names) => `Se dejan fuera las skills que el repo ya tiene como propias: ${list(names)}. Para reemplazarlas, corre agent-kitchen apply en una terminal.`,
     saved: (file, commits) => `Guardé qué piezas usa el repo en ${file}${commits ? "" : "; commitéalo"}.`,

package/dist/tools.d.ts

@@ -19,13 +19,35 @@ export declare function compareVersions(left: string, right: string): number;
  * @example isRelease("1.2.3") // true
  */
 export declare function isRelease(version: string): boolean;
+/**
+ * Whether a version is exact semver: a release like 1.2.3, or one with a prerelease like 1.2.3-rc.0.
+ * @param version - The text.
+ * @returns True for an exact version; ranges, tags and build metadata are not.
+ * @example isExactVersion("1.0.0-rc.0") // true
+ */
+export declare function isExactVersion(version: string): boolean;
+/**
+ * Compares two exact versions by semver precedence, prereleases included.
+ * @param left - A version like 1.0.0-rc.0.
+ * @param right - Another.
+ * @returns Negative if left is older, 0 if equal, positive if newer.
+ * @example compareSemver("1.0.0-rc.1", "1.0.0") // -1
+ */
+export declare function compareSemver(left: string, right: string): number;
 /**
  * The latest version of a package on npm.
  * @param name - The package.
  * @returns The version, or null if npm cannot tell.
- * @example await npmLatest("@ramon-sg/claude-cloud") // "1.0.0"
+ * @example await npmLatest("agent-cloud-kit") // "1.0.0"
  */
 export declare function npmLatest(name: string): Promise<string | null>;
+/**
+ * The `latest` version of a package on npm, even if it is a prerelease like 1.0.0-rc.0.
+ * @param name - The package.
+ * @returns The version, or null if npm cannot tell or it is not exact semver.
+ * @example await npmLatestExact("agent-cloud-kit") // "1.0.0-rc.0"
+ */
+export declare function npmLatestExact(name: string): Promise<string | null>;
 /**
  * The dependencies a version of a package declares on npm.
  * @param spec - The package and its version, as `name@x.y.z`.
@@ -46,7 +68,7 @@ export declare function latestTag(repo: string): Promise<string | null>;
  * @param root - The repo.
  * @param spec - The package, as npx takes it.
  * @returns When it is done.
- * @example void download(root, "@ramon-sg/claude-cloud@1.0.0")
+ * @example void download(root, "agent-cloud-kit@1.0.0")
  */
 export declare function download(root: string, spec: string): Promise<void>;
 /** How a tool ended, and what it printed if it was kept. */
@@ -60,7 +82,7 @@ export interface ToolRun {
  * @param root - The repo.
  * @param args - The package and its arguments.
  * @returns Whether it exited 0, and what it printed.
- * @example await runNpx(root, ["@ramon-sg/claude-cloud@1.0.0", "init"])
+ * @example await runNpx(root, ["agent-cloud-kit@1.0.0", "init"])
  */
 export declare function runNpx(root: string, args: string[]): Promise<ToolRun>;
 /**

package/dist/tools.js

@@ -12,6 +12,8 @@
 import { spawn } from "node:child_process";
 /** A release version. */
 const VERSION = /^(\d+)\.(\d+)\.(\d+)$/;
+/** An exact semver version: release plus an optional prerelease, no build metadata. */
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?$/;
 /** How long a lookup of the latest version may take before it counts as unknown. */
 const LOOKUP_TIMEOUT_MS = 20_000;
 /** A release tag in `git ls-remote --tags --refs` output. */
@@ -58,6 +60,50 @@ export function compareVersions(left, right) {
 export function isRelease(version) {
     return VERSION.test(version);
 }
+/**
+ * Whether a version is exact semver: a release like 1.2.3, or one with a prerelease like 1.2.3-rc.0.
+ * @param version - The text.
+ * @returns True for an exact version; ranges, tags and build metadata are not.
+ * @example isExactVersion("1.0.0-rc.0") // true
+ */
+export function isExactVersion(version) {
+    return SEMVER.test(version);
+}
+/**
+ * Compares two exact versions by semver precedence, prereleases included.
+ * @param left - A version like 1.0.0-rc.0.
+ * @param right - Another.
+ * @returns Negative if left is older, 0 if equal, positive if newer.
+ * @example compareSemver("1.0.0-rc.1", "1.0.0") // -1
+ */
+export function compareSemver(left, right) {
+    const [a, b] = [SEMVER.exec(left), SEMVER.exec(right)];
+    for (let index = 1; index <= 3; index += 1) {
+        const diff = Number(a?.[index] ?? 0) - Number(b?.[index] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    const [pre, other] = [a?.[4], b?.[4]];
+    if (pre === other)
+        return 0;
+    if (pre === undefined)
+        return 1;
+    if (other === undefined)
+        return -1;
+    const [x, y] = [pre.split("."), other.split(".")];
+    for (let index = 0; index < Math.min(x.length, y.length); index += 1) {
+        const [p, q] = [x[index], y[index]];
+        if (p === q)
+            continue;
+        const [pNumber, qNumber] = [/^\d+$/.test(p), /^\d+$/.test(q)];
+        if (pNumber && qNumber)
+            return Number(p) - Number(q);
+        if (pNumber !== qNumber)
+            return pNumber ? -1 : 1;
+        return p < q ? -1 : 1;
+    }
+    return x.length - y.length;
+}
 /**
  * Runs a program and collects what it prints.
  * @param program - The program.
@@ -102,15 +148,35 @@ function once(key, lookup) {
  * The latest version of a package on npm.
  * @param name - The package.
  * @returns The version, or null if npm cannot tell.
- * @example await npmLatest("@ramon-sg/claude-cloud") // "1.0.0"
+ * @example await npmLatest("agent-cloud-kit") // "1.0.0"
  */
 export function npmLatest(name) {
     return once(`npm:${name}`, async () => {
-        const result = await run("npm", ["view", name, "version", "--fetch-retries=0"], { timeout: LOOKUP_TIMEOUT_MS });
-        const version = result.status === 0 ? result.out.trim() : "";
+        const version = await npmVersion(name);
         return isRelease(version) ? version : null;
     });
 }
+/**
+ * The `latest` version of a package on npm, even if it is a prerelease like 1.0.0-rc.0.
+ * @param name - The package.
+ * @returns The version, or null if npm cannot tell or it is not exact semver.
+ * @example await npmLatestExact("agent-cloud-kit") // "1.0.0-rc.0"
+ */
+export function npmLatestExact(name) {
+    return once(`npm-exact:${name}`, async () => {
+        const version = await npmVersion(name);
+        return isExactVersion(version) ? version : null;
+    });
+}
+/**
+ * What `npm view <name> version` prints.
+ * @param name - The package.
+ * @returns The text, or "" if npm fails.
+ */
+async function npmVersion(name) {
+    const result = await run("npm", ["view", name, "version", "--fetch-retries=0"], { timeout: LOOKUP_TIMEOUT_MS });
+    return result.status === 0 ? result.out.trim() : "";
+}
 /**
  * The dependencies a version of a package declares on npm.
  * @param spec - The package and its version, as `name@x.y.z`.
@@ -152,7 +218,7 @@ export function latestTag(repo) {
  * @param root - The repo.
  * @param spec - The package, as npx takes it.
  * @returns When it is done.
- * @example void download(root, "@ramon-sg/claude-cloud@1.0.0")
+ * @example void download(root, "agent-cloud-kit@1.0.0")
  */
 export function download(root, spec) {
     const known = downloads.get(spec);
@@ -168,7 +234,7 @@ export function download(root, spec) {
  * @param root - The repo.
  * @param args - The package and its arguments.
  * @returns Whether it exited 0, and what it printed.
- * @example await runNpx(root, ["@ramon-sg/claude-cloud@1.0.0", "init"])
+ * @example await runNpx(root, ["agent-cloud-kit@1.0.0", "init"])
  */
 export async function runNpx(root, args) {
     const result = await run("npx", ["--yes", ...args], { cwd: root, inherit: verbose });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-kitchen",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "One command to install, update and check a repo's agent tooling: the issue flow and its skills, the general skills, Claude cloud sessions, claude-repo-guard and the installed-versions rule in AGENTS.md.",
   "license": "MIT",
   "type": "module",