agent-kitchen 0.5.0 → 0.7.0

package/dist/pieces/guard.js

@@ -141,11 +141,11 @@ function installedVersion(root) {
  */
 function stepFor(root, installed, latest, flowComing) {
     if (installed === undefined)
-        return { piece: NAME, checked: true, downloads: [guardSpec(latest)], label: `Instalar claude-repo-guard ${latest ?? "(main)"}: modo auto con sandbox, y un documento de qué protege`, run: (context) => install(context, latest) };
+        return { piece: NAME, checked: true, downloads: [guardSpec(latest)], text: { kind: "guard-install", version: latest }, run: (context) => install(context, latest) };
     if (latest !== null && (installed === null || compareVersions(latest, installed) > 0))
-        return { piece: NAME, checked: true, downloads: [guardSpec(latest)], label: `Actualizar claude-repo-guard ${installed ?? "?"} → ${latest}`, run: (context) => install(context, latest) };
+        return { piece: NAME, checked: true, downloads: [guardSpec(latest)], text: { kind: "guard-update", from: installed, to: latest }, run: (context) => install(context, latest) };
     if (flowComing || guardOptions(root, process.platform).changes.length > 0)
-        return { piece: NAME, checked: true, downloads: [guardSpec(installed)], label: "Ajustar claude-repo-guard a lo que necesita el flujo de issues", run: (context) => addOptions(context, installed) };
+        return { piece: NAME, checked: true, downloads: [guardSpec(installed)], text: { kind: "guard-adjust" }, run: (context) => addOptions(context, installed) };
     return null;
 }
 /**

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

@@ -1,11 +1,17 @@
 /**
  * @file The issue flow (`@ramon-sg/issue-flow`): its CLI, hooks and config, and its skills.
- * The repo's version is the one in package.json. Installing runs its `init` at the latest
- * version; updating runs its `upgrade` at the new one and then moves its skills to the same
- * tag, because the skills call the CLI. If only the skills are off, it moves them alone.
- * From 0.2.6 it also offers `labels sync`, after the install or update, when GitHub lacks
- * some of the labels the flow expects.
- * `init` runs with `--yes`: the person answered agent-kitchen's questions before the steps.
+ * The repo's version is the one in package.json. From 0.3.0, installing and updating run its
+ * `apply` at the latest version, and reading its `--json` tells what it kept as it was; at
+ * the repo's version, `apply` also repairs hooks or a `$schema` its doctor finds behind (a
+ * version raised by hand or by Dependabot). Before 0.3.0, installing runs `init` and
+ * updating runs `upgrade`. After updating or repairing, and after installing with `apply`,
+ * the flow's skills move to the same tag, because they call the CLI. If only the skills are
+ * off, they move alone. From 0.2.6 it also offers `labels sync`, after the install or
+ * update, when GitHub lacks some of the labels the flow expects. From 0.3.0, whose `apply`
+ * keeps the repo's github-rest, it also raises an exact github-rest below the floor of the
+ * range that version of the flow declares on npm, as the flow itself reads it.
+ * `apply` and `init` run with `--yes`: the person answered agent-kitchen's questions before
+ * the steps.
  */
 import { type Check, type PieceStatus } from "../piece.js";
 /** The piece's name, as `--skip` takes it. */

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).
@@ -116,7 +197,7 @@ async function missingLabels(root, version) {
  * @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) => {
+    return { piece: NAME, checked: true, downloads: [`${FLOW_PACKAGE}@${version}`], text: { kind: "flow-labels", missing }, run: async (context) => {
             if (flowVersion(context.root) !== version) {
                 context.note(`no se crearon: el repo no tiene issue-flow ${version}`);
                 return true;
@@ -124,20 +205,67 @@ 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: [], text: { kind: "github-rest-bump", from: current, to: minimum, 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}`], text: { kind: "flow-install", version: latest }, 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}`], text: { kind: "flow-update", from: installed, to: latest }, run: async (context) => (await update(context)) && (await moveSkills(context, latest)) };
+    }
+    if (installed !== null && repair)
+        return { piece: NAME, checked: true, downloads: [`${FLOW_PACKAGE}@${installed}`], text: { kind: "flow-repair", version: installed }, 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 { piece: NAME, checked: true, downloads: [], text: { kind: "flow-skills", version: installed }, 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}`],
+            text: { kind: "skills-manager-create", version: 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}` : "";
@@ -64,13 +85,13 @@ export function skillsManagerStatus(root, withSkills) {
     }
     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 text = now.kind === "missing" ? { kind: "skills-manager-add", version: MIN_VERSION } : { kind: "skills-manager-bump", from: now.version, to: MIN_VERSION };
     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,
+        text,
         run: async (context) => {
             const current = pinned(context.root);
             if (current.kind === "missing" || (current.kind === "exact" && below(current.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/pieces/skills.js

@@ -174,7 +174,7 @@ async function updateStep(root, catalog, ref) {
         piece: NAME,
         checked: true,
         downloads: [skillsManagerSpec(root)],
-        label: `Actualizar skills de ${catalog} ${from} → v${latest}: ${behind.map((skill) => skill.name).join(", ")}`,
+        text: { kind: "skills-update", catalog, from, to: latest, names: behind.map((skill) => skill.name) },
         run: async (context) => {
             if (ref !== null)
                 pinCatalog(context.root, catalog, `v${latest}`);
@@ -215,10 +215,9 @@ export async function skillsStatus(root, withFlow) {
         });
         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) }] };
+        return { name: NAME, summary, installed: false, state, steps: [{ piece: NAME, checked: true, downloads: [], text: { kind: "skills-install", count: offered.length, catalogs }, 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 ?? []);
@@ -227,7 +226,7 @@ export async function skillsStatus(root, withFlow) {
     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) });
+        steps.push({ piece: NAME, checked: false, downloads: [skillsManagerSpec(root)], text: { kind: "skills-add", names: fresh.map((candidate) => candidate.name) }, 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;

package/dist/progress.d.ts

@@ -0,0 +1,29 @@
+import type { Output } from "./output.js";
+import type { StepText } from "./texts/step-text.js";
+/** How a step's progress is shown. */
+export interface Progress {
+    start: (text: StepText) => void;
+    stop: (text: StepText, ok: boolean) => void;
+}
+/**
+ * Progress as plain lines: the start, a line now and then while it runs, and the end.
+ * @param out - Where to write.
+ * @param options - Whether to print while it runs, how often, and the clock.
+ * @returns The progress.
+ * @example plainProgress(out, { ticks: true }).start({ kind: "guard-adjust" })
+ */
+export declare function plainProgress(out: Output, options: {
+    ticks: boolean;
+    tickMs?: number;
+    now?: () => number;
+}): Progress;
+/**
+ * How progress is shown: a spinner in a terminal, plain lines otherwise or when `plain` asks
+ * for them. Only for the steps, after every question: a spinner shown before a question
+ * leaves the second question deaf to the keyboard (@clack/prompts 1.8.1).
+ * @param out - Where to write.
+ * @param verbose - Whether the tools print on the terminal.
+ * @param plain - Whether a question may come after the steps (`--commit`).
+ * @returns The progress.
+ */
+export declare function progressFor(out: Output, verbose: boolean, plain: boolean): Progress;

package/dist/progress.js

@@ -0,0 +1,75 @@
+/**
+ * @file How a step's progress is shown. Its start says what is happening ("Actualizando…") and
+ * its end what is left, with how long it took. In a terminal, a spinner; otherwise plain
+ * lines, and a step that takes a while prints how long it has been running, so it does not
+ * look stuck (unless the tools print their own output, with `--verbose`).
+ */
+import { spinner } from "@clack/prompts";
+import { phrases, ui } from "./texts/index.js";
+/** How often a plain step says it is still running. */
+const TICK_MS = 10_000;
+/**
+ * The end line of a step.
+ * @param text - What the step does.
+ * @param ok - Whether it worked.
+ * @param ms - How long it took.
+ * @returns The line, without the mark.
+ */
+function endLine(text, ok, ms) {
+    const said = phrases(text);
+    return `${ok ? said.done : ui.failed(said.menu)} (${ui.duration(ms)})`;
+}
+/**
+ * Progress as plain lines: the start, a line now and then while it runs, and the end.
+ * @param out - Where to write.
+ * @param options - Whether to print while it runs, how often, and the clock.
+ * @returns The progress.
+ * @example plainProgress(out, { ticks: true }).start({ kind: "guard-adjust" })
+ */
+export function plainProgress(out, options) {
+    const now = options.now ?? Date.now;
+    let started = 0;
+    let timer;
+    return {
+        start: (text) => {
+            started = now();
+            out.stdout(`${phrases(text).doing}\n`);
+            if (options.ticks)
+                timer = setInterval(() => out.stdout(`${ui.still(ui.duration(now() - started))}\n`), options.tickMs ?? TICK_MS);
+        },
+        stop: (text, ok) => {
+            clearInterval(timer);
+            timer = undefined;
+            out.stdout(`${ok ? "✓" : "✗"} ${endLine(text, ok, now() - started)}\n`);
+        },
+    };
+}
+/**
+ * How progress is shown: a spinner in a terminal, plain lines otherwise or when `plain` asks
+ * for them. Only for the steps, after every question: a spinner shown before a question
+ * leaves the second question deaf to the keyboard (@clack/prompts 1.8.1).
+ * @param out - Where to write.
+ * @param verbose - Whether the tools print on the terminal.
+ * @param plain - Whether a question may come after the steps (`--commit`).
+ * @returns The progress.
+ */
+export function progressFor(out, verbose, plain) {
+    if (out.interactive && !verbose && !plain) {
+        const spin = spinner();
+        let started = 0;
+        return {
+            start: (text) => {
+                started = Date.now();
+                spin.start(phrases(text).doing);
+            },
+            stop: (text, ok) => {
+                const line = endLine(text, ok, Date.now() - started);
+                if (ok)
+                    spin.stop(line);
+                else
+                    spin.error(line);
+            },
+        };
+    }
+    return plainProgress(out, { ticks: !verbose });
+}

package/dist/texts/catalog.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @file The shape of a catalog of the texts the person sees while `apply` runs its steps.
+ * Every language implements `Catalog`; the compiler then asks for every kind of step and every
+ * message. The interface uses `ui`; the commit and the PR do not (see commit-texts.ts).
+ */
+import type { StepKind, StepOf } from "./step-text.js";
+/** One step's texts, one per place it shows. */
+export interface StepPhrases {
+    /** In the menu and the lists of steps, as an order: "Actualizar issue-flow 0.2.7 → 0.3.0". */
+    menu: string;
+    /** While it runs: "Actualizando issue-flow de 0.2.7 a 0.3.0…". */
+    doing: string;
+    /** When it worked, saying what is left: "issue-flow actualizado de 0.2.7 a 0.3.0". */
+    done: string;
+}
+/** Every text of `apply` around its steps. */
+export interface Catalog {
+    /** Each kind of step's texts. */
+    steps: {
+        [K in StepKind]: (step: StepOf<K>) => StepPhrases;
+    };
+    /** Added to a step of a piece the repo has not decided on yet. */
+    fresh: string;
+    /** The end line of a step that failed, from its menu text. */
+    failed: (menu: string) => string;
+    /** A duration, short: "0,4 s", "12 s", "1 min 5 s". */
+    duration: (ms: number) => string;
+    /** The line a long step prints while it runs, so it does not look stuck. */
+    still: (elapsed: string) => string;
+    /** The line before looking at the pieces. */
+    checking: string;
+    /** Nothing to install or update. */
+    upToDate: string;
+    /** With --yes and nothing suggested: the optional steps. */
+    onlyOptional: (menus: string[]) => string;
+    /** The heading of the steps listed without running them. */
+    suggested: (dryRun: boolean) => string;
+    /** The last line when every step worked or some failed. */
+    summary: (failed: string[]) => string;
+    /** What is left to do by hand after the steps, without --commit. */
+    next: (manager: string) => string;
+    /** A new piece left out because no one was asked about it. */
+    undecided: (names: string[]) => string;
+    /** The repo's own skills left out of a pick. */
+    ownSkillsKept: (names: string[]) => string;
+    /** The decisions were saved. */
+    saved: (file: string, commits: boolean) => string;
+    /** The closing line when no step ran: the person left, or picked none. */
+    noSteps: (why: "leave" | "none", wrote: boolean) => string;
+}

package/dist/texts/catalog.js

@@ -0,0 +1 @@
+export {};

package/dist/texts/es.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @file The texts in Spanish. The menu orders ("Actualizar"), progress says what is happening
+ * ("Actualizando") and the end line says what is left ("actualizado").
+ */
+import type { Catalog } from "./catalog.js";
+/** The texts in Spanish. */
+export declare const es: Catalog;