agent-kitchen 0.2.0 → 0.3.0

package/README.md

@@ -11,8 +11,10 @@ Al arrancar revisa si npm tiene una versión más nueva de sí mismo. Si la hay,
 
 ## En simple
 
-- Muestra cada pieza con la versión que tiene el repo y la última que existe.
-- Ofrece instalar lo que falta y actualizar lo que está atrasado, en un menú de casillas. Todo viene marcado; desmarcas lo que no quieres.
+- Muestra cada pieza con la versión que tiene el repo y si está al día.
+- Pregunta una vez: **todo lo sugerido** (Enter), **elegir** los pasos y las skills, o **salir**. Todas las preguntas van antes de instalar; después corre solo.
+- Cada paso es una línea con ✓ o ✗. La salida de cada herramienta solo aparece si falla, o con `--verbose`.
+- Es rápido: las versiones se consultan todas a la vez y las herramientas se descargan mientras respondes.
 - Cada pieza la instala su propia herramienta. `agent-kitchen` solo sabe cuáles hay, en qué versión están y cómo se conectan entre sí.
 - Correrlo de nuevo no rompe nada: si todo está al día, lo dice y termina.
 
@@ -23,23 +25,25 @@ Al arrancar revisa si npm tiene una versión más nueva de sí mismo. Si la hay,
 | `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 init` | `issue-flow upgrade` en la versión nueva, y sus skills a la misma tag |
 | `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` |
 | `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 | `install` en esa tag | `install` 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 | El menú de `skills-manager` | `skills-manager update` |
+| `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` |
 
 Si npm o GitHub no responden, la pieza se muestra pero no se ofrece actualizarla. Si un paso falla, los demás siguen y el comando dice cómo reintentarlo.
 
 ### Cómo se conectan
 
 - **Las skills del flujo van con su CLI,** porque la llaman: se instalan en la tag de la versión del flujo y se mueven con él. Las generales llevan cada una su propia versión.
-- **Skills nuevas:** si un catálogo trae skills que el repo no tiene, aparecen en el menú sin marcar. Al marcarlas se abre el menú de `skills-manager` para elegir.
+- **Qué skills:** la primera vez vienen todas las de los catálogos. Con "Elegir" aparece un menú agrupado por catálogo, con la descripción de cada una. Si un catálogo trae skills que el repo no tiene, se ofrecen como un paso sin marcar.
+- **Skills propias del repo:** si el repo ya tiene una carpeta con el nombre de una skill del catálogo, pregunta una vez si reemplazarlas. Al reemplazar se conserva su `project.md`. Con `--yes` no se reemplazan: se dejan fuera y lo dice.
 - **Seguridad y flujo:** si el repo tiene el flujo, antes de instalar `claude-repo-guard` se escribe en sus opciones que abrir el PR en draft, asignar la issue y agregar el "Slug de rama" son parte del trabajo normal. También se escribe la rama base del flujo como `integrationBranch`. En macOS se agrega `weakerNetworkIsolation`, que `gh` necesita dentro del sandbox. Si `claude-repo-guard` ya estaba al día pero le faltan esas opciones, se ofrecen como un paso.
 - **La nube no molesta en local:** el hook de sesión solo actúa en la nube. Un repo que nunca se abre ahí no pierde nada.
 
 ## Uso
 
 ```sh
-npx agent-kitchen                        # menú, en una terminal
-npx agent-kitchen --dry-run              # solo muestra qué ofrecería
+npx agent-kitchen                        # pregunta, en una terminal (Enter: todo lo sugerido)
+npx agent-kitchen --dry-run              # solo muestra qué haría
 npx agent-kitchen --yes                  # hace lo sugerido sin preguntar
+npx agent-kitchen --verbose              # muestra la salida de cada herramienta
 npx agent-kitchen --skip claude-cloud    # deja fuera una pieza (o varias, con comas)
 npx agent-kitchen doctor                 # revisa cada pieza con su propio doctor
 ```
@@ -52,7 +56,7 @@ npx agent-kitchen doctor                 # revisa cada pieza con su propio docto
 
 ## Sumar una pieza
 
-Una pieza es un archivo en `src/pieces/` con dos funciones: `status(root)` dice qué tiene el repo y qué pasos ofrece, y `checks(root)` da sus revisiones para `doctor`. Se registra en `PIECES` de `src/commands/sync.ts` y en `src/commands/doctor.ts`. Cada paso corre la herramienta de la pieza, que es dueña de sus archivos. Un catálogo de skills nuevo es una línea en `GENERAL_CATALOGS` de `src/piece.ts`.
+Una pieza es un archivo en `src/pieces/` con dos funciones asíncronas: `status(root)` dice qué tiene el repo y qué pasos ofrece, y `checks(root)` da sus revisiones para `doctor`. Un paso dice qué paquetes descargar antes (`downloads`) y nunca pregunta nada: las preguntas van antes, en `src/menu.ts`. Se registra en `PIECES` de `src/commands/sync.ts` y en `src/commands/doctor.ts`. Cada paso corre la herramienta de la pieza, que es dueña de sus archivos. Un catálogo de skills nuevo es una línea en `GENERAL_CATALOGS` de `src/piece.ts`.
 
 ## Desarrollo
 
@@ -61,7 +65,7 @@ npm install
 npm test        # compila y corre los tests
 ```
 
-Los tests corren el CLI compilado sobre repos reales. `npx` y `npm` son falsos (`test/fake-tools.mjs`) y registran cada llamada. Las tags de GitHub salen de repos locales a los que git llega reescribiendo `https://github.com/`, así que `git ls-remote` es el real. El menú no se prueba renderizado: se prueba `menuOptions` y se corrió a mano en una terminal.
+Los tests corren el CLI compilado sobre repos reales. `npx` y `npm` son falsos (`test/fake-tools.mjs`) y registran cada llamada. Las tags de GitHub salen de repos locales a los que git llega reescribiendo `https://github.com/`, así que `git ls-remote` es el real. Los menús no se prueban renderizados: se prueban `menuOptions` y `skillOptions`, y se corrieron en una terminal con `expect`. Con `@clack/prompts` 1.8.1, una ruedita mostrada antes de una pregunta deja a la segunda pregunta sin teclado; por eso la revisión inicial es una línea de texto.
 
 ## Publicar una versión
 

package/dist/cli.js

@@ -11,23 +11,27 @@ import { parseArgs } from "node:util";
 import { doctor } from "./commands/doctor.js";
 import { pieceNames, sync } from "./commands/sync.js";
 import { KitError, processOutput, UsageError } from "./output.js";
-import { compareVersions, isRelease, npmLatest } from "./tools.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";
 /** 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. */
 const HANDED_OVER = "AGENT_KITCHEN_HANDED_OVER";
 /** Usage text. */
-const USAGE = `Usage:
-  agent-kitchen [--yes | --dry-run] [--skip <piece>,...]
+const USAGE = `Uso:
+  agent-kitchen [--yes | --dry-run] [--verbose] [--skip <pieza>,...]
   agent-kitchen doctor
 
-agent-kitchen looks at each piece of the repo's agent tooling (${pieceNames().join(", ")}),
-shows what the repo has and the latest of each, and offers to install what is missing and
-update what is behind: in a terminal, a menu where you untick what you do not want. --yes
-runs what it suggests without asking; without a terminal it only shows it. Run it in the
-main checkout, from your terminal.
+agent-kitchen revisa cada pieza de las herramientas de agentes del repo (${pieceNames().join(", ")}),
+muestra qué tiene el repo y la última versión de cada una, y ofrece instalar lo que falta y
+actualizar lo que está atrasado. En una terminal pregunta una vez: hacer todo lo sugerido,
+o elegir los pasos y las skills. --yes hace lo sugerido sin preguntar; sin terminal solo lo
+muestra. --verbose muestra la salida de cada herramienta. Córrelo en la copia principal del
+repo, desde tu terminal.
 
-doctor runs each piece's own checks at the repo's version, and changes nothing.`;
+doctor corre las revisiones de cada pieza en la versión del repo, sin cambiar nada.`;
 /**
  * This package's version.
  * @returns The version in its package.json.
@@ -36,19 +40,29 @@ function ownVersion() {
     const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
     return pkg.version ?? "unknown";
 }
+/**
+ * Starts the lookups of the latest versions, so they run while this one checks its own.
+ */
+function startLookups() {
+    void npmLatest(FLOW_PACKAGE);
+    void npmLatest(CLOUD_PACKAGE);
+    void latestTag(GUARD_REPO);
+    for (const catalog of GENERAL_CATALOGS)
+        void latestTag(catalog);
+}
 /**
  * Runs the latest agent-kitchen with the same arguments, if npm has one newer than this.
  * @param argv - The arguments.
  * @returns Its exit code, or null if this one is the latest or npm cannot tell.
  */
-function handOver(argv) {
+async function handOver(argv) {
     const own = ownVersion();
     if (process.env[HANDED_OVER] !== undefined || !isRelease(own))
         return null;
-    const latest = npmLatest(PACKAGE);
+    const latest = await npmLatest(PACKAGE);
     if (latest === null || compareVersions(latest, own) <= 0)
         return null;
-    process.stderr.write(`agent-kitchen: running ${latest}, the latest (this is ${own}).\n`);
+    process.stderr.write(`agent-kitchen: uso ${latest}, la última (esta es ${own}).\n`);
     const result = spawnSync("npx", ["--yes", `${PACKAGE}@${latest}`, ...argv], { stdio: "inherit", env: { ...process.env, [HANDED_OVER]: own } });
     return result.status ?? 1;
 }
@@ -63,7 +77,7 @@ async function main(argv) {
     const { values, positionals } = parseArgs({
         args: argv,
         allowPositionals: true,
-        options: { yes: { type: "boolean" }, "dry-run": { type: "boolean" }, skip: { type: "string" }, help: { type: "boolean", short: "h" }, version: { type: "boolean" } },
+        options: { yes: { type: "boolean" }, "dry-run": { type: "boolean" }, verbose: { type: "boolean", short: "v" }, skip: { type: "string" }, help: { type: "boolean", short: "h" }, version: { type: "boolean" } },
     });
     if (values.help === true) {
         out.stdout(`${USAGE}\n`);
@@ -73,19 +87,20 @@ async function main(argv) {
         out.stdout(`${ownVersion()}\n`);
         return 0;
     }
-    const handed = handOver(argv);
+    startLookups();
+    const handed = await handOver(argv);
     if (handed !== null)
         return handed;
     const [command, ...rest] = positionals;
     if (rest.length > 0 || (command !== undefined && command !== "doctor"))
-        throw new UsageError(`unknown command ${positionals.join(" ")}.`);
+        throw new UsageError(`no existe el comando ${positionals.join(" ")}.`);
     if (command === "doctor") {
-        if (values.yes !== undefined || values["dry-run"] !== undefined || values.skip !== undefined)
-            throw new UsageError("doctor takes no flags.");
+        if (values.yes !== undefined || values["dry-run"] !== undefined || values.skip !== undefined || values.verbose !== undefined)
+            throw new UsageError("doctor no lleva opciones.");
         return doctor(process.cwd(), out);
     }
     const skip = (values.skip ?? "").split(",").map((name) => name.trim()).filter((name) => name !== "");
-    return sync({ cwd: process.cwd(), yes: values.yes ?? false, dryRun: values["dry-run"] ?? false, skip }, out);
+    return sync({ cwd: process.cwd(), yes: values.yes ?? false, dryRun: values["dry-run"] ?? false, verbose: values.verbose ?? false, skip }, out);
 }
 try {
     process.exitCode = await main(process.argv.slice(2));

package/dist/commands/doctor.d.ts

@@ -11,6 +11,6 @@ import type { Output } from "../output.js";
  * @param out - Where to write.
  * @returns 0 if nothing failed, 1 if something did.
  * @throws KitError outside a checkout or with a broken file.
- * @example doctor(process.cwd(), out)
+ * @example await doctor(process.cwd(), out)
  */
-export declare function doctor(cwd: string, out: Output): number;
+export declare function doctor(cwd: string, out: Output): Promise<number>;

package/dist/commands/doctor.js

@@ -11,11 +11,11 @@ const MARKS = { ok: "✓", fail: "✗", info: "·" };
  * @param out - Where to write.
  * @returns 0 if nothing failed, 1 if something did.
  * @throws KitError outside a checkout or with a broken file.
- * @example doctor(process.cwd(), out)
+ * @example await doctor(process.cwd(), out)
  */
-export function doctor(cwd, out) {
+export async function doctor(cwd, out) {
     const root = mainCheckout(cwd, "agent-kitchen doctor");
-    const checks = [...issueFlowChecks(root), ...skillsChecks(root), ...cloudChecks(root), ...guardChecks(root)];
+    const checks = (await Promise.all([issueFlowChecks(root), skillsChecks(root), cloudChecks(root), guardChecks(root)])).flat();
     for (const check of checks)
         out.stdout(`${MARKS[check.status]} ${check.name}: ${check.detail}\n`);
     return checks.some((check) => check.status === "fail") ? 1 : 0;

package/dist/commands/sync.d.ts

@@ -4,6 +4,7 @@ export interface SyncOptions {
     cwd: string;
     yes: boolean;
     dryRun: boolean;
+    verbose: boolean;
     skip: string[];
 }
 /**
@@ -18,6 +19,6 @@ export declare function pieceNames(): string[];
  * @param out - Where to write and ask.
  * @returns 0, or 1 if a step failed or the person cancelled.
  * @throws KitError outside the main checkout or with a broken file; UsageError for an unknown piece.
- * @example await sync({ cwd, yes: false, dryRun: true, skip: [] }, out)
+ * @example await sync({ cwd, yes: false, dryRun: true, verbose: false, skip: [] }, out)
  */
 export declare function sync(options: SyncOptions, out: Output): Promise<number>;

package/dist/commands/sync.js

@@ -1,33 +1,48 @@
 /**
- * @file `agent-kitchen [--yes] [--dry-run] [--skip <piece>,...]`: the one command. It looks at
- * each piece (the issue flow, claude-cloud, claude-repo-guard, the skills), shows what the
- * repo has and the latest of each, and offers the steps that install what is missing or
- * update what is behind. In a terminal the person unticks what they do not want; with
- * `--yes` it runs the ticked ones; without a terminal it only shows them. The steps run in
- * order (the flow first, the skills last, since they follow the flow's version) and one that
- * fails does not stop the rest.
+ * @file `agent-kitchen [--yes] [--dry-run] [--verbose] [--skip <piece>,...]`: the one command.
+ * It looks at each piece (the issue flow, claude-cloud, claude-repo-guard, the skills) 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
+ * suggested, or pick the steps and the skills; whether to replace the repo's own skills.
+ * While the person answers, the tools download. Then the steps run in order (the flow
+ * first, the skills last, since they follow the flow's version), one line each, with the
+ * tools' output only when one fails; one that fails does not stop the rest. With `--yes`
+ * it does what is suggested without asking (and keeps the repo's own skills); without a
+ * terminal it only shows the steps.
  */
-import { askSteps } from "../menu.js";
+import { spinner } from "@clack/prompts";
+import { askPath, askReplace, askSkills, askSteps } from "../menu.js";
 import { KitError, UsageError, warn } from "../output.js";
 import { cloudStatus, NAME as CLOUD } from "../pieces/cloud.js";
 import { guardStatus, NAME as GUARD } from "../pieces/guard.js";
 import { issueFlowStatus, NAME as FLOW } from "../pieces/issue-flow.js";
-import { NAME as SKILLS, skillsStatus } from "../pieces/skills.js";
+import { keepOwn, NAME as SKILLS, ownInPick, skillsStatus } from "../pieces/skills.js";
 import { mainCheckout, packageManager } from "../repo.js";
+import { download, failedOutput, setVerbose } from "../tools.js";
 /** Every piece, in the order its steps run. */
-const PIECES = [
-    { name: FLOW, status: issueFlowStatus },
-    { name: CLOUD, status: cloudStatus },
-    { name: GUARD, status: (root, before) => guardStatus(root, before.some((status) => status.name === FLOW && !status.installed && status.steps.length > 0)) },
-    { name: SKILLS, status: skillsStatus },
-];
+const PIECES = [FLOW, CLOUD, GUARD, SKILLS];
 /**
  * The names `--skip` takes.
  * @returns The pieces' names.
  * @example pieceNames() // ["issue-flow", "claude-cloud", "claude-repo-guard", "skills"]
  */
 export function pieceNames() {
-    return PIECES.map((piece) => piece.name);
+    return [...PIECES];
+}
+/**
+ * Each piece's status, with every lookup at once. The guard's step depends on whether the
+ * flow is about to be installed, so it waits for the flow's status.
+ * @param root - The repo.
+ * @param skip - The pieces left out.
+ * @returns The statuses, in the pieces' order.
+ */
+async function statusesOf(root, skip) {
+    const flow = skip.includes(FLOW) ? null : issueFlowStatus(root);
+    const cloud = skip.includes(CLOUD) ? null : cloudStatus(root);
+    const skills = skip.includes(SKILLS) ? null : skillsStatus(root, !skip.includes(FLOW));
+    const guard = skip.includes(GUARD) ? null : (flow ?? Promise.resolve(null)).then((status) => guardStatus(root, status !== null && !status.installed && status.steps.length > 0));
+    const all = await Promise.all([flow, cloud, guard, skills]);
+    return all.flatMap((status) => status ?? []);
 }
 /**
  * Prints what the repo has of each piece.
@@ -36,28 +51,145 @@ export function pieceNames() {
  */
 function printStatus(statuses, out) {
     const width = Math.max(...statuses.map((status) => status.name.length));
-    out.stdout("This repo has:\n");
+    const stateWidth = Math.max(...statuses.map((status) => status.state.length));
+    out.stdout("\nEste repo tiene:\n");
     for (const status of statuses)
-        out.stdout(`  ${status.name.padEnd(width)}  ${status.state}  · ${status.summary}\n`);
+        out.stdout(`  ${status.name.padEnd(width)}  ${status.state.padEnd(stateWidth)}  · ${status.summary}\n`);
+    out.stdout("\n");
+}
+/**
+ * Leaves the repo's own skills out of a step's pick, saying so.
+ * @param root - The repo.
+ * @param step - A step that installs skills.
+ * @param out - Where to write.
+ */
+function keepOwnSkills(root, step, out) {
+    if (step.skills === undefined)
+        return;
+    const own = ownInPick(root, step.skills);
+    if (own.length === 0)
+        return;
+    Object.assign(step.skills, keepOwn(step.skills, own));
+    out.stdout(`Se dejan fuera las skills que el repo ya tiene como propias: ${own.join(", ")}. Para reemplazarlas, corre agent-kitchen en una terminal.\n`);
+}
+/**
+ * Asks, for a step that installs skills, which ones, and whether to replace the repo's own.
+ * @param root - The repo.
+ * @param step - The step.
+ * @param chooseSkills - Whether to show the skills menu, or keep the step's pick.
+ * @returns False if the person cancelled.
+ */
+async function askAboutSkills(root, step, chooseSkills) {
+    const pick = step.skills;
+    if (pick === undefined)
+        return true;
+    if (chooseSkills) {
+        const picked = await askSkills(pick.candidates, pick.picked.length > 0 ? pick.picked : pick.candidates.map((candidate) => candidate.id));
+        if (picked === null)
+            return false;
+        pick.picked = picked;
+    }
+    const own = ownInPick(root, pick);
+    if (own.length === 0)
+        return true;
+    const replace = await askReplace(own);
+    if (replace === null)
+        return false;
+    if (replace)
+        pick.replace = own;
+    else
+        Object.assign(pick, keepOwn(pick, own));
+    return true;
 }
 /**
- * The steps to run: the ticked ones with `--yes`, the picked ones in a terminal, or none.
+ * The steps to run: the suggested ones with `--yes`, what the person picks in a terminal,
+ * or none (only shown) with `--dry-run` or without a terminal.
+ * @param root - The repo.
  * @param steps - The steps offered.
  * @param options - The options.
  * @param out - Where to write.
- * @returns The steps, or null if nothing should run.
+ * @returns The steps, "leave" if the person chose to leave, or null if nothing should run (only shown, or cancelled).
  */
-async function chooseSteps(steps, options, out) {
-    if (options.yes)
-        return steps.filter((step) => step.checked);
+async function chooseSteps(root, steps, options, out) {
+    const suggested = steps.filter((step) => step.checked);
+    if (options.yes) {
+        if (suggested.length === 0)
+            out.stdout(`Todo al día. Opcional, para elegir en una terminal: ${steps.map((step) => step.label).join("; ")}.\n`);
+        for (const step of suggested)
+            keepOwnSkills(root, step, out);
+        return suggested;
+    }
     if (options.dryRun || !out.interactive) {
-        out.stdout(`It would offer${options.dryRun ? "" : " (run it in a terminal to pick, or with --yes)"}:\n${steps.map((step) => `  [${step.checked ? "x" : " "}] ${step.label}\n`).join("")}`);
+        const hint = options.dryRun ? "" : " (para hacerlos, corre agent-kitchen en una terminal, o con --yes)";
+        out.stdout(`Pasos sugeridos${hint}:\n${steps.map((step) => `  [${step.checked ? "x" : " "}] ${step.label}\n`).join("")}`);
         return null;
     }
-    const picked = await askSteps(steps);
-    if (picked === null)
-        warn(out, "cancelled; nothing changed.");
-    return picked;
+    for (const step of suggested)
+        for (const spec of step.downloads)
+            void download(root, spec);
+    const path = await askPath(suggested.length);
+    if (path === "leave")
+        return "leave";
+    const chosen = path === "all" ? suggested : await askSteps(steps);
+    if (chosen === null)
+        return null;
+    for (const step of chosen) {
+        if (!(await askAboutSkills(root, step, path === "pick")))
+            return null;
+    }
+    return chosen;
+}
+/**
+ * How progress is shown: a spinner in a terminal (unless the tools print with
+ * `--verbose`), plain lines otherwise. Only for the steps, after every question: a spinner
+ * shown before a question leaves the second question deaf to the keyboard (@clack/prompts
+ * 1.8.1).
+ * @param out - Where to write.
+ * @param verbose - Whether the tools print on the terminal.
+ * @returns The progress.
+ */
+function progressFor(out, verbose) {
+    if (out.interactive && !verbose) {
+        const spin = spinner();
+        return { start: (text) => spin.start(text), stop: (text, ok) => (ok ? spin.stop(text) : spin.error(text)) };
+    }
+    return { start: (text) => out.stdout(`→ ${text}\n`), stop: (text, ok) => out.stdout(`${ok ? "✓" : "✗"} ${text}\n`) };
+}
+/**
+ * Runs one step and shows how it went: its notes, and what to do if it failed.
+ * @param root - The repo.
+ * @param step - The step.
+ * @param progress - How progress is shown.
+ * @param out - Where to write.
+ * @returns Whether it worked.
+ * @throws What the step throws that is not a KitError.
+ */
+async function runStep(root, step, progress, out) {
+    const notes = [];
+    const failures = [];
+    const context = {
+        root,
+        note: (text) => notes.push(text),
+        fail: (text, output) => failures.push(`  ${text}\n${output === undefined ? "" : failedOutput(output)}`),
+    };
+    progress.start(step.label);
+    await Promise.all(step.downloads.map((spec) => download(root, spec)));
+    let ok;
+    try {
+        ok = await step.run(context);
+    }
+    catch (error) {
+        if (!(error instanceof KitError))
+            throw error;
+        failures.push(`  ${error.message}\n`);
+        ok = false;
+    }
+    progress.stop(step.label, ok);
+    for (const note of notes)
+        out.stdout(`  · ${note}\n`);
+    for (const failure of failures)
+        out.stderr(failure);
+    return ok;
 }
 /**
  * Runs the command; see the file's header.
@@ -65,47 +197,47 @@ async function chooseSteps(steps, options, out) {
  * @param out - Where to write and ask.
  * @returns 0, or 1 if a step failed or the person cancelled.
  * @throws KitError outside the main checkout or with a broken file; UsageError for an unknown piece.
- * @example await sync({ cwd, yes: false, dryRun: true, skip: [] }, out)
+ * @example await sync({ cwd, yes: false, dryRun: true, verbose: false, skip: [] }, out)
  */
 export async function sync(options, out) {
     const unknown = options.skip.find((name) => !pieceNames().includes(name));
     if (unknown !== undefined)
-        throw new UsageError(`unknown piece ${unknown}; there are ${pieceNames().join(", ")}.`);
+        throw new UsageError(`no existe la pieza ${unknown}; son ${pieceNames().join(", ")}.`);
     if (options.yes && options.dryRun)
-        throw new UsageError("use --yes or --dry-run, not both.");
+        throw new UsageError("usa --yes o --dry-run, no los dos.");
     const root = mainCheckout(options.cwd, "agent-kitchen");
-    const statuses = [];
-    for (const piece of PIECES.filter((item) => !options.skip.includes(item.name)))
-        statuses.push(piece.status(root, statuses));
+    setVerbose(options.verbose);
+    if (out.interactive)
+        out.stdout("Revisando el repo y las últimas versiones…\n");
+    const statuses = await statusesOf(root, options.skip);
     printStatus(statuses, out);
     const steps = statuses.flatMap((status) => status.steps);
     if (steps.length === 0) {
-        out.stdout("Nothing to install or update.\n");
+        out.stdout("Todo al día: no hay nada que instalar ni actualizar.\n");
         return 0;
     }
-    const chosen = await chooseSteps(steps, options, out);
-    if (chosen === null)
+    const chosen = await chooseSteps(root, steps, options, out);
+    if (chosen === "leave") {
+        out.stdout("No se cambió nada.\n");
+        return 0;
+    }
+    if (chosen === null) {
+        if (!options.dryRun && out.interactive)
+            warn(out, "no se cambió nada.");
         return options.dryRun || !out.interactive ? 0 : 1;
+    }
     if (chosen.length === 0) {
-        out.stdout("Nothing picked; nothing changed.\n");
+        if (!options.yes)
+            out.stdout("No elegiste nada; no se cambió nada.\n");
         return 0;
     }
+    const progress = progressFor(out, options.verbose);
     const failed = [];
     for (const step of chosen) {
-        out.stdout(`\n→ ${step.label}\n`);
-        let ok;
-        try {
-            ok = step.run({ root, yes: options.yes || !out.interactive, out });
-        }
-        catch (error) {
-            if (!(error instanceof KitError))
-                throw error;
-            warn(out, error.message);
-            ok = false;
-        }
-        if (!ok)
+        if (!(await runStep(root, step, progress, out)))
             failed.push(step.label);
     }
-    out.stdout(`\n${failed.length === 0 ? "Done." : `Done, but these failed: ${failed.join("; ")}.`} Next: run '${packageManager(root)} install', review the diff and commit it.\n`);
+    const next = `Falta: corre '${packageManager(root)} install', revisa el diff y haz commit.`;
+    out.stdout(`\n${failed.length === 0 ? "Listo." : `Terminó, pero fallaron: ${failed.join("; ")}.`} ${next}\n`);
     return failed.length === 0 ? 0 : 1;
 }

package/dist/menu.d.ts

@@ -1,4 +1,6 @@
-import type { Step } from "./piece.js";
+import type { Candidate, Step } from "./piece.js";
+/** What the person wants after seeing the table. */
+export type Path = "all" | "pick" | "leave";
 /**
  * The menu's options: each step's index and label, which names its piece.
  * @param steps - The steps.
@@ -12,6 +14,24 @@ export declare function menuOptions(steps: Step[]): {
     }[];
     initialValues: number[];
 };
+/**
+ * The skills menu's options: grouped by catalog, each with its description cut short.
+ * @param candidates - What the catalogs offer.
+ * @returns The groups.
+ * @example Object.keys(skillOptions(candidates)) // ["ramon-sg/issue-flow", "ramon-sg/agent-skills"]
+ */
+export declare function skillOptions(candidates: Candidate[]): Record<string, {
+    value: string;
+    label: string;
+    hint?: string;
+}[]>;
+/**
+ * Asks what to do: everything suggested, pick step by step, or leave.
+ * @param count - How many steps are suggested; with none, the option to do them is not shown.
+ * @returns The answer; "leave" if the person cancelled.
+ * @example await askPath(4) // "all"
+ */
+export declare function askPath(count: number): Promise<Path>;
 /**
  * Asks which steps to run.
  * @param steps - The steps.
@@ -19,3 +39,18 @@ export declare function menuOptions(steps: Step[]): {
  * @example await askSteps(steps)
  */
 export declare function askSteps(steps: Step[]): Promise<Step[] | null>;
+/**
+ * Asks which skills to install.
+ * @param candidates - What the catalogs offer.
+ * @param ticked - The ids ticked at the start.
+ * @returns The picked ids, or null if the person cancelled.
+ * @example await askSkills(candidates, ["catalog:ramon-sg/agent-skills/planning"])
+ */
+export declare function askSkills(candidates: Candidate[], ticked: string[]): Promise<string[] | null>;
+/**
+ * Asks whether the catalog's skills replace the repo's own ones with the same name.
+ * @param own - Their names.
+ * @returns True to replace them, false to keep them, or null if the person cancelled.
+ * @example await askReplace(["planning"])
+ */
+export declare function askReplace(own: string[]): Promise<boolean | null>;