agent-kitchen 0.5.0 → 0.6.0

package/dist/decisions.js

@@ -0,0 +1,91 @@
+/**
+ * @file What the repo wants of each piece, kept in `.agents/kitchen.json`: `true` to have it,
+ * `false` to leave it out for good. Only the pieces that are a choice carry a decision;
+ * `skills-manager` does not, because it is the tool that installs the others' skills and is
+ * always kept up to date, never opted in or out.
+ */
+import { isObject, readJson, writeJson } from "./repo.js";
+import { NAME as AGENTS_MD } from "./pieces/agents-md.js";
+import { NAME as CLOUD } from "./pieces/cloud.js";
+import { NAME as GUARD } from "./pieces/guard.js";
+import { NAME as ISSUE_FLOW } from "./pieces/issue-flow.js";
+import { NAME as SKILLS } from "./pieces/skills.js";
+/** The file with the decisions, relative to the repo. */
+export const DECISIONS = ".agents/kitchen.json";
+/** The pieces a repo can decide on, in the order sync runs them. */
+export const DECIDABLE = [ISSUE_FLOW, CLOUD, GUARD, SKILLS, AGENTS_MD];
+/**
+ * Reads the decisions of a repo.
+ * @param root - The repo.
+ * @returns The decisions, or null if the file does not exist.
+ * @throws KitError if the file is not valid JSON.
+ * @example readDecisions(root)?.pieces // { "claude-repo-guard": false }
+ */
+export function readDecisions(root) {
+    const raw = readJson(root, DECISIONS);
+    if (raw === null)
+        return null;
+    const stored = isObject(raw.pieces) ? raw.pieces : {};
+    const pieces = {};
+    const warnings = [];
+    for (const name of DECIDABLE) {
+        if (!(name in stored))
+            continue;
+        const value = stored[name];
+        if (typeof value === "boolean")
+            pieces[name] = value;
+        else
+            warnings.push(`${DECISIONS}: "${name}" no es true ni false; se trata como sin decisión.`);
+    }
+    return { pieces, raw, warnings };
+}
+/**
+ * The decidable pieces with no decision yet.
+ * @param saved - What was read, or null if there is no file.
+ * @returns Their names; all of them without a file.
+ * @example undecided(null) // ["issue-flow", "claude-cloud", ...]
+ */
+export function undecided(saved) {
+    return DECIDABLE.filter((name) => saved?.pieces[name] === undefined);
+}
+/**
+ * The pieces the repo decided not to have.
+ * @param saved - What was read, or null if there is no file.
+ * @returns Their names.
+ * @example off({ pieces: { skills: false }, raw: {}, warnings: [] }) // ["skills"]
+ */
+export function off(saved) {
+    return DECIDABLE.filter((name) => saved?.pieces[name] === false);
+}
+/**
+ * Settles the pieces that have no decision from what the repo has and what was chosen.
+ * @param statuses - What each piece found.
+ * @param chosen - The steps the user picked.
+ * @param previous - The decisions already made; they never change here.
+ * @returns `previous` plus a decision for each decidable piece without one: installed or
+ * with a chosen step is true, offered steps all unchosen is false, no steps leaves it open.
+ * @example decide([{ name: "skills", installed: true, summary: "", state: "", steps: [] }], [], {}) // { skills: true }
+ */
+export function decide(statuses, chosen, previous) {
+    const result = { ...previous };
+    for (const status of statuses) {
+        if (!DECIDABLE.includes(status.name) || status.name in previous)
+            continue;
+        if (status.installed || chosen.some((step) => step.piece === status.name))
+            result[status.name] = true;
+        else if (status.steps.length > 0)
+            result[status.name] = false;
+    }
+    return result;
+}
+/**
+ * Writes the decisions, keeping every other key of the file.
+ * @param root - The repo.
+ * @param pieces - The decisions to write.
+ * @param raw - The whole file as it was read (empty if there was none).
+ * @example writeDecisions(root, { "issue-flow": true }, {})
+ */
+export function writeDecisions(root, pieces, raw) {
+    const rawPieces = isObject(raw.pieces) ? raw.pieces : {};
+    writeJson(root, DECISIONS, { ...raw, pieces: { ...rawPieces, ...pieces } });
+}

package/dist/git-finish.d.ts

@@ -0,0 +1,53 @@
+/** What to do with the changes: leave them, commit on the base, on a branch, or a branch with a PR. */
+export type FinishChoice = "leave" | "base" | "branch" | "pr";
+/**
+ * The base branch, as issue-flow takes it: `baseBranch` of `.agents/flow.json`, or origin's
+ * default as git knows it, or `main`.
+ * @param root - The repo.
+ * @returns The branch.
+ * @example baseBranch(root) // "main"
+ */
+export declare function baseBranch(root: string): string;
+/**
+ * The files that differ from HEAD, tracked or not, one by one, without the repo's worktrees.
+ * @param root - The repo.
+ * @returns Their paths.
+ * @example changedPaths(root) // ["package.json", "package-lock.json"]
+ */
+export declare function changedPaths(root: string): string[];
+/**
+ * Checks, before any step, that the repo has no changes and is on its base branch.
+ * @param root - The repo.
+ * @param base - The base branch.
+ * @throws KitError saying what is wrong and what to do.
+ */
+export declare function checkReady(root: string, base: string): void;
+/**
+ * The branch for today's changes: a new name, also against origin's branches git knows of.
+ * @param root - The repo.
+ * @param date - Today.
+ * @returns `chore/agent-kitchen-apply-AAAA-MM-DD`, or with `-2`, `-3`… if taken.
+ * @example branchName(root, new Date()) // "chore/agent-kitchen-apply-2026-11-01"
+ */
+export declare function branchName(root: string, date: Date): string;
+/** What `finish` needs to know. */
+export interface FinishOptions {
+    base: string;
+    branch: string;
+    steps: string[];
+    paths: string[];
+    manager: string;
+    packageChanged?: boolean;
+}
+/**
+ * Does what the person chose with the changes.
+ * @param root - The repo, on the base, with the changes of the run.
+ * @param choice - What to do.
+ * @param options - The base, the new branch's name, the steps that ran, the files to commit (the ones shown), the package manager and whether package.json changed.
+ * @returns The lines to show and whether it all worked.
+ * @example await finish(root, "pr", { base: "main", branch: "chore/agent-kitchen-apply-2026-11-01", steps, manager: "npm" })
+ */
+export declare function finish(root: string, choice: FinishChoice, options: FinishOptions): Promise<{
+    ok: boolean;
+    lines: string[];
+}>;

package/dist/git-finish.js

@@ -0,0 +1,253 @@
+/**
+ * @file What `apply --commit` does with git: before any step, it checks that the repo has no
+ * changes (the repo's worktrees under it do not count) and is on its base branch; after the
+ * steps, it commits what changed where the person chose. A new branch is made by passing
+ * through it for the length of the command: `git switch -c`, the commit there (so a hook that
+ * forbids commits on the base does not stop it), the push and the PR if asked, and back to
+ * the base, which never moves. git runs its hooks; nothing here skips them.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { KitError } from "./output.js";
+import { FLOW_CONFIG } from "./piece.js";
+import { dependencyVersion, readJson } from "./repo.js";
+import { captureNpxWithout, isRelease, npmLatest } from "./tools.js";
+/** The subject of the commit and the title of the PR. */
+const TITLE = "chore: agent-kitchen apply";
+/** github-rest on npm, which opens the PR (REST, never gh's GraphQL). */
+const GITHUB_REST = "@ramon-sg/github-rest";
+/**
+ * Runs git in the repo.
+ * @param root - The repo.
+ * @param args - The arguments.
+ * @param inherit - True to show its output on the terminal, for a push that may ask for credentials.
+ * @returns How it went.
+ */
+function git(root, args, inherit = false) {
+    const result = spawnSync("git", args, { cwd: root, encoding: "utf8", stdio: inherit ? "inherit" : "pipe" });
+    return { ok: result.status === 0, out: (result.stdout ?? "").trimEnd(), err: (result.stderr ?? "").trim() };
+}
+/**
+ * The base branch, as issue-flow takes it: `baseBranch` of `.agents/flow.json`, or origin's
+ * default as git knows it, or `main`.
+ * @param root - The repo.
+ * @returns The branch.
+ * @example baseBranch(root) // "main"
+ */
+export function baseBranch(root) {
+    const flow = readJson(root, FLOW_CONFIG);
+    if (typeof flow?.baseBranch === "string" && flow.baseBranch !== "")
+        return flow.baseBranch;
+    const head = git(root, ["symbolic-ref", "-q", "--short", "refs/remotes/origin/HEAD"]);
+    return head.ok && head.out.startsWith("origin/") ? head.out.slice("origin/".length) : "main";
+}
+/**
+ * The repo's other worktrees that live inside it, relative to it.
+ * @param root - The repo.
+ * @returns Their folders, like `.claude/worktrees/feat+1-x`.
+ */
+function innerWorktrees(root) {
+    const list = git(root, ["worktree", "list", "--porcelain"]);
+    if (!list.ok)
+        return [];
+    return list.out
+        .split("\n")
+        .filter((line) => line.startsWith("worktree "))
+        .map((line) => relative(root, line.slice("worktree ".length)))
+        .filter((path) => path !== "" && !path.startsWith(".."));
+}
+/**
+ * The files that differ from HEAD, tracked or not, one by one, without the repo's worktrees.
+ * @param root - The repo.
+ * @returns Their paths.
+ * @example changedPaths(root) // ["package.json", "package-lock.json"]
+ */
+export function changedPaths(root) {
+    const status = git(root, ["status", "--porcelain", "-uall", "-z"]);
+    if (!status.ok)
+        throw new KitError(`no pude leer git status: ${status.err}`);
+    const worktrees = innerWorktrees(root);
+    const entries = status.out.split("\0").filter((entry) => entry !== "");
+    const paths = [];
+    for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index] ?? "";
+        if (/[RC]/.test(entry.slice(0, 2)))
+            index += 1;
+        const path = entry.slice(3).replace(/\/$/, "");
+        if (!worktrees.some((tree) => path === tree || path.startsWith(`${tree}/`)))
+            paths.push(path);
+    }
+    return paths;
+}
+/**
+ * Checks, before any step, that the repo has no changes and is on its base branch.
+ * @param root - The repo.
+ * @param base - The base branch.
+ * @throws KitError saying what is wrong and what to do.
+ */
+export function checkReady(root, base) {
+    const branch = git(root, ["branch", "--show-current"]).out;
+    if (branch === "")
+        throw new KitError(`--commit necesita estar en ${base}, y HEAD no está en ninguna rama.`);
+    if (branch !== base)
+        throw new KitError(`--commit necesita estar en ${base}, la rama base, y estás en ${branch}.`);
+    const paths = changedPaths(root);
+    if (paths.length > 0)
+        throw new KitError(`--commit necesita el repo sin cambios, y hay cambios en: ${paths.join(", ")}. Commitéalos o guárdalos aparte y corre otra vez.`);
+}
+/**
+ * The branch for today's changes: a new name, also against origin's branches git knows of.
+ * @param root - The repo.
+ * @param date - Today.
+ * @returns `chore/agent-kitchen-apply-AAAA-MM-DD`, or with `-2`, `-3`… if taken.
+ * @example branchName(root, new Date()) // "chore/agent-kitchen-apply-2026-11-01"
+ */
+export function branchName(root, date) {
+    const pad = (n) => String(n).padStart(2, "0");
+    const name = `chore/agent-kitchen-apply-${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+    const taken = (candidate) => git(root, ["rev-parse", "-q", "--verify", `refs/heads/${candidate}`]).ok || git(root, ["rev-parse", "-q", "--verify", `refs/remotes/origin/${candidate}`]).ok;
+    if (!taken(name))
+        return name;
+    let n = 2;
+    while (taken(`${name}-${n}`))
+        n += 1;
+    return `${name}-${n}`;
+}
+/**
+ * Stages the files shown to the person, taken literally, and commits them, with the hooks.
+ * @param root - The repo.
+ * @param paths - The files.
+ * @param steps - The steps that ran, for the body.
+ * @returns How git went.
+ */
+function commit(root, paths, steps) {
+    const add = git(root, ["--literal-pathspecs", "add", "-A", "--", ...paths]);
+    if (!add.ok)
+        return add;
+    return git(root, ["commit", "-q", "-m", TITLE, "-m", steps.map((step) => `- ${step}`).join("\n")]);
+}
+/**
+ * The version of github-rest to open the PR with: the repo's exact one, or npm's latest.
+ * @param root - The repo.
+ * @returns The version, or null if neither is known.
+ */
+async function githubRestVersion(root) {
+    const own = dependencyVersion(readJson(root, "package.json"), GITHUB_REST);
+    if (own !== null && isRelease(own))
+        return own;
+    return npmLatest(GITHUB_REST);
+}
+/**
+ * Opens the PR with github-rest, without GH_REPO, so the repo is origin's.
+ * @param root - The repo, on the branch.
+ * @param branch - The branch.
+ * @param base - The base.
+ * @param steps - The steps, for the body.
+ * @returns The PR's URL, or why it failed.
+ */
+async function openPr(root, branch, base, steps) {
+    const version = await githubRestVersion(root);
+    if (version === null)
+        return { error: `no sé qué versión de ${GITHUB_REST} usar.` };
+    const dir = mkdtempSync(join(tmpdir(), "agent-kitchen-pr-"));
+    const bodyFile = join(dir, "body.md");
+    writeFileSync(bodyFile, `Cambios de \`agent-kitchen apply\`:\n\n${steps.map((step) => `- ${step}`).join("\n")}\n`);
+    try {
+        const result = await captureNpxWithout(root, [`${GITHUB_REST}@${version}`, "pr", "create", "--head", branch, "--base", base, "--title", TITLE, "--body-file", bodyFile], ["GH_REPO"]);
+        const url = result.out.trim().split("\n").at(-1) ?? "";
+        return result.status === 0 && url !== "" ? { url } : { error: `${result.err}${result.out}`.trim() || "github-rest falló sin decir por qué." };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/**
+ * What the person can run to open the PR by hand.
+ * @param branch - The branch.
+ * @param base - The base.
+ * @returns The command.
+ */
+function prCommand(branch, base) {
+    return `npx @ramon-sg/github-rest pr create --head ${branch} --base ${base} --title "${TITLE}" --body "..."`;
+}
+/**
+ * Pushes the branch and opens its PR, saying what to run if either fails.
+ * @param root - The repo, on the branch.
+ * @param branch - The branch.
+ * @param base - The base.
+ * @param steps - The steps, for the body.
+ * @param lines - Where to add what happened.
+ * @returns Whether both worked.
+ */
+async function pushAndOpen(root, branch, base, steps, lines) {
+    const pushed = git(root, ["push", "-u", "origin", branch], true);
+    if (!pushed.ok) {
+        lines.push(`No pude subir la rama. Falta: git push -u origin ${branch}, y luego ${prCommand(branch, base)}`);
+        return false;
+    }
+    const pr = await openPr(root, branch, base, steps);
+    if ("url" in pr) {
+        lines.push(`PR: ${pr.url}`);
+        return true;
+    }
+    lines.push(`La rama está en origin, pero no pude abrir el PR: ${pr.error}`, `Falta: ${prCommand(branch, base)}`);
+    return false;
+}
+/**
+ * Does what the person chose with the changes.
+ * @param root - The repo, on the base, with the changes of the run.
+ * @param choice - What to do.
+ * @param options - The base, the new branch's name, the steps that ran, the files to commit (the ones shown), the package manager and whether package.json changed.
+ * @returns The lines to show and whether it all worked.
+ * @example await finish(root, "pr", { base: "main", branch: "chore/agent-kitchen-apply-2026-11-01", steps, manager: "npm" })
+ */
+export async function finish(root, choice, options) {
+    const { base, branch, steps, paths } = options;
+    if (choice === "leave")
+        return { ok: true, lines: ["Falta: revisa el diff y haz commit."] };
+    if (choice === "base") {
+        const done = commit(root, paths, steps);
+        if (!done.ok)
+            return { ok: false, lines: [`No pude commitear en ${base}; los cambios quedan sin commit.`, done.err || done.out] };
+        return { ok: true, lines: [`Commit en ${base}. Falta: git push cuando quieras.`] };
+    }
+    const moved = git(root, ["switch", "-q", "-c", branch]);
+    if (!moved.ok)
+        return { ok: false, lines: [`No pude crear la rama ${branch}; los cambios quedan sin commit.`, moved.err] };
+    const lines = [];
+    let ok = true;
+    let committed = false;
+    try {
+        const done = commit(root, paths, steps);
+        if (!done.ok) {
+            ok = false;
+            lines.push("No pude commitear.", done.err || done.out);
+        }
+        else {
+            committed = true;
+            lines.push(`Commit en la rama ${branch}.`);
+            if (choice === "pr")
+                ok = await pushAndOpen(root, branch, base, steps, lines);
+        }
+    }
+    finally {
+        const back = git(root, ["switch", "-q", base]);
+        if (!back.ok) {
+            ok = false;
+            lines.push(`No pude volver a ${base}: ${back.err}. Sigues en ${branch}.`);
+        }
+        else if (!committed) {
+            git(root, ["branch", "-q", "-d", branch]);
+            lines.push(`Vuelves a ${base} con los cambios sin commit.`);
+        }
+        else
+            lines.push(`Vuelves a ${base}, sin los cambios: están en ${branch}.`);
+    }
+    if (!committed)
+        return { ok: false, lines };
+    if (options.packageChanged === true)
+        lines.push(`node_modules quedó con lo de la rama; si sigues en ${base}, corre '${options.manager} install'.`);
+    return { ok, lines };
+}

package/dist/menu.d.ts

@@ -1,3 +1,4 @@
+import type { FinishChoice } from "./git-finish.js";
 import type { Candidate, Step } from "./piece.js";
 /** What the person wants after seeing the table. */
 export type Path = "all" | "pick" | "leave";
@@ -14,6 +15,20 @@ export declare function menuOptions(steps: Step[]): {
     }[];
     initialValues: number[];
 };
+/**
+ * The pieces menu's options: each piece by its name, ticked if the repo uses it.
+ * @param names - The pieces, in the order to show them.
+ * @param ticked - The ones ticked at the start.
+ * @returns The options and the ones ticked at the start.
+ * @example pieceOptions(["issue-flow", "skills"], ["skills"]).initialValues // ["skills"]
+ */
+export declare function pieceOptions(names: string[], ticked: string[]): {
+    options: {
+        value: string;
+        label: string;
+    }[];
+    initialValues: string[];
+};
 /**
  * The skills menu's options: grouped by catalog, each with its description cut short.
  * @param candidates - What the catalogs offer.
@@ -39,6 +54,14 @@ export declare function askPath(count: number): Promise<Path>;
  * @example await askSteps(steps)
  */
 export declare function askSteps(steps: Step[]): Promise<Step[] | null>;
+/**
+ * Asks which pieces the repo uses.
+ * @param names - The pieces.
+ * @param ticked - The ones ticked at the start.
+ * @returns The picked pieces, or null if the person cancelled.
+ * @example await askPieces(["issue-flow", "skills"], ["skills"])
+ */
+export declare function askPieces(names: string[], ticked: string[]): Promise<string[] | null>;
 /**
  * Asks which skills to install.
  * @param candidates - What the catalogs offer.
@@ -54,3 +77,13 @@ export declare function askSkills(candidates: Candidate[], ticked: string[]): Pr
  * @example await askReplace(["planning"])
  */
 export declare function askReplace(own: string[]): Promise<boolean | null>;
+/**
+ * Asks, after the steps, what to do with the changes. Leaving them is the default, and
+ * cancelling leaves them too.
+ * @param base - The base branch.
+ * @param branch - The name of the new branch.
+ * @param failed - Whether a step failed, to warn above the question.
+ * @returns The answer.
+ * @example await askFinish("main", "chore/agent-kitchen-apply-2026-11-01", false) // "pr"
+ */
+export declare function askFinish(base: string, branch: string, failed: boolean): Promise<FinishChoice>;

package/dist/menu.js

@@ -28,6 +28,16 @@ export function menuOptions(steps) {
         initialValues: steps.flatMap((step, index) => (step.checked ? [index] : [])),
     };
 }
+/**
+ * The pieces menu's options: each piece by its name, ticked if the repo uses it.
+ * @param names - The pieces, in the order to show them.
+ * @param ticked - The ones ticked at the start.
+ * @returns The options and the ones ticked at the start.
+ * @example pieceOptions(["issue-flow", "skills"], ["skills"]).initialValues // ["skills"]
+ */
+export function pieceOptions(names, ticked) {
+    return { options: names.map((name) => ({ value: name, label: name })), initialValues: names.filter((name) => ticked.includes(name)) };
+}
 /**
  * The skills menu's options: grouped by catalog, each with its description cut short.
  * @param candidates - What the catalogs offer.
@@ -72,6 +82,19 @@ export async function askSteps(steps) {
         return null;
     return steps.filter((_, index) => picked.includes(index));
 }
+/**
+ * Asks which pieces the repo uses.
+ * @param names - The pieces.
+ * @param ticked - The ones ticked at the start.
+ * @returns The picked pieces, or null if the person cancelled.
+ * @example await askPieces(["issue-flow", "skills"], ["skills"])
+ */
+export async function askPieces(names, ticked) {
+    spanishKeys();
+    const { options, initialValues } = pieceOptions(names, ticked);
+    const picked = await multiselect({ message: "¿Qué piezas usa este repo?", options, initialValues, required: false });
+    return isCancel(picked) ? null : picked;
+}
 /**
  * Asks which skills to install.
  * @param candidates - What the catalogs offer.
@@ -98,3 +121,26 @@ export async function askReplace(own) {
     });
     return isCancel(answer) ? null : answer;
 }
+/**
+ * Asks, after the steps, what to do with the changes. Leaving them is the default, and
+ * cancelling leaves them too.
+ * @param base - The base branch.
+ * @param branch - The name of the new branch.
+ * @param failed - Whether a step failed, to warn above the question.
+ * @returns The answer.
+ * @example await askFinish("main", "chore/agent-kitchen-apply-2026-11-01", false) // "pr"
+ */
+export async function askFinish(base, branch, failed) {
+    spanishKeys();
+    const answer = await select({
+        message: failed ? "Algún paso falló. ¿Qué hago con los cambios?" : "¿Qué hago con los cambios?",
+        initialValue: "leave",
+        options: [
+            { value: "leave", label: "Dejarlos sin commit" },
+            { value: "base", label: `Commit en ${base}` },
+            { value: "branch", label: `Commit en una rama nueva, ${branch}`, hint: `${base} queda como está` },
+            { value: "pr", label: "Commit en una rama nueva, push y PR", hint: `contra ${base}` },
+        ],
+    });
+    return isCancel(answer) ? "leave" : answer;
+}

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

@@ -1,11 +1,17 @@
 /**
  * @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.
- * From 0.2.6 it also offers `labels sync`, after the install or update, when GitHub lacks
- * some of the labels the flow expects.
- * `init` runs with `--yes`: the person answered agent-kitchen's questions before the steps.
+ * The repo's version is the one in package.json. From 0.3.0, installing and updating run its
+ * `apply` at the latest version, and reading its `--json` tells what it kept as it was; at
+ * the repo's version, `apply` also repairs hooks or a `$schema` its doctor finds behind (a
+ * version raised by hand or by Dependabot). Before 0.3.0, installing runs `init` and
+ * updating runs `upgrade`. After updating or repairing, and after installing with `apply`,
+ * the flow's skills move to the same tag, because they call the CLI. If only the skills are
+ * off, they move alone. From 0.2.6 it also offers `labels sync`, after the install or
+ * update, when GitHub lacks some of the labels the flow expects. From 0.3.0, whose `apply`
+ * keeps the repo's github-rest, it also raises an exact github-rest below the floor of the
+ * range that version of the flow declares on npm, as the flow itself reads it.
+ * `apply` and `init` run 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. */