@tanstack/intent 0.0.21 → 0.0.27

package/dist/cli.mjs

@@ -1,35 +1,75 @@
 #!/usr/bin/env node
-import { t as INSTALL_PROMPT } from "./install-prompt-C0M-U3WZ.mjs";
+import "./utils-COlDcU72.mjs";
+import "./workspace-patterns-BuJMfudb.mjs";
+import { t as resolveProjectContext } from "./project-context-B7UXTA9F.mjs";
+import { n as runInstallCommand } from "./install-BzDmD5yI.mjs";
 import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
-import { dirname, join, relative, sep } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { cac } from "cac";
 
-//#region src/cli.ts
-function getMetaDir() {
-	return join(dirname(fileURLToPath(import.meta.url)), "..", "meta");
-}
+//#region src/cli-error.ts
+const CLI_FAILURE = Symbol("CliFailure");
 function fail(message, exitCode = 1) {
 	throw {
+		[CLI_FAILURE]: true,
 		message,
 		exitCode
 	};
 }
 function isCliFailure(value) {
-	return !!value && typeof value === "object" && "message" in value && typeof value.message === "string" && "exitCode" in value && typeof value.exitCode === "number";
+	return !!value && typeof value === "object" && CLI_FAILURE in value;
+}
+
+//#endregion
+//#region src/cli-support.ts
+function printWarnings(warnings) {
+	if (warnings.length === 0) return;
+	console.log("Warnings:");
+	for (const warning of warnings) console.log(`  ⚠ ${warning}`);
+}
+function getMetaDir() {
+	return join(dirname(fileURLToPath(import.meta.url)), "..", "meta");
 }
 async function scanIntentsOrFail() {
-	const { scanForIntents } = await import("./scanner-RWHFrJ_C.mjs");
+	const { scanForIntents } = await import("./scanner-CERQgrRN.mjs");
 	try {
-		return await scanForIntents();
+		return scanForIntents();
 	} catch (err) {
-		fail(err.message);
+		fail(err instanceof Error ? err.message : String(err));
 	}
 }
-function printWarnings(warnings) {
-	if (warnings.length === 0) return;
-	console.log("Warnings:");
-	for (const warning of warnings) console.log(`  ⚠ ${warning}`);
+function readPackageName(root) {
+	try {
+		const pkgJson = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+		return typeof pkgJson.name === "string" ? pkgJson.name : relative(process.cwd(), root) || "unknown";
+	} catch {
+		return relative(process.cwd(), root) || "unknown";
+	}
+}
+async function resolveStaleTargets(targetDir) {
+	const resolvedRoot = targetDir ? join(process.cwd(), targetDir) : process.cwd();
+	const { checkStaleness } = await import("./staleness-SRims-ZP.mjs");
+	if (existsSync(join(resolvedRoot, "skills"))) return { reports: [await checkStaleness(resolvedRoot, readPackageName(resolvedRoot))] };
+	const { findPackagesWithSkills, findWorkspaceRoot } = await import("./workspace-patterns-Boa5mAbf.mjs");
+	const workspaceRoot = findWorkspaceRoot(resolvedRoot);
+	if (workspaceRoot) {
+		const packageDirs = findPackagesWithSkills(workspaceRoot);
+		if (packageDirs.length > 0) return { reports: await Promise.all(packageDirs.map((packageDir) => checkStaleness(packageDir, readPackageName(packageDir)))) };
+	}
+	const staleResult = await scanIntentsOrFail();
+	return { reports: await Promise.all(staleResult.packages.map((pkg) => checkStaleness(pkg.packageRoot, pkg.name))) };
 }
+
+//#endregion
+//#region src/commands/edit-package-json.ts
+async function runEditPackageJsonCommand(root) {
+	const { runEditPackageJsonAll } = await import("./setup.mjs");
+	runEditPackageJsonAll(root);
+}
+
+//#endregion
+//#region src/commands/list.ts
 function formatScanCoverage(result) {
 	const coverage = [];
 	if (result.nodeModules.local.scanned) coverage.push("project node_modules");
@@ -49,24 +89,10 @@ function printVersionConflicts(result) {
 		console.log();
 	}
 }
-function buildValidationFailure(errors, warnings) {
-	const lines = [
-		"",
-		`❌ Validation failed with ${errors.length} error(s):`,
-		""
-	];
-	for (const { file, message } of errors) lines.push(`  ${file}: ${message}`);
-	if (warnings.length > 0) {
-		lines.push("", "⚠ Packaging warnings:");
-		for (const warning of warnings) lines.push(`  ${warning}`);
-	}
-	return lines.join("\n");
-}
-async function cmdList(args) {
-	const { computeSkillNameWidth, printSkillTree, printTable } = await import("./display-CuCDLPP_.mjs");
-	const jsonOutput = args.includes("--json");
-	const result = await scanIntentsOrFail();
-	if (jsonOutput) {
+async function runListCommand(options, scanIntentsOrFail$1) {
+	const { computeSkillNameWidth, printSkillTree, printTable } = await import("./display-DdmZXLZm.mjs");
+	const result = await scanIntentsOrFail$1();
+	if (options.json) {
 		console.log(JSON.stringify(result, null, 2));
 		return;
 	}
@@ -80,7 +106,7 @@ async function cmdList(args) {
 		}
 		return;
 	}
-	const totalSkills = result.packages.reduce((sum, p) => sum + p.skills.length, 0);
+	const totalSkills = result.packages.reduce((sum, pkg) => sum + pkg.skills.length, 0);
 	console.log(`\n${result.packages.length} intent-enabled packages, ${totalSkills} skills (${result.packageManager})\n`);
 	if (scanCoverage) console.log(`Scanned: ${scanCoverage}${result.nodeModules.global.scanned ? " (local packages take precedence)" : ""}\n`);
 	printTable([
@@ -95,8 +121,8 @@ async function cmdList(args) {
 		pkg.intent.requires?.join(", ") || "–"
 	]));
 	printVersionConflicts(result);
-	const nameWidth = computeSkillNameWidth(result.packages.map((p) => p.skills));
-	const showTypes = result.packages.some((p) => p.skills.some((s) => s.type));
+	const nameWidth = computeSkillNameWidth(result.packages.map((pkg) => pkg.skills));
+	const showTypes = result.packages.some((pkg) => pkg.skills.some((skill) => skill.type));
 	console.log(`\nSkills:\n`);
 	for (const pkg of result.packages) {
 		console.log(`  ${pkg.name}`);
@@ -106,18 +132,18 @@ async function cmdList(args) {
 		});
 		console.log();
 	}
-	console.log(`Feedback:`);
-	console.log(`  Submit feedback on skill usage to help maintainers improve the skills.`);
-	console.log(`  Load: node_modules/@tanstack/intent/meta/feedback-collection/SKILL.md`);
+	console.log("Feedback:");
+	console.log("  Submit feedback on skill usage to help maintainers improve the skills.");
+	console.log("  Load: node_modules/@tanstack/intent/meta/feedback-collection/SKILL.md");
 	console.log();
 	printWarnings(result.warnings);
 }
-async function cmdMeta(args) {
-	const { parseFrontmatter } = await import("./utils-D7OKi0Rn.mjs");
-	const metaDir = getMetaDir();
+
+//#endregion
+//#region src/commands/meta.ts
+async function runMetaCommand(name, metaDir) {
 	if (!existsSync(metaDir)) fail("Meta-skills directory not found.");
-	if (args.length > 0) {
-		const name = args[0];
+	if (name) {
 		if (name.includes("..") || name.includes("/") || name.includes("\\")) fail(`Invalid meta-skill name: "${name}"`);
 		const skillFile = join(metaDir, name, "SKILL.md");
 		if (!existsSync(skillFile)) fail(`Meta-skill "${name}" not found. Run \`intent meta\` to list available meta-skills.`);
@@ -128,7 +154,8 @@ async function cmdMeta(args) {
 		}
 		return;
 	}
-	const entries = readdirSync(metaDir, { withFileTypes: true }).filter((e) => e.isDirectory()).filter((e) => existsSync(join(metaDir, e.name, "SKILL.md")));
+	const { parseFrontmatter } = await import("./utils-dkVvY7D7.mjs");
+	const entries = readdirSync(metaDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).filter((entry) => existsSync(join(metaDir, entry.name, "SKILL.md")));
 	if (entries.length === 0) {
 		console.log("No meta-skills found.");
 		return;
@@ -138,14 +165,133 @@ async function cmdMeta(args) {
 		const fm = parseFrontmatter(join(metaDir, entry.name, "SKILL.md"));
 		let description = "";
 		if (typeof fm?.description === "string") description = fm.description.replace(/\s+/g, " ").trim();
-		const shortDesc = description.length > 60 ? description.slice(0, 57) + "..." : description;
+		const shortDesc = description.length > 60 ? `${description.slice(0, 57)}...` : description;
 		console.log(`  ${entry.name.padEnd(28)} ${shortDesc}`);
 	}
-	console.log(`\nUsage: load the SKILL.md into your AI agent conversation.`);
-	console.log(`Path: node_modules/@tanstack/intent/meta/<name>/SKILL.md`);
+	console.log("\nUsage: load the SKILL.md into your AI agent conversation.");
+	console.log("Path: node_modules/@tanstack/intent/meta/<name>/SKILL.md");
+}
+
+//#endregion
+//#region src/commands/scaffold.ts
+function runScaffoldCommand(metaDir) {
+	function metaSkillPath(name) {
+		return join(metaDir, name, "SKILL.md");
+	}
+	const prompt = `You are helping a library maintainer scaffold Intent skills.
+
+Run the three meta skills below **one at a time, in order**. For each step:
+1. Load the SKILL.md file specified
+2. Follow its instructions completely
+3. Present outputs to the maintainer for review
+4. Do NOT proceed to the next step until the maintainer confirms
+
+## Before you start
+
+Gather this context yourself (do not ask the maintainer — agents should never
+ask for information they can discover):
+1. Read package.json for library name, repository URL, and homepage/docs URL
+2. Detect if this is a monorepo (look for workspaces field, packages/ directory, lerna.json)
+3. Use skills/ as the default skills root
+4. For monorepos:
+   - Domain map artifacts go at the REPO ROOT: _artifacts/
+   - Skills go INSIDE EACH PACKAGE: packages/<pkg>/skills/
+   - Identify which packages are client-facing (usually client SDKs and primary framework adapters)
+
+---
+
+## Step 1 — Domain Discovery
+
+Load and follow: ${metaSkillPath("domain-discovery")}
+
+This produces: domain_map.yaml and skill_spec.md in the artifacts directory.
+Domain discovery covers the WHOLE library (one domain map even for monorepos).
+
+**STOP. Review outputs with the maintainer before continuing.**
+
+---
+
+## Step 2 — Tree Generator
+
+Load and follow: ${metaSkillPath("tree-generator")}
+
+This produces: skill_tree.yaml in the artifacts directory.
+For monorepos, each skill entry should include a \`package\` field.
+
+**STOP. Review outputs with the maintainer before continuing.**
+
+---
+
+## Step 3 — Generate Skills
+
+Load and follow: ${metaSkillPath("generate-skill")}
+
+This produces: individual SKILL.md files.
+- Single-repo: skills/<domain>/<skill>/SKILL.md
+- Monorepo: packages/<pkg>/skills/<domain>/<skill>/SKILL.md
+
+---
+
+## After all skills are generated
+
+1. Run \`intent validate\` in each package directory
+2. Commit skills/ and artifacts
+3. For each publishable package, run: \`npx @tanstack/intent edit-package-json\`
+4. Ensure each package has \`@tanstack/intent\` as a devDependency
+5. Create a \`skill:<skill-name>\` label on the GitHub repo for each skill (use \`gh label create\`)
+6. Add a README note: "If you use an AI agent, run \`npx @tanstack/intent@latest install\`"
+`;
+	console.log(prompt);
+}
+
+//#endregion
+//#region src/commands/setup-github-actions.ts
+async function runSetupGithubActionsCommand(root, metaDir) {
+	const { runSetupGithubActions } = await import("./setup.mjs");
+	runSetupGithubActions(root, metaDir);
+}
+
+//#endregion
+//#region src/commands/stale.ts
+async function runStaleCommand(targetDir, options, resolveStaleTargets$1) {
+	const { reports } = await resolveStaleTargets$1(targetDir);
+	if (reports.length === 0) {
+		console.log("No intent-enabled packages found.");
+		return;
+	}
+	if (options.json) {
+		console.log(JSON.stringify(reports, null, 2));
+		return;
+	}
+	for (const report of reports) {
+		const driftLabel = report.versionDrift ? ` [${report.versionDrift} drift]` : "";
+		const vLabel = report.skillVersion && report.currentVersion ? ` (${report.skillVersion} → ${report.currentVersion})` : "";
+		console.log(`${report.library}${vLabel}${driftLabel}`);
+		const stale = report.skills.filter((skill) => skill.needsReview);
+		if (stale.length === 0) console.log("  All skills up-to-date");
+		else for (const skill of stale) console.log(`  ⚠ ${skill.name}: ${skill.reasons.join(", ")}`);
+		console.log();
+	}
 }
-function collectPackagingWarnings(root) {
-	const pkgJsonPath = join(root, "package.json");
+
+//#endregion
+//#region src/commands/validate.ts
+function buildValidationFailure(errors, warnings) {
+	const lines = [
+		"",
+		`❌ Validation failed with ${errors.length} error(s):`,
+		""
+	];
+	for (const { file, message } of errors) lines.push(`  ${file}: ${message}`);
+	if (warnings.length > 0) {
+		lines.push("", "⚠ Packaging warnings:");
+		for (const warning of warnings) lines.push(`  ${warning}`);
+	}
+	return lines.join("\n");
+}
+function collectPackagingWarnings(context) {
+	if (!context.packageRoot || !context.targetPackageJsonPath) return [];
+	const pkgJsonPath = context.targetPackageJsonPath;
 	if (!existsSync(pkgJsonPath)) return [];
 	let pkgJson;
 	try {
@@ -160,60 +306,18 @@ function collectPackagingWarnings(root) {
 	const files = pkgJson.files;
 	if (Array.isArray(files)) {
 		if (!files.includes("skills")) warnings.push("\"skills\" is not in the \"files\" array — skills won't be published");
-		if (!(() => {
-			let dir = join(root, "..");
-			for (let i = 0; i < 5; i++) {
-				const parentPkg = join(dir, "package.json");
-				if (existsSync(parentPkg)) try {
-					const parent = JSON.parse(readFileSync(parentPkg, "utf8"));
-					return Array.isArray(parent.workspaces) || parent.workspaces?.packages;
-				} catch {
-					return false;
-				}
-				const next = dirname(dir);
-				if (next === dir) break;
-				dir = next;
-			}
-			return false;
-		})() && !files.includes("!skills/_artifacts")) warnings.push("\"!skills/_artifacts\" is not in the \"files\" array — artifacts will be published unnecessarily");
+		if (!context.isMonorepo && !files.includes("!skills/_artifacts")) warnings.push("\"!skills/_artifacts\" is not in the \"files\" array — artifacts will be published unnecessarily");
 	}
 	return warnings;
 }
-function resolvePackageRoot(startDir) {
-	let dir = startDir;
-	while (true) {
-		if (existsSync(join(dir, "package.json"))) return dir;
-		const next = dirname(dir);
-		if (next === dir) return startDir;
-		dir = next;
-	}
-}
-function readPackageName(root) {
-	try {
-		const pkgJson = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
-		return typeof pkgJson.name === "string" ? pkgJson.name : relative(process.cwd(), root) || "unknown";
-	} catch {
-		return relative(process.cwd(), root) || "unknown";
-	}
-}
-async function resolveStaleTargets(targetDir) {
-	const resolvedRoot = targetDir ? join(process.cwd(), targetDir) : process.cwd();
-	const { checkStaleness } = await import("./staleness-Dr5-5wj5.mjs");
-	if (existsSync(join(resolvedRoot, "skills"))) return { reports: [await checkStaleness(resolvedRoot, readPackageName(resolvedRoot))] };
-	const { findPackagesWithSkills, findWorkspaceRoot } = await import("./setup.mjs");
-	const workspaceRoot = findWorkspaceRoot(resolvedRoot);
-	if (workspaceRoot) {
-		const packageDirs = findPackagesWithSkills(workspaceRoot);
-		if (packageDirs.length > 0) return { reports: await Promise.all(packageDirs.map((packageDir) => checkStaleness(packageDir, readPackageName(packageDir)))) };
-	}
-	const staleResult = await scanIntentsOrFail();
-	return { reports: await Promise.all(staleResult.packages.map((pkg) => checkStaleness(pkg.packageRoot, pkg.name))) };
-}
-async function cmdValidate(args) {
-	const [{ parse: parseYaml }, { findSkillFiles }] = await Promise.all([import("yaml"), import("./utils-D7OKi0Rn.mjs")]);
-	const targetDir = args[0] ?? "skills";
-	const skillsDir = join(process.cwd(), targetDir);
-	const packageRoot = resolvePackageRoot(skillsDir);
+async function runValidateCommand(dir) {
+	const [{ parse: parseYaml }, { findSkillFiles }] = await Promise.all([import("yaml"), import("./utils-dkVvY7D7.mjs")]);
+	const targetDir = dir ?? "skills";
+	const context = resolveProjectContext({
+		cwd: process.cwd(),
+		targetPath: targetDir
+	});
+	const skillsDir = context.targetSkillsDir ?? resolve(process.cwd(), targetDir);
 	if (!existsSync(skillsDir)) fail(`Skills directory not found: ${skillsDir}`);
 	const errors = [];
 	const skillFiles = findSkillFiles(skillsDir);
@@ -239,10 +343,11 @@ async function cmdValidate(args) {
 		let fm;
 		try {
 			fm = parseYaml(match[1]);
-		} catch {
+		} catch (err) {
+			const detail = err instanceof Error ? err.message : String(err);
 			errors.push({
 				file: rel,
-				message: "Invalid YAML frontmatter"
+				message: `Invalid YAML frontmatter: ${detail}`
 			});
 			continue;
 		}
@@ -276,7 +381,7 @@ async function cmdValidate(args) {
 		});
 	}
 	const artifactsDir = join(skillsDir, "_artifacts");
-	if (existsSync(artifactsDir)) for (const fileName of [
+	if (!context.isMonorepo && existsSync(artifactsDir)) for (const fileName of [
 		"domain_map.yaml",
 		"skill_spec.md",
 		"skill_tree.yaml"
@@ -299,224 +404,90 @@ async function cmdValidate(args) {
 		}
 		if (fileName.endsWith(".yaml")) try {
 			parseYaml(content);
-		} catch {
+		} catch (err) {
+			const detail = err instanceof Error ? err.message : String(err);
 			errors.push({
 				file: relative(process.cwd(), artifactPath),
-				message: "Invalid YAML in artifact file"
+				message: `Invalid YAML in artifact file: ${detail}`
 			});
 		}
 	}
-	const warnings = collectPackagingWarnings(packageRoot);
+	const warnings = collectPackagingWarnings(context);
 	if (errors.length > 0) fail(buildValidationFailure(errors, warnings));
 	console.log(`✅ Validated ${skillFiles.length} skill files — all passed`);
 	if (warnings.length > 0) console.log();
 	printWarnings(warnings);
 }
-function cmdScaffold() {
-	const metaDir = getMetaDir();
-	const metaSkillPath = (name) => join(metaDir, name, "SKILL.md");
-	const prompt = `You are helping a library maintainer scaffold Intent skills.
-
-Run the three meta skills below **one at a time, in order**. For each step:
-1. Load the SKILL.md file specified
-2. Follow its instructions completely
-3. Present outputs to the maintainer for review
-4. Do NOT proceed to the next step until the maintainer confirms
-
-## Before you start
-
-Gather this context yourself (do not ask the maintainer — agents should never
-ask for information they can discover):
-1. Read package.json for library name, repository URL, and homepage/docs URL
-2. Detect if this is a monorepo (look for workspaces field, packages/ directory, lerna.json)
-3. Use skills/ as the default skills root
-4. For monorepos:
-   - Domain map artifacts go at the REPO ROOT: _artifacts/
-   - Skills go INSIDE EACH PACKAGE: packages/<pkg>/skills/
-   - Identify which packages are client-facing (usually client SDKs and primary framework adapters)
-
----
-
-## Step 1 — Domain Discovery
-
-Load and follow: ${metaSkillPath("domain-discovery")}
-
-This produces: domain_map.yaml and skill_spec.md in the artifacts directory.
-Domain discovery covers the WHOLE library (one domain map even for monorepos).
-
-**STOP. Review outputs with the maintainer before continuing.**
-
----
-
-## Step 2 — Tree Generator
-
-Load and follow: ${metaSkillPath("tree-generator")}
-
-This produces: skill_tree.yaml in the artifacts directory.
-For monorepos, each skill entry should include a \`package\` field.
-
-**STOP. Review outputs with the maintainer before continuing.**
-
----
-
-## Step 3 — Generate Skills
-
-Load and follow: ${metaSkillPath("generate-skill")}
-
-This produces: individual SKILL.md files.
-- Single-repo: skills/<domain>/<skill>/SKILL.md
-- Monorepo: packages/<pkg>/skills/<domain>/<skill>/SKILL.md
-
----
-
-## After all skills are generated
-
-1. Run \`intent validate\` in each package directory
-2. Commit skills/ and artifacts
-3. For each publishable package, run: \`npx @tanstack/intent edit-package-json\`
-4. Ensure each package has \`@tanstack/intent\` as a devDependency
-5. Create a \`skill:<skill-name>\` label on the GitHub repo for each skill (use \`gh label create\`)
-6. Add a README note: "If you use an AI agent, run \`npx @tanstack/intent@latest install\`"
-`;
-	console.log(prompt);
-}
-const USAGE = `TanStack Intent CLI
-
-Usage:
-  intent list [--json]           Discover intent-enabled packages
-  intent meta [name]             List meta-skills, or print one by name
-  intent validate [<dir>]        Validate skill files (default: skills/)
-  intent install                  Print a skill that guides your coding agent to set up skill-to-task mappings
-  intent scaffold                Print maintainer scaffold prompt
-  intent edit-package-json       Wire package.json (files, keywords) for skill publishing
-  intent setup-github-actions    Copy CI workflow templates to .github/workflows/
-  intent stale [dir] [--json]    Check skills for staleness`;
-const HELP_BY_COMMAND = {
-	list: `${USAGE}
-
-Examples:
-  intent list
-  intent list --json`,
-	meta: `intent meta [name]
-
-List shipped meta-skills, or print a single meta-skill by name.
-
-Examples:
-  intent meta
-  intent meta domain-discovery`,
-	validate: `intent validate [dir]
-
-Validate SKILL.md files in the target directory.
-
-Examples:
-  intent validate
-  intent validate packages/query/skills`,
-	install: `intent install
-
-Print the install prompt used to set up skill-to-task mappings.`,
-	scaffold: `intent scaffold
-
-Print the guided maintainer prompt for generating skills.`,
-	stale: `intent stale [dir] [--json]
 
-Check installed skills for version and source drift.
-
-Examples:
-  intent stale
-  intent stale packages/query
-  intent stale --json`,
-	"edit-package-json": `intent edit-package-json
-
-Update package.json files so skills are published.`,
-	"setup-github-actions": `intent setup-github-actions
-
-Copy Intent CI workflow templates into .github/workflows/.`
-};
-function isHelpFlag(arg) {
-	return arg === "-h" || arg === "--help";
-}
-function printHelp(command) {
-	if (!command) {
-		console.log(`${USAGE}
-
-Run \`intent help <command>\` for details on a specific command.`);
-		return;
-	}
-	console.log(HELP_BY_COMMAND[command] ?? USAGE);
+//#endregion
+//#region src/cli.ts
+function createCli() {
+	const cli = cac("intent");
+	cli.usage("<command> [options]");
+	cli.command("list", "Discover intent-enabled packages").usage("list [--json]").option("--json", "Output JSON").example("list").example("list --json").action(async (options) => {
+		await runListCommand(options, scanIntentsOrFail);
+	});
+	cli.command("meta [name]", "List meta-skills, or print one by name").usage("meta [name]").example("meta").example("meta domain-discovery").action(async (name) => {
+		await runMetaCommand(name, getMetaDir());
+	});
+	cli.command("validate [dir]", "Validate skill files").usage("validate [dir]").example("validate").example("validate packages/query/skills").action(async (dir) => {
+		await runValidateCommand(dir);
+	});
+	cli.command("install", "Print a skill that guides your coding agent to set up skill-to-task mappings").usage("install").action(() => {
+		runInstallCommand();
+	});
+	cli.command("scaffold", "Print maintainer scaffold prompt").usage("scaffold").action(() => {
+		runScaffoldCommand(getMetaDir());
+	});
+	cli.command("stale [dir]", "Check skills for staleness").usage("stale [dir] [--json]").option("--json", "Output JSON").example("stale").example("stale packages/query").example("stale --json").action(async (targetDir, options) => {
+		await runStaleCommand(targetDir, options, resolveStaleTargets);
+	});
+	cli.command("edit-package-json", "Update package.json files so skills are published").usage("edit-package-json").action(async () => {
+		await runEditPackageJsonCommand(process.cwd());
+	});
+	cli.command("setup-github-actions", "Copy Intent CI workflow templates into .github/workflows/").usage("setup-github-actions").action(async () => {
+		await runSetupGithubActionsCommand(process.cwd(), getMetaDir());
+	});
+	cli.command("help [command]", "Display help for a command").action((commandName) => {
+		if (!commandName) {
+			cli.outputHelp();
+			return;
+		}
+		const command = cli.commands.find((candidate) => candidate.isMatched(commandName));
+		if (!command) fail(`Unknown command: ${commandName}`);
+		command.outputHelp();
+	});
+	cli.help();
+	return cli;
 }
 async function main(argv = process.argv.slice(2)) {
-	const command = argv[0];
-	const commandArgs = argv.slice(1);
 	try {
-		if (!command || isHelpFlag(command)) {
-			printHelp();
-			return 0;
-		}
-		if (command === "help") {
-			printHelp(commandArgs[0]);
+		const cli = createCli();
+		if (argv.length === 0) {
+			cli.outputHelp();
 			return 0;
 		}
-		if (isHelpFlag(commandArgs[0])) {
-			printHelp(command);
-			return 0;
-		}
-		switch (command) {
-			case "list":
-				await cmdList(commandArgs);
-				return 0;
-			case "meta":
-				await cmdMeta(commandArgs);
-				return 0;
-			case "validate":
-				await cmdValidate(commandArgs);
-				return 0;
-			case "install":
-				console.log(INSTALL_PROMPT);
-				return 0;
-			case "scaffold":
-				cmdScaffold();
-				return 0;
-			case "stale": {
-				const jsonStale = commandArgs.includes("--json");
-				const { reports } = await resolveStaleTargets(commandArgs.find((arg) => !arg.startsWith("-")));
-				if (reports.length === 0) {
-					console.log("No intent-enabled packages found.");
-					return 0;
-				}
-				if (jsonStale) {
-					console.log(JSON.stringify(reports, null, 2));
-					return 0;
-				}
-				for (const report of reports) {
-					const driftLabel = report.versionDrift ? ` [${report.versionDrift} drift]` : "";
-					const vLabel = report.skillVersion && report.currentVersion ? ` (${report.skillVersion} → ${report.currentVersion})` : "";
-					console.log(`${report.library}${vLabel}${driftLabel}`);
-					const stale = report.skills.filter((s) => s.needsReview);
-					if (stale.length === 0) console.log("  All skills up-to-date");
-					else for (const skill of stale) console.log(`  ⚠ ${skill.name}: ${skill.reasons.join(", ")}`);
-					console.log();
-				}
-				return 0;
-			}
-			case "edit-package-json": {
-				const { runEditPackageJsonAll } = await import("./setup.mjs");
-				runEditPackageJsonAll(process.cwd());
-				return 0;
-			}
-			case "setup-github-actions": {
-				const { runSetupGithubActions } = await import("./setup.mjs");
-				runSetupGithubActions(process.cwd(), getMetaDir());
-				return 0;
-			}
-			default:
-				printHelp();
-				return command ? 1 : 0;
+		cli.parse([
+			"intent",
+			"intent",
+			...argv
+		], { run: false });
+		if (cli.options.help) return 0;
+		if (!cli.matchedCommand) {
+			cli.outputHelp();
+			return 1;
 		}
+		await cli.runMatchedCommand();
+		return 0;
 	} catch (err) {
 		if (isCliFailure(err)) {
 			console.error(err.message);
 			return err.exitCode;
 		}
+		if (err instanceof Error) {
+			console.error(err.message);
+			return 1;
+		}
 		throw err;
 	}
 }
@@ -530,4 +501,4 @@ if (isMain) {
 }
 
 //#endregion
-export { USAGE, main };
+export { main };