agent-kitchen 0.0.0-stage → 0.3.0

package/dist/skills-files.d.ts

@@ -0,0 +1,75 @@
+import { type ToolRun } from "./tools.js";
+/** A skill in the lock: its name and the tag it is at. */
+export interface LockedSkill {
+    name: string;
+    tag: string | null;
+}
+/**
+ * Where the repo's skills lock is: the manifest's `paths.lock`, or the default.
+ * @param root - The repo.
+ * @returns The path, relative to the repo.
+ * @example lockPath(root) // ".agents/skills.lock.json"
+ */
+export declare function lockPath(root: string): string;
+/**
+ * Every skill in the repo's lock, by name.
+ * @param root - The repo.
+ * @returns The lock's entries.
+ * @example Object.keys(lockedSkills(root)) // ["close-pr", "code-audit"]
+ */
+export declare function lockedSkills(root: string): Record<string, unknown>;
+/**
+ * Runs `skills-manager update <name>` for each skill, stopping at the first that fails.
+ * @param root - The repo.
+ * @param names - The skills.
+ * @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 declare function updateSkills(root: string, names: string[]): Promise<{
+    command: string;
+    run: ToolRun;
+} | 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 declare function ownSkills(root: string, names: string[]): string[];
+/**
+ * The skills of a catalog in the repo's lock.
+ * @param root - The repo.
+ * @param catalog - The catalog, as owner/name.
+ * @returns Name and tag of each one.
+ * @example catalogSkills(root, "ramon-sg/issue-flow") // [{ name: "close-pr", tag: "v0.2.0" }]
+ */
+export declare function catalogSkills(root: string, catalog: string): LockedSkill[];
+/**
+ * The catalogs in the repo's skills manifest, with the ref each one is pinned to.
+ * @param root - The repo.
+ * @returns Each catalog and its ref (null if it follows the latest release).
+ * @example manifestCatalogs(root) // [{ catalog: "ramon-sg/issue-flow", ref: "v0.2.0" }]
+ */
+export declare function manifestCatalogs(root: string): {
+    catalog: string;
+    ref: string | null;
+}[];
+/**
+ * Pins a catalog of the manifest to a tag, so `skills-manager update` moves its skills there.
+ * @param root - The repo.
+ * @param catalog - The catalog.
+ * @param tag - The tag, like v0.2.0.
+ * @returns Whether the manifest has the catalog.
+ * @example pinCatalog(root, "ramon-sg/issue-flow", "v0.2.0") // true
+ */
+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.
+ * @param root - The repo.
+ * @returns The npx spec.
+ * @example skillsManagerSpec(root) // "@ramon-sg/skills-manager@1.1.0"
+ */
+export declare function skillsManagerSpec(root: string): string;

package/dist/skills-files.js

@@ -0,0 +1,116 @@
+/**
+ * @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.
+ */
+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.
+ * @returns The path, relative to the repo.
+ * @example lockPath(root) // ".agents/skills.lock.json"
+ */
+export function lockPath(root) {
+    const paths = readJson(root, SKILLS_MANIFEST)?.paths;
+    return isObject(paths) && typeof paths.lock === "string" && paths.lock !== "" ? paths.lock : SKILLS_LOCK;
+}
+/**
+ * Every skill in the repo's lock, by name.
+ * @param root - The repo.
+ * @returns The lock's entries.
+ * @example Object.keys(lockedSkills(root)) // ["close-pr", "code-audit"]
+ */
+export function lockedSkills(root) {
+    const lock = readJson(root, lockPath(root));
+    return isObject(lock?.skills) ? lock.skills : {};
+}
+/**
+ * Runs `skills-manager update <name>` for each skill, stopping at the first that fails.
+ * @param root - The repo.
+ * @param names - The skills.
+ * @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 async function updateSkills(root, names) {
+    const spec = skillsManagerSpec(root);
+    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.
+ * @param root - The repo.
+ * @param catalog - The catalog, as owner/name.
+ * @returns Name and tag of each one.
+ * @example catalogSkills(root, "ramon-sg/issue-flow") // [{ name: "close-pr", tag: "v0.2.0" }]
+ */
+export function catalogSkills(root, catalog) {
+    const skills = lockedSkills(root);
+    return Object.entries(skills)
+        .filter(([, entry]) => isObject(entry) && entry.source === `catalog:${catalog}`)
+        .map(([name, entry]) => ({ name, tag: isObject(entry) && typeof entry.tag === "string" ? entry.tag : null }));
+}
+/**
+ * The catalogs in the repo's skills manifest, with the ref each one is pinned to.
+ * @param root - The repo.
+ * @returns Each catalog and its ref (null if it follows the latest release).
+ * @example manifestCatalogs(root) // [{ catalog: "ramon-sg/issue-flow", ref: "v0.2.0" }]
+ */
+export function manifestCatalogs(root) {
+    const manifest = readJson(root, SKILLS_MANIFEST);
+    const sources = Array.isArray(manifest?.sources) ? manifest.sources.filter(isObject) : [];
+    return sources.flatMap((source) => (typeof source.catalog === "string" ? [{ catalog: source.catalog, ref: typeof source.ref === "string" ? source.ref : null }] : []));
+}
+/**
+ * Pins a catalog of the manifest to a tag, so `skills-manager update` moves its skills there.
+ * @param root - The repo.
+ * @param catalog - The catalog.
+ * @param tag - The tag, like v0.2.0.
+ * @returns Whether the manifest has the catalog.
+ * @example pinCatalog(root, "ramon-sg/issue-flow", "v0.2.0") // true
+ */
+export function pinCatalog(root, catalog, tag) {
+    const manifest = readJson(root, SKILLS_MANIFEST);
+    const sources = Array.isArray(manifest?.sources) ? manifest.sources : [];
+    if (manifest === null || !sources.some((source) => isObject(source) && source.catalog === catalog))
+        return false;
+    const moved = sources.map((source) => (isObject(source) && source.catalog === catalog ? { ...source, ref: tag } : source));
+    writeJson(root, SKILLS_MANIFEST, { ...manifest, sources: moved });
+    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.
+ * @param root - The repo.
+ * @returns The npx spec.
+ * @example skillsManagerSpec(root) // "@ramon-sg/skills-manager@1.1.0"
+ */
+export function skillsManagerSpec(root) {
+    return `${SKILLS_MANAGER}@${dependencyVersion(readJson(root, "package.json"), SKILLS_MANAGER) ?? "1"}`;
+}

package/dist/tools.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ * @param right - Another.
+ * @returns Negative if left is older, 0 if equal, positive if newer.
+ * @example compareVersions("0.10.0", "0.9.1") // 1
+ */
+export declare function compareVersions(left: string, right: string): number;
+/**
+ * Whether a version is a release like 1.2.3.
+ * @param version - The text.
+ * @returns True for a release version.
+ * @example isRelease("1.2.3") // true
+ */
+export declare function isRelease(version: string): boolean;
+/**
+ * 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 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 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: 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 declare function runNpx(root: string, args: string[]): Promise<ToolRun>;
+/**
+ * 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 failedOutput(output: string): string;
+/**
+ * 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 captureNpx(root: string, args: string[], lookup?: boolean): Promise<{
+    out: string;
+    status: number | null;
+} | null>;

package/dist/tools.js

@@ -0,0 +1,175 @@
+/**
+ * @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. 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 { 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.
+ * @param right - Another.
+ * @returns Negative if left is older, 0 if equal, positive if newer.
+ * @example compareVersions("0.10.0", "0.9.1") // 1
+ */
+export function compareVersions(left, right) {
+    const parts = (version) => (VERSION.exec(version) ?? []).slice(1).map(Number);
+    const [a, b] = [parts(left), parts(right)];
+    for (let index = 0; index < 3; index += 1) {
+        const diff = (a[index] ?? 0) - (b[index] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * Whether a version is a release like 1.2.3.
+ * @param version - The text.
+ * @returns True for a release version.
+ * @example isRelease("1.2.3") // true
+ */
+export function isRelease(version) {
+    return VERSION.test(version);
+}
+/**
+ * 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.
+ */
+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 a lookup once: later calls get the same promise.
+ * @param key - What it looks up.
+ * @param lookup - How.
+ * @returns Its result.
+ */
+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 await npmLatest("@ramon-sg/claude-cloud") // "1.0.0"
+ */
+export function npmLatest(name) {
+    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 await latestTag("ramon-sg/agent-skills") // "0.1.0"
+ */
+export function latestTag(repo) {
+    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,22 @@
 {
   "name": "agent-kitchen",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "bin": { "agent-kitchen": "dist/cli.js" },
+  "files": ["dist"],
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public", "provenance": true },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ramon-sg/agent-kitchen.git"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test test/*.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": { "@clack/prompts": "1.8.1" },
+  "devDependencies": { "@types/node": "^24.0.0", "typescript": "^5.9.3" }
+}