pruff-skills 0.1.0 → 0.2.0

package/README.md

@@ -38,6 +38,15 @@ The catalog also ships **Claude Code subagents**. `find` lists them alongside sk
 npx pruff-skills agents add <name>      # → .claude/agents/  (add -g for ~/.claude/agents/)
 ```
 
+It also ships **coding-convention rules** for the Pruff repos, each tagged by scope
+(`client` / `server` / `common`, where `common` applies to both). `find` lists them tagged
+`[rule]`. Install one by name, or a whole repo's set at once:
+
+```bash
+npx pruff-skills rules add <name>          # → .claude/rules/  (add -g for ~/.claude/rules/)
+npx pruff-skills rules add --scope server  # all server + common rules (client/server pull in common)
+```
+
 ## Use a Skill Without Installing
 
 Generate a prompt for one skill, or start a supported coding agent interactively:

package/dist/cli.mjs

@@ -434,7 +434,7 @@ const CLONE_TIMEOUT_MS = (() => {
 	const parsed = Number.parseInt(raw, 10);
 	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CLONE_TIMEOUT_MS;
 })();
-const execFileAsync$2 = promisify(execFile);
+const execFileAsync$3 = promisify(execFile);
 var GitCloneError = class extends Error {
 	url;
 	isTimeout;
@@ -513,7 +513,7 @@ async function resetTempDir(dir) {
 async function tryGhClone(repo, tempDir, ref) {
 	let cloneTarget = repo.slug;
 	try {
-		const { stdout, stderr } = await execFileAsync$2("gh", [
+		const { stdout, stderr } = await execFileAsync$3("gh", [
 			"auth",
 			"status",
 			"-h",
@@ -530,7 +530,7 @@ async function tryGhClone(repo, tempDir, ref) {
 	} catch {
 		return false;
 	}
-	await execFileAsync$2("gh", [
+	await execFileAsync$3("gh", [
 		"repo",
 		"clone",
 		cloneTarget,
@@ -3997,7 +3997,7 @@ function parseAddOptions(args) {
 		options
 	};
 }
-const execFileAsync$1 = promisify(execFile);
+const execFileAsync$2 = promisify(execFile);
 const claudeAgentsDir = (global) => global ? join(process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude"), "agents") : join(process.cwd(), ".claude", "agents");
 async function fetchAgentFile(source, name) {
 	const rel = `agents/${name}.md`;
@@ -4006,7 +4006,7 @@ async function fetchAgentFile(source, name) {
 		return existsSync(file) ? readFile(file, "utf8") : null;
 	}
 	if (/^[^/]+\/[^/]+$/.test(source)) try {
-		const { stdout } = await execFileAsync$1("gh", [
+		const { stdout } = await execFileAsync$2("gh", [
 			"api",
 			`repos/${source}/contents/${rel}`,
 			"--jq",
@@ -4103,6 +4103,152 @@ async function runAgents(args) {
 	console.log(`Unknown agents command: ${sub}`);
 	console.log(AGENTS_HELP);
 }
+const execFileAsync$1 = promisify(execFile);
+const RULE_SCOPES = [
+	"client",
+	"server",
+	"common"
+];
+const claudeRulesDir = (global) => global ? join(process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude"), "rules") : join(process.cwd(), ".claude", "rules");
+function stripFrontmatter(md) {
+	const m = md.match(/^---\n[\s\S]*?\n---\n+/);
+	return m ? md.slice(m[0].length) : md;
+}
+async function fetchFromCatalog(source, rel) {
+	if (source.startsWith(".") || isAbsolute(source)) {
+		const file = join(source, rel);
+		return existsSync(file) ? readFile(file, "utf8") : null;
+	}
+	if (/^[^/]+\/[^/]+$/.test(source)) try {
+		const { stdout } = await execFileAsync$1("gh", [
+			"api",
+			`repos/${source}/contents/${rel}`,
+			"--jq",
+			".content"
+		], { env: {
+			...process.env,
+			GIT_TERMINAL_PROMPT: "0"
+		} });
+		return Buffer.from(stdout.trim(), "base64").toString("utf8");
+	} catch {
+		return null;
+	}
+	try {
+		const file = join(await cloneRepo(source), rel);
+		return existsSync(file) ? readFile(file, "utf8") : null;
+	} catch {
+		return null;
+	}
+}
+const fetchRuleFile = (source, name) => fetchFromCatalog(source, `rules/${name}.md`);
+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 [];
+	}
+}
+function expandScopes(scopes) {
+	const set = new Set(scopes);
+	if (set.has("client") || set.has("server")) set.add("common");
+	return set;
+}
+function parseRulesOptions(args) {
+	const names = [];
+	const options = {};
+	const pushScope = (value) => {
+		if (value && RULE_SCOPES.includes(value)) (options.scopes ??= []).push(value);
+		else M.warn(`Ignoring invalid --scope value: ${import_picocolors.default.yellow(value ?? "(missing)")}`);
+	};
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "-g" || arg === "--global") options.global = true;
+		else if (arg === "-y" || arg === "--yes") options.yes = true;
+		else if (arg === "--all") options.all = true;
+		else if (arg === "-s" || arg === "--scope") pushScope(args[++i]);
+		else if (arg.startsWith("--scope=")) pushScope(arg.slice(8));
+		else if (!arg.startsWith("-")) names.push(arg);
+	}
+	return {
+		names,
+		options
+	};
+}
+async function addRules(names, options) {
+	const source = PRUFF_CATALOG;
+	const targetDir = claudeRulesDir(options.global ?? false);
+	Ie(import_picocolors.default.cyan("pruff-skills rules"));
+	let toInstall = names.filter(Boolean);
+	if (options.all || options.scopes?.length) {
+		const index = await fetchRuleIndex(source);
+		if (index.length === 0) {
+			M.error(`Could not read the rules catalog (${source}).`);
+			process.exit(1);
+		}
+		const wanted = options.all ? null : expandScopes(options.scopes ?? []);
+		const matched = index.filter((r) => wanted ? !!r.scope && wanted.has(r.scope) : true).map((r) => r.name);
+		toInstall = Array.from(new Set([...toInstall, ...matched]));
+	}
+	if (toInstall.length === 0) {
+		M.error("Specify a rule name, a --scope, or --all.");
+		M.message(import_picocolors.default.dim("e.g. `pruff-skills rules add service-patterns`"));
+		M.message(import_picocolors.default.dim("or   `pruff-skills rules add --scope server`"));
+		M.message(import_picocolors.default.dim("Browse them with `npx pruff-skills find`."));
+		process.exit(1);
+	}
+	await mkdir(targetDir, { recursive: true });
+	const installed = [];
+	for (const name of toInstall) {
+		if (!isBareSkillName(name)) {
+			M.warn(`Skipping invalid rule name: ${import_picocolors.default.yellow(name)}`);
+			continue;
+		}
+		const content = await fetchRuleFile(source, name);
+		if (!content) {
+			M.error(`Rule ${import_picocolors.default.yellow(name)} not found in the catalog (${source}).`);
+			continue;
+		}
+		const dest = join(targetDir, `${sanitizeName(name)}.md`);
+		await writeFile(dest, stripFrontmatter(content));
+		installed.push(dest);
+		M.success(`${import_picocolors.default.green(name)} → ${dest}`);
+	}
+	if (installed.length === 0) {
+		Se(import_picocolors.default.red("No rules installed."));
+		process.exit(1);
+	}
+	Se(`Installed ${installed.length} rule${installed.length === 1 ? "" : "s"} into ${import_picocolors.default.dim(targetDir)}.`);
+}
+const RULES_HELP = `${import_picocolors.default.bold("Usage:")} pruff-skills rules <command> [options]
+
+${import_picocolors.default.bold("Commands:")}
+  add <name...>      Install one or more rules into .claude/rules/
+
+${import_picocolors.default.bold("Options:")}
+  -s, --scope <s>    Install every rule in a scope: client | server | common
+                     (client/server also pull in common). Repeatable.
+  --all              Install every rule in the catalog
+  -g, --global       Install to ~/.claude/rules/ instead of the project
+  -y, --yes          Skip prompts
+
+${import_picocolors.default.bold("Examples:")}
+  pruff-skills rules add service-patterns bigint-handling
+  pruff-skills rules add --scope server      ${import_picocolors.default.dim("# all server + common rules")}
+  pruff-skills rules add --scope client -g
+  pruff-skills rules add --all
+
+Browse available rules with ${import_picocolors.default.cyan("npx pruff-skills find")}.`;
+async function runRules(args) {
+	const sub = args[0];
+	if (!sub || sub === "--help" || sub === "-h") {
+		console.log(RULES_HELP);
+		return;
+	}
+	const { names, options } = parseRulesOptions(sub === "add" || sub === "a" || sub === "install" || sub === "i" ? args.slice(1) : args);
+	await addRules(names, options);
+}
 const execFileAsync = promisify(execFile);
 const RESET$3 = "\x1B[0m";
 const BOLD$3 = "\x1B[1m";
@@ -4111,6 +4257,7 @@ const TEXT$2 = "\x1B[38;5;145m";
 const CYAN$1 = "\x1B[36m";
 const GREEN = "\x1B[32m";
 const MAGENTA = "\x1B[35m";
+const BLUE$1 = "\x1B[38;2;110;139;255m";
 const CATALOG_SOURCE = process.env.PRUFF_SKILLS_CATALOG || "Pruff-Tech/pruff-skills";
 async function fetchCatalogIndex(source) {
 	const rel = ".well-known/agent-skills/index.json";
@@ -4149,6 +4296,10 @@ function agentInstalled(name) {
 	const globalClaude = process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude");
 	return existsSync(join(process.cwd(), ".claude", "agents", `${name}.md`)) || existsSync(join(globalClaude, "agents", `${name}.md`));
 }
+function ruleInstalled(name) {
+	const globalClaude = process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude");
+	return existsSync(join(process.cwd(), ".claude", "rules", `${name}.md`)) || existsSync(join(globalClaude, "rules", `${name}.md`));
+}
 let catalogCache = null;
 async function loadCatalog() {
 	if (catalogCache) return catalogCache;
@@ -4157,6 +4308,8 @@ async function loadCatalog() {
 		const installedSkills = await installedSkillNames();
 		const toEntry = (e, kind) => {
 			const name = sanitizeMetadata(e.name);
+			const badge = kind === "rule" ? e.scope : e.category;
+			const installed = kind === "agent" ? agentInstalled(name) : kind === "rule" ? ruleInstalled(name) : installedSkills.has(name);
 			return {
 				name,
 				slug: name,
@@ -4164,11 +4317,15 @@ async function loadCatalog() {
 				installs: 0,
 				description: sanitizeMetadata(e.description || ""),
 				kind,
-				category: e.category ? sanitizeMetadata(e.category) : void 0,
-				installed: kind === "agent" ? agentInstalled(name) : installedSkills.has(name)
+				category: badge ? sanitizeMetadata(badge) : void 0,
+				installed
 			};
 		};
-		catalogCache = [...(index.skills ?? []).map((e) => toEntry(e, "skill")), ...(index.agents ?? []).map((e) => toEntry(e, "agent"))];
+		catalogCache = [
+			...(index.skills ?? []).map((e) => toEntry(e, "skill")),
+			...(index.agents ?? []).map((e) => toEntry(e, "agent")),
+			...(index.rules ?? []).map((e) => toEntry(e, "rule"))
+		];
 	} catch {
 		catalogCache = [];
 	}
@@ -4199,7 +4356,7 @@ async function runSearchPrompt(kind, initialQuery = "") {
 	let query = initialQuery;
 	let loading = false;
 	let lastRenderedLines = 0;
-	const noun = kind === "agent" ? "subagents" : "skills";
+	const noun = kind === "agent" ? "subagents" : kind === "rule" ? "rules" : "skills";
 	if (process.stdin.isTTY) process.stdin.setRawMode(true);
 	readline.emitKeypressEvents(process.stdin);
 	process.stdin.resume();
@@ -4316,10 +4473,10 @@ ${DIM$3}  2) npx pruff-skills add <skill>${RESET$3}`;
 			console.log(`${DIM$3}Nothing in the catalog matches "${query}"${RESET$3}`);
 			return;
 		}
-		console.log(`${DIM$3}Install a skill with${RESET$3} npx pruff-skills add <name>${DIM$3}, a subagent with${RESET$3} npx pruff-skills agents add <name>`);
+		console.log(`${DIM$3}Install a skill with${RESET$3} npx pruff-skills add <name>${DIM$3}, a subagent with${RESET$3} npx pruff-skills agents add <name>${DIM$3}, a rule with${RESET$3} npx pruff-skills rules add <name>`);
 		console.log();
 		for (const skill of results.slice(0, 10)) {
-			const kindBadge = skill.kind === "agent" ? ` ${MAGENTA}[subagent]${RESET$3}` : ` ${CYAN$1}[skill]${RESET$3}`;
+			const kindBadge = skill.kind === "agent" ? ` ${MAGENTA}[subagent]${RESET$3}` : skill.kind === "rule" ? ` ${BLUE$1}[rule]${RESET$3}` : ` ${CYAN$1}[skill]${RESET$3}`;
 			console.log(`${TEXT$2}${skill.name}${RESET$3}${kindBadge}${rowBadge(skill)}`);
 			if (skill.description) console.log(`${DIM$3}└ ${skill.description}${RESET$3}`);
 			console.log();
@@ -4335,19 +4492,28 @@ ${DIM$3}  2) npx pruff-skills add <skill>${RESET$3}`;
 	const all = await searchSkillsAPI("");
 	const skillCount = all.filter((s) => s.kind === "skill").length;
 	const agentCount = all.filter((s) => s.kind === "agent").length;
+	const ruleCount = all.filter((s) => s.kind === "rule").length;
 	let selected = "back";
 	while (selected === "back") {
 		const kindChoice = await ve({
 			message: "What are you looking for?",
-			options: [{
-				value: "skill",
-				label: "Skills",
-				hint: `${skillCount} available`
-			}, {
-				value: "agent",
-				label: "Subagents",
-				hint: `${agentCount} available`
-			}]
+			options: [
+				{
+					value: "skill",
+					label: "Skills",
+					hint: `${skillCount} available`
+				},
+				{
+					value: "agent",
+					label: "Subagents",
+					hint: `${agentCount} available`
+				},
+				{
+					value: "rule",
+					label: "Rules",
+					hint: `${ruleCount} available`
+				}
+			]
 		});
 		if (pD(kindChoice)) {
 			console.log(`${DIM$3}Search cancelled${RESET$3}`);
@@ -4365,6 +4531,7 @@ ${DIM$3}  2) npx pruff-skills add <skill>${RESET$3}`;
 	const skillName = selected.name;
 	console.log();
 	if (selected.kind === "agent") await addAgents([skillName], {});
+	else if (selected.kind === "rule") await addRules([skillName], {});
 	else {
 		const pkg = selected.source || selected.slug;
 		console.log(`${TEXT$2}Installing ${BOLD$3}${skillName}${RESET$3} from ${DIM$3}${pkg}${RESET$3}...`);
@@ -6012,6 +6179,7 @@ async function showBanner() {
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills list${RESET}              ${DIM}List installed skills${RESET}`);
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills find ${DIM}[query]${RESET}      ${DIM}Search the Pruff catalog${RESET}`);
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills agents add ${DIM}<name>${RESET} ${DIM}Add a Pruff subagent${RESET}`);
+	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills rules add ${DIM}<name>${RESET}  ${DIM}Add a Pruff rule (.claude/rules/)${RESET}`);
 	console.log();
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills update${RESET}            ${DIM}Update installed skills${RESET}`);
 	console.log();
@@ -6039,6 +6207,11 @@ ${BOLD}Manage Skills:${RESET}
 ${BOLD}Subagents:${RESET}
   agents add <name>    Install a Claude Code subagent into .claude/agents/ (-g for global)
 
+${BOLD}Rules:${RESET}
+  rules add <name>     Install a coding-convention rule into .claude/rules/ (-g for global)
+  rules add --scope <client|server|common>
+                       Install a whole repo's rule set (client/server also pull in common)
+
 ${BOLD}Updates:${RESET}
   update [skills...]   Update skills to latest versions (alias: upgrade)
 
@@ -6239,6 +6412,11 @@ async function main() {
 			if (!inAgent) await showLogo();
 			await runAgents(restArgs);
 			break;
+		case "rules":
+		case "rule":
+			if (!inAgent) await showLogo();
+			await runRules(restArgs);
+			break;
 		case "remove":
 		case "rm":
 		case "r":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pruff-skills",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The official Pruff agent skills CLI",
   "type": "module",
   "bin": {