agent-kitchen 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramón Soto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# agent-kitchen
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Un solo comando para instalar, actualizar y revisar lo que un repo usa para trabajar con agentes: el flujo de issues con sus skills, las skills generales, las sesiones de Claude en la nube y las barandas de seguridad.
+
+```sh
+npx agent-kitchen          # muestra qué hay, qué falta y qué está atrasado, y pregunta
+npx agent-kitchen doctor   # revisa que todo funcione, sin cambiar nada
+```
+
+Al arrancar revisa si npm tiene una versión más nueva de sí mismo. Si la hay, corre esa con los mismos argumentos, así que `npx` nunca usa una copia vieja de su caché.
+
+## 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.
+- 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.
+
+## Las piezas
+
+| Pieza | Qué es | Versión del repo | Última | Instalar | Actualizar |
+|---|---|---|---|---|---|
+| `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` |
+
+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.
+- **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 --yes                  # hace lo sugerido sin preguntar
+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
+```
+
+- **Sin terminal y sin `--yes`** (por ejemplo, desde un agente), solo muestra lo que ofrecería.
+- **Corre en el checkout principal,** no en un worktree, y desde tu terminal. Dentro de una sesión de Claude, el sandbox de `claude-repo-guard` no deja escribir `.claude/settings.json`.
+- **Al terminar,** corre el `install` de tu gestor de paquetes, revisa el diff y haz commit.
+
+**`doctor`** corre el doctor de cada herramienta en la versión del repo: `issue-flow doctor --json`, `skills-manager check` y `claude-repo-guard doctor --json`. Además revisa que las skills del flujo estén en la tag de su CLI, que `.claude/cloud.json` fije una versión exacta y, en macOS, `weakerNetworkIsolation`. Lo que no está instalado o tiene una versión nueva solo se anota con `·`. Sale con 1 si algo falla (`✗`).
+
+## 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`.
+
+## Desarrollo
+
+```sh
+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.
+
+## Publicar una versión
+
+Una versión es una release `vX.Y.Z` en GitHub, con el mismo número que `package.json`. Al publicarla, GitHub Actions corre los tests y publica en npm con procedencia (`.github/workflows/publish.yml`).
+
+La primera versión va a mano, porque npm solo deja configurar la publicación desde GitHub en un paquete que ya existe:
+
+1. `npm login` y, desde `main`, `npm publish --provenance=false`.
+2. En npmjs.com, en el paquete, Settings → Trusted publishing: GitHub Actions, repo `ramon-sg/agent-kitchen`, workflow `publish.yml`.
+3. Pushear la tag de esa versión sin crear una release: una release volvería a publicar la misma versión y fallaría.
+
+## Licencia
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * @file Entry point of `agent-kitchen`: parses the arguments and runs the command. Before
+ * that, if npm has a newer agent-kitchen than the one running (npx may run an old copy from
+ * its cache), it runs that one instead with the same arguments. Usage errors exit 2 with
+ * the usage text; errors of the repo exit 1 with their message.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+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";
+/** 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>,...]
+  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.
+
+doctor runs each piece's own checks at the repo's version, and changes nothing.`;
+/**
+ * This package's version.
+ * @returns The version in its package.json.
+ */
+function ownVersion() {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return pkg.version ?? "unknown";
+}
+/**
+ * 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) {
+    const own = ownVersion();
+    if (process.env[HANDED_OVER] !== undefined || !isRelease(own))
+        return null;
+    const latest = npmLatest(PACKAGE);
+    if (latest === null || compareVersions(latest, own) <= 0)
+        return null;
+    process.stderr.write(`agent-kitchen: running ${latest}, the latest (this is ${own}).\n`);
+    const result = spawnSync("npx", ["--yes", `${PACKAGE}@${latest}`, ...argv], { stdio: "inherit", env: { ...process.env, [HANDED_OVER]: own } });
+    return result.status ?? 1;
+}
+/**
+ * Runs the CLI.
+ * @param argv - The arguments, without node and the script.
+ * @returns The exit code.
+ * @throws UsageError for unknown arguments; KitError from the command.
+ */
+async function main(argv) {
+    const out = processOutput();
+    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" } },
+    });
+    if (values.help === true) {
+        out.stdout(`${USAGE}\n`);
+        return 0;
+    }
+    if (values.version === true) {
+        out.stdout(`${ownVersion()}\n`);
+        return 0;
+    }
+    const handed = 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(" ")}.`);
+    if (command === "doctor") {
+        if (values.yes !== undefined || values["dry-run"] !== undefined || values.skip !== undefined)
+            throw new UsageError("doctor takes no flags.");
+        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);
+}
+try {
+    process.exitCode = await main(process.argv.slice(2));
+}
+catch (error) {
+    if (error instanceof UsageError || (error instanceof TypeError && "code" in error && String(error.code).startsWith("ERR_PARSE_ARGS"))) {
+        process.stderr.write(`agent-kitchen: ${error.message}\n\n${USAGE}\n`);
+        process.exitCode = 2;
+    }
+    else if (error instanceof KitError) {
+        process.stderr.write(`agent-kitchen: ${error.message}\n`);
+        process.exitCode = 1;
+    }
+    else {
+        throw error;
+    }
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file `agent-kitchen doctor`: whether each piece the repo has works, with the doctor of each
+ * tool at the repo's own version: the issue flow (and its skills at its tag),
+ * `skills-manager check`, the version `.claude/cloud.json` pins, and claude-repo-guard. It
+ * changes nothing. A piece the repo does not have, or a newer release, is only noted.
+ */
+import type { Output } from "../output.js";
+/**
+ * Checks the repo; see the file's header.
+ * @param cwd - Where it runs.
+ * @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)
+ */
+export declare function doctor(cwd: string, out: Output): number;

package/dist/commands/doctor.js

@@ -0,0 +1,22 @@
+import { cloudChecks } from "../pieces/cloud.js";
+import { guardChecks } from "../pieces/guard.js";
+import { issueFlowChecks } from "../pieces/issue-flow.js";
+import { skillsChecks } from "../pieces/skills.js";
+import { mainCheckout } from "../repo.js";
+/** The mark of each check's status. */
+const MARKS = { ok: "✓", fail: "✗", info: "·" };
+/**
+ * Checks the repo; see the file's header.
+ * @param cwd - Where it runs.
+ * @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)
+ */
+export function doctor(cwd, out) {
+    const root = mainCheckout(cwd, "agent-kitchen doctor");
+    const checks = [...issueFlowChecks(root), ...skillsChecks(root), ...cloudChecks(root), ...guardChecks(root)];
+    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

@@ -0,0 +1,23 @@
+import { type Output } from "../output.js";
+/** Options of the command. */
+export interface SyncOptions {
+    cwd: string;
+    yes: boolean;
+    dryRun: boolean;
+    skip: string[];
+}
+/**
+ * The names `--skip` takes.
+ * @returns The pieces' names.
+ * @example pieceNames() // ["issue-flow", "claude-cloud", "claude-repo-guard", "skills"]
+ */
+export declare function pieceNames(): string[];
+/**
+ * Runs the command; see the file's header.
+ * @param options - The options.
+ * @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)
+ */
+export declare function sync(options: SyncOptions, out: Output): Promise<number>;

package/dist/commands/sync.js

@@ -0,0 +1,111 @@
+/**
+ * @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.
+ */
+import { 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 { mainCheckout, packageManager } from "../repo.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 },
+];
+/**
+ * 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);
+}
+/**
+ * Prints what the repo has of each piece.
+ * @param statuses - The pieces' statuses.
+ * @param out - Where to write.
+ */
+function printStatus(statuses, out) {
+    const width = Math.max(...statuses.map((status) => status.name.length));
+    out.stdout("This repo has:\n");
+    for (const status of statuses)
+        out.stdout(`  ${status.name.padEnd(width)}  ${status.state}  · ${status.summary}\n`);
+}
+/**
+ * The steps to run: the ticked ones with `--yes`, the picked ones in a terminal, or none.
+ * @param steps - The steps offered.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns The steps, or null if nothing should run.
+ */
+async function chooseSteps(steps, options, out) {
+    if (options.yes)
+        return steps.filter((step) => step.checked);
+    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("")}`);
+        return null;
+    }
+    const picked = await askSteps(steps);
+    if (picked === null)
+        warn(out, "cancelled; nothing changed.");
+    return picked;
+}
+/**
+ * Runs the command; see the file's header.
+ * @param options - The options.
+ * @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)
+ */
+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(", ")}.`);
+    if (options.yes && options.dryRun)
+        throw new UsageError("use --yes or --dry-run, not both.");
+    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));
+    printStatus(statuses, out);
+    const steps = statuses.flatMap((status) => status.steps);
+    if (steps.length === 0) {
+        out.stdout("Nothing to install or update.\n");
+        return 0;
+    }
+    const chosen = await chooseSteps(steps, options, out);
+    if (chosen === null)
+        return options.dryRun || !out.interactive ? 0 : 1;
+    if (chosen.length === 0) {
+        out.stdout("Nothing picked; nothing changed.\n");
+        return 0;
+    }
+    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)
+            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`);
+    return failed.length === 0 ? 0 : 1;
+}

package/dist/menu.d.ts

@@ -0,0 +1,21 @@
+import type { Step } from "./piece.js";
+/**
+ * The menu's options: each step's index and label, which names its piece.
+ * @param steps - The steps.
+ * @returns The options and the ones ticked at the start.
+ * @example menuOptions(steps).initialValues // [0, 1]
+ */
+export declare function menuOptions(steps: Step[]): {
+    options: {
+        value: number;
+        label: string;
+    }[];
+    initialValues: number[];
+};
+/**
+ * Asks which steps to run.
+ * @param steps - The steps.
+ * @returns The picked ones, in their order, or null if the person cancelled.
+ * @example await askSteps(steps)
+ */
+export declare function askSteps(steps: Step[]): Promise<Step[] | null>;

package/dist/menu.js

@@ -0,0 +1,31 @@
+/**
+ * @file The checkbox menu of the steps (`@clack/prompts`): one line per step, the ones a
+ * piece suggests already ticked; space toggles, enter runs (the library shows the keys). It
+ * only runs with a terminal.
+ */
+import { isCancel, multiselect } from "@clack/prompts";
+/**
+ * The menu's options: each step's index and label, which names its piece.
+ * @param steps - The steps.
+ * @returns The options and the ones ticked at the start.
+ * @example menuOptions(steps).initialValues // [0, 1]
+ */
+export function menuOptions(steps) {
+    return {
+        options: steps.map((step, index) => ({ value: index, label: step.label })),
+        initialValues: steps.flatMap((step, index) => (step.checked ? [index] : [])),
+    };
+}
+/**
+ * Asks which steps to run.
+ * @param steps - The steps.
+ * @returns The picked ones, in their order, or null if the person cancelled.
+ * @example await askSteps(steps)
+ */
+export async function askSteps(steps) {
+    const { options, initialValues } = menuOptions(steps);
+    const picked = await multiselect({ message: "What to do?", options, initialValues, required: false });
+    if (isCancel(picked))
+        return null;
+    return steps.filter((_, index) => picked.includes(index));
+}

package/dist/output.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file Where commands write, and the errors that end them. Commands get an `Output`
+ * instead of writing to `process` directly, so the entry point decides about the terminal.
+ */
+/** Usage error: exits 2 and prints the usage text. */
+export declare class UsageError extends Error {
+}
+/** An error of the repo or of a file in it: exits 1 with the message. */
+export declare class KitError extends Error {
+}
+/** Where a command writes, and whether someone can answer a question. */
+export interface Output {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    interactive: boolean;
+}
+/**
+ * The process's output; interactive when both stdin and stdout are a terminal.
+ * @returns The output.
+ * @example processOutput().interactive
+ */
+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")
+ */
+export declare function warn(out: Output, text: string): void;

package/dist/output.js

@@ -0,0 +1,31 @@
+/**
+ * @file Where commands write, and the errors that end them. Commands get an `Output`
+ * instead of writing to `process` directly, so the entry point decides about the terminal.
+ */
+/** Usage error: exits 2 and prints the usage text. */
+export class UsageError extends Error {
+}
+/** An error of the repo or of a file in it: exits 1 with the message. */
+export class KitError extends Error {
+}
+/**
+ * The process's output; interactive when both stdin and stdout are a terminal.
+ * @returns The output.
+ * @example processOutput().interactive
+ */
+export function processOutput() {
+    return {
+        stdout: (text) => process.stdout.write(text),
+        stderr: (text) => process.stderr.write(text),
+        interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    };
+}
+/**
+ * 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")
+ */
+export function warn(out, text) {
+    out.stderr(`agent-kitchen: ${text}\n`);
+}

package/dist/piece.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @file What agent-kitchen knows of each piece it manages, and the names they share. A piece
+ * (the issue flow, claude-cloud, claude-repo-guard, the skills) 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 writes the few lines that join two pieces.
+ */
+import type { Output } from "./output.js";
+/** The issue flow on npm. */
+export declare const FLOW_PACKAGE = "@ramon-sg/issue-flow";
+/** The GitHub repo of the issue flow, which is also the catalog of its skills. */
+export declare const FLOW_CATALOG = "ramon-sg/issue-flow";
+/** The catalogs of general skills, offered next to the flow's. */
+export declare const GENERAL_CATALOGS: string[];
+/** `skills-manager` when the repo does not pin it. */
+export declare const SKILLS_MANAGER = "@ramon-sg/skills-manager";
+/** Where `skills-manager` keeps the repo's skills manifest. */
+export declare const SKILLS_MANIFEST = ".agents/skills.json";
+/** Where `skills-manager` keeps the repo's skills lock. */
+export declare const SKILLS_LOCK = ".agents/skills.lock.json";
+/** The issue flow's config. */
+export declare const FLOW_CONFIG = ".agents/flow.json";
+/** One step a piece offers: what it does, and how it runs. */
+export interface Step {
+    piece: string;
+    label: string;
+    checked: boolean;
+    run: (context: Context) => boolean;
+}
+/** What a piece found in the repo: whether it has it, how it is, and the steps offered. */
+export interface PieceStatus {
+    name: string;
+    summary: string;
+    installed: boolean;
+    state: string;
+    steps: Step[];
+}
+/** What a step gets when it runs. */
+export interface Context {
+    root: string;
+    yes: boolean;
+    out: Output;
+}
+/** One check of `agent-kitchen doctor`: passed, failed, or only worth knowing. */
+export interface Check {
+    name: string;
+    status: "ok" | "fail" | "info";
+    detail: string;
+}

package/dist/piece.js

@@ -0,0 +1,14 @@
+/** The issue flow on npm. */
+export const FLOW_PACKAGE = "@ramon-sg/issue-flow";
+/** The GitHub repo of the issue flow, which is also the catalog of its skills. */
+export const FLOW_CATALOG = "ramon-sg/issue-flow";
+/** The catalogs of general skills, offered next to the flow's. */
+export const GENERAL_CATALOGS = ["ramon-sg/agent-skills"];
+/** `skills-manager` when the repo does not pin it. */
+export const SKILLS_MANAGER = "@ramon-sg/skills-manager";
+/** Where `skills-manager` keeps the repo's skills manifest. */
+export const SKILLS_MANIFEST = ".agents/skills.json";
+/** Where `skills-manager` keeps the repo's skills lock. */
+export const SKILLS_LOCK = ".agents/skills.lock.json";
+/** The issue flow's config. */
+export const FLOW_CONFIG = ".agents/flow.json";

package/dist/pieces/cloud.d.ts

@@ -0,0 +1,17 @@
+import type { Check, PieceStatus } from "../piece.js";
+/** The piece's name, as `--skip` takes it. */
+export declare const NAME = "claude-cloud";
+/**
+ * What the repo has of claude-cloud, and the step it needs.
+ * @param root - The repo.
+ * @returns The piece's status.
+ * @example cloudStatus(root).state // "1.0.0, the latest"
+ */
+export declare function cloudStatus(root: string): PieceStatus;
+/**
+ * Whether `.claude/cloud.json` pins a version, and whether a newer one exists.
+ * @param root - The repo.
+ * @returns The checks.
+ * @example cloudChecks(root)[0].status // "ok"
+ */
+export declare function cloudChecks(root: string): Check[];