@minhduydev/mdpi 0.3.0

package/dist/index.js

@@ -0,0 +1,1187 @@
+#!/usr/bin/env node
+import { cac } from "cac";
+import { dirname, join, relative } from "node:path";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import * as p from "@clack/prompts";
+import color from "picocolors";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { mkdir, readdir } from "node:fs/promises";
+//#region package.json
+var version = "0.3.0";
+//#endregion
+//#region src/utils/manifest.ts
+/**
+* Template manifest — SHA-256 hash map of every installed kit file.
+*
+* Generated by `mdpi init` after copying the kit into a project's .pi/.
+* Used by `mdpi upgrade` (future) to detect user-modified files:
+*   - "unmodified" → file matches template hash, safe to overwrite on upgrade
+*   - "modified"   → user edited it, preserve on upgrade
+*   - "unknown"    → not a template file (user-added) or no manifest present
+*
+* Ported from OpenCodeKit's utils/manifest.ts (paradigm-agnostic — file/hash
+* ops only, no OpenCode-specific coupling).
+*/
+const MANIFEST_FILE = ".template-manifest.json";
+/** Compute SHA-256 hash of a file's content. */
+function hashFile(filePath) {
+	return createHash("sha256").update(readFileSync(filePath, "utf-8")).digest("hex");
+}
+/** Walk a directory recursively → {relativePath: sha256}. */
+function buildManifestFromDir(dir, skipDirs = [
+	"node_modules",
+	".git",
+	"dist",
+	"coverage"
+]) {
+	const files = {};
+	function walk(currentDir) {
+		for (const entry of readdirSync(currentDir, { withFileTypes: true })) if (entry.isDirectory()) {
+			if (skipDirs.includes(entry.name)) continue;
+			walk(join(currentDir, entry.name));
+		} else if (entry.isFile()) {
+			if (entry.name === ".template-manifest.json") continue;
+			const fullPath = join(currentDir, entry.name);
+			files[relative(dir, fullPath)] = hashFile(fullPath);
+		}
+	}
+	walk(dir);
+	return files;
+}
+/** Generate + write the manifest into a kit directory. */
+function generateManifest(piDir, version) {
+	const manifest = {
+		version,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+		files: buildManifestFromDir(piDir)
+	};
+	writeFileSync(join(piDir, MANIFEST_FILE), JSON.stringify(manifest, null, 2));
+	return manifest;
+}
+/** Load an existing manifest, or null if none. */
+function loadManifest(piDir) {
+	const manifestPath = join(piDir, MANIFEST_FILE);
+	if (!existsSync(manifestPath)) return null;
+	try {
+		return JSON.parse(readFileSync(manifestPath, "utf-8"));
+	} catch {
+		return null;
+	}
+}
+/** Has the user modified a template file since install? */
+function fileModificationStatus(filePath, relativePath, manifest) {
+	if (!manifest) return "unknown";
+	const templateHash = manifest.files[relativePath];
+	if (!templateHash) return "unknown";
+	if (!existsSync(filePath)) return "unmodified";
+	return hashFile(filePath) === templateHash ? "unmodified" : "modified";
+}
+//#endregion
+//#region src/utils/template.ts
+/** Shared template + version helpers used by init / upgrade / doctor. */
+const DEFAULT_SKIP_DIRS = [
+	"node_modules",
+	".git",
+	"dist",
+	"coverage",
+	".next",
+	".turbo"
+];
+/** Resolve the bundled template root: dist/template (published) or repo root (dev tsx). */
+function getTemplateRoot() {
+	const __dirname = dirname(fileURLToPath(import.meta.url));
+	const candidates = [join(__dirname, "template"), join(__dirname, "..", "..")];
+	for (const candidate of candidates) if (existsSync(join(candidate, ".pi"))) return candidate;
+	return null;
+}
+/** Resolve the mdpi package version (inlined by tsdown from package.json at build). */
+function getPackageVersion() {
+	const __dirname = dirname(fileURLToPath(import.meta.url));
+	const pkgPaths = [join(__dirname, "..", "..", "package.json"), join(__dirname, "..", "package.json")];
+	for (const pkgPath of pkgPaths) {
+		if (!existsSync(pkgPath)) continue;
+		try {
+			return JSON.parse(readFileSync(pkgPath, "utf-8")).version ?? "unknown";
+		} catch {
+			continue;
+		}
+	}
+	return "unknown";
+}
+/** Walk a directory recursively → relative file paths (excludes skipDirs + skipFiles). */
+function listFilesRel(dir, skipDirs = DEFAULT_SKIP_DIRS, skipFiles = []) {
+	const out = [];
+	function walk(d) {
+		for (const e of readdirSync(d, { withFileTypes: true })) if (e.isDirectory()) {
+			if (skipDirs.includes(e.name)) continue;
+			walk(join(d, e.name));
+		} else if (e.isFile()) {
+			if (skipFiles.includes(e.name)) continue;
+			out.push(relative(dir, join(d, e.name)));
+		}
+	}
+	walk(dir);
+	return out;
+}
+//#endregion
+//#region src/commands/lint.ts
+/**
+* mdpi lint — governance checks for the .pi/ kit.
+*
+* Adapted from OpenCodeKit's validation/ suite to pi conventions:
+*   - skill-lint: pi frontmatter (name + description required, NOT version/tags/
+*     dependencies which pi doesn't use), H1, When to Use / NOT to Use, line
+*     limits, references/ depth, and DEAD CROSS-REF detection (the bug class
+*     fixed manually in commit 0a20e46 — skills referencing non-existent skills).
+*   - docs-drift: .pi/README.md counts + slash-command refs vs actual content.
+*
+* Usage: mdpi lint [skills|docs|all] [--json] [--fix]
+*   --fix auto-applies the safely-fixable rules:
+*     - name-match   → set frontmatter `name:` to the skill directory name
+*     - count-*      → rewrite the README kit-summary counts to match reality
+*   Non-fixable rules (dead-cross-ref, missing H1/frontmatter, missing/unknown
+*   prompt refs, max-lines, refs-depth) are still reported.
+* Exit code: 1 if any error-severity issue remains, else 0.
+*/
+const REQUIRED_FRONTMATTER = ["name", "description"];
+const MAX_LINES = 500;
+const MAX_LINES_WARNING = 400;
+/** Kit categories whose README "(N)" counts are verified + auto-fixable. */
+const COUNT_LABELS = [
+	"skill",
+	"prompt",
+	"agent",
+	"workflow",
+	"template"
+];
+const KNOWN_PI_BUILTINS = /* @__PURE__ */ new Set([
+	"reload",
+	"skill",
+	"memory",
+	"agent",
+	"agents",
+	"clear",
+	"compact",
+	"new",
+	"help",
+	"exit",
+	"quit",
+	"model",
+	"theme",
+	"tools",
+	"keys",
+	"config",
+	"ask",
+	"dcp",
+	"vcc",
+	"observation",
+	"session"
+]);
+function parseFrontmatter(content) {
+	const m = content.match(/^---\n([\s\S]*?)\n---/);
+	if (!m) return null;
+	const fields = {};
+	for (const line of m[1].split("\n")) {
+		const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+		if (kv) {
+			const [, key, value] = kv;
+			fields[key] = value.replace(/^['"]|['"]$/g, "").trim();
+		}
+	}
+	return fields;
+}
+function skillDirNames(skillsDir) {
+	if (!existsSync(skillsDir)) return /* @__PURE__ */ new Set();
+	return new Set(readdirSync(skillsDir).filter((n) => statSync(join(skillsDir, n)).isDirectory() && !n.startsWith(".")));
+}
+/** Extract skill names referenced in body: `/skill:<n>`, `skill:<n>`, `` `<n>` skill ``. */
+function findCrossRefs(content) {
+	const refs = /* @__PURE__ */ new Set();
+	for (const m of content.matchAll(/(?:\/skill:|skill:)([a-z0-9][a-z0-9-]*)/g)) refs.add(m[1]);
+	for (const m of content.matchAll(/`([a-z0-9][a-z0-9-]*)`\s+skill\b/g)) refs.add(m[1]);
+	return [...refs];
+}
+/** Lint one skill. With `fix=true`, rewrites the frontmatter `name:` to match the dir. */
+function lintSkill(skillsDir, name, valid, fix) {
+	const issues = [];
+	let fixed = 0;
+	const skillPath = join(skillsDir, name, "SKILL.md");
+	if (!existsSync(skillPath)) {
+		issues.push({
+			scope: name,
+			rule: "file-exists",
+			severity: "error",
+			message: "Missing SKILL.md",
+			fix: "Create SKILL.md with name + description frontmatter"
+		});
+		return {
+			issues,
+			fixed
+		};
+	}
+	const content = readFileSync(skillPath, "utf-8");
+	const lineCount = content.split("\n").length;
+	if (lineCount > MAX_LINES) issues.push({
+		scope: name,
+		rule: "max-lines",
+		severity: "error",
+		message: `${lineCount} lines (max ${MAX_LINES}); move detail to references/`,
+		fix: "Extract examples/patterns to references/"
+	});
+	else if (lineCount > MAX_LINES_WARNING) issues.push({
+		scope: name,
+		rule: "max-lines-warn",
+		severity: "warning",
+		message: `${lineCount} lines (warn ${MAX_LINES_WARNING})`
+	});
+	const fm = parseFrontmatter(content);
+	if (!fm) issues.push({
+		scope: name,
+		rule: "frontmatter",
+		severity: "error",
+		message: "Missing YAML frontmatter (--- … ---)",
+		fix: "Add frontmatter with name + description"
+	});
+	else {
+		for (const f of REQUIRED_FRONTMATTER) if (!(f in fm) || !fm[f]) issues.push({
+			scope: name,
+			rule: `frontmatter-${f}`,
+			severity: "error",
+			message: `Missing frontmatter field: ${f}`,
+			fix: `Add '${f}:'`
+		});
+		const nm = fm.name;
+		if (typeof nm === "string" && nm !== name) if (fix) {
+			const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+			if (fmMatch) {
+				const fmBody = fmMatch[1].replace(/^(\s*name:\s*).*$/m, `$1${name}`);
+				if (fmBody !== fmMatch[1]) {
+					writeFileSync(skillPath, content.replace(fmMatch[0], `---\n${fmBody}\n---`));
+					fixed++;
+				}
+			}
+		} else issues.push({
+			scope: name,
+			rule: "name-match",
+			severity: "warning",
+			message: `frontmatter name '${nm}' ≠ directory '${name}'`,
+			fix: `Set frontmatter name: ${name} (or run: mdpi lint --fix)`
+		});
+	}
+	if (!/^#\s+\S/m.test(content)) issues.push({
+		scope: name,
+		rule: "h1",
+		severity: "error",
+		message: "Missing H1 title",
+		fix: "Add '# Title' after frontmatter"
+	});
+	if (!/^##\s+When\s+to\s+Use/im.test(content)) issues.push({
+		scope: name,
+		rule: "when-to-use",
+		severity: "warning",
+		message: "Missing '## When to Use'"
+	});
+	if (!/^##\s+When\s+NOT\s+to\s+Use/im.test(content)) issues.push({
+		scope: name,
+		rule: "when-not-to-use",
+		severity: "warning",
+		message: "Missing '## When NOT to Use'"
+	});
+	for (const ref of findCrossRefs(content)) if (!valid.has(ref)) issues.push({
+		scope: name,
+		rule: "dead-cross-ref",
+		severity: "error",
+		message: `references skill '${ref}' which does not exist in .pi/skills/`,
+		fix: `Remove the reference or add skill '${ref}'`
+	});
+	const refsDir = join(skillsDir, name, "references");
+	if (existsSync(refsDir)) {
+		const nested = readdirSync(refsDir).filter((e) => statSync(join(refsDir, e)).isDirectory());
+		if (nested.length) issues.push({
+			scope: name,
+			rule: "refs-depth",
+			severity: "warning",
+			message: `${nested.length} nested dir(s) in references/ — prefer flat`,
+			fix: "Flatten references/ to one level"
+		});
+	}
+	return {
+		issues,
+		fixed
+	};
+}
+function lintSkills(piDir, fix = false) {
+	const skillsDir = join(piDir, "skills");
+	if (!existsSync(skillsDir)) return {
+		ok: false,
+		issues: [{
+			scope: "(root)",
+			rule: "skills-dir",
+			severity: "error",
+			message: `skills/ not found: ${skillsDir}`
+		}],
+		stats: {
+			total: 0,
+			passed: 0,
+			failed: 0,
+			warnings: 0,
+			fixed: 0
+		}
+	};
+	const valid = skillDirNames(skillsDir);
+	const names = [...valid].sort();
+	const issues = [];
+	let failed = 0;
+	let warns = 0;
+	let fixed = 0;
+	for (const n of names) {
+		const si = lintSkill(skillsDir, n, valid, fix);
+		issues.push(...si.issues);
+		if (si.issues.some((i) => i.severity === "error")) failed++;
+		warns += si.issues.filter((i) => i.severity === "warning").length;
+		fixed += si.fixed;
+	}
+	return {
+		ok: failed === 0,
+		issues,
+		stats: {
+			total: names.length,
+			passed: names.length - failed,
+			failed,
+			warnings: warns,
+			fixed
+		}
+	};
+}
+/**
+* Rewrite the README kit-summary counts to match reality. For each label, finds
+* the first `` `label/` (N…) `` form and replaces N with the actual count,
+* preserving any suffix (e.g. ` + INDEX`). Only matches the backtick-wrapped
+* kit-summary form — leaves prose mentions of counts untouched.
+*/
+function fixReadmeCounts(readme, counts) {
+	let out = readme;
+	for (const [label, actual] of Object.entries(counts)) {
+		const re = new RegExp("(`" + label + "s?/?`\\s*\\()(\\d+)([^)]*\\))");
+		out = out.replace(re, (_m, pre, _n, suf) => `${pre}${actual}${suf}`);
+	}
+	return out;
+}
+function lintDocs(piDir, fix = false) {
+	const readmePath = join(piDir, "README.md");
+	if (!existsSync(readmePath)) return {
+		ok: true,
+		issues: [],
+		stats: {
+			total: 0,
+			passed: 0,
+			failed: 0,
+			warnings: 0,
+			fixed: 0
+		}
+	};
+	const readme = readFileSync(readmePath, "utf-8");
+	const issues = [];
+	const list = (sub) => existsSync(join(piDir, sub)) ? readdirSync(join(piDir, sub)).filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")) : [];
+	const actualPrompts = list("prompts").filter((n) => n !== "INDEX").sort();
+	const actualAgents = list("agents").filter((n) => n !== "INDEX").length;
+	const actualSkills = existsSync(join(piDir, "skills")) ? readdirSync(join(piDir, "skills")).filter((n) => statSync(join(piDir, "skills", n)).isDirectory()).length : 0;
+	const actualWorkflows = list("workflows").filter((n) => n !== "INDEX").length;
+	const actualTemplates = list("templates").filter((n) => n !== "INDEX").length;
+	const counts = {
+		skill: actualSkills,
+		prompt: actualPrompts.length,
+		agent: actualAgents,
+		workflow: actualWorkflows,
+		template: actualTemplates
+	};
+	const documented = /* @__PURE__ */ new Set();
+	for (const m of readme.matchAll(/`\/([a-z0-9-]+)`/g)) documented.add(m[1]);
+	for (const cmd of actualPrompts) if (!documented.has(cmd)) issues.push({
+		scope: "README",
+		rule: "readme-missing-prompt",
+		severity: "warning",
+		message: `README missing '/${cmd}' (prompt exists)`
+	});
+	for (const cmd of documented) if (!actualPrompts.includes(cmd) && !KNOWN_PI_BUILTINS.has(cmd)) issues.push({
+		scope: "README",
+		rule: "readme-unknown-prompt",
+		severity: "warning",
+		message: `README references unknown '/${cmd}'`
+	});
+	const drift = (label) => {
+		const actual = counts[label];
+		const m = readme.match(new RegExp(`\\b${label}s?[^\\(\\n]*\\((\\d+)[^)]*\\)`));
+		if (!m) return null;
+		const doc = Number.parseInt(m[1], 10);
+		return doc === actual ? null : {
+			doc,
+			actual
+		};
+	};
+	const driftedLabeled = COUNT_LABELS.map((label) => ({
+		label,
+		d: drift(label)
+	})).filter((x) => x.d);
+	let fixed = 0;
+	if (fix) {
+		if (driftedLabeled.length) {
+			const fixedReadme = fixReadmeCounts(readme, counts);
+			if (fixedReadme !== readme) {
+				writeFileSync(readmePath, fixedReadme);
+				fixed = driftedLabeled.length;
+			}
+		}
+	} else for (const { label, d } of driftedLabeled) issues.push({
+		scope: "README",
+		rule: `count-${label}`,
+		severity: "warning",
+		message: `${label} count (${d.doc}) ≠ actual (${d.actual})`,
+		fix: `Update README ${label} count to ${d.actual} (or run: mdpi lint --fix)`
+	});
+	return {
+		ok: issues.length === 0,
+		issues,
+		stats: {
+			total: 1,
+			passed: issues.length === 0 ? 1 : 0,
+			failed: 0,
+			warnings: issues.length,
+			fixed
+		}
+	};
+}
+function lintAll(piDir, opts = {}) {
+	const target = opts.target ?? "all";
+	const fix = opts.fix ?? false;
+	const results = [];
+	if (target === "skills" || target === "all") results.push({
+		name: "skills",
+		r: lintSkills(piDir, fix)
+	});
+	if (target === "docs" || target === "all") results.push({
+		name: "docs",
+		r: lintDocs(piDir, fix)
+	});
+	if (opts.json) {
+		console.log(JSON.stringify(results, null, 2));
+		const anyFail = results.some(({ r }) => !r.ok);
+		process.exitCode = anyFail ? 1 : 0;
+		return;
+	}
+	const totalFixed = results.reduce((s, { r }) => s + r.stats.fixed, 0);
+	for (const { name, r } of results) {
+		const fixedNote = r.stats.fixed ? color.green(` · ${r.stats.fixed} fixed`) : "";
+		console.log(`\n${color.bold(color.cyan(name))}: ${r.stats.total} total · ${r.stats.passed} passed · ${r.stats.failed} failed · ${r.stats.warnings} warnings${fixedNote}`);
+		const byScope = /* @__PURE__ */ new Map();
+		for (const i of r.issues) {
+			const a = byScope.get(i.scope) ?? [];
+			a.push(i);
+			byScope.set(i.scope, a);
+		}
+		for (const [scope, iss] of byScope) {
+			const hasErr = iss.some((i) => i.severity === "error");
+			console.log(`  ${hasErr ? color.red("✗") : color.yellow("⚠")} ${scope}`);
+			for (const i of iss) {
+				console.log(`    ${i.severity === "error" ? color.red("ERR ") : color.yellow("WARN")} [${i.rule}] ${i.message}`);
+				if (i.fix) console.log(`         fix: ${i.fix}`);
+			}
+		}
+	}
+	if (totalFixed) console.log(`\n${color.green("✓")} auto-fixed ${totalFixed} issue(s)`);
+	const anyFail = results.some(({ r }) => !r.ok);
+	process.exitCode = anyFail ? 1 : 0;
+}
+//#endregion
+//#region src/commands/doctor.ts
+/**
+* mdpi doctor — .pi/ health check.
+*
+* Verifies: mdpi version match, manifest valid, settings.json valid JSON, kit
+* dirs present (skills/prompts/agents/templates/workflows/extensions), orphan
+* detection (manifest files no longer in template), and a lint summary.
+*/
+function row(ok, label, detail) {
+	console.log(`  ${ok ? color.green("✓") : color.red("✗")} ${label}: ${detail}`);
+}
+async function doctorCommand(options = {}) {
+	const quiet = process.argv.includes("--quiet");
+	if (!quiet) p.intro(color.bgCyan(color.black(" mdpi doctor ")));
+	const piDir = join(process.cwd(), ".pi");
+	if (!existsSync(piDir)) {
+		if (!quiet) {
+			p.log.error(".pi/ not found — run `mdpi init`");
+			p.outro(color.red("Failed"));
+		}
+		process.exitCode = 1;
+		return;
+	}
+	const mdpiVersion = getPackageVersion();
+	const installedVersion = existsSync(join(piDir, ".version")) ? readFileSync(join(piDir, ".version"), "utf-8").trim() : "(none)";
+	let manifest = loadManifest(piDir);
+	let manifestOk = !!manifest && typeof manifest.version === "string" && !!manifest.files;
+	let manifestFixed = false;
+	if (!manifestOk && options.fix) {
+		manifest = generateManifest(piDir, installedVersion !== "(none)" ? installedVersion : mdpiVersion);
+		manifestOk = !!manifest && !!manifest.files;
+		manifestFixed = manifestOk;
+	}
+	let settingsOk = false;
+	try {
+		JSON.parse(readFileSync(join(piDir, "settings.json"), "utf-8"));
+		settingsOk = true;
+	} catch {
+		settingsOk = false;
+	}
+	const countMd = (sub) => existsSync(join(piDir, sub)) ? readdirSync(join(piDir, sub)).filter((f) => f.endsWith(".md") && f !== "INDEX.md").length : 0;
+	const countExt = (sub, ext) => existsSync(join(piDir, sub)) ? readdirSync(join(piDir, sub)).filter((f) => f.endsWith(ext)).length : 0;
+	const skillCount = existsSync(join(piDir, "skills")) ? readdirSync(join(piDir, "skills")).filter((n) => statSync(join(piDir, "skills", n)).isDirectory()).length : 0;
+	const templateRoot = getTemplateRoot();
+	let orphans = 0;
+	if (templateRoot && manifest) {
+		const srcPi = join(templateRoot, ".pi");
+		const newFiles = new Set(listFilesRel(srcPi, [
+			"node_modules",
+			".git",
+			"dist",
+			"coverage"
+		], [".template-manifest.json"]));
+		orphans = Object.keys(manifest.files).filter((f) => !newFiles.has(f) && f !== ".version").length;
+	}
+	console.log(`\n${color.bold("mdpi doctor")} — .pi/ health\n`);
+	row(true, "mdpi version", `installed ${installedVersion} · cli ${mdpiVersion}` + (installedVersion !== mdpiVersion ? color.yellow("  (out of date — run mdpi upgrade)") : ""));
+	row(manifestOk, "manifest", manifestOk ? `${Object.keys(manifest.files).length} files tracked (v${manifest.version})` + (manifestFixed ? color.green("  (regenerated by --fix)") : "") : "missing or invalid .template-manifest.json" + (options.fix ? "" : " (run: mdpi doctor --fix)"));
+	row(settingsOk, "settings.json", settingsOk ? "valid JSON" : "INVALID JSON");
+	row(skillCount > 0, "skills", `${skillCount} skill dirs`);
+	row(countMd("prompts") > 0, "prompts", `${countMd("prompts")} prompts`);
+	row(countMd("agents") > 0, "agents", `${countMd("agents")} agents`);
+	row(countMd("templates") > 0, "templates", `${countMd("templates")} templates`);
+	row(countMd("workflows") > 0, "workflows", `${countMd("workflows")} workflows`);
+	row(countExt("extensions", ".ts") > 0, "extensions", `${countExt("extensions", ".ts")} extensions`);
+	if (templateRoot) row(orphans === 0, "orphans", orphans === 0 ? "none (template-removed files)" : `${orphans} orphan(s) — run mdpi upgrade --prune-all`);
+	const lr = lintSkills(piDir);
+	console.log(`  ${lr.ok ? color.green("✓") : color.red("✗")} lint: ${lr.stats.failed} errors · ${lr.stats.warnings} warnings (run ${color.cyan("mdpi lint")} for detail)`);
+	const healthy = manifestOk && settingsOk && skillCount > 0 && lr.stats.failed === 0;
+	if (!quiet) p.outro(healthy ? color.green("Healthy") : color.yellow("Issues found"));
+	process.exitCode = healthy ? 0 : 1;
+}
+//#endregion
+//#region src/commands/init.ts
+/**
+* mdpi init — scaffold a Pi coding-agent kit (.pi/) into the current repo.
+*
+* Mirrors OpenCodeKit's `ock init` but pi-native:
+*   - No license gate (open MIT).
+*   - No --global (pi global dir ~/.pi/agent/ is pi's own config; installing the
+*     full kit there is a footgun). Project-local only.
+*   - Bundled template is the CURATED kit (runtime dirs already stripped at
+*     build time by scripts/bundle-template.mjs).
+*
+* After copy, writes .pi/.version and generates .pi/.template-manifest.json
+* (SHA-256 map) so a future `mdpi upgrade` can detect user modifications.
+*
+* --only <cats> installs only the listed category dirs (plus the always-on kit
+* config/docs) and rewrites settings.json to drop references to the excluded
+* `skills`/`prompts`/`extensions` dirs so pi doesn't resolve dangling paths.
+* Caveat: `mdpi upgrade` always compares against the FULL template — a subset
+* install is not remembered as partial, so upgrade will offer the missing
+* categories (use `--check` first, or re-run `init` without `--only`).
+*
+* --quiet suppresses the @clack UI but still performs the install (emits one
+* machine-readable line). --force overwrites template files but preserves any
+* extra user-created files under .pi/ (safe, non-destructive to custom work).
+*/
+const EXCLUDED_DIRS = [
+	"node_modules",
+	".git",
+	"dist",
+	".DS_Store",
+	"coverage",
+	".next",
+	".turbo"
+];
+const EXCLUDED_FILES = [
+	"bun.lock",
+	"package-lock.json",
+	"yarn.lock",
+	"pnpm-lock.yaml"
+];
+/** Selectable kit categories for `--only`. */
+const CATEGORIES = [
+	"agents",
+	"prompts",
+	"skills",
+	"templates",
+	"workflows",
+	"context",
+	"extensions"
+];
+/** Kit infrastructure always installed (not selectable via --only). */
+const ALWAYS_ENTRIES = [
+	"scripts",
+	"artifacts/example",
+	"settings.json",
+	"AGENTS.md",
+	"README.md",
+	"QUALITY.md",
+	"VERSION",
+	".env.example",
+	"guard.example.json",
+	"subagents.json"
+];
+/** Recursively copy a directory, skipping runtime/lockfile noise. */
+async function copyDir(src, dest) {
+	await mkdir(dest, { recursive: true });
+	for (const entry of await readdir(src, { withFileTypes: true })) {
+		if (EXCLUDED_DIRS.includes(entry.name)) continue;
+		if (!entry.isDirectory() && EXCLUDED_FILES.includes(entry.name)) continue;
+		const srcPath = join(src, entry.name);
+		const destPath = join(dest, entry.name);
+		if (entry.isSymbolicLink()) continue;
+		if (entry.isDirectory()) await copyDir(srcPath, destPath);
+		else writeFileSync(destPath, readFileSync(srcPath, "utf-8"));
+	}
+}
+/** Copy one template entry (dir or file) into the kit, creating parent dirs. */
+async function copyEntry(srcPi, piDir, rel) {
+	const from = join(srcPi, rel);
+	if (!existsSync(from)) return;
+	const to = join(piDir, rel);
+	if (statSync(from).isDirectory()) await copyDir(from, to);
+	else {
+		await mkdir(join(to, ".."), { recursive: true });
+		writeFileSync(to, readFileSync(from, "utf-8"));
+	}
+}
+/** Parse `--only cats` into a Set. Throws on an unknown category. */
+function parseOnly(only) {
+	if (!only) return null;
+	const cats = /* @__PURE__ */ new Set();
+	for (const raw of only.split(",").map((s) => s.trim()).filter(Boolean)) {
+		if (!CATEGORIES.includes(raw)) throw new Error(`unknown --only category '${raw}'. Valid: ${CATEGORIES.join(", ")}`);
+		cats.add(raw);
+	}
+	return cats;
+}
+/**
+* Drop settings.json keys that reference excluded category dirs so pi doesn't
+* resolve dangling `./skills`, `./prompts`, `./extensions` paths. `packages`
+* (general pi runtime deps) is left untouched — agents/skills may still use
+* those tools even when a category dir is absent.
+*/
+function adaptSettingsJson(piDir, only) {
+	const path = join(piDir, "settings.json");
+	if (!existsSync(path)) return false;
+	let json;
+	try {
+		json = JSON.parse(readFileSync(path, "utf-8"));
+	} catch {
+		return false;
+	}
+	let changed = false;
+	for (const key of [
+		"skills",
+		"prompts",
+		"extensions"
+	]) if (!only.has(key) && key in json) {
+		delete json[key];
+		changed = true;
+	}
+	if (changed) writeFileSync(path, JSON.stringify(json, null, 2) + "\n");
+	return changed;
+}
+async function initCommand(options = {}) {
+	const quiet = process.argv.includes("--quiet");
+	if (!quiet) p.intro(color.bgCyan(color.black(" mdpi ")));
+	let only = null;
+	if (options.only) try {
+		only = parseOnly(options.only);
+	} catch (error) {
+		if (!quiet) {
+			p.log.error(error instanceof Error ? error.message : String(error));
+			p.outro(color.red("Failed"));
+		}
+		process.exitCode = 1;
+		return;
+	}
+	const piDir = join(process.cwd(), ".pi");
+	if (!quiet) p.log.info(`Installing Pi kit to: ${color.cyan(piDir)}`);
+	if (existsSync(piDir) && !options.force) {
+		if (!quiet) {
+			p.log.warn(".pi/ already exists in this project");
+			p.log.info(`Use ${color.cyan("--force")} to overwrite template files (preserves extra user files)`);
+			p.outro("Nothing to do");
+		}
+		return;
+	}
+	const templateRoot = getTemplateRoot();
+	if (!templateRoot) {
+		if (!quiet) {
+			p.log.error("Template not found. Please reinstall mdpi.");
+			p.outro(color.red("Failed"));
+		}
+		process.exitCode = 1;
+		return;
+	}
+	const srcPi = join(templateRoot, ".pi");
+	if (!existsSync(srcPi)) {
+		if (!quiet) {
+			p.log.error("Template .pi/ not found");
+			p.outro(color.red("Failed"));
+		}
+		process.exitCode = 1;
+		return;
+	}
+	const spinner = quiet ? null : p.spinner();
+	spinner?.start(only ? `Copying subset (${[...only].join(",")}) to .pi/` : "Copying kit to .pi/");
+	try {
+		if (only) {
+			for (const entry of ALWAYS_ENTRIES) await copyEntry(srcPi, piDir, entry);
+			for (const cat of CATEGORIES) if (only.has(cat)) await copyEntry(srcPi, piDir, cat);
+		} else await copyDir(srcPi, piDir);
+	} catch (error) {
+		spinner?.stop("Failed");
+		if (!quiet) {
+			p.log.error(error instanceof Error ? error.message : String(error));
+			p.outro(color.red("Failed"));
+		}
+		process.exitCode = 1;
+		return;
+	}
+	spinner?.stop("Done");
+	const version = getPackageVersion();
+	writeFileSync(join(piDir, ".version"), version);
+	if (only) adaptSettingsJson(piDir, only);
+	const manifest = generateManifest(piDir, version);
+	const fileCount = Object.keys(manifest.files).length;
+	if (quiet) {
+		const subset = only ? ` subset=[${[...only].join(",")}]` : "";
+		console.log(`mdpi: installed ${fileCount} files to ${piDir} (v${version})${subset}`);
+	} else {
+		const subsetNote = only ? `Subset: ${[...only].join(", ")} (+ always-on config).\n\nsettings.json trimmed to drop references to excluded\nskills/prompts/extensions dirs.\n\nNote: mdpi upgrade compares against the FULL template —\nrun \`mdpi upgrade --check\` before applying.\n\n` : "";
+		p.note(`Pi kit installed at:\n${piDir}\n\n${fileCount} template files tracked via manifest.\n\n` + subsetNote + `Next: open pi in this repo to use the kit.`, "Installation complete");
+		p.outro(color.green("Ready!"));
+	}
+}
+//#endregion
+//#region src/commands/new.ts
+/**
+* mdpi new — scaffold a new kit component from a lint-passing skeleton.
+*
+*   mdpi new <kind> <name> [--description <text>] [--force]
+*
+* Kinds + destinations:
+*   skill      → .pi/skills/<name>/SKILL.md
+*   prompt     → .pi/prompts/<name>.md
+*   agent      → .pi/agents/<name>.md
+*   workflow   → .pi/workflows/<name>.md
+*   template   → .pi/templates/<name>.md
+*
+* Skeletons are pre-shaped to pass `mdpi lint` immediately (skills get
+* frontmatter + H1 + When to Use / NOT; workflows get the DAG phase format;
+* prompts get the $ARGUMENTS + argument table). Idempotent: refuses to
+* overwrite an existing file unless --force.
+*/
+const KINDS = [
+	"skill",
+	"prompt",
+	"agent",
+	"workflow",
+	"template"
+];
+/** Title-case a kebab name for H1s: "my-skill" → "My Skill". */
+function titleCase(name) {
+	return name.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+/** Validate a kebab-case file/dir name (lowercase letters, digits, hyphens). */
+function validName(name) {
+	return /^[a-z][a-z0-9-]*[a-z0-9]$|^[a-z]$/.test(name) && !name.includes("--");
+}
+/** Build the skeleton body for a kind, substituting name + description. */
+function skeleton(kind, name, desc) {
+	const title = titleCase(name);
+	const description = desc || `TODO: when to use this ${kind}`;
+	switch (kind) {
+		case "skill": return `---
+name: ${name}
+description: ${description}
+---
+
+# ${title}
+
+TODO: what this skill does and when to reach for it.
+
+## When to Use
+
+- TODO: trigger conditions and boundaries
+
+## When NOT to Use
+
+- TODO: when to avoid this skill (overlapping skills, anti-patterns)
+
+## Procedure
+
+1. TODO: first concrete step
+2. TODO: second step
+
+## Pitfalls
+
+- TODO: common mistake / caveat
+
+## Verification
+
+- TODO: how to confirm success
+`;
+		case "prompt": return `---
+description: ${description}
+argument-hint: "[<args>] [--help]"
+---
+
+# ${title}: $ARGUMENTS
+
+TODO: what this slash command does.
+
+## Parse Arguments
+
+| Argument     | Default  | Description                |
+| ------------ | -------- | -------------------------- |
+| \`<args>\`    | required | TODO: what the user passes |
+| \`--help\`   | false    | Show this usage             |
+
+## Phase 1: TODO
+
+TODO: first step.
+`;
+		case "agent": return `---
+name: ${name}
+description: ${description}
+tools: read, grep, find, ls, bash, edit, write
+model: ollama-cloud/glm-5.2
+---
+
+You are a Pi subagent.
+
+# ${title}
+
+**Purpose**: TODO — one line on what this agent is for.
+
+## When to dispatch
+
+TODO: trigger conditions.
+
+## Constraints
+
+- TODO: scope boundaries (files touched, tools allowed)
+`;
+		case "workflow": return `---
+description: ${description}
+---
+
+# ${name}
+
+TODO: what this workflow does. Use when ...
+
+## Args
+
+- \`arg1\` (required) — TODO: what the caller passes
+
+## Phases
+
+### Phase 1: TODO
+
+- **Agent:** general
+- **Concurrency:** 1
+- **Depends on:** —
+- **Tool:** \`subagent\`
+
+**Prompt:**
+
+\`\`\`
+TODO: prompt for phase 1.
+\`\`\`
+`;
+		case "template": return `# ${title} Template
+
+> **Template Instructions:**
+>
+> - Replace ALL bracketed placeholders with real content
+> - If you cannot fill a section, use \`[NEEDS CLARIFICATION: reason]\` instead of guessing
+
+## Section 1
+
+TODO: content.
+`;
+	}
+}
+/** Resolve the destination path for a kind + name. */
+function destPath(piDir, kind, name) {
+	switch (kind) {
+		case "skill": return join(piDir, "skills", name, "SKILL.md");
+		case "prompt": return join(piDir, "prompts", `${name}.md`);
+		case "agent": return join(piDir, "agents", `${name}.md`);
+		case "workflow": return join(piDir, "workflows", `${name}.md`);
+		case "template": return join(piDir, "templates", `${name}.md`);
+	}
+}
+async function newCommand(kindArg, name, options = {}) {
+	const quiet = process.argv.includes("--quiet");
+	if (!quiet) p.intro(color.bgCyan(color.black(" mdpi new ")));
+	if (!KINDS.includes(kindArg)) {
+		if (!quiet) {
+			p.log.error(`unknown kind '${kindArg}'. Valid: ${KINDS.join(", ")}`);
+			p.outro(color.red("Failed"));
+		}
+		process.exitCode = 1;
+		return;
+	}
+	const kind = kindArg;
+	if (!name || !validName(name)) {
+		if (!quiet) {
+			p.log.error(`invalid name '${name ?? ""}'. Use kebab-case (lowercase letters, digits, hyphens; no leading/trailing/double hyphen).`);
+			p.outro(color.red("Failed"));
+		}
+		process.exitCode = 1;
+		return;
+	}
+	const piDir = join(process.cwd(), ".pi");
+	if (!existsSync(piDir)) {
+		if (!quiet) {
+			p.log.error(".pi/ not found — run `mdpi init` first");
+			p.outro(color.red("Failed"));
+		}
+		process.exitCode = 1;
+		return;
+	}
+	const dest = destPath(piDir, kind, name);
+	if (existsSync(dest) && !options.force) {
+		if (!quiet) {
+			p.log.warn(`${dest} already exists`);
+			p.log.info(`Use ${color.cyan("--force")} to overwrite`);
+			p.outro("Nothing to do");
+		}
+		return;
+	}
+	mkdirSync(join(dest, ".."), { recursive: true });
+	writeFileSync(dest, skeleton(kind, name, options.description ?? ""));
+	if (quiet) console.log(`mdpi: created ${kind} '${name}' → ${dest}`);
+	else {
+		p.note(`Created: ${color.cyan(dest)}\n\nEdit the skeleton, then run ${color.cyan("mdpi lint")} to verify.`, "Scaffolded");
+		p.outro(color.green("Ready!"));
+	}
+}
+//#endregion
+//#region src/commands/upgrade.ts
+/**
+* mdpi upgrade — bring an installed .pi/ kit up to the bundled template version.
+*
+* Manifest-based (no patch files): for each template file, compare the user's
+* current file hash against the install-time manifest:
+*   - "unmodified" → safe to overwrite with the new template version
+*   - "modified"   → user edited it → preserve (skip) unless --force
+*   - "unknown"   → not in manifest (new template file, or no manifest) → add
+*                   (or, with no manifest, preserve unless --force)
+*
+* Orphans = files in the manifest but no longer in the new template
+* (template-removed). Listed by default; --prune-all deletes them.
+*
+* Flags: --check (dry-run), --force (overwrite modified), --prune-all (delete
+* orphans). --quiet → 1-line machine output.
+*/
+const SKIP_DIRS = [
+	"node_modules",
+	".git",
+	"dist",
+	"coverage",
+	".next",
+	".turbo"
+];
+/**
+* Classify each template file against the install-time manifest.
+* Pure logic (no fs writes) — extracted so it can be unit-tested.
+*
+*   unmodified → toUpdate (hash matches manifest)
+*   modified   → preserved unless force (user edited it)
+*   unknown    → toAdd if a manifest exists (new template file); with no
+*               manifest, preserved unless force (can't detect edits)
+*/
+function classifyFiles(newFiles, piDir, manifest, force) {
+	const toUpdate = [];
+	const toAdd = [];
+	const preserved = [];
+	for (const rel of newFiles) {
+		const status = fileModificationStatus(join(piDir, rel), rel, manifest);
+		if (status === "unmodified") toUpdate.push(rel);
+		else if (status === "modified") if (force) toUpdate.push(rel);
+		else preserved.push(rel);
+		else if (manifest) toAdd.push(rel);
+		else if (force) toAdd.push(rel);
+		else preserved.push(rel);
+	}
+	return {
+		toUpdate,
+		toAdd,
+		preserved
+	};
+}
+/**
+* Orphans: files in the manifest but no longer in the new template
+* (template-removed since install). Excludes `.version` — it is mdpi-managed
+* (regenerated each init/upgrade), not a template file, so it must never be a
+* prune candidate. Returns [] when there is no manifest.
+*/
+function findOrphans(installedFiles, newFiles, manifest) {
+	if (!manifest) return [];
+	const newSet = new Set(newFiles);
+	return installedFiles.filter((f) => !newSet.has(f) && f in manifest.files && f !== ".version");
+}
+async function upgradeCommand(options = {}) {
+	const quiet = process.argv.includes("--quiet");
+	if (!quiet) p.intro(color.bgCyan(color.black(" mdpi upgrade ")));
+	const piDir = join(process.cwd(), ".pi");
+	if (!existsSync(piDir)) {
+		if (!quiet) {
+			p.log.error(".pi/ not found — run `mdpi init` first");
+			p.outro(color.red("Failed"));
+		}
+		process.exitCode = 1;
+		return;
+	}
+	const templateRoot = getTemplateRoot();
+	if (!templateRoot) {
+		if (!quiet) {
+			p.log.error("Template not found. Reinstall mdpi.");
+			p.outro(color.red("Failed"));
+		}
+		process.exitCode = 1;
+		return;
+	}
+	const srcPi = join(templateRoot, ".pi");
+	const currentVersion = existsSync(join(piDir, ".version")) ? readFileSync(join(piDir, ".version"), "utf-8").trim() : "unknown";
+	const targetVersion = getPackageVersion();
+	const manifest = loadManifest(piDir);
+	const newFiles = listFilesRel(srcPi, SKIP_DIRS, [MANIFEST_FILE]);
+	const installedFiles = listFilesRel(piDir, SKIP_DIRS, [MANIFEST_FILE]);
+	const { toUpdate, toAdd, preserved } = classifyFiles(newFiles, piDir, manifest, !!options.force);
+	const orphans = findOrphans(installedFiles, newFiles, manifest);
+	if (!quiet) {
+		p.log.info(`v${currentVersion} → v${targetVersion}`);
+		p.log.info(`update ${toUpdate.length} · add ${toAdd.length} · preserve ${preserved.length} (user-modified) · orphans ${orphans.length}`);
+		if (preserved.length) p.log.warn(`preserved: ${preserved.slice(0, 5).join(", ")}${preserved.length > 5 ? " …" : ""}`);
+		if (orphans.length && !options.pruneAll) p.log.warn(`orphans kept: ${orphans.slice(0, 5).join(", ")}${orphans.length > 5 ? " …" : ""} — use --prune-all to delete`);
+	}
+	if (currentVersion === targetVersion && toUpdate.length === 0 && toAdd.length === 0 && !options.force) {
+		if (!quiet) p.outro(color.green("Already up to date"));
+		return;
+	}
+	if (options.check) {
+		if (!quiet) p.outro("dry-run (--check), no changes written");
+		return;
+	}
+	if (!manifest && !options.force) {
+		if (!quiet) {
+			p.log.error("no manifest — cannot safely detect user modifications. Use --force to overwrite everything.");
+			p.outro(color.red("Aborted"));
+		}
+		process.exitCode = 1;
+		return;
+	}
+	const spinner = quiet ? null : p.spinner();
+	spinner?.start("Applying upgrade");
+	try {
+		for (const rel of [...toUpdate, ...toAdd]) {
+			const dest = join(piDir, rel);
+			mkdirSync(dirname(dest), { recursive: true });
+			cpSync(join(srcPi, rel), dest);
+		}
+		if (options.pruneAll) for (const rel of orphans) rmSync(join(piDir, rel));
+	} catch (error) {
+		spinner?.stop("Failed");
+		if (!quiet) {
+			p.log.error(error instanceof Error ? error.message : String(error));
+			p.outro(color.red("Failed"));
+		}
+		process.exitCode = 1;
+		return;
+	}
+	spinner?.stop("Done");
+	writeFileSync(join(piDir, ".version"), targetVersion);
+	const newManifest = generateManifest(piDir, targetVersion);
+	const total = Object.keys(newManifest.files).length;
+	const prunedNote = options.pruneAll ? ` · pruned ${orphans.length}` : "";
+	if (quiet) console.log(`mdpi: upgraded v${currentVersion}→v${targetVersion} (${toUpdate.length} updated, ${toAdd.length} added${prunedNote}, ${total} tracked)`);
+	else {
+		p.note(`Upgraded v${currentVersion} → v${targetVersion}\n\n${toUpdate.length} updated · ${toAdd.length} added · ${preserved.length} preserved${prunedNote}\n${total} files now tracked.`, "Upgrade complete");
+		p.outro(color.green("Ready!"));
+	}
+}
+//#endregion
+//#region src/utils/logger.ts
+const WEIGHT = {
+	debug: 10,
+	info: 20,
+	warn: 30,
+	error: 40
+};
+let threshold = "info";
+function setLogLevel(level) {
+	threshold = level;
+}
+function emit(level, message) {
+	if (WEIGHT[level] < WEIGHT[threshold]) return;
+	const tag = level === "error" ? "error:" : level === "warn" ? "warn:" : level === "debug" ? "debug:" : "";
+	if (level === "error") console.error(tag ? `${tag} ${message}` : message);
+	else console.log(tag ? `${tag} ${message}` : message);
+}
+const logger = {
+	debug: (msg) => emit("debug", msg),
+	info: (msg) => emit("info", msg),
+	warn: (msg) => emit("warn", msg),
+	error: (msg) => emit("error", msg)
+};
+//#endregion
+//#region src/index.ts
+if (process.stdout.setEncoding) process.stdout.setEncoding("utf8");
+if (process.stderr.setEncoding) process.stderr.setEncoding("utf8");
+const packageVersion = version;
+const cli = cac("mdpi");
+cli.option("--verbose", "Enable verbose (debug) logging");
+cli.option("--quiet", "Suppress UI output");
+cli.version(`${packageVersion}`);
+cli.help();
+cli.command("init", "Scaffold a Pi coding-agent kit (.pi/) into the current repo").option("--force", "Overwrite existing .pi/ template files (preserves extra user files)").option("-y, --yes", "Skip prompts, use defaults (for CI)").option("--only <cats>", "Install only these categories (comma-sep: agents,prompts,skills,templates,workflows,context,extensions)").action(async (options) => {
+	await initCommand(options);
+});
+cli.command("upgrade", "Bring .pi/ up to the bundled template version").option("--force", "Overwrite user-modified files (default: preserve them)").option("--check", "Dry-run: report what would change without writing").option("--prune-all", "Delete orphan files (template-removed since install)").action(async (options) => {
+	await upgradeCommand(options);
+});
+cli.command("new <kind> [name]", "Scaffold a new kit component (skill|prompt|agent|workflow|template)").option("-d, --description <text>", "Set the frontmatter description (default: TODO placeholder)").option("--force", "Overwrite an existing file at the destination").action(async (kind, name, options) => {
+	await newCommand(kind, name, {
+		force: options?.force,
+		description: options?.description
+	});
+});
+cli.command("lint [target]", "Governance checks (skills|docs|all)").option("--json", "Output machine-readable JSON").option("--fix", "Auto-fix fixable issues (name-match, README counts)").action(async (target, options) => {
+	lintAll(join(process.cwd(), ".pi"), {
+		target: target ?? "all",
+		json: options?.json,
+		fix: options?.fix
+	});
+});
+cli.command("doctor", "Check .pi/ health").option("--fix", "Auto-fix: regenerate manifest if missing/invalid").action(async (options) => {
+	await doctorCommand({ fix: options?.fix });
+});
+cli.command("", "Show help").action(() => {
+	cli.outputHelp();
+});
+try {
+	const argv = process.argv.slice(2);
+	if (argv.includes("--verbose")) setLogLevel("debug");
+	if (argv.includes("--quiet")) setLogLevel("error");
+	cli.parse(process.argv);
+} catch (error) {
+	logger.error(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+}
+//#endregion
+export { cli };