agent-kitchen 0.2.0 → 0.3.0

package/dist/skills-files.js

@@ -2,12 +2,16 @@
  * @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), and updating skills one by one, because `skills-manager update`
- * takes a single name.
+ * 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 { SKILLS_LOCK, SKILLS_MANAGER, SKILLS_MANIFEST } from "./piece.js";
 import { runNpx } from "./tools.js";
+/** Where `skills-manager` puts the skills when the manifest does not say. */
+const SKILLS_DIR = ".agents/skills";
 /**
  * Where the repo's skills lock is: the manifest's `paths.lock`, or the default.
  * @param root - The repo.
@@ -32,13 +36,32 @@ export function lockedSkills(root) {
  * Runs `skills-manager update <name>` for each skill, stopping at the first that fails.
  * @param root - The repo.
  * @param names - The skills.
- * @returns The command that failed, to retry it, or null if every one worked.
- * @example updateSkills(root, ["close-pr", "pr-review-comments"]) // null
+ * @returns Null if every one worked, or the command that failed, to retry it, and what it printed.
+ * @example await updateSkills(root, ["close-pr", "pr-review-comments"]) // null
  */
-export function updateSkills(root, names) {
+export async function updateSkills(root, names) {
     const spec = skillsManagerSpec(root);
-    const failed = names.find((name) => !runNpx(root, [spec, "update", name]));
-    return failed === undefined ? null : `npx ${spec} update ${failed}`;
+    for (const name of names) {
+        const run = await runNpx(root, [spec, "update", name]);
+        if (!run.ok)
+            return { command: `npx ${spec} update ${name}`, run };
+    }
+    return null;
+}
+/**
+ * The repo's own skills among some names: a folder in the skills folder that the lock does
+ * not know, which `skills-manager` replaces only when allowed.
+ * @param root - The repo.
+ * @param names - The skills about to be installed.
+ * @returns The names that are the repo's own.
+ * @example ownSkills(root, ["planning", "code-audit"]) // ["planning"]
+ */
+export function ownSkills(root, names) {
+    const paths = readJson(root, SKILLS_MANIFEST)?.paths;
+    const dir = join(root, isObject(paths) && typeof paths.skillsDir === "string" && paths.skillsDir !== "" ? paths.skillsDir : SKILLS_DIR);
+    const folders = existsSync(dir) ? readdirSync(dir) : [];
+    const locked = lockedSkills(root);
+    return [...new Set(names)].filter((name) => folders.includes(name) && locked[name] === undefined);
 }
 /**
  * The skills of a catalog in the repo's lock.

package/dist/tools.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Shows the tools' output as it comes instead of only when they fail.
+ * @param value - True for `--verbose`.
+ * @example setVerbose(true)
+ */
+export declare function setVerbose(value: boolean): void;
 /**
  * Compares two release versions.
  * @param left - A version like 0.2.0.
@@ -14,35 +20,58 @@ export declare function compareVersions(left: string, right: string): number;
  */
 export declare function isRelease(version: string): boolean;
 /**
- * Runs `npx --yes <args>` in the repo, with its output and questions on this terminal.
+ * The latest version of a package on npm.
+ * @param name - The package.
+ * @returns The version, or null if npm cannot tell.
+ * @example await npmLatest("@ramon-sg/claude-cloud") // "1.0.0"
+ */
+export declare function npmLatest(name: string): Promise<string | null>;
+/**
+ * The highest `vX.Y.Z` tag of a GitHub repo.
+ * @param repo - The repo, as owner/name.
+ * @returns The version without the `v`, or null if it has none or git cannot reach it.
+ * @example await latestTag("ramon-sg/agent-skills") // "0.1.0"
+ */
+export declare function latestTag(repo: string): Promise<string | null>;
+/**
+ * Downloads a package into npx's cache without running it, once per package, so its step
+ * starts at once. A failed download is ignored: the step itself will say what failed.
  * @param root - The repo.
- * @param args - The package and its arguments.
- * @returns Whether it exited 0.
- * @example runNpx(root, ["@ramon-sg/claude-cloud@1.0.0", "init"])
+ * @param spec - The package, as npx takes it.
+ * @returns When it is done.
+ * @example void download(root, "@ramon-sg/claude-cloud@1.0.0")
  */
-export declare function runNpx(root: string, args: string[]): boolean;
+export declare function download(root: string, spec: string): Promise<void>;
+/** How a tool ended, and what it printed if it was kept. */
+export interface ToolRun {
+    ok: boolean;
+    output: string;
+}
 /**
- * Runs `npx --yes <args>` in the repo and returns what it printed.
+ * Runs `npx --yes <args>` in the repo: quietly, or with its output on the terminal with
+ * `--verbose`. It must not ask anything: the person answered before the steps ran.
  * @param root - The repo.
  * @param args - The package and its arguments.
- * @returns Its stdout and exit code, or null if npx could not start.
- * @example captureNpx(root, ["@ramon-sg/issue-flow@0.2.0", "doctor", "--json"])
+ * @returns Whether it exited 0, and what it printed.
+ * @example await runNpx(root, ["@ramon-sg/claude-cloud@1.0.0", "init"])
  */
-export declare function captureNpx(root: string, args: string[]): {
-    out: string;
-    status: number | null;
-} | null;
+export declare function runNpx(root: string, args: string[]): Promise<ToolRun>;
 /**
- * The latest version of a package on npm.
- * @param name - The package.
- * @returns The version, or null if npm cannot tell.
- * @example npmLatest("@ramon-sg/claude-cloud") // "1.0.0"
+ * The end of a failed tool's output, indented, to show under its step.
+ * @param output - What it printed.
+ * @returns Its last lines, or an empty text.
+ * @example failedOutput("npm error 404\n") // "    npm error 404\n"
  */
-export declare function npmLatest(name: string): string | null;
+export declare function failedOutput(output: string): string;
 /**
- * The highest `vX.Y.Z` tag of a GitHub repo.
- * @param repo - The repo, as owner/name.
- * @returns The version without the `v`, or null if it has none or git cannot reach it.
- * @example latestTag("ramon-sg/agent-skills") // "0.1.0"
+ * Runs `npx --yes <args>` in the repo and returns what it printed on stdout.
+ * @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.
+ * @example await captureNpx(root, ["@ramon-sg/issue-flow@0.2.0", "doctor", "--json"])
  */
-export declare function latestTag(repo: string): string | null;
+export declare function captureNpx(root: string, args: string[], lookup?: boolean): Promise<{
+    out: string;
+    status: number | null;
+} | null>;

package/dist/tools.js

@@ -2,16 +2,36 @@
  * @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
- * `vX.Y.Z` tag on GitHub. A lookup that fails, or takes over 20 seconds, gives null: the
- * piece is shown, not offered. git never asks for credentials here.
+ * `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.
+ *
+ * The tools run quietly: their output is kept and shown only when they fail, so the person
+ * reads one line per step. `--verbose` shows it as it comes.
  */
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 /** A release version. */
 const VERSION = /^(\d+)\.(\d+)\.(\d+)$/;
 /** How long a lookup of the latest version may take before it counts as unknown. */
 const LOOKUP_TIMEOUT_MS = 20_000;
 /** A release tag in `git ls-remote --tags --refs` output. */
 const TAG_REF = /refs\/tags\/v(\d+\.\d+\.\d+)$/;
+/** How many lines of a failed tool's output are shown. */
+const FAILED_LINES = 25;
+/** Whether the tools' output goes straight to the terminal. */
+let verbose = false;
+/** Lookups already started, by what they look up. */
+const lookups = new Map();
+/** Downloads already started, by package. */
+const downloads = new Map();
+/**
+ * Shows the tools' output as it comes instead of only when they fail.
+ * @param value - True for `--verbose`.
+ * @example setVerbose(true)
+ */
+export function setVerbose(value) {
+    verbose = value;
+}
 /**
  * Compares two release versions.
  * @param left - A version like 0.2.0.
@@ -39,47 +59,117 @@ export function isRelease(version) {
     return VERSION.test(version);
 }
 /**
- * Runs `npx --yes <args>` in the repo, with its output and questions on this terminal.
- * @param root - The repo.
- * @param args - The package and its arguments.
- * @returns Whether it exited 0.
- * @example runNpx(root, ["@ramon-sg/claude-cloud@1.0.0", "init"])
+ * Runs a program and collects what it prints.
+ * @param program - The program.
+ * @param args - Its arguments.
+ * @param options - The folder, a time limit, extra variables, and whether its output goes to the terminal.
+ * @returns How it ended; status null if it could not start or ran out of time.
  */
-export function runNpx(root, args) {
-    return spawnSync("npx", ["--yes", ...args], { cwd: root, stdio: "inherit" }).status === 0;
+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"] });
+        let out = "";
+        let err = "";
+        child.stdout?.on("data", (chunk) => (out += chunk.toString()));
+        child.stderr?.on("data", (chunk) => (err += chunk.toString()));
+        const timer = options.timeout === undefined ? undefined : setTimeout(() => child.kill(), options.timeout);
+        child.on("error", () => resolve({ status: null, out, err }));
+        child.on("close", (code, signal) => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            resolve({ status: signal === null ? code : null, out, err });
+        });
+    });
 }
 /**
- * Runs `npx --yes <args>` in the repo and returns what it printed.
- * @param root - The repo.
- * @param args - The package and its arguments.
- * @returns Its stdout and exit code, or null if npx could not start.
- * @example captureNpx(root, ["@ramon-sg/issue-flow@0.2.0", "doctor", "--json"])
+ * Runs a lookup once: later calls get the same promise.
+ * @param key - What it looks up.
+ * @param lookup - How.
+ * @returns Its result.
  */
-export function captureNpx(root, args) {
-    const result = spawnSync("npx", ["--yes", ...args], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] });
-    return result.error === undefined ? { out: result.stdout, status: result.status } : null;
+function once(key, lookup) {
+    const known = lookups.get(key);
+    if (known !== undefined)
+        return known;
+    const started = lookup();
+    lookups.set(key, started);
+    return started;
 }
 /**
  * The latest version of a package on npm.
  * @param name - The package.
  * @returns The version, or null if npm cannot tell.
- * @example npmLatest("@ramon-sg/claude-cloud") // "1.0.0"
+ * @example await npmLatest("@ramon-sg/claude-cloud") // "1.0.0"
  */
 export function npmLatest(name) {
-    const result = spawnSync("npm", ["view", name, "version", "--fetch-retries=0"], { encoding: "utf8", timeout: LOOKUP_TIMEOUT_MS });
-    const version = result.status === 0 ? result.stdout.trim() : "";
-    return isRelease(version) ? version : null;
+    return once(`npm:${name}`, async () => {
+        const result = await run("npm", ["view", name, "version", "--fetch-retries=0"], { timeout: LOOKUP_TIMEOUT_MS });
+        const version = result.status === 0 ? result.out.trim() : "";
+        return isRelease(version) ? version : null;
+    });
 }
 /**
  * The highest `vX.Y.Z` tag of a GitHub repo.
  * @param repo - The repo, as owner/name.
  * @returns The version without the `v`, or null if it has none or git cannot reach it.
- * @example latestTag("ramon-sg/agent-skills") // "0.1.0"
+ * @example await latestTag("ramon-sg/agent-skills") // "0.1.0"
  */
 export function latestTag(repo) {
-    const result = spawnSync("git", ["ls-remote", "--tags", "--refs", `https://github.com/${repo}.git`], { encoding: "utf8", timeout: LOOKUP_TIMEOUT_MS, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } });
-    if (result.status !== 0)
-        return null;
-    const versions = result.stdout.split("\n").flatMap((line) => TAG_REF.exec(line.trim())?.slice(1, 2) ?? []);
-    return versions.sort(compareVersions).at(-1) ?? null;
+    return once(`tag:${repo}`, async () => {
+        const result = await run("git", ["ls-remote", "--tags", "--refs", `https://github.com/${repo}.git`], { timeout: LOOKUP_TIMEOUT_MS, env: { GIT_TERMINAL_PROMPT: "0" } });
+        if (result.status !== 0)
+            return null;
+        const versions = result.out.split("\n").flatMap((line) => TAG_REF.exec(line.trim())?.slice(1, 2) ?? []);
+        return versions.sort(compareVersions).at(-1) ?? null;
+    });
+}
+/**
+ * Downloads a package into npx's cache without running it, once per package, so its step
+ * starts at once. A failed download is ignored: the step itself will say what failed.
+ * @param root - The repo.
+ * @param spec - The package, as npx takes it.
+ * @returns When it is done.
+ * @example void download(root, "@ramon-sg/claude-cloud@1.0.0")
+ */
+export function download(root, spec) {
+    const known = downloads.get(spec);
+    if (known !== undefined)
+        return known;
+    const started = run("npx", ["--yes", "--package", spec, "--", "node", "-e", ""], { cwd: root }).then(() => undefined);
+    downloads.set(spec, started);
+    return started;
+}
+/**
+ * Runs `npx --yes <args>` in the repo: quietly, or with its output on the terminal with
+ * `--verbose`. It must not ask anything: the person answered before the steps ran.
+ * @param root - The repo.
+ * @param args - The package and its arguments.
+ * @returns Whether it exited 0, and what it printed.
+ * @example await runNpx(root, ["@ramon-sg/claude-cloud@1.0.0", "init"])
+ */
+export async function runNpx(root, args) {
+    const result = await run("npx", ["--yes", ...args], { cwd: root, inherit: verbose });
+    return { ok: result.status === 0, output: `${result.out}${result.err}` };
+}
+/**
+ * The end of a failed tool's output, indented, to show under its step.
+ * @param output - What it printed.
+ * @returns Its last lines, or an empty text.
+ * @example failedOutput("npm error 404\n") // "    npm error 404\n"
+ */
+export function failedOutput(output) {
+    const lines = output.trimEnd().split("\n").filter((line) => line.trim() !== "");
+    return lines.slice(-FAILED_LINES).map((line) => `    ${line}\n`).join("");
+}
+/**
+ * Runs `npx --yes <args>` in the repo and returns what it printed on stdout.
+ * @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.
+ * @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 };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-kitchen",
-  "version": "0.2.0",
+  "version": "0.3.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 and claude-repo-guard.",
   "license": "MIT",
   "type": "module",