agent-kitchen 0.0.0-stage → 0.3.0

package/dist/menu.js

@@ -0,0 +1,100 @@
+/**
+ * @file The questions, in Spanish (`@clack/prompts`), all asked before any step runs: the
+ * quick path (do everything suggested, pick, or leave), the checkbox menu of the steps, the
+ * skills of a step grouped by catalog with their description, and whether to replace the
+ * repo's own skills. They only run with a terminal.
+ */
+import { styleText } from "node:util";
+import { confirm, groupMultiselect, isCancel, MULTISELECT_INSTRUCTIONS, multiselect, select, SELECT_INSTRUCTIONS } from "@clack/prompts";
+/** Width a skill's description is cut to in the menu. */
+const DESCRIPTION_WIDTH = 70;
+/**
+ * Puts the keys' help of the menus in Spanish. The library exports those lines as arrays,
+ * so they are replaced in place.
+ */
+function spanishKeys() {
+    MULTISELECT_INSTRUCTIONS.splice(0, MULTISELECT_INSTRUCTIONS.length, `${styleText("dim", "↑/↓")} moverse`, `${styleText("dim", "Espacio:")} marcar`, `${styleText("dim", "Enter:")} seguir`);
+    SELECT_INSTRUCTIONS.splice(0, SELECT_INSTRUCTIONS.length, `${styleText("dim", "↑/↓")} moverse`, `${styleText("dim", "Enter:")} elegir`);
+}
+/**
+ * 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] : [])),
+    };
+}
+/**
+ * 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 function skillOptions(candidates) {
+    const groups = {};
+    for (const candidate of candidates) {
+        const hint = candidate.description.length > DESCRIPTION_WIDTH ? `${candidate.description.slice(0, DESCRIPTION_WIDTH - 1)}…` : candidate.description;
+        const group = candidate.catalog === "" ? "skills" : candidate.catalog;
+        groups[group] = [...(groups[group] ?? []), { value: candidate.id, label: candidate.name, ...(hint === "" ? {} : { hint }) }];
+    }
+    return groups;
+}
+/**
+ * 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 async function askPath(count) {
+    spanishKeys();
+    const all = { value: "all", label: `Todo lo sugerido (${count} ${count === 1 ? "paso" : "pasos"})`, hint: "recomendado" };
+    const answer = await select({
+        message: "¿Qué hago?",
+        options: [...(count === 0 ? [] : [all]), { value: "pick", label: "Elegir qué hacer" }, { value: "leave", label: "Salir sin cambiar nada" }],
+    });
+    return isCancel(answer) ? "leave" : answer;
+}
+/**
+ * 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) {
+    spanishKeys();
+    const { options, initialValues } = menuOptions(steps);
+    const picked = await multiselect({ message: "¿Qué pasos hago?", options, initialValues, required: false });
+    if (isCancel(picked))
+        return null;
+    return steps.filter((_, index) => picked.includes(index));
+}
+/**
+ * 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 async function askSkills(candidates, ticked) {
+    spanishKeys();
+    const picked = await groupMultiselect({ message: "¿Qué skills instalo?", options: skillOptions(candidates), initialValues: ticked, required: false });
+    return isCancel(picked) ? null : picked;
+}
+/**
+ * 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 async function askReplace(own) {
+    const answer = await confirm({
+        message: `El repo ya tiene su propia versión de: ${own.join(", ")}. ¿Las reemplazo por las del catálogo? Su project.md se conserva.`,
+        active: "Sí, reemplazar",
+        inactive: "No, dejarlas fuera",
+    });
+    return isCancel(answer) ? null : answer;
+}

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,69 @@
+/**
+ * @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.
+ */
+/** 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";
+/** A skill a catalog offers, as `skills-manager --candidates` lists it. */
+export interface Candidate {
+    id: string;
+    name: string;
+    catalog: string;
+    description: string;
+    skills: string[];
+    requires: string[];
+}
+/** The skills a step installs: what it offers, and what the person picked and lets it replace. */
+export interface SkillPick {
+    candidates: Candidate[];
+    picked: string[];
+    replace: string[];
+}
+/** One step a piece offers: what it does, what it downloads, and how it runs. */
+export interface Step {
+    piece: string;
+    label: string;
+    checked: boolean;
+    downloads: string[];
+    skills?: SkillPick;
+    run: (context: Context) => Promise<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: the repo, and where to say what it did (`note`, one short
+ * line under the step) or what went wrong (`fail`, with the command to run by hand and the
+ * tool's output).
+ */
+export interface Context {
+    root: string;
+    note: (text: string) => void;
+    fail: (text: string, output?: string) => void;
+}
+/** 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,21 @@
+/**
+ * @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.
+ */
+/** 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,26 @@
+/**
+ * @file Claude cloud sessions (`@ramon-sg/claude-cloud`). 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.
+ */
+import type { Check, PieceStatus } from "../piece.js";
+/** The piece's name, as `--skip` takes it. */
+export declare const NAME = "claude-cloud";
+/** The package on npm. */
+export declare const PACKAGE = "@ramon-sg/claude-cloud";
+/**
+ * What the repo has of claude-cloud, 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 declare function cloudStatus(root: string): Promise<PieceStatus>;
+/**
+ * Whether `.claude/cloud.json` pins a version, and whether a newer one exists.
+ * @param root - The repo.
+ * @returns The checks.
+ * @example (await cloudChecks(root))[0].status // "ok"
+ */
+export declare function cloudChecks(root: string): Promise<Check[]>;

package/dist/pieces/cloud.js

@@ -0,0 +1,88 @@
+import { readJson, writeJson } from "../repo.js";
+import { compareVersions, isRelease, npmLatest, runNpx } from "../tools.js";
+/** The piece's name, as `--skip` takes it. */
+export const NAME = "claude-cloud";
+/** The package on npm. */
+export const PACKAGE = "@ramon-sg/claude-cloud";
+/** Its config in the repo, which pins its version. */
+const CONFIG = ".claude/cloud.json";
+/**
+ * The version `.claude/cloud.json` pins.
+ * @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;
+}
+/**
+ * The step the repo needs, if any.
+ * @param config - The config, or null.
+ * @param latest - The latest on npm, or null.
+ * @returns The step, or null.
+ */
+function stepFor(config, latest) {
+    const version = pinned(config);
+    if (config === null) {
+        const spec = `${PACKAGE}@${latest ?? "1"}`;
+        return {
+            piece: NAME,
+            checked: true,
+            downloads: [spec],
+            label: `Instalar claude-cloud ${latest ?? "1.x"}: prepara las sesiones en la nube de Claude`,
+            run: async (context) => {
+                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);
+                return false;
+            },
+        };
+    }
+    if (latest === null || (version !== null && compareVersions(latest, version) <= 0))
+        return null;
+    return {
+        piece: NAME,
+        checked: true,
+        downloads: [],
+        label: `Actualizar claude-cloud ${version ?? "?"} → ${latest} (la versión que fija ${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;
+            writeJson(context.root, CONFIG, { ...current, ...(schema === undefined ? {} : { $schema: schema }), version: latest });
+            return true;
+        },
+    };
+}
+/**
+ * What the repo has of claude-cloud, 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 version = pinned(config);
+    const step = stepFor(config, latest);
+    const known = latest === null ? " (npm no responde)" : "";
+    const state = config === null ? `no instalado${known}` : version === null ? `${CONFIG} no fija versión` : step === null ? `${version}, al día${known}` : `${version}, hay ${latest ?? "?"}`;
+    return { name: NAME, summary: "sesiones en la nube de Claude", installed: config !== null, state, steps: step === null ? [] : [step] };
+}
+/**
+ * Whether `.claude/cloud.json` pins a version, and whether a newer one exists.
+ * @param root - The repo.
+ * @returns The checks.
+ * @example (await cloudChecks(root))[0].status // "ok"
+ */
+export async function cloudChecks(root) {
+    const config = readJson(root, CONFIG);
+    if (config === null)
+        return [{ name: NAME, status: "info", detail: "no instalado" }];
+    const version = pinned(config);
+    const latest = await npmLatest(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)
+        return [{ name: NAME, status: "info", detail: `${version}, hay ${latest}: corre npx agent-kitchen` }];
+    return [{ name: NAME, status: "ok", detail: version }];
+}

package/dist/pieces/guard.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file The guardrails (`claude-repo-guard`): auto mode with the sandbox, installed in the
+ * repo. It is not on npm, so it runs from GitHub at its `vX.Y.Z` tag; the repo's version is
+ * the one its manifest records. Before installing or updating, agent-kitchen writes in its
+ * options what the issue flow needs, if the repo has the flow: the auto mode is told that
+ * the flow's writes are normal, the flow's base branch becomes `integrationBranch`, and on
+ * macOS `weakerNetworkIsolation` lets `gh` work inside the sandbox (the guard's own default
+ * is false, so false counts as missing; the step can be unticked). When the flow is
+ * installed in the same run, the guard gets those options in that run too.
+ */
+import { type Check, type PieceStatus } from "../piece.js";
+/** The piece's name, as `--skip` takes it. */
+export declare const NAME = "claude-repo-guard";
+/** Its GitHub repo. */
+export declare const REPO = "ramon-sg/claude-repo-guard";
+/** What the auto mode is told about the issue flow. */
+export declare const GUARD_ENVIRONMENT = "issue-flow is this repo's issue workflow: making the branch and worktree of an issue, its empty start commit, pushing it, opening its draft PR, assigning the issue and adding its \"Slug de rama\" block are normal steps of the work, not risky actions.";
+/** The option that lets `gh` verify TLS inside the macOS sandbox. */
+export declare const WEAKER_NETWORK = "weakerNetworkIsolation";
+/**
+ * The npx spec of a version.
+ * @param version - The version, or null for the default branch.
+ * @returns The spec.
+ * @example guardSpec("0.2.0") // "github:ramon-sg/claude-repo-guard#v0.2.0"
+ */
+export declare function guardSpec(version: string | null): string;
+/**
+ * The guard's options with what the flow needs added; what the repo set stays.
+ * @param root - The repo.
+ * @param platform - The operating system (`process.platform`).
+ * @returns The new options and what changed.
+ * @example guardOptions(root, "darwin").changes // ["weakerNetworkIsolation activado, …"]
+ */
+export declare function guardOptions(root: string, platform: string): {
+    options: Record<string, unknown>;
+    changes: string[];
+};
+/**
+ * What the repo has of claude-repo-guard, and the step it needs.
+ * @param root - The repo.
+ * @param flowComing - Whether an earlier step of this run installs the issue flow.
+ * @returns The piece's status.
+ * @example (await guardStatus(root, false)).state // "no instalado"
+ */
+export declare function guardStatus(root: string, flowComing: boolean): Promise<PieceStatus>;
+/**
+ * The guard's own doctor at the repo's version and, on macOS, the option `gh` needs.
+ * @param root - The repo.
+ * @returns The checks.
+ * @example (await guardChecks(root)).map((check) => check.status) // ["ok"]
+ */
+export declare function guardChecks(root: string): Promise<Check[]>;

package/dist/pieces/guard.js

@@ -0,0 +1,165 @@
+/**
+ * @file The guardrails (`claude-repo-guard`): auto mode with the sandbox, installed in the
+ * repo. It is not on npm, so it runs from GitHub at its `vX.Y.Z` tag; the repo's version is
+ * the one its manifest records. Before installing or updating, agent-kitchen writes in its
+ * options what the issue flow needs, if the repo has the flow: the auto mode is told that
+ * the flow's writes are normal, the flow's base branch becomes `integrationBranch`, and on
+ * macOS `weakerNetworkIsolation` lets `gh` work inside the sandbox (the guard's own default
+ * is false, so false counts as missing; the step can be unticked). When the flow is
+ * installed in the same run, the guard gets those options in that run too.
+ */
+import { FLOW_CONFIG } from "../piece.js";
+import { readJson, writeJson } from "../repo.js";
+import { captureNpx, compareVersions, isRelease, latestTag, runNpx } from "../tools.js";
+/** The piece's name, as `--skip` takes it. */
+export const NAME = "claude-repo-guard";
+/** Its GitHub repo. */
+export const REPO = "ramon-sg/claude-repo-guard";
+/** Its options in the repo. */
+const CONFIG = ".claude/repo-guard.config.json";
+/** What its install records, with its version. */
+const MANIFEST = ".claude/repo-guard.manifest.json";
+/** What the auto mode is told about the issue flow. */
+export const GUARD_ENVIRONMENT = "issue-flow is this repo's issue workflow: making the branch and worktree of an issue, its empty start commit, pushing it, opening its draft PR, assigning the issue and adding its \"Slug de rama\" block are normal steps of the work, not risky actions.";
+/** The option that lets `gh` verify TLS inside the macOS sandbox. */
+export const WEAKER_NETWORK = "weakerNetworkIsolation";
+/**
+ * The npx spec of a version.
+ * @param version - The version, or null for the default branch.
+ * @returns The spec.
+ * @example guardSpec("0.2.0") // "github:ramon-sg/claude-repo-guard#v0.2.0"
+ */
+export function guardSpec(version) {
+    return version === null ? `github:${REPO}` : `github:${REPO}#v${version}`;
+}
+/**
+ * The guard's options with what the flow needs added; what the repo set stays.
+ * @param root - The repo.
+ * @param platform - The operating system (`process.platform`).
+ * @returns The new options and what changed.
+ * @example guardOptions(root, "darwin").changes // ["weakerNetworkIsolation activado, …"]
+ */
+export function guardOptions(root, platform) {
+    const options = { ...(readJson(root, CONFIG) ?? {}) };
+    const changes = [];
+    const flow = readJson(root, FLOW_CONFIG);
+    const environment = Array.isArray(options.environment) ? options.environment.map(String) : [];
+    if (flow !== null && !environment.includes(GUARD_ENVIRONMENT)) {
+        options.environment = [...environment, GUARD_ENVIRONMENT];
+        changes.push("le explica el flujo de issues al modo auto");
+    }
+    const baseBranch = typeof flow?.baseBranch === "string" ? flow.baseBranch : null;
+    if (baseBranch !== null && (options.integrationBranch === undefined || options.integrationBranch === "")) {
+        options.integrationBranch = baseBranch;
+        changes.push(`rama de integración ${baseBranch}`);
+    }
+    if (platform === "darwin" && options[WEAKER_NETWORK] !== true) {
+        options[WEAKER_NETWORK] = true;
+        changes.push(`${WEAKER_NETWORK} activado, para que gh funcione en el sandbox de macOS`);
+    }
+    return { options, changes };
+}
+/**
+ * Writes the flow's options and installs the guard at a version.
+ * @param context - Where it runs.
+ * @param version - The version, or null for the default branch.
+ * @returns Whether it installed.
+ */
+async function install(context, version) {
+    const { options, changes } = guardOptions(context.root, process.platform);
+    if (changes.length > 0)
+        writeJson(context.root, CONFIG, options);
+    for (const change of changes)
+        context.note(change);
+    const run = await runNpx(context.root, [guardSpec(version), "install", "--yes"]);
+    if (run.ok)
+        return true;
+    context.fail(`claude-repo-guard no se instaló; corre 'npx ${guardSpec(version)} install' desde tu terminal (dentro de una sesión de Claude su sandbox bloquea .claude/settings.json).`, run.output);
+    return false;
+}
+/**
+ * Writes the flow's options and reinstalls the guard at its version, if they are missing
+ * by now (the flow may have been installed earlier in this run).
+ * @param context - Where it runs.
+ * @param version - The guard's version, or null.
+ * @returns Whether it worked, or true if nothing was missing.
+ */
+async function addOptions(context, version) {
+    if (guardOptions(context.root, process.platform).changes.length > 0)
+        return install(context, version);
+    context.note("sus opciones ya tienen lo que necesita el flujo");
+    return true;
+}
+/**
+ * The version its manifest records.
+ * @param root - The repo.
+ * @returns The version, null if it records none, or undefined if it is not installed.
+ */
+function installedVersion(root) {
+    const manifest = readJson(root, MANIFEST);
+    if (manifest === null)
+        return undefined;
+    return typeof manifest.version === "string" && isRelease(manifest.version) ? manifest.version : null;
+}
+/**
+ * The step the repo needs, if any.
+ * @param root - The repo.
+ * @param installed - The repo's version, null if unknown, undefined if not installed.
+ * @param latest - The latest tag, or null.
+ * @returns The step, or null.
+ */
+function stepFor(root, installed, latest, flowComing) {
+    if (installed === undefined)
+        return { piece: NAME, checked: true, downloads: [guardSpec(latest)], label: `Instalar claude-repo-guard ${latest ?? "(main)"}: modo auto con sandbox, y un documento de qué protege`, run: (context) => install(context, latest) };
+    if (latest !== null && (installed === null || compareVersions(latest, installed) > 0))
+        return { piece: NAME, checked: true, downloads: [guardSpec(latest)], label: `Actualizar claude-repo-guard ${installed ?? "?"} → ${latest}`, run: (context) => install(context, latest) };
+    if (flowComing || guardOptions(root, process.platform).changes.length > 0)
+        return { piece: NAME, checked: true, downloads: [guardSpec(installed)], label: "Ajustar claude-repo-guard a lo que necesita el flujo de issues", run: (context) => addOptions(context, installed) };
+    return null;
+}
+/**
+ * What the repo has of claude-repo-guard, and the step it needs.
+ * @param root - The repo.
+ * @param flowComing - Whether an earlier step of this run installs the issue flow.
+ * @returns The piece's status.
+ * @example (await guardStatus(root, false)).state // "no instalado"
+ */
+export async function guardStatus(root, flowComing) {
+    const installed = installedVersion(root);
+    const latest = await latestTag(REPO);
+    const known = latest === null ? " (GitHub no tiene una versión)" : "";
+    const state = installed === undefined ? `no instalado${known}` : latest !== null && (installed === null || compareVersions(latest, installed) > 0) ? `${installed ?? "versión desconocida"}, hay ${latest}` : `${installed ?? "versión desconocida"}, al día${known}`;
+    const step = stepFor(root, installed, latest, flowComing);
+    return { name: NAME, summary: "barandas: modo auto con sandbox", installed: installed !== undefined, state, steps: step === null ? [] : [step] };
+}
+/**
+ * The guard's own doctor at the repo's version and, on macOS, the option `gh` needs.
+ * @param root - The repo.
+ * @returns The checks.
+ * @example (await guardChecks(root)).map((check) => check.status) // ["ok"]
+ */
+export async function guardChecks(root) {
+    const installed = installedVersion(root);
+    if (installed === undefined)
+        return [{ name: NAME, status: "info", detail: "no instalado (Claude se abre con tus propios permisos)" }];
+    const checks = [];
+    if (process.platform === "darwin" && readJson(root, CONFIG)?.[WEAKER_NETWORK] !== true)
+        checks.push({ name: `${NAME}: ${WEAKER_NETWORK}`, status: "fail", detail: `no está activado en ${CONFIG}, así que gh falla en el sandbox de macOS: corre npx agent-kitchen` });
+    const result = await captureNpx(root, [guardSpec(installed), "doctor", "--json"]);
+    let found;
+    try {
+        found = JSON.parse(result?.out ?? "");
+    }
+    catch {
+        found = null;
+    }
+    if (!Array.isArray(found))
+        return [...checks, { name: NAME, status: "fail", detail: `no se pudo correr su doctor; corre 'npx ${guardSpec(installed)} doctor'` }];
+    const bad = found.filter((check) => typeof check !== "object" || check === null || check.ok !== true);
+    if (bad.length === 0)
+        return [...checks, { name: NAME, status: "ok", detail: `${installed ?? "versión desconocida"}, su doctor pasa` }];
+    return [...checks, ...bad.map((check) => {
+            const entry = typeof check === "object" && check !== null ? check : { name: "?", detail: String(check) };
+            return { name: `${NAME}: ${String(entry.name)}`, status: "fail", detail: String(entry.detail) };
+        })];
+}

package/dist/pieces/issue-flow.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file The issue flow (`@ramon-sg/issue-flow`): its CLI, hooks and config, and its skills.
+ * The repo's version is the one in package.json. Installing runs its `init` at the latest
+ * version; updating runs its `upgrade` at the new one and then moves its skills to the same
+ * tag, because the skills call the CLI. If only the skills are off, it moves them alone.
+ * `init` runs with `--yes`: the person answered agent-kitchen's questions before the steps.
+ */
+import { type Check, type PieceStatus } from "../piece.js";
+/** The piece's name, as `--skip` takes it. */
+export declare const NAME = "issue-flow";
+/**
+ * The issue flow's version in the repo, as package.json has it: an exact release when the
+ * flow set it up, or anything else (a range, a `file:` link) someone wrote by hand.
+ * @param root - The repo.
+ * @returns The version in package.json, or null.
+ * @example flowVersion(root) // "0.2.0"
+ */
+export declare function flowSpec(root: string): string | null;
+/**
+ * The issue flow's release in the repo: what package.json pins, if it is an exact release.
+ * @param root - The repo.
+ * @returns The version, or null if there is none or it is not a release.
+ * @example flowVersion(root) // "0.2.0"
+ */
+export declare function flowVersion(root: string): string | null;
+/**
+ * What the repo has of the issue flow, and the step it needs.
+ * @param root - The repo.
+ * @returns The piece's status.
+ * @example (await issueFlowStatus(root)).state // "0.1.0, hay 0.2.0"
+ */
+export declare function issueFlowStatus(root: string): Promise<PieceStatus>;
+/**
+ * The flow's own doctor at the repo's version, and whether its skills are at that tag.
+ * @param root - The repo.
+ * @returns The checks.
+ * @example (await issueFlowChecks(root))[0].name // "issue-flow: .agents/flow.json"
+ */
+export declare function issueFlowChecks(root: string): Promise<Check[]>;