agent-kitchen 0.0.0-stage → 0.2.0

package/dist/repo.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Whether a value is a plain JSON object.
+ * @param value - The value.
+ * @returns True for an object that is not an array nor null.
+ * @example isObject({}) // true
+ */
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * The main checkout of the repo a folder is in.
+ * @param cwd - The folder.
+ * @param command - The command that runs, for the error.
+ * @returns Its root, with symlinks resolved.
+ * @throws KitError outside a git checkout or inside a worktree.
+ * @example mainCheckout(process.cwd(), "agent-kitchen") // "/code/shop"
+ */
+export declare function mainCheckout(cwd: string, command: string): string;
+/**
+ * Reads a JSON object of the repo.
+ * @param root - The repo.
+ * @param path - The file, relative to the repo.
+ * @returns The object, or null if the file does not exist.
+ * @throws KitError if it is not valid JSON or not an object: it is never overwritten then.
+ * @example readJson(root, ".claude/cloud.json")
+ */
+export declare function readJson(root: string, path: string): Record<string, unknown> | null;
+/**
+ * Writes a JSON file of the repo, indented by two spaces, creating its folder.
+ * @param root - The repo.
+ * @param path - The file, relative to the repo.
+ * @param value - What to write.
+ * @example writeJson(root, ".claude/cloud.json", { version: "1.1.0" })
+ */
+export declare function writeJson(root: string, path: string, value: unknown): void;
+/**
+ * The version of a dependency in `package.json`, development or not.
+ * @param pkg - The package.json, or null.
+ * @param name - The package.
+ * @returns The version, or null if it is not there.
+ * @example dependencyVersion(pkg, "@ramon-sg/issue-flow") // "0.2.0"
+ */
+export declare function dependencyVersion(pkg: Record<string, unknown> | null, name: string): string | null;
+/**
+ * The repo's package manager: the `packageManager` field, then its lockfile, then npm.
+ * @param root - The repo.
+ * @returns `npm`, `pnpm`, `bun` or `yarn`.
+ * @example packageManager(root) // "pnpm"
+ */
+export declare function packageManager(root: string): string;

package/dist/repo.js

@@ -0,0 +1,117 @@
+/**
+ * @file The repo agent-kitchen works on: its main checkout (never a worktree, whose files are
+ * not the ones the team commits from), the JSON files the pieces keep in it, and its
+ * package manager.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { KitError } from "./output.js";
+/**
+ * Whether a value is a plain JSON object.
+ * @param value - The value.
+ * @returns True for an object that is not an array nor null.
+ * @example isObject({}) // true
+ */
+export function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Runs git in a folder.
+ * @param cwd - The folder.
+ * @param args - The arguments.
+ * @returns Its trimmed stdout, or null if it failed.
+ */
+function git(cwd, args) {
+    const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+    return result.status === 0 ? result.stdout.trim() : null;
+}
+/**
+ * The main checkout of the repo a folder is in.
+ * @param cwd - The folder.
+ * @param command - The command that runs, for the error.
+ * @returns Its root, with symlinks resolved.
+ * @throws KitError outside a git checkout or inside a worktree.
+ * @example mainCheckout(process.cwd(), "agent-kitchen") // "/code/shop"
+ */
+export function mainCheckout(cwd, command) {
+    const common = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+    const top = git(cwd, ["rev-parse", "--show-toplevel"]);
+    if (common === null || top === null)
+        throw new KitError(`run ${command} inside a checkout of the repo.`);
+    const main = realpathSync(dirname(common));
+    if (realpathSync(top) !== main)
+        throw new KitError(`run ${command} in the main checkout, ${main}, not in a worktree.`);
+    return main;
+}
+/**
+ * Reads a JSON object of the repo.
+ * @param root - The repo.
+ * @param path - The file, relative to the repo.
+ * @returns The object, or null if the file does not exist.
+ * @throws KitError if it is not valid JSON or not an object: it is never overwritten then.
+ * @example readJson(root, ".claude/cloud.json")
+ */
+export function readJson(root, path) {
+    const file = join(root, path);
+    if (!existsSync(file))
+        return null;
+    let value;
+    try {
+        value = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new KitError(`${path} is not valid JSON (${error instanceof Error ? error.message : String(error)}); fix it and run again.`);
+    }
+    if (!isObject(value))
+        throw new KitError(`${path} is not a JSON object; fix it and run again.`);
+    return value;
+}
+/**
+ * Writes a JSON file of the repo, indented by two spaces, creating its folder.
+ * @param root - The repo.
+ * @param path - The file, relative to the repo.
+ * @param value - What to write.
+ * @example writeJson(root, ".claude/cloud.json", { version: "1.1.0" })
+ */
+export function writeJson(root, path, value) {
+    const file = join(root, path);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+/**
+ * The version of a dependency in `package.json`, development or not.
+ * @param pkg - The package.json, or null.
+ * @param name - The package.
+ * @returns The version, or null if it is not there.
+ * @example dependencyVersion(pkg, "@ramon-sg/issue-flow") // "0.2.0"
+ */
+export function dependencyVersion(pkg, name) {
+    for (const field of ["devDependencies", "dependencies"]) {
+        const deps = pkg?.[field];
+        if (isObject(deps) && typeof deps[name] === "string")
+            return deps[name];
+    }
+    return null;
+}
+/** The lockfile of each package manager, in the order they are looked for. */
+const LOCKFILES = [
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"],
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["package-lock.json", "npm"],
+];
+/**
+ * The repo's package manager: the `packageManager` field, then its lockfile, then npm.
+ * @param root - The repo.
+ * @returns `npm`, `pnpm`, `bun` or `yarn`.
+ * @example packageManager(root) // "pnpm"
+ */
+export function packageManager(root) {
+    const pkg = readJson(root, "package.json");
+    const field = typeof pkg?.packageManager === "string" ? pkg.packageManager.split("@")[0] : undefined;
+    if (field !== undefined && field !== "")
+        return field;
+    return LOCKFILES.find(([file]) => existsSync(join(root, file)))?.[1] ?? "npm";
+}

package/dist/skills-files.d.ts

@@ -0,0 +1,62 @@
+/** 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 The command that failed, to retry it, or null if every one worked.
+ * @example updateSkills(root, ["close-pr", "pr-review-comments"]) // null
+ */
+export declare function updateSkills(root: string, names: string[]): string | null;
+/**
+ * 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,93 @@
+/**
+ * @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.
+ */
+import { dependencyVersion, isObject, readJson, writeJson } from "./repo.js";
+import { SKILLS_LOCK, SKILLS_MANAGER, SKILLS_MANIFEST } from "./piece.js";
+import { runNpx } from "./tools.js";
+/**
+ * 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 The command that failed, to retry it, or null if every one worked.
+ * @example updateSkills(root, ["close-pr", "pr-review-comments"]) // null
+ */
+export 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}`;
+}
+/**
+ * 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,48 @@
+/**
+ * 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;
+/**
+ * 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"])
+ */
+export declare function runNpx(root: string, args: string[]): boolean;
+/**
+ * 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"])
+ */
+export declare function captureNpx(root: string, args: string[]): {
+    out: string;
+    status: number | null;
+} | null;
+/**
+ * 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"
+ */
+export declare function npmLatest(name: string): 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 latestTag("ramon-sg/agent-skills") // "0.1.0"
+ */
+export declare function latestTag(repo: string): string | null;

package/dist/tools.js

@@ -0,0 +1,85 @@
+/**
+ * @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.
+ */
+import { spawnSync } 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+)$/;
+/**
+ * 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 `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"])
+ */
+export function runNpx(root, args) {
+    return spawnSync("npx", ["--yes", ...args], { cwd: root, stdio: "inherit" }).status === 0;
+}
+/**
+ * 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"])
+ */
+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;
+}
+/**
+ * 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"
+ */
+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;
+}
+/**
+ * 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"
+ */
+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;
+}

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.2.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" }
+}