agent-kitchen 0.0.0-stage → 0.3.0

package/dist/pieces/issue-flow.js

@@ -0,0 +1,151 @@
+/**
+ * @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 { FLOW_CATALOG, FLOW_PACKAGE } from "../piece.js";
+import { dependencyVersion, readJson } from "../repo.js";
+import { catalogSkills, manifestCatalogs, pinCatalog, updateSkills } from "../skills-files.js";
+import { captureNpx, compareVersions, isRelease, npmLatest, runNpx } from "../tools.js";
+/** The piece's name, as `--skip` takes it. */
+export const NAME = "issue-flow";
+/** How the catalog's ref is named when it is off. */
+const SKILLS_CATALOG_LABEL = "el catálogo";
+/** The first version whose `doctor` prints `--json`. */
+const JSON_DOCTOR = "0.2.0";
+/**
+ * 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 function flowSpec(root) {
+    return dependencyVersion(readJson(root, "package.json"), FLOW_PACKAGE);
+}
+/**
+ * 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 function flowVersion(root) {
+    const spec = flowSpec(root);
+    return spec !== null && isRelease(spec) ? spec : null;
+}
+/**
+ * The flow's skills that are not at a version's tag, or the catalog pinned elsewhere.
+ * @param root - The repo.
+ * @param version - The flow's version.
+ * @returns Their names; the catalog's ref as well if it is off.
+ */
+function skillsOff(root, version) {
+    const tag = `v${version}`;
+    const off = catalogSkills(root, FLOW_CATALOG).filter((skill) => skill.tag !== tag).map((skill) => `${skill.name} en ${skill.tag ?? "sin tag"}`);
+    const source = manifestCatalogs(root).find((item) => item.catalog === FLOW_CATALOG);
+    return source !== undefined && source.ref !== tag ? [...off, `${SKILLS_CATALOG_LABEL} en ${source.ref ?? "la última"}`] : off;
+}
+/**
+ * Moves the flow's skills to a version's tag: the catalog's ref in the manifest, and then
+ * `skills-manager update` on them.
+ * @param context - Where it runs.
+ * @param version - The flow's version.
+ * @returns Whether it worked, or true if the repo has none of the flow's skills.
+ */
+async function moveSkills(context, version) {
+    if (!pinCatalog(context.root, FLOW_CATALOG, `v${version}`))
+        return true;
+    const names = catalogSkills(context.root, FLOW_CATALOG).map((skill) => skill.name);
+    const failed = await updateSkills(context.root, names);
+    if (failed === null) {
+        context.note(`skills del flujo en v${version}: ${names.join(", ")}`);
+        return true;
+    }
+    context.fail(`skills-manager no actualizó las skills del flujo; corre '${failed.command}' y luego agent-kitchen otra vez.`, failed.run.output);
+    return false;
+}
+/**
+ * Runs the flow's own command at a version.
+ * @param context - Where it runs.
+ * @param version - The version.
+ * @param args - The command and its flags.
+ * @returns Whether it exited 0.
+ */
+async function runFlow(context, version, args) {
+    const run = await runNpx(context.root, [`${FLOW_PACKAGE}@${version}`, ...args]);
+    if (run.ok)
+        return true;
+    context.fail(`issue-flow ${args[0] ?? ""} falló; corre 'npx ${FLOW_PACKAGE}@${version} ${args.join(" ")}'.`, run.output);
+    return false;
+}
+/**
+ * The step the repo needs, if any.
+ * @param installed - The repo's version, or null.
+ * @param latest - The latest on npm, or null.
+ * @param root - The repo.
+ * @returns The step, or null.
+ */
+function stepFor(installed, latest, root) {
+    if (installed === null && latest !== null)
+        return { piece: NAME, checked: true, downloads: [`${FLOW_PACKAGE}@${latest}`], label: `Instalar issue-flow ${latest}: config del flujo, hooks y scripts`, run: (context) => runFlow(context, latest, ["init", "--yes"]) };
+    if (installed !== null && latest !== null && compareVersions(latest, installed) > 0)
+        return { piece: NAME, checked: true, downloads: [`${FLOW_PACKAGE}@${latest}`], label: `Actualizar issue-flow ${installed} → ${latest}, con sus hooks y sus skills`, run: async (context) => (await runFlow(context, latest, ["upgrade"])) && (await moveSkills(context, latest)) };
+    if (installed !== null && skillsOff(root, installed).length > 0)
+        return { piece: NAME, checked: true, downloads: [], label: `Poner las skills del flujo en v${installed}, la versión de issue-flow`, run: (context) => moveSkills(context, installed) };
+    return 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 async function issueFlowStatus(root) {
+    const summary = "rama, worktree y PR en draft por issue";
+    const spec = flowSpec(root);
+    if (spec !== null && !isRelease(spec))
+        return { name: NAME, summary, installed: true, state: `package.json tiene ${spec}, no una versión exacta; no se toca`, steps: [] };
+    const installed = flowVersion(root);
+    const latest = await npmLatest(FLOW_PACKAGE);
+    const step = stepFor(installed, latest, root);
+    const known = latest === null ? " (npm no responde)" : "";
+    const state = installed === null ? `no instalado${known}` : latest !== null && compareVersions(latest, installed) > 0 ? `${installed}, hay ${latest}` : `${installed}, al día${known}`;
+    return { name: NAME, summary, installed: installed !== null, state, steps: step === null ? [] : [step] };
+}
+/**
+ * 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 async function issueFlowChecks(root) {
+    const spec = flowSpec(root);
+    if (spec === null)
+        return [{ name: NAME, status: "info", detail: "no instalado" }];
+    const installed = flowVersion(root);
+    if (installed === null)
+        return [{ name: NAME, status: "info", detail: `package.json tiene ${spec}, no una versión exacta` }];
+    if (compareVersions(installed, JSON_DOCTOR) < 0)
+        return [{ name: NAME, status: "info", detail: `${installed} no tiene doctor --json: corre npx agent-kitchen para actualizarlo` }];
+    const result = await captureNpx(root, [`${FLOW_PACKAGE}@${installed}`, "doctor", "--json"]);
+    let found;
+    try {
+        found = JSON.parse(result?.out ?? "");
+    }
+    catch {
+        found = null;
+    }
+    const own = Array.isArray(found)
+        ? found.map((check) => ({ name: `${NAME}: ${String(check.name)}`, status: check.ok === true ? "ok" : "fail", detail: String(check.detail) }))
+        : [{ name: NAME, status: "fail", detail: `no se pudo correr su doctor; corre 'npx ${FLOW_PACKAGE}@${installed} doctor'` }];
+    const off = skillsOff(root, installed);
+    const count = catalogSkills(root, FLOW_CATALOG).length;
+    const skills = count === 0 && off.length === 0
+        ? { name: `${NAME}: skills`, status: "info", detail: "ninguna instalada" }
+        : off.length === 0
+            ? { name: `${NAME}: skills`, status: "ok", detail: `${count} en v${installed}` }
+            : { name: `${NAME}: skills`, status: "fail", detail: `${off.join(", ")}; issue-flow está en ${installed}: corre npx agent-kitchen` };
+    return [...own, skills];
+}

package/dist/pieces/skills.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @file The skills, through `skills-manager`: the flow's catalog (pinned to the flow's
+ * version, because its skills call the CLI) and the general catalogs (each skill at its
+ * own tag). agent-kitchen reads what the catalogs offer (`--candidates`), lets the person
+ * pick before any step runs, and then installs the pick with `--select`, so
+ * `skills-manager` asks nothing. The first time every skill comes ticked. Later it offers
+ * to move the general skills to their catalog's latest tag, and, unticked, the skills a
+ * catalog has that the repo does not take yet. The flow's skills move with the flow
+ * (pieces/issue-flow.ts), never here.
+ *
+ * A skill the repo already has as its own (a folder the lock does not know) is replaced
+ * only if the person allows it (`--replace`); `skills-manager` keeps its `project.md`.
+ */
+import { type Candidate, type Check, type PieceStatus, type SkillPick } from "../piece.js";
+/** The piece's name, as `--skip` takes it. */
+export declare const NAME = "skills";
+/**
+ * Every skill some candidates bring: their own and what they require, all the way down,
+ * as `skills-manager` follows it.
+ * @param candidates - Every candidate offered.
+ * @param ids - The candidates picked.
+ * @returns The skills' names.
+ * @example skillsOf(candidates, ["catalog:ramon-sg/issue-flow/close-pr"]) // ["close-pr", "pr-review-comments", "github-issues"]
+ */
+export declare function skillsOf(candidates: Candidate[], ids: string[]): string[];
+/**
+ * The repo's own skills a pick would replace: each picked skill and what it requires.
+ * @param root - The repo.
+ * @param pick - The pick.
+ * @returns Their names.
+ * @example ownInPick(root, step.skills) // ["planning"]
+ */
+export declare function ownInPick(root: string, pick: SkillPick): string[];
+/**
+ * Drops from a pick the skills that would replace one of the repo's own (or that require
+ * one), for when the person does not allow replacing them.
+ * @param pick - The pick.
+ * @param own - The repo's own skills that stay.
+ * @returns The pick without them.
+ * @example keepOwn(pick, ["planning"]).picked
+ */
+export declare function keepOwn(pick: SkillPick, own: string[]): SkillPick;
+/**
+ * What the repo has of the skills, and the steps it can take.
+ * @param root - The repo.
+ * @param withFlow - Whether this run may install the flow (it is not left out with `--skip`).
+ * @returns The piece's status.
+ * @example (await skillsStatus(root, true)).state // "6 instaladas"
+ */
+export declare function skillsStatus(root: string, withFlow: boolean): Promise<PieceStatus>;
+/**
+ * Whether `skills-manager check` passes: disk, lock and manifest agree.
+ * @param root - The repo.
+ * @returns The checks.
+ * @example (await skillsChecks(root))[0].status // "ok"
+ */
+export declare function skillsChecks(root: string): Promise<Check[]>;

package/dist/pieces/skills.js

@@ -0,0 +1,251 @@
+/**
+ * @file The skills, through `skills-manager`: the flow's catalog (pinned to the flow's
+ * version, because its skills call the CLI) and the general catalogs (each skill at its
+ * own tag). agent-kitchen reads what the catalogs offer (`--candidates`), lets the person
+ * pick before any step runs, and then installs the pick with `--select`, so
+ * `skills-manager` asks nothing. The first time every skill comes ticked. Later it offers
+ * to move the general skills to their catalog's latest tag, and, unticked, the skills a
+ * catalog has that the repo does not take yet. The flow's skills move with the flow
+ * (pieces/issue-flow.ts), never here.
+ *
+ * A skill the repo already has as its own (a folder the lock does not know) is replaced
+ * only if the person allows it (`--replace`); `skills-manager` keeps its `project.md`.
+ */
+import { FLOW_CATALOG, FLOW_PACKAGE, GENERAL_CATALOGS, SKILLS_MANIFEST } from "../piece.js";
+import { isObject, readJson } from "../repo.js";
+import { catalogSkills, lockedSkills, manifestCatalogs, ownSkills, pinCatalog, skillsManagerSpec, updateSkills } from "../skills-files.js";
+import { captureNpx, compareVersions, latestTag, npmLatest, runNpx } from "../tools.js";
+import { flowVersion } from "./issue-flow.js";
+/** The piece's name, as `--skip` takes it. */
+export const NAME = "skills";
+/** The skills picked when the catalogs cannot be read: the flow's, and the audit `close-pr` uses. */
+const DEFAULT_SKILLS = [
+    ...["github-issues", "start-issue", "close-pr", "pr-review-comments", "pr-worktree"].map((name) => `catalog:${FLOW_CATALOG}/${name}`),
+    "catalog:ramon-sg/agent-skills/code-audit",
+];
+/** A release tag. */
+const RELEASE_TAG = /^v\d+\.\d+\.\d+$/;
+/**
+ * The `--catalog` flags: the flow's at a version, if there is one, and the general ones.
+ * @param flow - The flow's version, or null.
+ * @returns The flags.
+ */
+function catalogArgs(flow) {
+    const catalogs = [...(flow === null ? [] : [`${FLOW_CATALOG}#v${flow}`]), ...GENERAL_CATALOGS];
+    return catalogs.flatMap((catalog) => ["--catalog", catalog]);
+}
+/**
+ * Reads one candidate of `--candidates`.
+ * @param value - An item of its output.
+ * @returns The candidate, or null if it is not one.
+ */
+function toCandidate(value) {
+    if (!isObject(value) || typeof value.id !== "string" || typeof value.name !== "string")
+        return null;
+    const names = (field) => (Array.isArray(field) ? field.map(String) : []);
+    return {
+        id: value.id,
+        name: value.name,
+        catalog: typeof value.catalog === "string" ? value.catalog : "",
+        description: typeof value.description === "string" ? value.description : "",
+        skills: names(value.skills),
+        requires: names(value.requires),
+    };
+}
+/**
+ * Every skill some candidates bring: their own and what they require, all the way down,
+ * as `skills-manager` follows it.
+ * @param candidates - Every candidate offered.
+ * @param ids - The candidates picked.
+ * @returns The skills' names.
+ * @example skillsOf(candidates, ["catalog:ramon-sg/issue-flow/close-pr"]) // ["close-pr", "pr-review-comments", "github-issues"]
+ */
+export function skillsOf(candidates, ids) {
+    const byName = new Map(candidates.map((candidate) => [candidate.name, candidate]));
+    const found = new Set();
+    const pending = candidates.filter((candidate) => ids.includes(candidate.id)).flatMap((candidate) => [...candidate.skills, ...candidate.requires]);
+    while (pending.length > 0) {
+        const name = pending.pop();
+        if (name === undefined || found.has(name))
+            continue;
+        found.add(name);
+        pending.push(...(byName.get(name)?.requires ?? []));
+    }
+    return [...found];
+}
+/**
+ * The catalog of a candidate's id (`catalog:<owner>/<repo>/<name>`).
+ * @param id - The id.
+ * @returns The catalog, as owner/repo.
+ */
+function catalogOf(id) {
+    return id.replace(/^catalog:/, "").split("/").slice(0, 2).join("/");
+}
+/**
+ * What the catalogs offer that the manifest does not take yet, as `skills-manager` lists it.
+ * @param root - The repo.
+ * @param flow - The flow's version whose catalog to read, or null.
+ * @returns The candidates, or null if `skills-manager` could not tell.
+ */
+async function readCandidates(root, flow) {
+    const command = readJson(root, SKILLS_MANIFEST) === null ? "init" : "add";
+    const result = await captureNpx(root, [skillsManagerSpec(root), command, "--candidates", ...catalogArgs(flow)], true);
+    let found;
+    try {
+        found = JSON.parse(result?.out ?? "");
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(found))
+        return null;
+    return found.flatMap((item) => toCandidate(item) ?? []);
+}
+/**
+ * The repo's own skills a pick would replace: each picked skill and what it requires.
+ * @param root - The repo.
+ * @param pick - The pick.
+ * @returns Their names.
+ * @example ownInPick(root, step.skills) // ["planning"]
+ */
+export function ownInPick(root, pick) {
+    return ownSkills(root, skillsOf(pick.candidates, pick.picked));
+}
+/**
+ * Drops from a pick the skills that would replace one of the repo's own (or that require
+ * one), for when the person does not allow replacing them.
+ * @param pick - The pick.
+ * @param own - The repo's own skills that stay.
+ * @returns The pick without them.
+ * @example keepOwn(pick, ["planning"]).picked
+ */
+export function keepOwn(pick, own) {
+    const picked = pick.picked.filter((id) => !skillsOf(pick.candidates, [id]).some((name) => own.includes(name)));
+    return { ...pick, picked, replace: [] };
+}
+/**
+ * Installs the picked skills with `--select`, replacing the own ones the person allowed.
+ * @param context - Where it runs.
+ * @param pick - What to install.
+ * @returns Whether `skills-manager` worked, or true if nothing was picked.
+ */
+async function install(context, pick) {
+    const flow = flowVersion(context.root);
+    const picked = flow === null ? pick.picked.filter((id) => catalogOf(id) !== FLOW_CATALOG) : pick.picked;
+    if (picked.length < pick.picked.length)
+        context.note("sin las skills del flujo, porque issue-flow no está instalado");
+    if (picked.length === 0) {
+        context.note("ninguna skill que instalar");
+        return true;
+    }
+    const spec = skillsManagerSpec(context.root);
+    const command = readJson(context.root, SKILLS_MANIFEST) === null ? "init" : "add";
+    const args = [spec, command, ...catalogArgs(flow), "--select", picked.join(","), ...(pick.replace.length === 0 ? [] : ["--replace", pick.replace.join(",")])];
+    const run = await runNpx(context.root, args);
+    if (!run.ok) {
+        context.fail(`skills-manager no instaló las skills; corre 'npx ${args.join(" ")}'.`, run.output);
+        return false;
+    }
+    const names = pick.candidates.filter((candidate) => picked.includes(candidate.id)).map((candidate) => candidate.name);
+    context.note(names.length === 0 ? `${picked.length} skills` : names.join(", "));
+    if (pick.replace.length > 0)
+        context.note(`reemplazadas (con su project.md): ${pick.replace.join(", ")}`);
+    return true;
+}
+/**
+ * The step that moves a general catalog's skills to its latest tag, if they are behind. A
+ * catalog that follows a branch has no tag to move to, so it gets no step.
+ * @param root - The repo.
+ * @param catalog - The catalog.
+ * @param ref - The ref the manifest pins it to, or null.
+ * @returns The step, or null.
+ */
+async function updateStep(root, catalog, ref) {
+    if (ref !== null && !RELEASE_TAG.test(ref))
+        return null;
+    const latest = await latestTag(catalog);
+    if (latest === null)
+        return null;
+    const behind = catalogSkills(root, catalog).filter((skill) => skill.tag !== null && RELEASE_TAG.test(skill.tag) && compareVersions(latest, skill.tag.replace(/^v/, "")) > 0);
+    if (behind.length === 0)
+        return null;
+    const from = [...new Set(behind.map((skill) => skill.tag ?? "?"))].join(", ");
+    return {
+        piece: NAME,
+        checked: true,
+        downloads: [skillsManagerSpec(root)],
+        label: `Actualizar skills de ${catalog} ${from} → v${latest}: ${behind.map((skill) => skill.name).join(", ")}`,
+        run: async (context) => {
+            if (ref !== null)
+                pinCatalog(context.root, catalog, `v${latest}`);
+            const failed = await updateSkills(context.root, behind.map((skill) => skill.name));
+            if (failed === null)
+                return true;
+            context.fail(`skills-manager no actualizó ${catalog}; corre '${failed.command}' y luego agent-kitchen otra vez.`, failed.run.output);
+            return false;
+        },
+    };
+}
+/**
+ * The flow's version whose catalog to offer: the repo's, or the latest when the repo does
+ * not have the flow yet (it is installed before the skills), unless the flow is left out.
+ * @param root - The repo.
+ * @param withFlow - Whether this run may install the flow.
+ * @returns The version, or null if there is none.
+ */
+async function offeredFlow(root, withFlow) {
+    return flowVersion(root) ?? (withFlow ? await npmLatest(FLOW_PACKAGE) : null);
+}
+/**
+ * What the repo has of the skills, and the steps it can take.
+ * @param root - The repo.
+ * @param withFlow - Whether this run may install the flow (it is not left out with `--skip`).
+ * @returns The piece's status.
+ * @example (await skillsStatus(root, true)).state // "6 instaladas"
+ */
+export async function skillsStatus(root, withFlow) {
+    const summary = "skills del flujo, planes y auditorías";
+    const flow = await offeredFlow(root, withFlow);
+    const candidatesRead = readCandidates(root, flow);
+    if (readJson(root, SKILLS_MANIFEST) === null) {
+        const candidates = await candidatesRead;
+        const fallback = DEFAULT_SKILLS.filter((id) => flow !== null || catalogOf(id) !== FLOW_CATALOG).map((id) => {
+            const name = id.split("/").at(-1) ?? id;
+            return { id, name, catalog: catalogOf(id), description: "", skills: [name], requires: [] };
+        });
+        const offered = candidates ?? fallback;
+        const catalogs = [...new Set(offered.map((candidate) => candidate.catalog))];
+        const label = `Instalar ${offered.length} skills de ${catalogs.join(" y ")}`;
+        const skills = { candidates: offered, picked: offered.map((candidate) => candidate.id), replace: [] };
+        const state = candidates === null ? "no instaladas (no se pudieron leer los catálogos)" : "no instaladas";
+        return { name: NAME, summary, installed: false, state, steps: [{ piece: NAME, checked: true, downloads: [], label, skills, run: (context) => install(context, skills) }] };
+    }
+    const general = manifestCatalogs(root).filter((source) => source.catalog !== FLOW_CATALOG);
+    const steps = (await Promise.all(general.map((source) => updateStep(root, source.catalog, source.ref)))).flatMap((step) => step ?? []);
+    const locked = lockedSkills(root);
+    const candidates = await candidatesRead;
+    const fresh = (candidates ?? []).filter((candidate) => locked[candidate.name] === undefined);
+    if (fresh.length > 0) {
+        const skills = { candidates: fresh, picked: [], replace: [] };
+        steps.push({ piece: NAME, checked: false, downloads: [skillsManagerSpec(root)], label: `Agregar skills nuevas (${fresh.length}): ${fresh.map((candidate) => candidate.name).join(", ")}`, skills, run: (context) => install(context, skills) });
+    }
+    const count = manifestCatalogs(root).reduce((total, source) => total + catalogSkills(root, source.catalog).length, 0);
+    const behind = steps.filter((step) => step.checked).length;
+    const unread = candidates === null ? " (no se pudieron leer los catálogos)" : "";
+    return { name: NAME, summary, installed: true, state: `${count} instaladas${behind > 0 ? ", algunas atrasadas" : ", al día"}${unread}`, steps };
+}
+/**
+ * Whether `skills-manager check` passes: disk, lock and manifest agree.
+ * @param root - The repo.
+ * @returns The checks.
+ * @example (await skillsChecks(root))[0].status // "ok"
+ */
+export async function skillsChecks(root) {
+    if (readJson(root, SKILLS_MANIFEST) === null)
+        return [{ name: NAME, status: "info", detail: "no instaladas" }];
+    const spec = skillsManagerSpec(root);
+    const result = await captureNpx(root, [spec, "check"]);
+    if (result?.status === 0)
+        return [{ name: NAME, status: "ok", detail: "skills-manager check pasa" }];
+    return [{ name: NAME, status: "fail", detail: `el disco, el lock y el manifiesto no coinciden: corre 'npx ${spec} check'` }];
+}

package/dist/repo.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Whether a value is a plain JSON object.
+ * @param value - The value.
+ * @returns True for an object that is not an array nor null.
+ * @example isObject({}) // true
+ */
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * The main checkout of the repo a folder is in.
+ * @param cwd - The folder.
+ * @param command - The command that runs, for the error.
+ * @returns Its root, with symlinks resolved.
+ * @throws KitError outside a git checkout or inside a worktree.
+ * @example mainCheckout(process.cwd(), "agent-kitchen") // "/code/shop"
+ */
+export declare function mainCheckout(cwd: string, command: string): string;
+/**
+ * Reads a JSON object of the repo.
+ * @param root - The repo.
+ * @param path - The file, relative to the repo.
+ * @returns The object, or null if the file does not exist.
+ * @throws KitError if it is not valid JSON or not an object: it is never overwritten then.
+ * @example readJson(root, ".claude/cloud.json")
+ */
+export declare function readJson(root: string, path: string): Record<string, unknown> | null;
+/**
+ * Writes a JSON file of the repo, indented by two spaces, creating its folder.
+ * @param root - The repo.
+ * @param path - The file, relative to the repo.
+ * @param value - What to write.
+ * @example writeJson(root, ".claude/cloud.json", { version: "1.1.0" })
+ */
+export declare function writeJson(root: string, path: string, value: unknown): void;
+/**
+ * The version of a dependency in `package.json`, development or not.
+ * @param pkg - The package.json, or null.
+ * @param name - The package.
+ * @returns The version, or null if it is not there.
+ * @example dependencyVersion(pkg, "@ramon-sg/issue-flow") // "0.2.0"
+ */
+export declare function dependencyVersion(pkg: Record<string, unknown> | null, name: string): string | null;
+/**
+ * The repo's package manager: the `packageManager` field, then its lockfile, then npm.
+ * @param root - The repo.
+ * @returns `npm`, `pnpm`, `bun` or `yarn`.
+ * @example packageManager(root) // "pnpm"
+ */
+export declare function packageManager(root: string): string;

package/dist/repo.js

@@ -0,0 +1,117 @@
+/**
+ * @file The repo agent-kitchen works on: its main checkout (never a worktree, whose files are
+ * not the ones the team commits from), the JSON files the pieces keep in it, and its
+ * package manager.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { KitError } from "./output.js";
+/**
+ * Whether a value is a plain JSON object.
+ * @param value - The value.
+ * @returns True for an object that is not an array nor null.
+ * @example isObject({}) // true
+ */
+export function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Runs git in a folder.
+ * @param cwd - The folder.
+ * @param args - The arguments.
+ * @returns Its trimmed stdout, or null if it failed.
+ */
+function git(cwd, args) {
+    const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+    return result.status === 0 ? result.stdout.trim() : null;
+}
+/**
+ * The main checkout of the repo a folder is in.
+ * @param cwd - The folder.
+ * @param command - The command that runs, for the error.
+ * @returns Its root, with symlinks resolved.
+ * @throws KitError outside a git checkout or inside a worktree.
+ * @example mainCheckout(process.cwd(), "agent-kitchen") // "/code/shop"
+ */
+export function mainCheckout(cwd, command) {
+    const common = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+    const top = git(cwd, ["rev-parse", "--show-toplevel"]);
+    if (common === null || top === null)
+        throw new KitError(`corre ${command} dentro del repo.`);
+    const main = realpathSync(dirname(common));
+    if (realpathSync(top) !== main)
+        throw new KitError(`corre ${command} en la copia principal, ${main}, no en un worktree.`);
+    return main;
+}
+/**
+ * Reads a JSON object of the repo.
+ * @param root - The repo.
+ * @param path - The file, relative to the repo.
+ * @returns The object, or null if the file does not exist.
+ * @throws KitError if it is not valid JSON or not an object: it is never overwritten then.
+ * @example readJson(root, ".claude/cloud.json")
+ */
+export function readJson(root, path) {
+    const file = join(root, path);
+    if (!existsSync(file))
+        return null;
+    let value;
+    try {
+        value = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new KitError(`${path} no es JSON válido (${error instanceof Error ? error.message : String(error)}); arréglalo y corre otra vez.`);
+    }
+    if (!isObject(value))
+        throw new KitError(`${path} no es un objeto JSON; arréglalo y corre otra vez.`);
+    return value;
+}
+/**
+ * Writes a JSON file of the repo, indented by two spaces, creating its folder.
+ * @param root - The repo.
+ * @param path - The file, relative to the repo.
+ * @param value - What to write.
+ * @example writeJson(root, ".claude/cloud.json", { version: "1.1.0" })
+ */
+export function writeJson(root, path, value) {
+    const file = join(root, path);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+/**
+ * The version of a dependency in `package.json`, development or not.
+ * @param pkg - The package.json, or null.
+ * @param name - The package.
+ * @returns The version, or null if it is not there.
+ * @example dependencyVersion(pkg, "@ramon-sg/issue-flow") // "0.2.0"
+ */
+export function dependencyVersion(pkg, name) {
+    for (const field of ["devDependencies", "dependencies"]) {
+        const deps = pkg?.[field];
+        if (isObject(deps) && typeof deps[name] === "string")
+            return deps[name];
+    }
+    return null;
+}
+/** The lockfile of each package manager, in the order they are looked for. */
+const LOCKFILES = [
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"],
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["package-lock.json", "npm"],
+];
+/**
+ * The repo's package manager: the `packageManager` field, then its lockfile, then npm.
+ * @param root - The repo.
+ * @returns `npm`, `pnpm`, `bun` or `yarn`.
+ * @example packageManager(root) // "pnpm"
+ */
+export function packageManager(root) {
+    const pkg = readJson(root, "package.json");
+    const field = typeof pkg?.packageManager === "string" ? pkg.packageManager.split("@")[0] : undefined;
+    if (field !== undefined && field !== "")
+        return field;
+    return LOCKFILES.find(([file]) => existsSync(join(root, file)))?.[1] ?? "npm";
+}