agent-kitchen 0.4.0 → 0.6.0

package/dist/pieces/issue-flow.js

@@ -1,20 +1,42 @@
 /**
  * @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.
+ * 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_PACKAGE } from "../piece.js";
-import { dependencyVersion, readJson } from "../repo.js";
+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. */
 const SKILLS_CATALOG_LABEL = "el catálogo";
 /** The first version whose `doctor` prints `--json`. */
 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.
@@ -80,18 +102,168 @@ 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).
+ * @param root - The repo.
+ * @param version - The flow's version.
+ * @returns Their names, none for a version without `labels sync`, or null if it could not tell.
+ * @example await missingLabels(root, "0.2.6") // ["spike"]
+ */
+async function missingLabels(root, version) {
+    if (compareVersions(version, LABELS_SINCE) < 0)
+        return [];
+    const result = await captureNpx(root, [`${FLOW_PACKAGE}@${version}`, "labels", "sync", "--dry-run", "--json"], true);
+    let found;
+    try {
+        found = JSON.parse(result?.out ?? "");
+    }
+    catch {
+        return null;
+    }
+    if (!isObject(found) || !Array.isArray(found.labels))
+        return null;
+    return found.labels.filter((label) => isObject(label) && label.status === "to-create").map((label) => String(label.name));
+}
+/**
+ * The step that makes in GitHub the labels the flow lacks, with its own command. It only
+ * runs if the repo has that version of the flow by then: not when its install or update
+ * was left out or failed.
+ * @param version - The flow's version.
+ * @param missing - The labels.
+ * @returns The step.
+ */
+function labelsStep(version, missing) {
+    return { piece: NAME, checked: true, downloads: [`${FLOW_PACKAGE}@${version}`], label: `Crear en GitHub los labels que faltan: ${missing.join(", ")}`, run: async (context) => {
+            if (flowVersion(context.root) !== version) {
+                context.note(`no se crearon: el repo no tiene issue-flow ${version}`);
+                return true;
+            }
+            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;
@@ -109,10 +281,15 @@ 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 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] };
+    const behind = installed !== null && latest !== null && compareVersions(latest, installed) > 0;
+    const target = installed === null || behind ? latest : installed;
+    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]), ...(rest === null ? [] : [rest]), ...(target !== null && missing !== null && missing.length > 0 ? [labelsStep(target, missing)] : [])];
+    return { name: NAME, summary, installed: installed !== null, state, steps };
 }
 /**
  * The flow's own doctor at the repo's version, and whether its skills are at that tag.
@@ -129,15 +306,9 @@ export async function issueFlowChecks(root) {
         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 apply 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)
+    const labelsRead = missingLabels(root, installed);
+    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);
@@ -147,5 +318,13 @@ export async function issueFlowChecks(root) {
         : 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 apply` };
-    return [...own, skills];
+    const missing = await labelsRead;
+    const labels = compareVersions(installed, LABELS_SINCE) < 0
+        ? []
+        : missing === null
+            ? [{ name: `${NAME}: labels`, status: "info", detail: "no se pudieron leer de GitHub" }]
+            : missing.length > 0
+                ? [{ name: `${NAME}: labels`, status: "info", detail: `faltan ${missing.join(", ")} en GitHub; corre npx agent-kitchen apply` }]
+                : [{ name: `${NAME}: labels`, status: "ok", detail: "GitHub tiene los que espera el flujo" }];
+    return [...own, skills, ...labels];
 }

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

@@ -0,0 +1,31 @@
+/**
+ * @file The version of `skills-manager` in the repo's package.json. agent-kitchen runs it to
+ * 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 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. */
+export declare const NAME = "skills-manager";
+/** The oldest `skills-manager` agent-kitchen works with: the first with `--replace`. */
+export declare const MIN_VERSION = "1.2.0";
+/**
+ * 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, false)?.state // "1.1.0, bajo 1.2.0"
+ */
+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.
+ * @returns The checks; none where the piece does not apply.
+ * @example skillsManagerChecks(root)[0]?.status // "ok"
+ */
+export declare function skillsManagerChecks(root: string): Check[];

package/dist/pieces/skills-manager.js

@@ -0,0 +1,127 @@
+/**
+ * @file The version of `skills-manager` in the repo's package.json. agent-kitchen runs it to
+ * 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 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, writeJson } from "../repo.js";
+import { compareVersions, isRelease } from "../tools.js";
+/** The piece's name, as `--skip` takes it. */
+export const NAME = "skills-manager";
+/** The oldest `skills-manager` agent-kitchen works with: the first with `--replace`. */
+export const MIN_VERSION = "1.2.0";
+/**
+ * What package.json has of skills-manager and, for a range, the version that runs: the one
+ * in node_modules, or the first x.y.z of the range.
+ * @param root - The repo.
+ * @returns What it has.
+ */
+function pinned(root) {
+    const spec = dependencyVersion(readJson(root, "package.json"), SKILLS_MANAGER);
+    if (spec === null)
+        return { kind: "missing" };
+    if (isRelease(spec))
+        return { kind: "exact", version: spec };
+    const floor = spec.startsWith("workspace:") ? null : (/\d+\.\d+\.\d+/.exec(spec)?.[0] ?? null);
+    return { kind: "other", spec, runs: installedVersion(root, SKILLS_MANAGER) ?? floor };
+}
+/**
+ * Whether a version is older than the one agent-kitchen needs.
+ * @param version - The version.
+ * @returns True if it is below the minimum.
+ */
+function below(version) {
+    return compareVersions(version, MIN_VERSION) < 0;
+}
+/**
+ * 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, 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, false)?.state // "1.1.0, bajo 1.2.0"
+ */
+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}` : "";
+        return { name: NAME, summary, installed: true, state: `package.json tiene ${now.spec}, no una versión exacta; no se toca${old}`, steps: [] };
+    }
+    if (now.kind === "exact" && !below(now.version))
+        return { name: NAME, summary, installed: true, state: `${now.version}, al día`, steps: [] };
+    const label = now.kind === "missing" ? `Agregar skills-manager ${MIN_VERSION} a package.json` : `Subir skills-manager ${now.version} → ${MIN_VERSION}, el mínimo de agent-kitchen`;
+    const state = now.kind === "missing" ? "no está en package.json" : `${now.version}, bajo ${MIN_VERSION}`;
+    const step = {
+        piece: NAME,
+        checked: true,
+        downloads: [`${SKILLS_MANAGER}@${MIN_VERSION}`],
+        label,
+        run: async (context) => {
+            const current = pinned(context.root);
+            if (current.kind === "missing" || (current.kind === "exact" && below(current.version))) {
+                setDependency(context.root, SKILLS_MANAGER, MIN_VERSION);
+                context.note(`${SKILLS_MANAGER} ${MIN_VERSION} en package.json`);
+            }
+            else
+                context.note("package.json ya tenía una versión que sirve");
+            return true;
+        },
+    };
+    return { name: NAME, summary, installed: now.kind !== "missing", state, steps: [step] };
+}
+/**
+ * Whether the version of skills-manager the repo runs is the one agent-kitchen needs.
+ * @param root - The repo.
+ * @returns The checks; none where the piece does not apply.
+ * @example skillsManagerChecks(root)[0]?.status // "ok"
+ */
+export function skillsManagerChecks(root) {
+    if (!applies(root, false, false))
+        return [];
+    const now = pinned(root);
+    if (now.kind === "missing")
+        return [{ name: NAME, status: "info", detail: `no está en package.json; corre npx agent-kitchen apply para fijar ${MIN_VERSION}` }];
+    if (now.kind === "exact")
+        return below(now.version)
+            ? [{ name: NAME, status: "fail", detail: `${now.version}, bajo ${MIN_VERSION}, el mínimo de agent-kitchen: corre npx agent-kitchen apply` }]
+            : [{ name: NAME, status: "ok", detail: `${now.version} (mínimo ${MIN_VERSION})` }];
+    if (now.runs !== null && below(now.runs))
+        return [{ name: NAME, status: "fail", detail: `${now.spec} corre ${now.runs}, bajo ${MIN_VERSION}, el mínimo de agent-kitchen: sube el rango` }];
+    return [{ name: NAME, status: "ok", detail: `${now.spec}${now.runs === null ? "" : `, corre ${now.runs}`}` }];
+}

package/dist/repo.d.ts

@@ -46,3 +46,23 @@ export declare function dependencyVersion(pkg: Record<string, unknown> | null, n
  * @example packageManager(root) // "pnpm"
  */
 export declare function packageManager(root: string): string;
+/**
+ * The version of a package installed in the repo's `node_modules`.
+ * @param root - The repo.
+ * @param name - The package.
+ * @returns Its version, or null if it is not installed.
+ * @example installedVersion(root, "@ramon-sg/skills-manager") // "1.3.0"
+ */
+export declare function installedVersion(root: string, name: string): string | null;
+/**
+ * Sets the version of a dependency in package.json, changing nothing else: the file keeps
+ * its indentation, line endings and key order. It changes the entry `dependencyVersion`
+ * reads (`devDependencies` first, then `dependencies`); a new one goes into
+ * `devDependencies`, in alphabetical order, as npm adds it.
+ * @param root - The repo.
+ * @param name - The package.
+ * @param version - The version.
+ * @throws KitError if package.json is missing or not a JSON object.
+ * @example setDependency(root, "@ramon-sg/skills-manager", "1.2.0")
+ */
+export declare function setDependency(root: string, name: string, version: string): void;

package/dist/repo.js

@@ -115,3 +115,54 @@ export function packageManager(root) {
         return field;
     return LOCKFILES.find(([file]) => existsSync(join(root, file)))?.[1] ?? "npm";
 }
+/**
+ * The version of a package installed in the repo's `node_modules`.
+ * @param root - The repo.
+ * @param name - The package.
+ * @returns Its version, or null if it is not installed.
+ * @example installedVersion(root, "@ramon-sg/skills-manager") // "1.3.0"
+ */
+export function installedVersion(root, name) {
+    const file = join(root, "node_modules", name, "package.json");
+    if (!existsSync(file))
+        return null;
+    try {
+        const pkg = JSON.parse(readFileSync(file, "utf8"));
+        return isObject(pkg) && typeof pkg.version === "string" ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Sets the version of a dependency in package.json, changing nothing else: the file keeps
+ * its indentation, line endings and key order. It changes the entry `dependencyVersion`
+ * reads (`devDependencies` first, then `dependencies`); a new one goes into
+ * `devDependencies`, in alphabetical order, as npm adds it.
+ * @param root - The repo.
+ * @param name - The package.
+ * @param version - The version.
+ * @throws KitError if package.json is missing or not a JSON object.
+ * @example setDependency(root, "@ramon-sg/skills-manager", "1.2.0")
+ */
+export function setDependency(root, name, version) {
+    const pkg = readJson(root, "package.json");
+    if (pkg === null)
+        throw new KitError("no hay package.json.");
+    const text = readFileSync(join(root, "package.json"), "utf8");
+    const indent = /^([ \t]+)"/m.exec(text)?.[1] ?? "  ";
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const [deps, dev] = [pkg.dependencies, pkg.devDependencies];
+    if (isObject(dev) && typeof dev[name] === "string")
+        dev[name] = version;
+    else if (isObject(deps) && typeof deps[name] === "string")
+        deps[name] = version;
+    else {
+        const entries = Object.entries(isObject(dev) ? dev : {});
+        const at = entries.findIndex(([key]) => key > name);
+        entries.splice(at === -1 ? entries.length : at, 0, [name, version]);
+        pkg.devDependencies = Object.fromEntries(entries);
+    }
+    const json = JSON.stringify(pkg, null, indent).replace(/\n/g, eol);
+    writeFileSync(join(root, "package.json"), /\r?\n$/.test(text) || text === "" ? `${json}${eol}` : json);
+}

package/dist/skills-files.d.ts

@@ -66,10 +66,12 @@ export declare function manifestCatalogs(root: string): {
  */
 export declare function pinCatalog(root: string, catalog: string, tag: string): boolean;
 /**
- * The `skills-manager` to run: the version the repo pins in package.json, so the lock is
- * written by the same version every time, or the latest 1.x.
+ * The `skills-manager` to run, so the lock is written by the same version every time: the
+ * exact version package.json pins (the one its install leaves, even before it runs), else
+ * the one in node_modules, else the range package.json has (npx cannot take `workspace:`),
+ * else the latest 1.x.
  * @param root - The repo.
  * @returns The npx spec.
- * @example skillsManagerSpec(root) // "@ramon-sg/skills-manager@1.1.0"
+ * @example skillsManagerSpec(root) // "@ramon-sg/skills-manager@1.2.0"
  */
 export declare function skillsManagerSpec(root: string): string;

package/dist/skills-files.js

@@ -1,15 +1,15 @@
 /**
  * @file What agent-kitchen reads of the files of `skills-manager`: which skills of a catalog
  * the lock has and at which tag (the lock is where the manifest's `paths.lock` says), the
- * catalog's source in the manifest, which `skills-manager` to run (the one the repo pins,
- * or the latest 1.x), the repo's own skills (folders the lock does not know), and updating
- * skills one by one, because `skills-manager update` takes a single name.
+ * catalog's source in the manifest, which `skills-manager` to run (the one the repo pins or
+ * has installed, or the latest 1.x), the repo's own skills (folders the lock does not know),
+ * and updating skills one by one, because `skills-manager update` takes a single name.
  */
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { dependencyVersion, isObject, readJson, writeJson } from "./repo.js";
+import { dependencyVersion, installedVersion, isObject, readJson, writeJson } from "./repo.js";
 import { SKILLS_LOCK, SKILLS_MANAGER, SKILLS_MANIFEST } from "./piece.js";
-import { runNpx } from "./tools.js";
+import { isRelease, runNpx } from "./tools.js";
 /** Where `skills-manager` puts the skills when the manifest does not say. */
 const SKILLS_DIR = ".agents/skills";
 /**
@@ -105,12 +105,18 @@ export function pinCatalog(root, catalog, tag) {
     return true;
 }
 /**
- * The `skills-manager` to run: the version the repo pins in package.json, so the lock is
- * written by the same version every time, or the latest 1.x.
+ * The `skills-manager` to run, so the lock is written by the same version every time: the
+ * exact version package.json pins (the one its install leaves, even before it runs), else
+ * the one in node_modules, else the range package.json has (npx cannot take `workspace:`),
+ * else the latest 1.x.
  * @param root - The repo.
  * @returns The npx spec.
- * @example skillsManagerSpec(root) // "@ramon-sg/skills-manager@1.1.0"
+ * @example skillsManagerSpec(root) // "@ramon-sg/skills-manager@1.2.0"
  */
 export function skillsManagerSpec(root) {
-    return `${SKILLS_MANAGER}@${dependencyVersion(readJson(root, "package.json"), SKILLS_MANAGER) ?? "1"}`;
+    const pinned = dependencyVersion(readJson(root, "package.json"), SKILLS_MANAGER);
+    if (pinned !== null && isRelease(pinned))
+        return `${SKILLS_MANAGER}@${pinned}`;
+    const range = pinned === null || pinned.startsWith("workspace:") ? null : pinned;
+    return `${SKILLS_MANAGER}@${installedVersion(root, SKILLS_MANAGER) ?? range ?? "1"}`;
 }

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;
+}>;