agent-kitchen 0.7.0 → 0.9.0

package/dist/pr-clone.js

@@ -0,0 +1,254 @@
+/**
+ * @file What `apply --pr` does with git. It fetches origin and clones the repo into a temporary
+ * folder at `origin/<base>`, so the steps see what the base has today and the person's checkout
+ * is never touched: not its branch, its files, nor its node_modules. A clone and not a worktree,
+ * because `issue-flow apply` refuses to run in a worktree. The clone shares the repo's objects
+ * (`--shared`), points its origin where the repo's does, and commits with the repo's hooks,
+ * identity and signing. The commit goes from the clone into the repo's objects and the repo
+ * pushes it straight to a new branch of origin, with its own credentials, so no local branch
+ * is made. Then github-rest opens the PR in draft. git runs its hooks; nothing here skips them.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, relative } from "node:path";
+import { COMMIT_TITLE as TITLE, prBody } from "./commit-texts.js";
+import { KitError } from "./output.js";
+import { FLOW_CONFIG } from "./piece.js";
+import { dependencyVersion, readJson } from "./repo.js";
+import { captureNpxWithout, isRelease, npmLatest } from "./tools.js";
+/** github-rest on npm, which opens the PR (REST, never gh's GraphQL). */
+const GITHUB_REST = "@ramon-sg/github-rest";
+/** The settings of the repo a commit made in the clone needs: who signs it and how. */
+const IDENTITY = ["user.name", "user.email", "user.signingkey", "commit.gpgsign", "gpg.format", "gpg.program", "gpg.openpgp.program", "gpg.x509.program", "gpg.ssh.program", "gpg.ssh.allowedsignersfile"];
+/**
+ * Runs git in a folder.
+ * @param cwd - The folder.
+ * @param args - The arguments.
+ * @returns How it went.
+ */
+function git(cwd, args) {
+    const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+    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";
+}
+/**
+ * Origin's URL.
+ * @param root - The repo.
+ * @returns The URL, or null if the repo has no origin.
+ */
+export function originUrl(root) {
+    const url = git(root, ["remote", "get-url", "origin"]);
+    return url.ok && url.out !== "" ? url.out : null;
+}
+/**
+ * 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;
+}
+/**
+ * How many commits the current branch is behind its upstream, as the last fetch saw it.
+ * @param root - The repo.
+ * @returns The count, or 0 without an upstream.
+ */
+export function behindUpstream(root) {
+    const count = git(root, ["rev-list", "--count", "HEAD..@{upstream}"]);
+    return count.ok ? Number(count.out) || 0 : 0;
+}
+/**
+ * The branch for today's changes: a new name, also against origin's branches.
+ * @param root - The repo, just fetched.
+ * @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}`;
+}
+/**
+ * The hooks the clone runs: the repo's `core.hooksPath` as is when it is relative and the
+ * folder is in the clone (committed, like `.githooks`), or else the folder the repo uses,
+ * absolute (`.git/hooks`, or a generated one like husky's).
+ * @param root - The repo.
+ * @param clone - The clone.
+ * @returns The folder.
+ */
+function hooksPath(root, clone) {
+    const own = git(root, ["config", "--get", "core.hooksPath"]);
+    if (own.ok && own.out !== "" && !isAbsolute(own.out) && existsSync(join(clone, own.out)))
+        return own.out;
+    return git(root, ["rev-parse", "--path-format=absolute", "--git-path", "hooks"]).out;
+}
+/**
+ * Fetches origin and clones the repo at `origin/<base>` into a temporary folder.
+ * @param root - The repo.
+ * @param base - The base branch.
+ * @returns The clone's folder.
+ * @throws KitError if the repo has no origin, the fetch fails or origin has no such branch.
+ */
+export function cloneFromOrigin(root, base) {
+    const url = originUrl(root);
+    if (url === null)
+        throw new KitError("--pr necesita un remoto origin, y este repo no tiene.");
+    const fetched = git(root, ["fetch", "-q", "--prune", "origin"]);
+    if (!fetched.ok)
+        throw new KitError(`no pude bajar origin con git fetch; revisa la conexión o las credenciales y corre otra vez.${fetched.err === "" ? "" : `\n${fetched.err}`}`);
+    const head = git(root, ["rev-parse", "-q", "--verify", `refs/remotes/origin/${base}^{commit}`]);
+    if (!head.ok)
+        throw new KitError(`origin no tiene la rama ${base}.`);
+    const clone = realpathSync(mkdtempSync(join(tmpdir(), "agent-kitchen-pr-")));
+    const steps = [
+        ["clone", "-q", "--shared", "--no-checkout", root, clone],
+        ["-C", clone, "remote", "set-url", "origin", url],
+        ["-C", clone, "update-ref", `refs/remotes/origin/${base}`, head.out],
+        ["-C", clone, "symbolic-ref", "refs/remotes/origin/HEAD", `refs/remotes/origin/${base}`],
+        ["-C", clone, "checkout", "-q", "--detach", head.out],
+    ];
+    for (const args of steps) {
+        const done = git(root, args);
+        if (!done.ok) {
+            rmSync(clone, { recursive: true, force: true });
+            throw new KitError(`no pude preparar la copia temporal: ${done.err}`);
+        }
+    }
+    for (const key of IDENTITY) {
+        const value = git(root, ["config", "--get", key]);
+        if (value.ok && value.out !== "")
+            git(clone, ["config", key, value.out]);
+    }
+    git(clone, ["config", "core.hooksPath", hooksPath(root, clone)]);
+    return clone;
+}
+/**
+ * Deletes the clone.
+ * @param clone - Its folder.
+ */
+export function removeClone(clone) {
+    rmSync(clone, { recursive: true, force: true });
+}
+/**
+ * The version of github-rest to open the PR with: the repo's exact one, or npm's latest.
+ * @param root - The checkout to read package.json from.
+ * @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 in draft with github-rest, without GH_REPO, so the repo is origin's.
+ * @param root - The repo.
+ * @param clone - The clone, whose package.json says which github-rest the base uses.
+ * @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, clone, branch, base, steps) {
+    const version = await githubRestVersion(clone);
+    if (version === null)
+        return { error: `no sé qué versión de ${GITHUB_REST} usar.` };
+    const dir = mkdtempSync(join(tmpdir(), "agent-kitchen-body-"));
+    const bodyFile = join(dir, "body.md");
+    writeFileSync(bodyFile, prBody(steps));
+    try {
+        const result = await captureNpxWithout(root, [`${GITHUB_REST}@${version}`, "pr", "create", "--head", branch, "--base", base, "--title", TITLE, "--body-file", bodyFile, "--draft"], ["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 "..." --draft`;
+}
+/**
+ * Commits the clone's changes, pushes them from the repo to a new branch of origin and opens
+ * the PR. Until the push works, the commit lives only in the clone, which the caller keeps.
+ * @param root - The repo.
+ * @param clone - The clone, with the changes.
+ * @param options - The base, the steps that ran (for the commit and the PR) and the files to commit (the ones shown).
+ * @returns The lines to show, whether it all worked and whether the changes reached origin.
+ * @example await publish(root, clone, { base: "main", steps, paths })
+ */
+export async function publish(root, clone, options) {
+    const { base, steps, paths } = options;
+    const add = git(clone, ["--literal-pathspecs", "add", "-A", "--", ...paths]);
+    const done = add.ok ? git(clone, ["commit", "-q", "-m", TITLE, "-m", steps.map((step) => `- ${step}`).join("\n")]) : add;
+    if (!done.ok)
+        return { ok: false, pushed: false, lines: ["No pude hacer el commit.", done.err || done.out].filter((line) => line !== "") };
+    const sha = git(clone, ["rev-parse", "HEAD"]).out;
+    const branch = branchName(root, new Date());
+    // git asks for credentials on the terminal itself, so its output can stay captured.
+    const fetched = git(root, ["fetch", "-q", clone, "HEAD"]);
+    const pushed = fetched.ok ? git(root, ["push", "-q", "origin", `${sha}:refs/heads/${branch}`]) : fetched;
+    if (!pushed.ok)
+        return { ok: false, pushed: false, lines: [`No pude subir la rama ${branch} a origin.`, pushed.err].filter((line) => line !== "") };
+    const pr = await openPr(root, clone, branch, base, steps);
+    if ("url" in pr)
+        return { ok: true, pushed: true, lines: [`PR en draft: ${pr.url}`] };
+    return { ok: false, pushed: true, lines: [`La rama ${branch} está en origin, pero no pude abrir el PR: ${pr.error}`, `Falta: ${prCommand(branch, base)}`] };
+}

package/dist/progress.d.ts

@@ -6,7 +6,8 @@ export interface Progress {
     stop: (text: StepText, ok: boolean) => void;
 }
 /**
- * Progress as plain lines: the start, a line now and then while it runs, and the end.
+ * Progress as plain lines: the start (marked ◒, like the spinner), a line now and then while it
+ * runs, and the end (marked ✓ or ✗).
  * @param out - Where to write.
  * @param options - Whether to print while it runs, how often, and the clock.
  * @returns The progress.
@@ -18,12 +19,11 @@ export declare function plainProgress(out: Output, options: {
     now?: () => number;
 }): Progress;
 /**
- * How progress is shown: a spinner in a terminal, plain lines otherwise or when `plain` asks
- * for them. Only for the steps, after every question: a spinner shown before a question
- * leaves the second question deaf to the keyboard (@clack/prompts 1.8.1).
+ * How progress is shown: a spinner in a terminal, plain lines otherwise. Only for the steps,
+ * after every question: a spinner shown before a question leaves the second question deaf to
+ * the keyboard (@clack/prompts 1.8.1).
  * @param out - Where to write.
  * @param verbose - Whether the tools print on the terminal.
- * @param plain - Whether a question may come after the steps (`--commit`).
  * @returns The progress.
  */
-export declare function progressFor(out: Output, verbose: boolean, plain: boolean): Progress;
+export declare function progressFor(out: Output, verbose: boolean): Progress;

package/dist/progress.js

@@ -20,7 +20,8 @@ function endLine(text, ok, ms) {
     return `${ok ? said.done : ui.failed(said.menu)} (${ui.duration(ms)})`;
 }
 /**
- * Progress as plain lines: the start, a line now and then while it runs, and the end.
+ * Progress as plain lines: the start (marked ◒, like the spinner), a line now and then while it
+ * runs, and the end (marked ✓ or ✗).
  * @param out - Where to write.
  * @param options - Whether to print while it runs, how often, and the clock.
  * @returns The progress.
@@ -33,7 +34,7 @@ export function plainProgress(out, options) {
     return {
         start: (text) => {
             started = now();
-            out.stdout(`${phrases(text).doing}\n`);
+            out.stdout(`◒ ${phrases(text).doing}\n`);
             if (options.ticks)
                 timer = setInterval(() => out.stdout(`${ui.still(ui.duration(now() - started))}\n`), options.tickMs ?? TICK_MS);
         },
@@ -45,16 +46,15 @@ export function plainProgress(out, options) {
     };
 }
 /**
- * How progress is shown: a spinner in a terminal, plain lines otherwise or when `plain` asks
- * for them. Only for the steps, after every question: a spinner shown before a question
- * leaves the second question deaf to the keyboard (@clack/prompts 1.8.1).
+ * How progress is shown: a spinner in a terminal, plain lines otherwise. Only for the steps,
+ * after every question: a spinner shown before a question leaves the second question deaf to
+ * the keyboard (@clack/prompts 1.8.1).
  * @param out - Where to write.
  * @param verbose - Whether the tools print on the terminal.
- * @param plain - Whether a question may come after the steps (`--commit`).
  * @returns The progress.
  */
-export function progressFor(out, verbose, plain) {
-    if (out.interactive && !verbose && !plain) {
+export function progressFor(out, verbose) {
+    if (out.interactive && !verbose) {
         const spin = spinner();
         let started = 0;
         return {

package/dist/repo.d.ts

@@ -46,6 +46,13 @@ export declare function dependencyVersion(pkg: Record<string, unknown> | null, n
  * @example packageManager(root) // "pnpm"
  */
 export declare function packageManager(root: string): string;
+/**
+ * The text of the repo's package.json, to tell later whether a run changed it.
+ * @param root - The repo.
+ * @returns Its text, or null if there is none.
+ * @example packageText(root) // '{ "devDependencies": … }'
+ */
+export declare function packageText(root: string): string | null;
 /**
  * The version of a package installed in the repo's `node_modules`.
  * @param root - The repo.

package/dist/repo.js

@@ -115,6 +115,16 @@ export function packageManager(root) {
         return field;
     return LOCKFILES.find(([file]) => existsSync(join(root, file)))?.[1] ?? "npm";
 }
+/**
+ * The text of the repo's package.json, to tell later whether a run changed it.
+ * @param root - The repo.
+ * @returns Its text, or null if there is none.
+ * @example packageText(root) // '{ "devDependencies": … }'
+ */
+export function packageText(root) {
+    const file = join(root, "package.json");
+    return existsSync(file) ? readFileSync(file, "utf8") : null;
+}
 /**
  * The version of a package installed in the repo's `node_modules`.
  * @param root - The repo.

package/dist/texts/catalog.d.ts

@@ -37,8 +37,8 @@ export interface Catalog {
     suggested: (dryRun: boolean) => string;
     /** The last line when every step worked or some failed. */
     summary: (failed: string[]) => string;
-    /** What is left to do by hand after the steps, without --commit. */
-    next: (manager: string) => string;
+    /** What is left to do by hand after the steps, in the checkout; with the manager if its install failed. */
+    next: (failedInstall: string | null) => string;
     /** A new piece left out because no one was asked about it. */
     undecided: (names: string[]) => string;
     /** The repo's own skills left out of a pick. */
@@ -47,4 +47,12 @@ export interface Catalog {
     saved: (file: string, commits: boolean) => string;
     /** The closing line when no step ran: the person left, or picked none. */
     noSteps: (why: "leave" | "none", wrote: boolean) => string;
+    /** With --pr, before the clone: from which branch of origin. */
+    cloning: (base: string) => string;
+    /** With --pr, the heading of the files that go in the PR. */
+    changes: string;
+    /** With --pr, nothing changed. */
+    noChanges: string;
+    /** With --pr, why no PR was opened and where the changes stay. */
+    prNotOpened: (why: "step" | "install" | "git", clone: string) => string;
 }

package/dist/texts/es.js

@@ -127,7 +127,7 @@ export const es = {
     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.`,
+    next: (failedInstall) => `Falta: ${failedInstall === null ? "" : `corre '${failedInstall} 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"}.`,
@@ -136,4 +136,11 @@ export const es = {
             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.";
     },
+    cloning: (base) => `Trabajo en una copia temporal de origin/${base}; tu copia no se toca.`,
+    changes: "Cambios del PR:",
+    noChanges: "No cambió ningún archivo: no hay PR que abrir.",
+    prNotOpened: (why, clone) => {
+        const reason = { step: "No abrí el PR porque algún paso falló.", install: "No abrí el PR porque falló el install.", git: "" }[why];
+        return `${reason === "" ? "" : `${reason} `}Los cambios quedan en la copia temporal ${clone}; bórrala con rm -rf cuando termines.`;
+    },
 };

package/package.json

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

package/dist/git-finish.d.ts

@@ -1,53 +0,0 @@
-/** 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[];
-}>;