agent-kitchen 0.5.0 → 0.6.0

package/dist/pieces/issue-flow.js

@@ -1,16 +1,22 @@
 /**
  * @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.
- */
-import { FLOW_CATALOG, FLOW_PACKAGE } from "../piece.js";
-import { dependencyVersion, isObject, readJson } from "../repo.js";
+ * 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 { FLOW_CATALOG, FLOW_CONFIG, FLOW_PACKAGE } from "../piece.js";
+import { dependencyVersion, isObject, readJson, setDependency } from "../repo.js";
 import { catalogSkills, manifestCatalogs, pinCatalog, updateSkills } from "../skills-files.js";
-import { captureNpx, compareVersions, isRelease, npmLatest, runNpx } from "../tools.js";
+import { captureNpx, compareVersions, isRelease, npmDependencies, 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. */
@@ -19,6 +25,18 @@ const SKILLS_CATALOG_LABEL = "el catálogo";
 const JSON_DOCTOR = "0.2.0";
 /** The first version with `labels sync`. */
 const LABELS_SINCE = "0.2.6";
+/** The first version whose `apply` installs, updates and repairs, instead of `init` and `upgrade`. */
+const APPLY_SINCE = "0.3.0";
+/** The client of GitHub's REST API that the flow's skills call. */
+const GITHUB_REST = "@ramon-sg/github-rest";
+/**
+ * Whether a version installs and updates with `apply`.
+ * @param version - The flow's version.
+ * @returns True from 0.3.0 on.
+ */
+function usesApply(version) {
+    return compareVersions(version, APPLY_SINCE) >= 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.
@@ -84,6 +102,69 @@ async function runFlow(context, version, args) {
     context.fail(`issue-flow ${args[0] ?? ""} falló; corre 'npx ${FLOW_PACKAGE}@${version} ${args.join(" ")}'.`, run.output);
     return false;
 }
+/**
+ * Runs the flow's `apply` at a version and reads its `--json`: what it kept as it was goes as
+ * a note. Output that is not its JSON counts as a failure, since it does not tell what it wrote.
+ * @param context - Where it runs.
+ * @param version - The version, 0.3.0 or later.
+ * @returns Whether it worked.
+ */
+async function applyFlow(context, version) {
+    const retry = `npx ${FLOW_PACKAGE}@${version} apply --yes`;
+    const result = await captureNpx(context.root, [`${FLOW_PACKAGE}@${version}`, "apply", "--yes", "--json"]);
+    const output = `${result?.out ?? ""}${result?.err ?? ""}`;
+    if (result === null || result.status !== 0) {
+        context.fail(`issue-flow apply falló; corre '${retry}'.`, output);
+        return false;
+    }
+    let report;
+    try {
+        report = JSON.parse(result.out);
+    }
+    catch {
+        report = null;
+    }
+    if (!isObject(report) || !Array.isArray(report.kept)) {
+        context.fail(`issue-flow apply no dijo qué hizo; corre '${retry}'.`, output);
+        return false;
+    }
+    for (const line of report.kept)
+        context.note(String(line));
+    return true;
+}
+/**
+ * The flow's own `doctor --json` at a version.
+ * @param root - The repo.
+ * @param version - The version, 0.2.0 or later.
+ * @param lookup - True to give up after the lookups' time limit, as the status does.
+ * @returns Its checks, or null if it could not run or its output is not a list.
+ */
+async function flowDoctor(root, version, lookup = false) {
+    const result = await captureNpx(root, [`${FLOW_PACKAGE}@${version}`, "doctor", "--json"], lookup);
+    try {
+        const found = JSON.parse(result?.out ?? "");
+        return Array.isArray(found) ? found : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether the flow's doctor finds what `apply` repairs: a hook missing or behind, or the
+ * config's `$schema` behind. A config that is invalid fails the same check but `apply` cannot
+ * fix it, so the `$schema` is told by its detail; and a hook newer than the repo's version
+ * makes `apply` refuse, so it does not count.
+ * @param checks - The doctor's checks.
+ * @param version - The repo's version.
+ * @returns True if `apply` would repair them.
+ */
+function needsRepair(checks, version) {
+    const hookBehind = (detail) => {
+        const found = /^at (\d+\.\d+\.\d+)/.exec(detail)?.[1];
+        return found === undefined || compareVersions(found, version) < 0;
+    };
+    return checks.some((check) => check.ok === false && (String(check.name).endsWith(" hook") ? hookBehind(String(check.detail)) : check.name === FLOW_CONFIG && String(check.detail).includes("$schema")));
+}
 /**
  * The labels the flow expects that GitHub lacks, as `labels sync --dry-run --json` of a
  * version tells (a label that only differs in color or description does not count).
@@ -124,18 +205,65 @@ function labelsStep(version, missing) {
             return runFlow(context, version, ["labels", "sync"]);
         } };
 }
+/**
+ * The lowest github-rest a version of the flow works with: the floor of the range it declares
+ * on npm (`^0.3.0` gives 0.3.0), as the flow reads it from its own package.json.
+ * @param version - The flow's version.
+ * @returns The version, or null before 0.3.0 (its `upgrade` raises github-rest) or if npm cannot tell.
+ * @example await restMinimum("0.3.0") // "0.3.0"
+ */
+async function restMinimum(version) {
+    if (!usesApply(version))
+        return null;
+    const range = (await npmDependencies(`${FLOW_PACKAGE}@${version}`))?.[GITHUB_REST]?.replace(/^[\^~]/, "");
+    return range !== undefined && isRelease(range) ? range : null;
+}
+/**
+ * The step that raises github-rest to a version of the flow's minimum, if package.json has an
+ * exact version below it. A missing one gets none: `apply` adds it at the minimum. A range is
+ * the repo's own choice. At run time it reads package.json again, and raises nothing unless
+ * the repo has that version of the flow by then.
+ * @param root - The repo.
+ * @param version - The flow's version the repo ends at.
+ * @param minimum - The lowest github-rest it works with.
+ * @returns The step, or null.
+ */
+function restStep(root, version, minimum) {
+    const below = (rest) => rest !== null && isRelease(rest) && compareVersions(rest, minimum) < 0;
+    const current = dependencyVersion(readJson(root, "package.json"), GITHUB_REST);
+    if (!below(current))
+        return null;
+    return { piece: NAME, checked: true, downloads: [], label: `Subir github-rest ${current} → ${minimum}, el mínimo de issue-flow ${version}`, run: async (context) => {
+            if (flowVersion(context.root) !== version)
+                context.note(`no se subió: el repo no tiene issue-flow ${version}`);
+            else if (!below(dependencyVersion(readJson(context.root, "package.json"), GITHUB_REST)))
+                context.note("package.json ya tenía una versión que sirve");
+            else {
+                setDependency(context.root, GITHUB_REST, minimum);
+                context.note(`${GITHUB_REST} ${minimum} en package.json`);
+            }
+            return true;
+        } };
+}
 /**
  * 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.
+ * @param repair - Whether the flow's doctor finds what `apply` repairs, at the repo's version.
  * @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)) };
+function stepFor(installed, latest, root, repair) {
+    if (installed === null && latest !== null) {
+        const run = usesApply(latest) ? async (context) => (await applyFlow(context, latest)) && (await moveSkills(context, latest)) : (context) => runFlow(context, latest, ["init", "--yes"]);
+        return { piece: NAME, checked: true, downloads: [`${FLOW_PACKAGE}@${latest}`], label: `Instalar issue-flow ${latest}: config del flujo, hooks y scripts`, run };
+    }
+    if (installed !== null && latest !== null && compareVersions(latest, installed) > 0) {
+        const update = (context) => (usesApply(latest) ? applyFlow(context, latest) : runFlow(context, latest, ["upgrade"]));
+        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 update(context)) && (await moveSkills(context, latest)) };
+    }
+    if (installed !== null && repair)
+        return { piece: NAME, checked: true, downloads: [`${FLOW_PACKAGE}@${installed}`], label: `Reparar issue-flow ${installed}: hooks y $schema`, run: async (context) => (await applyFlow(context, installed)) && (skillsOff(context.root, installed).length === 0 || (await moveSkills(context, installed))) };
     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;
@@ -153,13 +281,14 @@ export async function issueFlowStatus(root) {
         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 behind = installed !== null && latest !== null && compareVersions(latest, installed) > 0;
     const target = installed === null || behind ? latest : installed;
-    const missing = target === null ? [] : await missingLabels(root, target);
+    const [missing, checks, minimum] = await Promise.all([target === null ? [] : missingLabels(root, target), installed !== null && !behind && usesApply(installed) ? flowDoctor(root, installed, true) : null, target === null ? null : restMinimum(target)]);
+    const step = stepFor(installed, latest, root, installed !== null && checks !== null && needsRepair(checks, installed));
+    const rest = target === null || minimum === null ? null : restStep(root, target, minimum);
     const known = `${latest === null ? " (npm no responde)" : ""}${missing === null ? " (no se pudieron leer los labels de GitHub)" : ""}`;
     const state = installed === null ? `no instalado${known}` : behind ? `${installed}, hay ${latest}${known}` : `${installed}, al día${known}`;
-    const steps = [...(step === null ? [] : [step]), ...(target !== null && missing !== null && missing.length > 0 ? [labelsStep(target, missing)] : [])];
+    const steps = [...(step === null ? [] : [step]), ...(rest === null ? [] : [rest]), ...(target !== null && missing !== null && missing.length > 0 ? [labelsStep(target, missing)] : [])];
     return { name: NAME, summary, installed: installed !== null, state, steps };
 }
 /**
@@ -178,15 +307,8 @@ export async function issueFlowChecks(root) {
     if (compareVersions(installed, JSON_DOCTOR) < 0)
         return [{ name: NAME, status: "info", detail: `${installed} no tiene doctor --json: corre npx agent-kitchen apply para actualizarlo` }];
     const labelsRead = missingLabels(root, installed);
-    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)
+    const found = await flowDoctor(root, installed);
+    const own = found !== null
         ? 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);

package/dist/pieces/skills-manager.d.ts

@@ -3,7 +3,9 @@
  * install and move the skills, so agent-kitchen is the one that knows the oldest version it
  * works with: it adds it when missing and raises an exact version below it, never lowers
  * one. A range or `workspace:` is the repo's own choice: it is left alone, with a warning if
- * the version it runs is too old. Only in a repo with package.json that uses skills.
+ * the version it runs is too old. Only in a repo that uses skills and has package.json, or
+ * gets one in this run from the flow's install: then the step makes package.json first, and
+ * the flow's `apply`, which never adds skills-manager, adds its own packages to it.
  */
 import { type Check, type PieceStatus } from "../piece.js";
 /** The piece's name, as `--skip` takes it. */
@@ -15,10 +17,11 @@ export declare const MIN_VERSION = "1.2.0";
  * package.json again when it runs.
  * @param root - The repo.
  * @param withSkills - Whether this run may install skills.
+ * @param flowComing - Whether this run installs the flow, which makes package.json if missing.
  * @returns The piece's status, or null where the piece does not apply.
- * @example skillsManagerStatus(root, true)?.state // "1.1.0, bajo 1.2.0"
+ * @example skillsManagerStatus(root, true, false)?.state // "1.1.0, bajo 1.2.0"
  */
-export declare function skillsManagerStatus(root: string, withSkills: boolean): PieceStatus | null;
+export declare function skillsManagerStatus(root: string, withSkills: boolean, flowComing: boolean): PieceStatus | null;
 /**
  * Whether the version of skills-manager the repo runs is the one agent-kitchen needs.
  * @param root - The repo.

package/dist/pieces/skills-manager.js

@@ -3,10 +3,12 @@
  * install and move the skills, so agent-kitchen is the one that knows the oldest version it
  * works with: it adds it when missing and raises an exact version below it, never lowers
  * one. A range or `workspace:` is the repo's own choice: it is left alone, with a warning if
- * the version it runs is too old. Only in a repo with package.json that uses skills.
+ * the version it runs is too old. Only in a repo that uses skills and has package.json, or
+ * gets one in this run from the flow's install: then the step makes package.json first, and
+ * the flow's `apply`, which never adds skills-manager, adds its own packages to it.
  */
 import { SKILLS_MANAGER, SKILLS_MANIFEST } from "../piece.js";
-import { dependencyVersion, installedVersion, readJson, setDependency } from "../repo.js";
+import { dependencyVersion, installedVersion, readJson, setDependency, writeJson } from "../repo.js";
 import { compareVersions, isRelease } from "../tools.js";
 /** The piece's name, as `--skip` takes it. */
 export const NAME = "skills-manager";
@@ -36,27 +38,46 @@ function below(version) {
     return compareVersions(version, MIN_VERSION) < 0;
 }
 /**
- * Whether the piece applies: the repo has package.json and uses skills, or this run may
- * install them.
+ * Whether the piece applies: the repo uses skills, or this run may install them, and it has
+ * package.json or the flow's install is about to make one.
  * @param root - The repo.
  * @param withSkills - Whether this run may install skills (`skills` is not left out).
+ * @param flowComing - Whether this run installs the flow.
  * @returns True if it applies.
  */
-function applies(root, withSkills) {
-    return readJson(root, "package.json") !== null && (withSkills || readJson(root, SKILLS_MANIFEST) !== null);
+function applies(root, withSkills, flowComing) {
+    return (flowComing || readJson(root, "package.json") !== null) && (withSkills || readJson(root, SKILLS_MANIFEST) !== null);
 }
 /**
  * What the repo has of skills-manager, and the step that raises it, if any. The step reads
  * package.json again when it runs.
  * @param root - The repo.
  * @param withSkills - Whether this run may install skills.
+ * @param flowComing - Whether this run installs the flow, which makes package.json if missing.
  * @returns The piece's status, or null where the piece does not apply.
- * @example skillsManagerStatus(root, true)?.state // "1.1.0, bajo 1.2.0"
+ * @example skillsManagerStatus(root, true, false)?.state // "1.1.0, bajo 1.2.0"
  */
-export function skillsManagerStatus(root, withSkills) {
-    if (!applies(root, withSkills))
+export function skillsManagerStatus(root, withSkills, flowComing) {
+    if (!applies(root, withSkills, flowComing))
         return null;
     const summary = "el CLI de las skills, que corre agent-kitchen";
+    if (readJson(root, "package.json") === null) {
+        const make = {
+            piece: NAME,
+            checked: true,
+            downloads: [`${SKILLS_MANAGER}@${MIN_VERSION}`],
+            label: `Crear package.json con skills-manager ${MIN_VERSION}`,
+            run: async (context) => {
+                if (readJson(context.root, "package.json") === null)
+                    writeJson(context.root, "package.json", { private: true, devDependencies: { [SKILLS_MANAGER]: MIN_VERSION } });
+                else if (pinned(context.root).kind === "missing")
+                    setDependency(context.root, SKILLS_MANAGER, MIN_VERSION);
+                context.note(`${SKILLS_MANAGER} ${MIN_VERSION} en package.json`);
+                return true;
+            },
+        };
+        return { name: NAME, summary, installed: false, state: "no hay package.json", steps: [make] };
+    }
     const now = pinned(root);
     if (now.kind === "other") {
         const old = now.runs !== null && below(now.runs) ? `; corre ${now.runs}, bajo ${MIN_VERSION}` : "";
@@ -91,7 +112,7 @@ export function skillsManagerStatus(root, withSkills) {
  * @example skillsManagerChecks(root)[0]?.status // "ok"
  */
 export function skillsManagerChecks(root) {
-    if (!applies(root, false))
+    if (!applies(root, false, false))
         return [];
     const now = pinned(root);
     if (now.kind === "missing")

package/dist/tools.d.ts

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

package/dist/tools.js

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

package/package.json

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