pi-rules-md 0.0.0-stage → 0.1.0

package/dist/cli.mjs

@@ -0,0 +1,842 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { existsSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { spawn } from "node:child_process";
+
+//#region src/cli/constants.ts
+const PACKAGE_NAME = "pi-rules-md";
+
+//#endregion
+//#region src/cli/interlock.ts
+function sandboxRefusal(opts) {
+	if ((opts.env.VITEST === "true" || opts.env.NODE_ENV === "test") && opts.agentDir === void 0) return "refusing to mutate Pi settings without an explicit agent directory under a test runtime; pass --agent-dir or set PI_RULES_AGENT_DIR";
+	return null;
+}
+
+//#endregion
+//#region src/cli/match.ts
+async function findMatchingEntries(packages, opts) {
+	const matches = [];
+	const unmatchedLocal = [];
+	for (const entry of packages) {
+		if (entry.kind === "malformed") continue;
+		const { source } = entry;
+		if (source.startsWith("npm:")) {
+			const spec = source.slice(4);
+			if (spec === "pi-rules-md") matches.push({
+				entry,
+				source,
+				kind: "npm"
+			});
+			else if (spec.startsWith(`${"pi-rules-md"}@`) && isVersion(spec.slice("pi-rules-md".length + 1))) matches.push({
+				entry,
+				source,
+				kind: "npm-pinned",
+				version: spec.slice(PACKAGE_NAME.length + 1)
+			});
+			continue;
+		}
+		if (source.startsWith("git:")) {
+			const repo = source.slice(4).split(/[?#]/, 1)[0] ?? "";
+			if (path.posix.basename(repo.replace(/\\/g, "/")).replace(/\.git$/i, "") === "pi-rules-md") matches.push({
+				entry,
+				source,
+				kind: "git"
+			});
+			continue;
+		}
+		const expanded = source.startsWith("~") ? path.join(homedir(), source.slice(1).replace(/^[/\\]/, "")) : source;
+		const target = path.resolve(path.isAbsolute(expanded) ? expanded : path.join(opts.settingsDir, expanded));
+		try {
+			const canonicalPath = await realpath(target);
+			const metadata = JSON.parse(await readFile(path.join(canonicalPath, "package.json"), "utf8"));
+			if (metadata && typeof metadata === "object" && !Array.isArray(metadata) && metadata.name === "pi-rules-md") matches.push({
+				entry,
+				source,
+				kind: "local",
+				canonicalPath
+			});
+			else unmatchedLocal.push(entry);
+		} catch {
+			unmatchedLocal.push(entry);
+		}
+	}
+	const groups = /* @__PURE__ */ new Map();
+	for (const match of matches) {
+		if (!match.canonicalPath) continue;
+		groups.set(match.canonicalPath, [...groups.get(match.canonicalPath) ?? [], match]);
+	}
+	return {
+		matches,
+		unmatchedLocal,
+		duplicates: new Map([...groups].filter(([, group]) => group.length > 1))
+	};
+}
+function isVersion(version) {
+	return /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version);
+}
+
+//#endregion
+//#region src/cli/paths.ts
+function resolveAgentDir(explicit, env) {
+	return explicit ?? env.PI_RULES_AGENT_DIR ?? path.join(homedir(), ".pi", "agent");
+}
+function resolvePersonalSettingsPath(agentDir) {
+	return path.join(agentDir, "settings.json");
+}
+function resolveProjectSettingsPath(opts) {
+	const cwd = path.resolve(opts.cwd);
+	const gitRoot = findGitRoot(cwd);
+	if (!gitRoot) return settingsPathIfPresent(cwd);
+	let current = cwd;
+	while (true) {
+		const settings = settingsPathIfPresent(current);
+		if (settings) return settings;
+		if (current === gitRoot) return void 0;
+		current = path.dirname(current);
+	}
+}
+function resolveNpmStorePath(agentDir) {
+	return path.join(agentDir, "npm", "node_modules", PACKAGE_NAME);
+}
+function settingsPathIfPresent(directory) {
+	const settings = path.join(directory, ".pi", "settings.json");
+	return existsSync(settings) ? settings : void 0;
+}
+function findGitRoot(start) {
+	let current = start;
+	while (true) {
+		if (existsSync(path.join(current, ".git"))) return current;
+		const parent = path.dirname(current);
+		if (parent === current) return void 0;
+		current = parent;
+	}
+}
+
+//#endregion
+//#region src/cli/pi-runner.ts
+function runPi({ argv, timeoutMs = 3e4, dryRun = false, capture = false, env = process.env, stdout = [] }) {
+	if (dryRun) {
+		stdout.push(`[pi-rules] [dry-run] Would run: pi ${argv.join(" ")}`);
+		return Promise.resolve({ exitCode: 0 });
+	}
+	return new Promise((resolve) => {
+		let child;
+		try {
+			child = spawn("pi", argv, {
+				shell: false,
+				env,
+				stdio: capture ? [
+					"ignore",
+					"pipe",
+					"pipe"
+				] : "inherit"
+			});
+		} catch (error) {
+			resolve({
+				exitCode: 1,
+				error: error instanceof Error ? error.message : String(error)
+			});
+			return;
+		}
+		let out = "";
+		let err = "";
+		let timedOut = false;
+		let spawnError;
+		if (capture) {
+			child.stdout?.setEncoding("utf8").on("data", (chunk) => {
+				out += chunk;
+			});
+			child.stderr?.setEncoding("utf8").on("data", (chunk) => {
+				err += chunk;
+			});
+		}
+		child.once("error", (error) => {
+			spawnError = error;
+		});
+		const timer = setTimeout(() => {
+			timedOut = true;
+			child.kill("SIGKILL");
+		}, timeoutMs);
+		child.once("close", (code, signal) => {
+			clearTimeout(timer);
+			if (spawnError?.code === "ENOENT") {
+				resolve({
+					exitCode: 1,
+					error: "pi CLI not found on PATH",
+					...capture ? {
+						stdout: out,
+						stderr: err
+					} : {}
+				});
+				return;
+			}
+			resolve({
+				exitCode: timedOut ? 1 : code ?? 1,
+				...capture ? {
+					stdout: out,
+					stderr: err
+				} : {},
+				...spawnError ? { error: spawnError.message } : {},
+				...timedOut ? {
+					timedOut: true,
+					signal: "SIGKILL"
+				} : signal ? { signal } : {}
+			});
+		});
+	});
+}
+
+//#endregion
+//#region src/cli/settings.ts
+async function loadSettings(target, opts) {
+	const settingsPath = target === "personal" ? resolvePersonalSettingsPath(resolveAgentDir(opts.agentDir, {})) : target === "project" ? resolveProjectSettingsPath({ cwd: opts.cwd }) ?? path.join(opts.cwd, ".pi", "settings.json") : path.resolve(target);
+	let text;
+	try {
+		text = await readFile(settingsPath, "utf8");
+	} catch (error) {
+		if (isMissing(error)) return {
+			path: settingsPath,
+			exists: false,
+			packages: []
+		};
+		return {
+			path: settingsPath,
+			exists: true,
+			readError: errorMessage(error),
+			packages: []
+		};
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		return {
+			path: settingsPath,
+			exists: true,
+			parseError: errorMessage(error),
+			packages: []
+		};
+	}
+	if (!isRecord(parsed) || !Array.isArray(parsed.packages)) return {
+		path: settingsPath,
+		exists: true,
+		shapeError: "\"packages\" must be an array",
+		packages: []
+	};
+	return {
+		path: settingsPath,
+		exists: true,
+		packages: parsed.packages.map((raw) => {
+			if (typeof raw === "string") return {
+				kind: "string",
+				source: raw
+			};
+			if (isRecord(raw) && typeof raw.source === "string") return {
+				kind: "object",
+				source: raw.source
+			};
+			return {
+				kind: "malformed",
+				raw
+			};
+		})
+	};
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isMissing(error) {
+	return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+
+//#endregion
+//#region src/cli/install.ts
+function ioFor$4(options) {
+	return options.io ?? {
+		env: process.env,
+		stdout: { push: (...lines) => console.log(...lines) },
+		stderr: { push: (...lines) => console.error(...lines) }
+	};
+}
+function settingsProblem$4(settings) {
+	if (settings.readError) return settings.readError;
+	if (settings.parseError) return settings.parseError;
+	return settings.shapeError;
+}
+async function installFlow(options) {
+	const io = ioFor$4(options);
+	const refusal = sandboxRefusal({
+		agentDir: options.agentDir,
+		env: io.env
+	});
+	if (refusal) {
+		io.stderr.push(refusal);
+		return 3;
+	}
+	const agentDir = resolveAgentDir(options.agentDir, process.env);
+	const local = options.local === true;
+	let matches = [];
+	const settings = await loadSettings(local ? "project" : "personal", {
+		agentDir,
+		cwd: process.cwd()
+	});
+	const { path: settingsPath, exists, packages } = settings;
+	const problem = settingsProblem$4(settings);
+	if (problem) io.stderr.push(`warning: unable to read settings at ${settingsPath}: ${problem}`);
+	else if (exists) {
+		const { matches: foundMatches } = await findMatchingEntries(packages, { settingsDir: path.dirname(settingsPath) });
+		matches = foundMatches;
+	}
+	let removed = 0;
+	for (const match of matches) {
+		const result = await runPi({
+			argv: [
+				"remove",
+				match.source,
+				...local ? ["--local"] : []
+			],
+			dryRun: options.dryRun,
+			env: io.env,
+			stdout: io.stdout
+		});
+		if (result.exitCode !== 0) return result.exitCode;
+		removed++;
+	}
+	const result = await runPi({
+		argv: [
+			"install",
+			`npm:${PACKAGE_NAME}`,
+			...local ? ["--local"] : []
+		],
+		dryRun: options.dryRun,
+		env: io.env,
+		stdout: io.stdout
+	});
+	if (result.exitCode !== 0) return result.exitCode;
+	const stale = removed > 0 ? `, removed ${removed} stale entr${removed === 1 ? "y" : "ies"}` : "";
+	io.stdout.push(`✓ Installed ${PACKAGE_NAME} (npm:${PACKAGE_NAME})${stale}\ntip: Run pi-rules doctor`);
+	return 0;
+}
+
+//#endregion
+//#region src/cli/scopes.ts
+async function loadScopes(scopes, opts) {
+	const loaded = [];
+	for (const scope of scopes) loaded.push({
+		scope,
+		settings: await loadSettings(scope, opts)
+	});
+	return loaded;
+}
+
+//#endregion
+//#region src/cli/uninstall.ts
+function ioFor$3(options) {
+	return options.io ?? {
+		env: process.env,
+		stdout: { push: (...lines) => console.log(...lines) },
+		stderr: { push: (...lines) => console.error(...lines) }
+	};
+}
+function settingsProblem$3(settings) {
+	if (settings.readError) return settings.readError;
+	if (settings.parseError) return settings.parseError;
+	return settings.shapeError;
+}
+function isStrictlyInside(parent, child) {
+	const relative = path.relative(parent, child);
+	return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function purgeStore(agentDir, io, dryRun) {
+	const storePath = resolveNpmStorePath(agentDir);
+	let realAgent;
+	let npm;
+	let nodeModules;
+	try {
+		realAgent = realpathSync(agentDir);
+		npm = realpathSync(path.join(agentDir, "npm"));
+		nodeModules = realpathSync(path.join(agentDir, "npm", "node_modules"));
+	} catch (error) {
+		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+			io.stdout.push("✓ package store already absent");
+			return 0;
+		}
+		io.stderr.push(`refusing to purge unsafe package store path: ${storePath}`);
+		return 1;
+	}
+	if (!isStrictlyInside(realAgent, npm) || !isStrictlyInside(npm, nodeModules)) {
+		io.stderr.push(`refusing to purge unsafe package store path: ${storePath}`);
+		return 1;
+	}
+	let store;
+	try {
+		store = realpathSync(storePath);
+	} catch (error) {
+		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+			io.stdout.push("✓ package store already absent");
+			return 0;
+		}
+		io.stderr.push(`refusing to purge unsafe package store path: ${storePath}`);
+		return 1;
+	}
+	if (!isStrictlyInside(nodeModules, store) || path.basename(storePath) !== "pi-rules-md") {
+		io.stderr.push(`refusing to purge unsafe package store path: ${storePath}`);
+		return 1;
+	}
+	if (dryRun) {
+		io.stdout.push(`[pi-rules] [dry-run] Would remove ${storePath}`);
+		return 0;
+	}
+	rmSync(storePath, {
+		recursive: true,
+		force: true
+	});
+	io.stdout.push(`✓ removed package store ${storePath}`);
+	io.stderr.push("run pi update --extensions to reconcile the package store");
+	return 0;
+}
+async function uninstallFlow(options) {
+	const io = ioFor$3(options);
+	const refusal = sandboxRefusal({
+		agentDir: options.agentDir,
+		env: io.env
+	});
+	if (refusal) {
+		io.stderr.push(refusal);
+		return 3;
+	}
+	const agentDir = resolveAgentDir(options.agentDir, process.env);
+	const scopes = options.local ? ["project"] : ["personal", "project"];
+	const loaded = await loadScopes(scopes, {
+		agentDir,
+		cwd: process.cwd()
+	});
+	const matches = [];
+	for (const { scope, settings } of loaded) {
+		const problem = settingsProblem$3(settings);
+		if (problem) {
+			io.stderr.push(`error: unable to read settings at ${settings.path}: ${problem}`);
+			return 1;
+		}
+		if (!settings.exists) continue;
+		const result = await findMatchingEntries(settings.packages, { settingsDir: path.dirname(settings.path) });
+		for (const entry of result.unmatchedLocal) if (entry.kind !== "malformed") io.stderr.push(`warning: local entry does not look like pi-rules-md, leaving it: ${entry.source}`);
+		matches.push(...result.matches.map(({ source }) => ({
+			scope,
+			source
+		})));
+	}
+	const hasPersonalScope = scopes.includes("personal");
+	if (matches.length === 0) {
+		io.stdout.push("✓ pi-rules-md not installed");
+		if (options.purge && hasPersonalScope) return purgeStore(agentDir, io, options.dryRun);
+		if (options.purge && options.local) io.stdout.push("nothing to purge in project scope");
+		return 0;
+	}
+	let anyFailed = false;
+	for (const match of matches) if ((await runPi({
+		argv: [
+			"remove",
+			match.source,
+			...match.scope === "project" ? ["--local"] : []
+		],
+		dryRun: options.dryRun,
+		env: io.env,
+		stdout: io.stdout
+	})).exitCode !== 0) anyFailed = true;
+	if (options.purge) {
+		if (purgeStore(agentDir, io, options.dryRun) !== 0) anyFailed = true;
+	}
+	return anyFailed ? 1 : 0;
+}
+
+//#endregion
+//#region src/cli/registry.ts
+const REGISTRY_LATEST_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/;
+async function fetchLatestVersion(fetchImpl = fetch, timeoutMs = 3e3) {
+	let timer;
+	const timeout = new Promise((resolve) => {
+		timer = setTimeout(() => resolve(null), timeoutMs);
+	});
+	const request = (async () => {
+		const response = await fetchImpl(REGISTRY_LATEST_URL, { signal: AbortSignal.timeout(timeoutMs) });
+		if (!response.ok) return null;
+		const body = await response.json();
+		if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+		const { version } = body;
+		return typeof version === "string" && VERSION_PATTERN.test(version) ? version : null;
+	})();
+	try {
+		return await Promise.race([request.catch(() => null), timeout]);
+	} catch {
+		return null;
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+}
+function parseSemver(version) {
+	if (!VERSION_PATTERN.test(version)) return null;
+	const [core] = version.split("-");
+	const parts = core?.split(".").map(Number);
+	if (!parts || parts.length !== 3 || parts.some((part) => !Number.isSafeInteger(part))) return null;
+	return {
+		major: parts[0],
+		minor: parts[1],
+		patch: parts[2]
+	};
+}
+function compareSemver(a, b) {
+	if (a == null || b == null) return null;
+	const left = parseSemver(a);
+	const right = parseSemver(b);
+	if (!left || !right) return null;
+	return left.major - right.major || left.minor - right.minor || left.patch - right.patch;
+}
+function isStale(installed, latest) {
+	const comparison = compareSemver(latest, installed);
+	return comparison !== null && comparison > 0;
+}
+
+//#endregion
+//#region src/cli/update.ts
+function ioFor$2(options) {
+	return options.io ?? {
+		env: process.env,
+		stdout: { push: (...lines) => console.log(...lines) },
+		stderr: { push: (...lines) => console.error(...lines) }
+	};
+}
+function settingsProblem$2(settings) {
+	return settings.readError ?? settings.parseError ?? settings.shapeError;
+}
+async function updateFlow(options) {
+	const io = ioFor$2(options);
+	const refusal = sandboxRefusal({
+		agentDir: options.agentDir,
+		env: io.env
+	});
+	if (refusal) {
+		io.stderr.push(refusal);
+		return 3;
+	}
+	const agentDir = resolveAgentDir(options.agentDir, process.env);
+	const scopes = options.local ? ["project"] : ["personal", "project"];
+	const loaded = await loadScopes(scopes, {
+		agentDir,
+		cwd: process.cwd()
+	});
+	const matches = [];
+	for (const { scope, settings } of loaded) {
+		const problem = settingsProblem$2(settings);
+		if (problem) {
+			io.stderr.push(`error: unable to read settings at ${settings.path}: ${problem}`);
+			continue;
+		}
+		if (!settings.exists) continue;
+		const result = await findMatchingEntries(settings.packages, { settingsDir: path.dirname(settings.path) });
+		matches.push(...result.matches.map(({ source, kind, version }) => ({
+			scope,
+			source,
+			kind,
+			...version === void 0 ? {} : { version }
+		})));
+	}
+	if (matches.length === 0) {
+		io.stdout.push("nothing to update (no pi-rules-md entries found)");
+		return 0;
+	}
+	if (matches.some(({ kind }) => kind === "npm" || kind === "npm-pinned")) {
+		const latest = await fetchLatestVersion(options.fetchImpl ?? fetch);
+		if (latest) io.stdout.push(`latest: ${latest}`);
+	}
+	let anyFailed = false;
+	const seen = /* @__PURE__ */ new Set();
+	for (const match of matches) {
+		if (match.kind === "local") {
+			io.stdout.push(`${match.scope}: ${match.source} tracks the working tree (not updated)`);
+			continue;
+		}
+		if (match.kind === "npm-pinned") {
+			io.stdout.push(`${match.scope}: ${match.source} pinned to ${match.version}, not updating`);
+			continue;
+		}
+		if (match.kind !== "npm") continue;
+		const key = `${match.scope}:${match.source}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		if ((await runPi({
+			argv: [
+				"update",
+				match.source,
+				...match.scope === "project" ? ["--local"] : []
+			],
+			dryRun: options.dryRun,
+			env: io.env,
+			stdout: io.stdout
+		})).exitCode !== 0) anyFailed = true;
+	}
+	return anyFailed ? 1 : 0;
+}
+
+//#endregion
+//#region src/cli/status.ts
+function ioFor$1(options) {
+	return options.io ?? {
+		env: process.env,
+		stdout: { push: (...lines) => console.log(...lines) },
+		stderr: { push: (...lines) => console.error(...lines) }
+	};
+}
+function settingsProblem$1(settings) {
+	return settings.readError ?? settings.parseError ?? settings.shapeError;
+}
+function readPackageVersion(pkgDir) {
+	try {
+		const metadata = JSON.parse(readFileSync(path.join(pkgDir, "package.json"), "utf8"));
+		if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) return void 0;
+		const { version } = metadata;
+		return typeof version === "string" ? version : void 0;
+	} catch {
+		return;
+	}
+}
+function installedVersion$1(match, agentDir) {
+	const packageDir = match.kind === "local" ? match.canonicalPath : resolveNpmStorePath(agentDir);
+	return packageDir ? readPackageVersion(packageDir) : void 0;
+}
+function kindLabel$1(kind) {
+	return kind === "npm" ? "npm" : kind === "npm-pinned" ? "npm-pinned" : kind;
+}
+async function statusFlow(options) {
+	const io = ioFor$1(options);
+	const agentDir = resolveAgentDir(options.agentDir, process.env);
+	const loaded = await loadScopes(["personal", "project"], {
+		agentDir,
+		cwd: process.cwd()
+	});
+	const matches = [];
+	for (const { scope, settings } of loaded) {
+		const problem = settingsProblem$1(settings);
+		if (problem) {
+			io.stderr.push(`error: unable to read settings at ${settings.path}: ${problem}`);
+			continue;
+		}
+		if (!settings.exists) continue;
+		const result = await findMatchingEntries(settings.packages, { settingsDir: path.dirname(settings.path) });
+		for (const match of result.matches) {
+			const installed = installedVersion$1(match, agentDir);
+			matches.push({
+				scope,
+				match,
+				installed
+			});
+			io.stdout.push(`${scope}: ${match.source} (${kindLabel$1(match.kind)}, installed ${installed ?? "unknown"})`);
+		}
+	}
+	if (matches.length === 0) {
+		io.stdout.push("pi-rules-md not installed");
+		return 0;
+	}
+	const latest = await fetchLatestVersion(options.fetchImpl ?? fetch);
+	if (latest) {
+		io.stdout.push(`latest: ${latest}`);
+		for (const { scope, match, installed } of matches) if ((match.kind === "npm" || match.kind === "npm-pinned") && installed && isStale(installed, latest)) io.stdout.push(`stale: ${scope} ${match.source} installed ${installed} < latest ${latest}`);
+	}
+	return 0;
+}
+
+//#endregion
+//#region src/cli/doctor.ts
+const MIN_NODE_VERSION = "22.19.0";
+const DIST_FILES = ["dist/extension.js", "dist/cli.mjs"];
+function ioFor(options) {
+	return options.io ?? {
+		env: process.env,
+		stdout: { push: (...lines) => console.log(...lines) },
+		stderr: { push: (...lines) => console.error(...lines) }
+	};
+}
+function settingsProblem(settings) {
+	return settings.readError ?? settings.parseError ?? settings.shapeError;
+}
+function checkNodeVersion(current) {
+	const comparison = compareSemver(current, MIN_NODE_VERSION);
+	if (comparison === null) return "unknown";
+	return comparison >= 0 ? "ok" : "outdated";
+}
+function installedVersion(match, agentDir) {
+	const packageDir = match.kind === "local" ? match.canonicalPath : resolveNpmStorePath(agentDir);
+	return packageDir ? readPackageVersion(packageDir) : void 0;
+}
+function kindLabel(kind) {
+	return kind === "npm-pinned" ? "npm-pinned" : kind;
+}
+async function doctorFlow(options) {
+	const io = ioFor(options);
+	const agentDir = resolveAgentDir(options.agentDir, process.env);
+	const loaded = await loadScopes(["personal", "project"], {
+		agentDir,
+		cwd: process.cwd()
+	});
+	const structural = [];
+	const advisory = [];
+	const matches = [];
+	for (const { scope, settings } of loaded) {
+		const problem = settingsProblem(settings);
+		if (problem) {
+			advisory.push(`advisory: ${scope} settings unreadable (${problem})`);
+			continue;
+		}
+		if (!settings.exists) {
+			io.stdout.push(`${scope}: no settings`);
+			continue;
+		}
+		const result = await findMatchingEntries(settings.packages, { settingsDir: path.dirname(settings.path) });
+		for (const match of result.matches) {
+			const installed = installedVersion(match, agentDir);
+			matches.push({
+				scope,
+				match,
+				installed
+			});
+			io.stdout.push(`${scope}: ${match.source} (${kindLabel(match.kind)}, installed ${installed ?? "unknown"})`);
+			if (match.kind === "local") {
+				for (const file of DIST_FILES) if (!match.canonicalPath || !existsSync(path.join(match.canonicalPath, file))) advisory.push(`advisory: ${scope} ${match.source} missing ${file} (run pnpm build in ${match.canonicalPath ?? "unknown"})`);
+			} else for (const file of DIST_FILES) if (!existsSync(path.join(resolveNpmStorePath(agentDir), file))) structural.push(`structural: ${scope} ${match.source} package store missing ${file}`);
+		}
+		for (const [canonicalPath, group] of result.duplicates) advisory.push(`advisory: duplicate entries resolve to ${canonicalPath} (${group.length} entries)`);
+	}
+	const nodeVersion = process.versions.node;
+	const nodeStatus = checkNodeVersion(nodeVersion);
+	if (nodeStatus === "outdated") structural.push(`structural: node ${nodeVersion} < ${MIN_NODE_VERSION} (engines requirement)`);
+	if (nodeStatus === "unknown") advisory.push(`advisory: unable to verify node version (${nodeVersion})`);
+	if (matches.length === 0) structural.push("structural: pi-rules-md is not installed (run pi-rules install)");
+	let latestLine;
+	if (matches.length > 0) {
+		const latest = await fetchLatestVersion(options.fetchImpl ?? fetch);
+		if (latest) {
+			latestLine = `latest: ${latest}`;
+			for (const { scope, match, installed } of matches) if (match.kind === "npm-pinned") advisory.push(`advisory: ${scope} ${match.source} pinned to ${match.version} — update manually if stale`);
+			else if (match.kind === "npm" && installed && isStale(installed, latest)) advisory.push(`advisory: ${scope} ${match.source} stale (installed ${installed} < latest ${latest})`);
+		} else advisory.push("advisory: registry unreachable, staleness skipped");
+	}
+	io.stdout.push(...structural);
+	if (latestLine) io.stdout.push(latestLine);
+	io.stdout.push(...advisory);
+	const structuralCount = structural.length;
+	io.stdout.push(structuralCount === 0 ? "summary: healthy" : `summary: ${structuralCount} structural issue(s)`);
+	return structuralCount === 0 ? 0 : 1;
+}
+
+//#endregion
+//#region src/cli/main.ts
+const USAGE = `Usage: pi-rules <command> [options]
+
+Commands:
+  install    Install pi-rules-md
+  uninstall  Remove pi-rules-md
+  update     Update pi-rules-md
+  status     Show installation status
+  doctor     Diagnose installation health
+
+Options:
+  --local              Use the project scope (install/uninstall/update)
+  --purge              Remove the package directory (uninstall)
+  --agent-dir <dir>    Use a specific Pi agent directory
+  --dry-run            Print actions without changing anything
+  --help               Show this help`;
+var NotImplementedFlowError = class extends Error {
+	constructor(name) {
+		super(`${name} flow not implemented`);
+		this.name = "NotImplementedFlowError";
+	}
+};
+const defaultFlows = {
+	install: installFlow,
+	uninstall: uninstallFlow,
+	update: updateFlow,
+	status: statusFlow,
+	doctor: doctorFlow
+};
+async function runCli(args, io, flows = defaultFlows) {
+	const [command, ...commandArgs] = args;
+	if (command === "--help") {
+		io.stdout.push(USAGE);
+		return 0;
+	}
+	if (!command) {
+		io.stderr.push(USAGE);
+		return 2;
+	}
+	if (!(command in defaultFlows)) {
+		io.stderr.push(USAGE);
+		return 2;
+	}
+	let options;
+	try {
+		const { values } = parseArgs({
+			args: commandArgs,
+			strict: true,
+			allowPositionals: false,
+			options: {
+				...command === "install" || command === "uninstall" || command === "update" ? { local: { type: "boolean" } } : {},
+				...command === "uninstall" ? { purge: { type: "boolean" } } : {},
+				"agent-dir": { type: "string" },
+				"dry-run": { type: "boolean" },
+				help: { type: "boolean" }
+			}
+		});
+		if (values.help) {
+			io.stdout.push(USAGE);
+			return 0;
+		}
+		const agentDir = values["agent-dir"] ?? io.env.PI_RULES_AGENT_DIR;
+		if (agentDir !== void 0 && agentDir.trim() === "") {
+			io.stderr.push(`error: --agent-dir requires a non-empty path\n${USAGE}`);
+			return 2;
+		}
+		options = {
+			...agentDir === void 0 ? {} : { agentDir },
+			local: values.local === true,
+			purge: values.purge === true,
+			dryRun: values["dry-run"] ?? false
+		};
+	} catch (error) {
+		io.stderr.push(`${error instanceof Error ? error.message : String(error)}\n${USAGE}`);
+		return 2;
+	}
+	try {
+		return await flows[command]({
+			...options,
+			io
+		});
+	} catch (error) {
+		if (error instanceof NotImplementedFlowError) {
+			io.stderr.push(`error: ${error.message} in this build; it lands in an upcoming release.\n${USAGE}`);
+			return 2;
+		}
+		throw error;
+	}
+}
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+	const io = {
+		env: process.env,
+		stdout: [],
+		stderr: []
+	};
+	process.exitCode = await runCli(process.argv.slice(2), io);
+	for (const line of io.stdout) console.log(line);
+	for (const line of io.stderr) console.error(line);
+}
+
+//#endregion
+export { NotImplementedFlowError, USAGE, runCli };