pruff-skills 0.13.0 → 1.0.1

package/README.md

@@ -131,6 +131,8 @@ npx pruff-skills add <skill> -g -a claude-code -y
 | `npx pruff-skills remove [skills]` | Remove installed skills from agents           |
 | `npx pruff-skills update [skills]` | Update installed skills to latest versions    |
 | `npx pruff-skills init [name]`     | Create a new `SKILL.md` template              |
+| `npx pruff-skills restore`         | Reinstall everything recorded in `skills-lock.json` |
+| `npx pruff-skills sync`            | Install skills found in `node_modules` into agent dirs |
 
 ```bash
 npx pruff-skills list                 # list installed skills
@@ -174,10 +176,63 @@ Scaffold one with `npx pruff-skills init my-skill`, then publish it by pushing t
 
 ## Environment Variables
 
-| Variable                  | Description                                                                          |
-| ------------------------- | ------------------------------------------------------------------------------------ |
-| `PRUFF_SKILLS_CATALOG`        | Source a bare skill name resolves to (default `Pruff-Tech/pruff-skills`). A GitHub `owner/repo`, git URL, or local path. Set to a local checkout for offline installs. |
-| `INSTALL_INTERNAL_SKILLS` | Set to `1` or `true` to show and install skills marked as `internal: true`          |
+Read by pruff-skills itself:
+
+| Variable | Description |
+| -------- | ----------- |
+| `PRUFF_SKILLS_CATALOG` | Source a bare skill name resolves to (default `Pruff-Tech/pruff-skills`). A GitHub `owner/repo`, git URL, or local path. Set to a local checkout for offline installs. |
+| `PRUFF_SKILLS_NO_ANIM` | Disable the animated logo. Also implied by `NO_COLOR` and `CI`. |
+| `PRUFF_SKILLS_DOWNLOAD_URL` | Base URL for blob downloads. Empty by default. |
+| `INSTALL_INTERNAL_SKILLS` | Set to `1` or `true` to show and install skills marked as `internal: true`. |
+| `SKILLS_CLONE_TIMEOUT_MS` | Timeout for a `git clone`, in milliseconds. |
+| `BUZZ_NEST_DIR` | Where `buzz setup` provisions its nest (default `~/.buzz`). |
+| `BUZZ_APP_DATA_DIR` | Override the Buzz application-data directory. |
+| `BUZZ_PACKS_DIR` | Where persona packs are read from (default: the `packs/` directory inside this package). |
+
+Read from the surrounding environment, not owned by this CLI:
+
+| Variable | Description |
+| -------- | ----------- |
+| `CLAUDE_CONFIG_DIR` | Claude Code's config directory (default `~/.claude`); determines where global skills, subagents and rules are installed. |
+| `XDG_STATE_HOME` | When set, relocates the global lock to `$XDG_STATE_HOME/skills/.skill-lock.json` instead of `~/.agents/`. |
+| `GITHUB_TOKEN` / `GH_TOKEN` | Used by `git`/`gh` when cloning a private catalog or skill repo. |
+| `NO_COLOR` / `CI` | Suppress the animated logo. |
+
+`CODEX_HOME`, `VIBE_HOME`, `HERMES_HOME`, `AUTOHAND_HOME`, `APPDATA`,
+`FLATPAK_XDG_CONFIG_HOME` and `XDG_DATA_HOME` are read the same way, to locate the skills
+directory of the corresponding agent.
+
+## Stability
+
+pruff-skills follows [semantic versioning](https://semver.org/). From 1.0.0 onward, a
+breaking change to anything in **Covered** below means a major version bump.
+
+**Covered:**
+
+- Command names and their documented aliases, and the flags listed in `--help`
+- Exit codes: `0` on success, non-zero on failure
+- The `PRUFF_SKILLS_*` and `INSTALL_INTERNAL_SKILLS` environment variables
+- The `skills-lock.json` format, including its `version` field
+- The `schemaVersion` of `list --json`
+- The `schemaVersion` of `.well-known/agent-skills/index.json`, the catalog discovery manifest
+- The required `SKILL.md` frontmatter fields: `name` and `description`
+
+**Not covered** — these may change in any release:
+
+- Human-readable output: log lines, colours, spinners, table layout, the banner. Parse
+  `list --json`, not stdout.
+- The mapping from an agent to its on-disk skills directory. These track each third-party
+  tool's own layout, so they change when that tool changes, not on our schedule.
+- The `buzz` command and its `BUZZ_*` variables — Pruff-internal team tooling.
+- The contents of the catalog. Skills, subagents and rules are added, reworded, and
+  occasionally renamed or removed; the CLI's contract is how you install them, not which
+  ones exist. Pin a skill by committing `skills-lock.json`.
+- Anything named `experimental_*`. `experimental_install` and `experimental_sync` are
+  retained as undocumented aliases of `restore` and `sync` and may be dropped.
+
+**On version fields.** Both lock files and both JSON schemas carry an explicit version, and
+a version this CLI cannot read is an error with instructions — never a silent reset. If you
+see one, the message names the file, both versions, and what to run.
 
 ## Telemetry
 

package/dist/cli.mjs

@@ -494,13 +494,12 @@ function isAuthFailure(message) {
 function createGitClient(extraEnv) {
 	return esm_default({
 		timeout: { block: CLONE_TIMEOUT_MS },
-		env: {
-			...process.env,
-			GIT_TERMINAL_PROMPT: "0",
-			GIT_LFS_SKIP_SMUDGE: "1",
-			...extraEnv
-		},
 		config: ["filter.lfs.required=false"]
+	}).env({
+		...process.env,
+		GIT_TERMINAL_PROMPT: "0",
+		GIT_LFS_SKIP_SMUDGE: "1",
+		...extraEnv
 	});
 }
 async function resetTempDir(dir) {
@@ -682,6 +681,8 @@ async function getPluginGroupings(basePath) {
 	} catch {}
 	return groupings;
 }
+var UserFacingError = class extends Error {};
+var LockVersionError = class extends UserFacingError {};
 const LOCAL_LOCK_FILE = "skills-lock.json";
 const CURRENT_VERSION$1 = 1;
 function getLocalLockPath(cwd) {
@@ -689,15 +690,23 @@ function getLocalLockPath(cwd) {
 }
 async function readLocalLock(cwd) {
 	const lockPath = getLocalLockPath(cwd);
+	let content;
 	try {
-		const content = await readFile(lockPath, "utf-8");
-		const parsed = JSON.parse(content);
-		if (typeof parsed.version !== "number" || !parsed.skills) return createEmptyLocalLock();
-		if (parsed.version < CURRENT_VERSION$1) return createEmptyLocalLock();
-		return parsed;
-	} catch {
-		return createEmptyLocalLock();
+		content = await readFile(lockPath, "utf-8");
+	} catch (error) {
+		if (error.code === "ENOENT") return createEmptyLocalLock();
+		throw new LockVersionError(`Could not read ${lockPath}: ${error.message}`);
 	}
+	let parsed;
+	try {
+		parsed = JSON.parse(content);
+	} catch (error) {
+		throw new LockVersionError(/^<{7} |^={7}$|^>{7} /m.test(content) ? `${lockPath} still has unresolved merge-conflict markers.\n  Resolve them (skill entries are independent keys, so both sides can usually be kept) and re-run.` : `${lockPath} is not valid JSON: ${error.message}`);
+	}
+	if (typeof parsed.version !== "number" || !parsed.skills) throw new LockVersionError(`${lockPath} is missing a numeric "version" or a "skills" object.\n  If it was hand-edited, restore it from git; otherwise delete it and re-add your skills.`);
+	if (parsed.version > CURRENT_VERSION$1) throw new LockVersionError(`${lockPath} is at lock schema v${parsed.version}, but this pruff-skills reads up to v${CURRENT_VERSION$1}.\n  A newer pruff-skills wrote it. Upgrade with: npm i -g pruff-skills@latest`);
+	if (parsed.version < CURRENT_VERSION$1) throw new LockVersionError(`${lockPath} is at lock schema v${parsed.version}, which predates every released format (v1 is the oldest).\n  Restore it from git, or delete it and re-add your skills.`);
+	return parsed;
 }
 async function writeLocalLock(lock, cwd) {
 	const lockPath = getLocalLockPath(cwd);
@@ -803,13 +812,14 @@ async function parseSkillMd(skillMdPath, options) {
 		const { data } = parseFrontmatter(content);
 		if (!data.name || !data.description) return null;
 		if (typeof data.name !== "string" || typeof data.description !== "string") return null;
-		if (data.metadata?.internal === true && !shouldInstallInternalSkills() && !options?.includeInternal) return null;
+		const metadata = typeof data.metadata === "object" && data.metadata !== null && !Array.isArray(data.metadata) ? data.metadata : void 0;
+		if (metadata?.internal === true && !shouldInstallInternalSkills() && !options?.includeInternal) return null;
 		return {
 			name: sanitizeMetadata(data.name),
 			description: sanitizeMetadata(data.description),
 			path: dirname(skillMdPath),
 			rawContent: content,
-			metadata: data.metadata
+			metadata
 		};
 	} catch {
 		return null;
@@ -2125,6 +2135,18 @@ const PRUFF_CATALOG = process.env.PRUFF_SKILLS_CATALOG || "Pruff-Tech/pruff-skil
 function isBareSkillName(value) {
 	return !!value && /^[a-z0-9][a-z0-9-]*$/.test(value) && !value.includes("/") && !value.includes(".") && !value.includes(":");
 }
+var CatalogSchemaError = class extends UserFacingError {};
+function parseCatalogIndex(raw, sourceLabel) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		throw new CatalogSchemaError(`Could not parse the catalog index from ${sourceLabel}: ${error.message}`);
+	}
+	const declared = parsed?.schemaVersion;
+	if (typeof declared === "number" && declared > 1) throw new CatalogSchemaError(`The catalog at ${sourceLabel} declares index schema v${declared}, but this pruff-skills understands up to v1.\n  Upgrade with: npm i -g pruff-skills@latest`);
+	return parsed ?? {};
+}
 var import_dist = require_dist();
 let cachedResult = null;
 const agentNameToType = {
@@ -2628,15 +2650,23 @@ function getSkillLockPath() {
 }
 async function readSkillLock() {
 	const lockPath = getSkillLockPath();
+	let content;
+	try {
+		content = await readFile(lockPath, "utf-8");
+	} catch (error) {
+		if (error.code === "ENOENT") return createEmptyLockFile();
+		throw new LockVersionError(`Could not read ${lockPath}: ${error.message}`);
+	}
+	let parsed;
 	try {
-		const content = await readFile(lockPath, "utf-8");
-		const parsed = JSON.parse(content);
-		if (typeof parsed.version !== "number" || !parsed.skills) return createEmptyLockFile();
-		if (parsed.version < CURRENT_VERSION) return createEmptyLockFile();
-		return parsed;
+		parsed = JSON.parse(content);
 	} catch (error) {
-		return createEmptyLockFile();
+		throw new LockVersionError(`${lockPath} is not valid JSON: ${error.message}\n  This file only records what is already installed. Deleting it is safe — you will just lose update tracking until each skill is re-added.`);
 	}
+	if (typeof parsed.version !== "number" || !parsed.skills) throw new LockVersionError(`${lockPath} is missing a numeric "version" or a "skills" object.\n  Deleting it is safe — you will just lose update tracking until each skill is re-added.`);
+	if (parsed.version > CURRENT_VERSION) throw new LockVersionError(`${lockPath} is at lock schema v${parsed.version}, but this pruff-skills reads up to v${CURRENT_VERSION}.\n  A newer pruff-skills wrote it. Upgrade with: npm i -g pruff-skills@latest`);
+	if (parsed.version < CURRENT_VERSION) throw new LockVersionError(`${lockPath} is at lock schema v${parsed.version}; this pruff-skills needs v${CURRENT_VERSION}, and the missing folder hashes cannot be reconstructed offline.\n  Delete it and re-add your skills:  rm ${lockPath}\n  Nothing installed is removed by that — only the update-tracking record.`);
+	return parsed;
 }
 async function writeSkillLock(lock) {
 	const lockPath = getSkillLockPath();
@@ -4216,11 +4246,7 @@ const fetchRuleFile = (source, name) => fetchFromCatalog(source, `rules/${name}.
 async function fetchRuleIndex(source) {
 	const raw = await fetchFromCatalog(source, ".well-known/agent-skills/index.json");
 	if (!raw) return [];
-	try {
-		return JSON.parse(raw).rules ?? [];
-	} catch {
-		return [];
-	}
+	return parseCatalogIndex(raw, source).rules ?? [];
 }
 function expandScopes(scopes) {
 	const set = new Set(scopes);
@@ -4335,10 +4361,7 @@ const UNCHECKED = "◻";
 const CATALOG_SOURCE = process.env.PRUFF_SKILLS_CATALOG || "Pruff-Tech/pruff-skills";
 async function fetchCatalogIndex(source) {
 	const rel = ".well-known/agent-skills/index.json";
-	if (source.startsWith(".") || isAbsolute(source)) {
-		const raw = readFileSync(join(source, rel), "utf8");
-		return JSON.parse(raw);
-	}
+	if (source.startsWith(".") || isAbsolute(source)) return parseCatalogIndex(readFileSync(join(source, rel), "utf8"), source);
 	if (source.match(/^[^/]+\/[^/]+$/)) {
 		const { stdout } = await execFileAsync$2("gh", [
 			"api",
@@ -4349,8 +4372,7 @@ async function fetchCatalogIndex(source) {
 			...process.env,
 			GIT_TERMINAL_PROMPT: "0"
 		} });
-		const json = Buffer.from(stdout.trim(), "base64").toString("utf8");
-		return JSON.parse(json);
+		return parseCatalogIndex(Buffer.from(stdout.trim(), "base64").toString("utf8"), source);
 	}
 	return {};
 }
@@ -4400,7 +4422,8 @@ async function loadCatalog() {
 			...(index.agents ?? []).map((e) => toEntry(e, "agent")),
 			...(index.rules ?? []).map((e) => toEntry(e, "rule"))
 		];
-	} catch {
+	} catch (error) {
+		if (error instanceof CatalogSchemaError) throw error;
 		catalogCache = [];
 	}
 	return catalogCache;
@@ -5026,6 +5049,7 @@ const BOLD$2 = "\x1B[1m";
 const DIM$2 = "\x1B[38;5;102m";
 const CYAN = "\x1B[36m";
 const YELLOW = "\x1B[33m";
+const LIST_JSON_SCHEMA_VERSION = 1;
 function shortenPath(fullPath, cwd) {
 	const home = homedir();
 	if (fullPath.startsWith(home)) return fullPath.replace(home, "~");
@@ -5070,12 +5094,15 @@ async function runList(args) {
 		agentFilter
 	});
 	if (options.json) {
-		const jsonOutput = installedSkills.map((skill) => ({
-			name: skill.name,
-			path: skill.canonicalPath,
-			scope: skill.scope,
-			agents: skill.agents.map((a) => agents[a].displayName)
-		}));
+		const jsonOutput = {
+			schemaVersion: LIST_JSON_SCHEMA_VERSION,
+			skills: installedSkills.map((skill) => ({
+				name: skill.name,
+				path: skill.canonicalPath,
+				scope: skill.scope,
+				agents: skill.agents
+			}))
+		};
 		console.log(JSON.stringify(jsonOutput, null, 2));
 		return;
 	}
@@ -5083,10 +5110,6 @@ async function runList(args) {
 	const cwd = process.cwd();
 	const scopeLabel = scope ? "Global" : "Project";
 	if (installedSkills.length === 0) {
-		if (options.json) {
-			console.log("[]");
-			return;
-		}
 		console.log(`${DIM$2}No ${scopeLabel.toLowerCase()} skills found.${RESET$2}`);
 		if (scope) console.log(`${DIM$2}Try listing project skills without -g${RESET$2}`);
 		else console.log(`${DIM$2}Try listing global skills with -g${RESET$2}`);
@@ -5190,6 +5213,7 @@ async function removeCommand(skillNames, options) {
 		Se(import_picocolors.default.yellow("No skills found to remove."));
 		return;
 	}
+	if (options.agent?.includes("*")) options.agent = Object.keys(agents);
 	if (options.agent && options.agent.length > 0) {
 		const validAgents = Object.keys(agents);
 		const invalidAgents = options.agent.filter((a) => !validAgents.includes(a));
@@ -5200,7 +5224,7 @@ async function removeCommand(skillNames, options) {
 		}
 	}
 	let selectedSkills = [];
-	if (options.all) selectedSkills = installedSkills;
+	if (options.all || skillNames.includes("*")) selectedSkills = installedSkills;
 	else if (skillNames.length > 0) {
 		selectedSkills = installedSkills.filter((s) => skillNames.some((name) => name.toLowerCase() === s.toLowerCase()));
 		if (selectedSkills.length === 0) {
@@ -5339,6 +5363,15 @@ function parseRemoveOptions(args) {
 				nextArg = args[i];
 			}
 			i--;
+		} else if (arg === "-s" || arg === "--skill") {
+			i++;
+			let nextArg = args[i];
+			while (i < args.length && nextArg && !nextArg.startsWith("-")) {
+				skills.push(nextArg);
+				i++;
+				nextArg = args[i];
+			}
+			i--;
 		} else if (arg && !arg.startsWith("-")) skills.push(arg);
 	}
 	return {
@@ -8846,9 +8879,9 @@ async function showBanner() {
 	console.log();
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills update${RESET}            ${DIM}Update installed skills + subagents${RESET}`);
 	console.log();
-	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills experimental_install${RESET} ${DIM}Restore from skills-lock.json${RESET}`);
+	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills restore${RESET}           ${DIM}Restore from skills-lock.json${RESET}`);
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills init ${DIM}[name]${RESET}       ${DIM}Create a new skill${RESET}`);
-	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills experimental_sync${RESET}   ${DIM}Sync skills from node_modules${RESET}`);
+	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills sync${RESET}              ${DIM}Sync skills from node_modules${RESET}`);
 	console.log();
 	console.log(`${DIM}try:${RESET} ${BLUE}npx pruff-skills add <skill>${RESET}`);
 	console.log();
@@ -8883,6 +8916,13 @@ ${BOLD}Usage analytics:${RESET}
                        ${DIM}Reports token/cost by skill, MCP tool, subagent and model.${RESET}
                        ${DIM}Never exports prompts, responses or file contents.${RESET}
 
+${BOLD}Buzz nest:${RESET}
+  buzz setup <team>    Provision a Buzz agent nest (~/.buzz): vault, team skills,
+                       subagents and persona packs
+  buzz sync [team]     Re-sync an existing nest with the catalog
+  buzz packs list      List the persona packs shipped with this CLI
+  buzz packs init <t>  Scaffold a new persona pack for a team
+
 ${BOLD}Onboarding:${RESET}
   onboarding [dir]     Set up a new machine (macOS), end to end: prerequisites +
                        GitHub auth, Claude Code, Obsidian, Bun, clone the
@@ -8908,9 +8948,9 @@ ${BOLD}Update Options:${RESET}
   -y, --yes              Skip scope prompt (auto-detect: project if in a project, else global)
 
 ${BOLD}Project:${RESET}
-  experimental_install Restore skills from skills-lock.json
+  restore              Restore skills from skills-lock.json
   init [name]          Initialize a skill (creates <name>/SKILL.md or ./SKILL.md)
-  experimental_sync    Sync skills from node_modules into agent directories
+  sync                 Sync skills from node_modules into agent directories
 
 ${BOLD}Add Options:${RESET}
   -g, --global           Install skill globally (user-level) instead of project-level
@@ -8936,9 +8976,10 @@ ${BOLD}Remove Options:${RESET}
   -y, --yes              Skip confirmation prompts
   --all                  Shorthand for --skill '*' --agent '*' -y
   
-${BOLD}Experimental Sync Options:${RESET}
+${BOLD}Sync Options:${RESET}
   -a, --agent <agents>   Specify agents to install to (use '*' for all agents)
   -y, --yes              Skip confirmation prompts
+  -f, --force            Re-copy skills already present in the agent directory
 
 ${BOLD}List Options:${RESET}
   -g, --global           List global skills (default: project)
@@ -8968,10 +9009,10 @@ ${BOLD}Examples:${RESET}
   ${DIM}$${RESET} pruff-skills update
   ${DIM}$${RESET} pruff-skills update <skill>         ${DIM}# update a single skill${RESET}
   ${DIM}$${RESET} pruff-skills update -g                  ${DIM}# update global skills only${RESET}
-  ${DIM}$${RESET} pruff-skills experimental_install          ${DIM}# restore from skills-lock.json${RESET}
+  ${DIM}$${RESET} pruff-skills restore                     ${DIM}# restore from skills-lock.json${RESET}
   ${DIM}$${RESET} pruff-skills init my-skill
-  ${DIM}$${RESET} pruff-skills experimental_sync            ${DIM}# sync from node_modules${RESET}
-  ${DIM}$${RESET} pruff-skills experimental_sync -y         ${DIM}# sync without prompts${RESET}
+  ${DIM}$${RESET} pruff-skills sync                        ${DIM}# sync from node_modules${RESET}
+  ${DIM}$${RESET} pruff-skills sync -y                     ${DIM}# sync without prompts${RESET}
 
 Browse the catalog with ${BLUE}npx pruff-skills find${RESET}
 `);
@@ -9058,7 +9099,7 @@ async function main() {
 	const inAgent = await isRunningInAgent();
 	if (args.length === 0) {
 		if (!inAgent) await showBanner();
-		return;
+		return 0;
 	}
 	const command = args[0];
 	const restArgs = args.slice(1);
@@ -9076,6 +9117,7 @@ async function main() {
 			console.log();
 			runInit(restArgs);
 			break;
+		case "restore":
 		case "experimental_install":
 			if (!inAgent) await showLogo();
 			await runInstallFromLock(restArgs);
@@ -9130,6 +9172,7 @@ async function main() {
 			const { skills, options: removeOptions } = parseRemoveOptions(restArgs);
 			await removeCommand(skills, removeOptions);
 			break;
+		case "sync":
 		case "experimental_sync": {
 			if (!inAgent) await showLogo();
 			const { options: syncOptions } = parseSyncOptions(restArgs);
@@ -9154,9 +9197,18 @@ async function main() {
 			console.log(VERSION);
 			break;
 		default:
-			console.log(`Unknown command: ${command}`);
-			console.log(`Run ${BOLD}pruff-skills --help${RESET} for usage.`);
-	}
-}
-main().finally(() => flushTelemetry().then(() => process.exit(0)));
+			console.error(`Unknown command: ${command}`);
+			console.error(`Run ${BOLD}pruff-skills --help${RESET} for usage.`);
+			return 1;
+	}
+	return 0;
+}
+main().then((code) => code ?? 0).catch((error) => {
+	if (error instanceof UserFacingError) console.error(error.message);
+	else console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+	return 1;
+}).then(async (code) => {
+	await flushTelemetry();
+	process.exit(code);
+});
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pruff-skills",
-  "version": "0.13.0",
+  "version": "1.0.1",
   "description": "The official Pruff agent skills CLI",
   "type": "module",
   "bin": {
@@ -22,8 +22,8 @@
     "sync-catalog:check": "node scripts/sync-catalog.mjs --check",
     "exec:test": "node scripts/execute-tests.ts",
     "prepublishOnly": "npm run build",
-    "format": "prettier --write \"src/**/*.ts\" \"scripts/**/*.ts\"",
-    "format:check": "prettier --check \"src/**/*.ts\" \"scripts/**/*.ts\"",
+    "format": "prettier --write \"src/**/*.ts\" \"scripts/**/*.ts\" \"tests/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"scripts/**/*.ts\" \"tests/**/*.ts\"",
     "prepare": "husky || true",
     "test": "vitest",
     "type-check": "tsc --noEmit",