agent-kitchen 0.5.0 → 0.7.0

package/dist/texts/es.js

@@ -0,0 +1,139 @@
+/**
+ * A list of names, joined with commas.
+ * @param names - The names.
+ * @returns The list.
+ */
+const list = (names) => names.join(", ");
+/** The texts in Spanish. */
+export const es = {
+    steps: {
+        "skills-manager-create": ({ version }) => ({
+            menu: `Crear package.json con skills-manager ${version}`,
+            doing: `Creando package.json con skills-manager ${version}…`,
+            done: `package.json creado con skills-manager ${version}`,
+        }),
+        "skills-manager-add": ({ version }) => ({
+            menu: `Agregar skills-manager ${version} a package.json`,
+            doing: `Agregando skills-manager ${version} a package.json…`,
+            done: `skills-manager ${version} agregado a package.json`,
+        }),
+        "skills-manager-bump": ({ from, to }) => ({
+            menu: `Subir skills-manager ${from} → ${to}, el mínimo de agent-kitchen`,
+            doing: `Subiendo skills-manager de ${from} a ${to}…`,
+            done: `skills-manager subido de ${from} a ${to}`,
+        }),
+        "flow-install": ({ version }) => ({
+            menu: `Instalar issue-flow ${version}: config del flujo, hooks y scripts`,
+            doing: `Instalando issue-flow ${version}…`,
+            done: `issue-flow ${version} instalado: config del flujo, hooks y scripts`,
+        }),
+        "flow-update": ({ from, to }) => ({
+            menu: `Actualizar issue-flow ${from} → ${to}, con sus hooks y sus skills`,
+            doing: `Actualizando issue-flow de ${from} a ${to}…`,
+            done: `issue-flow actualizado de ${from} a ${to}, con sus hooks y sus skills`,
+        }),
+        "flow-repair": ({ version }) => ({
+            menu: `Reparar issue-flow ${version}: hooks y $schema`,
+            doing: `Reparando issue-flow ${version}…`,
+            done: `issue-flow ${version} reparado: hooks y $schema`,
+        }),
+        "flow-skills": ({ version }) => ({
+            menu: `Poner las skills del flujo en v${version}, la versión de issue-flow`,
+            doing: `Poniendo las skills del flujo en v${version}…`,
+            done: `Skills del flujo en v${version}, la versión de issue-flow`,
+        }),
+        "flow-labels": ({ missing }) => ({
+            menu: `Crear en GitHub los labels que faltan: ${list(missing)}`,
+            doing: `Creando en GitHub los labels que faltan: ${list(missing)}…`,
+            done: `Labels creados en GitHub: ${list(missing)}`,
+        }),
+        "github-rest-bump": ({ from, to, flow }) => ({
+            menu: `Subir github-rest ${from} → ${to}, el mínimo de issue-flow ${flow}`,
+            doing: `Subiendo github-rest de ${from} a ${to}…`,
+            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`,
+        }),
+        "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}`,
+        }),
+        "guard-install": ({ version }) => ({
+            menu: `Instalar claude-repo-guard ${version ?? "(main)"}: modo auto con sandbox, y un documento de qué protege`,
+            doing: `Instalando claude-repo-guard ${version ?? "(main)"}…`,
+            done: `claude-repo-guard ${version ?? "(main)"} instalado: modo auto con sandbox, y un documento de qué protege`,
+        }),
+        "guard-update": ({ from, to }) => ({
+            menu: `Actualizar claude-repo-guard ${from ?? "?"} → ${to}`,
+            doing: `Actualizando claude-repo-guard de ${from ?? "?"} a ${to}…`,
+            done: `claude-repo-guard actualizado de ${from ?? "?"} a ${to}`,
+        }),
+        "guard-adjust": () => ({
+            menu: "Ajustar claude-repo-guard a lo que necesita el flujo de issues",
+            doing: "Ajustando claude-repo-guard al flujo de issues…",
+            done: "claude-repo-guard ajustado a lo que necesita el flujo de issues",
+        }),
+        "skills-install": ({ count, catalogs }) => ({
+            menu: `Instalar ${count} skills de ${catalogs.join(" y ")}`,
+            doing: `Instalando ${count} skills de ${catalogs.join(" y ")}…`,
+            done: `${count} skills instaladas de ${catalogs.join(" y ")}`,
+        }),
+        "skills-update": ({ catalog, from, to, names }) => ({
+            menu: `Actualizar skills de ${catalog} ${from} → v${to}: ${list(names)}`,
+            doing: `Actualizando skills de ${catalog} de ${from} a v${to}…`,
+            done: `Skills de ${catalog} actualizadas a v${to}: ${list(names)}`,
+        }),
+        "skills-add": ({ names }) => ({
+            menu: `Agregar skills nuevas (${names.length}): ${list(names)}`,
+            doing: `Agregando skills nuevas: ${list(names)}…`,
+            done: `Skills nuevas agregadas: ${list(names)}`,
+        }),
+        "agents-md": ({ rule, claudeImport }) => {
+            const files = [...(rule ? ["AGENTS.md"] : []), ...(claudeImport ? ["CLAUDE.md"] : [])].join(", ");
+            if (!rule)
+                return {
+                    menu: `Agregar @AGENTS.md a CLAUDE.md, para que Claude Code lea AGENTS.md: ${files}`,
+                    doing: "Agregando @AGENTS.md a CLAUDE.md…",
+                    done: "@AGENTS.md agregado a CLAUDE.md: Claude Code lee AGENTS.md",
+                };
+            const also = claudeImport ? " (y @AGENTS.md en CLAUDE.md)" : "";
+            return {
+                menu: `Agregar a AGENTS.md la regla de versiones instaladas${also}: ${files}`,
+                doing: `Agregando a AGENTS.md la regla de versiones instaladas${also}…`,
+                done: `Regla de versiones instaladas agregada a AGENTS.md${also}`,
+            };
+        },
+        "install-deps": ({ manager }) => ({
+            menu: `Instalar las dependencias con ${manager}`,
+            doing: `Instalando las dependencias con ${manager}…`,
+            done: `Dependencias instaladas con ${manager}`,
+        }),
+    },
+    fresh: " (nueva)",
+    failed: (menu) => `Falló: ${menu}`,
+    duration: (ms) => {
+        if (ms < 10_000)
+            return `${(ms / 1000).toFixed(1).replace(".", ",")} s`;
+        const seconds = Math.round(ms / 1000);
+        return seconds < 60 ? `${seconds} s` : `${Math.floor(seconds / 60)} min${seconds % 60 === 0 ? "" : ` ${seconds % 60} s`}`;
+    },
+    still: (elapsed) => `  … sigue (${elapsed})`,
+    checking: "Revisando el repo y las últimas versiones…",
+    upToDate: "Todo al día: no hay nada que instalar ni actualizar.",
+    onlyOptional: (menus) => `Todo al día. Opcional, para elegir en una terminal: ${menus.join("; ")}.`,
+    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: (manager) => `Falta: corre '${manager} install', revisa el diff y haz commit.`,
+    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"}.`,
+    noSteps: (why, wrote) => {
+        if (why === "leave")
+            return wrote ? "No corrí ningún paso; solo guardé qué piezas usa el repo." : "No se cambió nada.";
+        return wrote ? "No elegiste pasos; solo guardé qué piezas usa el repo." : "No elegiste nada; no se cambió nada.";
+    },
+};

package/dist/texts/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file The interface's texts, and how a step reads in a list. Another language is a file
+ * like es.ts that implements `Catalog`, chosen here.
+ */
+import type { Step } from "../piece.js";
+import type { Catalog, StepPhrases } from "./catalog.js";
+import type { StepText } from "./step-text.js";
+/** The catalog the interface uses. */
+export declare const ui: Catalog;
+/**
+ * A step's texts in a catalog.
+ * @param catalog - The catalog.
+ * @param text - What the step does.
+ * @returns Its texts.
+ * @example phrasesIn(es, { kind: "guard-adjust" }).doing // "Ajustando claude-repo-guard al flujo de issues…"
+ */
+export declare function phrasesIn(catalog: Catalog, text: StepText): StepPhrases;
+/**
+ * A step's texts in the interface.
+ * @param text - What the step does.
+ * @returns Its texts.
+ */
+export declare function phrases(text: StepText): StepPhrases;
+/**
+ * How a step reads in the menu and in lists: its order, marked if its piece is new.
+ * @param step - The step.
+ * @returns The text.
+ * @example stepLabel(step) // "Actualizar issue-flow 0.2.7 → 0.3.0, con sus hooks y sus skills"
+ */
+export declare function stepLabel(step: Pick<Step, "text" | "fresh">): string;

package/dist/texts/index.js

@@ -0,0 +1,31 @@
+import { es } from "./es.js";
+/** The catalog the interface uses. */
+export const ui = es;
+/**
+ * A step's texts in a catalog.
+ * @param catalog - The catalog.
+ * @param text - What the step does.
+ * @returns Its texts.
+ * @example phrasesIn(es, { kind: "guard-adjust" }).doing // "Ajustando claude-repo-guard al flujo de issues…"
+ */
+export function phrasesIn(catalog, text) {
+    const render = catalog.steps[text.kind];
+    return render(text);
+}
+/**
+ * A step's texts in the interface.
+ * @param text - What the step does.
+ * @returns Its texts.
+ */
+export function phrases(text) {
+    return phrasesIn(ui, text);
+}
+/**
+ * How a step reads in the menu and in lists: its order, marked if its piece is new.
+ * @param step - The step.
+ * @returns The text.
+ * @example stepLabel(step) // "Actualizar issue-flow 0.2.7 → 0.3.0, con sus hooks y sus skills"
+ */
+export function stepLabel(step) {
+    return `${phrases(step.text).menu}${step.fresh === true ? ui.fresh : ""}`;
+}

package/dist/texts/step-text.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @file What a step does, as data: its kind, the piece's versions and what it brings. No
+ * words here; each place that shows a step (the menu, the start and end of its progress, the
+ * commit) turns this into its own text, so the interface can change language without the
+ * commits changing too.
+ */
+/** A version that may be unknown (`null`), shown as `?` or as the place it comes from. */
+type MaybeVersion = string | null;
+/** What a step does, one kind per thing a piece can offer. */
+export type StepText = {
+    kind: "skills-manager-create";
+    version: string;
+} | {
+    kind: "skills-manager-add";
+    version: string;
+} | {
+    kind: "skills-manager-bump";
+    from: string;
+    to: string;
+} | {
+    kind: "flow-install";
+    version: string;
+} | {
+    kind: "flow-update";
+    from: string;
+    to: string;
+} | {
+    kind: "flow-repair";
+    version: string;
+} | {
+    kind: "flow-skills";
+    version: string;
+} | {
+    kind: "flow-labels";
+    missing: string[];
+} | {
+    kind: "github-rest-bump";
+    from: string;
+    to: string;
+    flow: string;
+} | {
+    kind: "cloud-install";
+    version: MaybeVersion;
+} | {
+    kind: "cloud-update";
+    from: MaybeVersion;
+    to: string;
+    config: string;
+} | {
+    kind: "guard-install";
+    version: MaybeVersion;
+} | {
+    kind: "guard-update";
+    from: MaybeVersion;
+    to: string;
+} | {
+    kind: "guard-adjust";
+} | {
+    kind: "skills-install";
+    count: number;
+    catalogs: string[];
+} | {
+    kind: "skills-update";
+    catalog: string;
+    from: string;
+    to: string;
+    names: string[];
+} | {
+    kind: "skills-add";
+    names: string[];
+} | {
+    kind: "agents-md";
+    rule: boolean;
+    claudeImport: boolean;
+} | {
+    kind: "install-deps";
+    manager: string;
+};
+/** The kinds of step. */
+export type StepKind = StepText["kind"];
+/** The data of one kind of step. */
+export type StepOf<K extends StepKind> = Extract<StepText, {
+    kind: K;
+}>;
+export {};

package/dist/texts/step-text.js

@@ -0,0 +1,7 @@
+/**
+ * @file What a step does, as data: its kind, the piece's versions and what it brings. No
+ * words here; each place that shows a step (the menu, the start and end of its progress, the
+ * commit) turns this into its own text, so the interface can change language without the
+ * commits changing too.
+ */
+export {};

package/dist/tools.d.ts

@@ -26,6 +26,13 @@ export declare function isRelease(version: string): boolean;
  * @example await npmLatest("@ramon-sg/claude-cloud") // "1.0.0"
  */
 export declare function npmLatest(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`.
+ * @returns Each dependency's range, or null if npm cannot tell.
+ * @example await npmDependencies("@ramon-sg/issue-flow@0.3.0") // { "@ramon-sg/github-rest": "^0.3.0" }
+ */
+export declare function npmDependencies(spec: string): Promise<Record<string, string> | null>;
 /**
  * The highest `vX.Y.Z` tag of a GitHub repo.
  * @param repo - The repo, as owner/name.
@@ -64,14 +71,38 @@ export declare function runNpx(root: string, args: string[]): Promise<ToolRun>;
  */
 export declare function failedOutput(output: string): string;
 /**
- * Runs `npx --yes <args>` in the repo and returns what it printed on stdout.
+ * Runs `npx --yes <args>` in the repo and returns what it printed.
  * @param root - The repo.
  * @param args - The package and its arguments.
  * @param lookup - True to give up after the lookups' time limit, for a read that only informs.
- * @returns Its stdout and exit code, or null if npx could not start.
+ * @returns Its stdout, stderr and exit code, or null if npx could not start.
  * @example await captureNpx(root, ["@ramon-sg/issue-flow@0.2.0", "doctor", "--json"])
  */
 export declare function captureNpx(root: string, args: string[], lookup?: boolean): Promise<{
     out: string;
+    err: string;
     status: number | null;
 } | null>;
+/**
+ * Runs the repo's package manager's install: quietly, or with its output on the terminal
+ * with `--verbose`.
+ * @param root - The repo.
+ * @param manager - `npm`, `pnpm`, `bun` or `yarn`.
+ * @returns Whether it worked and, if it ran quietly, what it printed.
+ * @example await runInstall(root, "pnpm")
+ */
+export declare function runInstall(root: string, manager: string): Promise<ToolRun>;
+/**
+ * Runs `npx --yes <args>` in the repo without some variables of the environment, and returns
+ * what it printed.
+ * @param root - The repo.
+ * @param args - The package and its arguments.
+ * @param unset - The variables left out.
+ * @returns Its stdout, stderr and exit code.
+ * @example await captureNpxWithout(root, ["@ramon-sg/github-rest@0.3.0", "pr", "create"], ["GH_REPO"])
+ */
+export declare function captureNpxWithout(root: string, args: string[], unset: string[]): Promise<{
+    out: string;
+    err: string;
+    status: number | null;
+}>;

package/dist/tools.js

@@ -1,7 +1,7 @@
 /**
  * @file How agent-kitchen reaches the other tools and their releases: `npx` to run them (always
  * by their scoped name or GitHub spec, because the unscoped names on npm belong to other
- * people), `npm view` for the latest version on npm, and `git ls-remote` for the latest
+ * people), `npm view` for the latest version on npm and a version's dependencies, and `git ls-remote` for the latest
  * `vX.Y.Z` tag on GitHub. Everything is asynchronous so the lookups run at the same time,
  * and each lookup runs once per process. A lookup that fails, or takes over 20 seconds,
  * gives null: the piece is shown, not offered. git never asks for credentials here.
@@ -67,7 +67,10 @@ export function isRelease(version) {
  */
 function run(program, args, options = {}) {
     return new Promise((resolve) => {
-        const child = spawn(program, args, { cwd: options.cwd, env: { ...process.env, ...options.env }, stdio: options.inherit === true ? "inherit" : ["ignore", "pipe", "pipe"] });
+        const env = { ...process.env, ...options.env };
+        for (const name of options.unset ?? [])
+            delete env[name];
+        const child = spawn(program, args, { cwd: options.cwd, env, stdio: options.inherit === true ? "inherit" : ["ignore", "pipe", "pipe"] });
         let out = "";
         let err = "";
         child.stdout?.on("data", (chunk) => (out += chunk.toString()));
@@ -108,6 +111,26 @@ export function npmLatest(name) {
         return isRelease(version) ? version : null;
     });
 }
+/**
+ * The dependencies a version of a package declares on npm.
+ * @param spec - The package and its version, as `name@x.y.z`.
+ * @returns Each dependency's range, or null if npm cannot tell.
+ * @example await npmDependencies("@ramon-sg/issue-flow@0.3.0") // { "@ramon-sg/github-rest": "^0.3.0" }
+ */
+export function npmDependencies(spec) {
+    return once(`npm-deps:${spec}`, async () => {
+        const result = await run("npm", ["view", spec, "dependencies", "--json", "--fetch-retries=0"], { timeout: LOOKUP_TIMEOUT_MS });
+        if (result.status !== 0)
+            return null;
+        try {
+            const found = JSON.parse(result.out);
+            return typeof found === "object" && found !== null && !Array.isArray(found) ? found : null;
+        }
+        catch {
+            return null;
+        }
+    });
+}
 /**
  * The highest `vX.Y.Z` tag of a GitHub repo.
  * @param repo - The repo, as owner/name.
@@ -162,14 +185,38 @@ export function failedOutput(output) {
     return lines.slice(-FAILED_LINES).map((line) => `    ${line}\n`).join("");
 }
 /**
- * Runs `npx --yes <args>` in the repo and returns what it printed on stdout.
+ * Runs `npx --yes <args>` in the repo and returns what it printed.
  * @param root - The repo.
  * @param args - The package and its arguments.
  * @param lookup - True to give up after the lookups' time limit, for a read that only informs.
- * @returns Its stdout and exit code, or null if npx could not start.
+ * @returns Its stdout, stderr and exit code, or null if npx could not start.
  * @example await captureNpx(root, ["@ramon-sg/issue-flow@0.2.0", "doctor", "--json"])
  */
 export async function captureNpx(root, args, lookup = false) {
     const result = await run("npx", ["--yes", ...args], { cwd: root, ...(lookup ? { timeout: LOOKUP_TIMEOUT_MS } : {}) });
-    return result.status === null && result.out === "" ? null : { out: result.out, status: result.status };
+    return result.status === null && result.out === "" ? null : { out: result.out, err: result.err, status: result.status };
+}
+/**
+ * Runs the repo's package manager's install: quietly, or with its output on the terminal
+ * with `--verbose`.
+ * @param root - The repo.
+ * @param manager - `npm`, `pnpm`, `bun` or `yarn`.
+ * @returns Whether it worked and, if it ran quietly, what it printed.
+ * @example await runInstall(root, "pnpm")
+ */
+export async function runInstall(root, manager) {
+    const result = await run(manager, ["install"], { cwd: root, inherit: verbose });
+    return { ok: result.status === 0, output: `${result.out}${result.err}` };
+}
+/**
+ * Runs `npx --yes <args>` in the repo without some variables of the environment, and returns
+ * what it printed.
+ * @param root - The repo.
+ * @param args - The package and its arguments.
+ * @param unset - The variables left out.
+ * @returns Its stdout, stderr and exit code.
+ * @example await captureNpxWithout(root, ["@ramon-sg/github-rest@0.3.0", "pr", "create"], ["GH_REPO"])
+ */
+export async function captureNpxWithout(root, args, unset) {
+    return run("npx", ["--yes", ...args], { cwd: root, unset });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-kitchen",
-  "version": "0.5.0",
+  "version": "0.7.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",