@tanstack/intent 0.0.21 → 0.0.23

package/dist/cli.d.mts

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 //#region src/cli.d.ts
-declare const USAGE = "TanStack Intent CLI\n\nUsage:\n  intent list [--json]           Discover intent-enabled packages\n  intent meta [name]             List meta-skills, or print one by name\n  intent validate [<dir>]        Validate skill files (default: skills/)\n  intent install                  Print a skill that guides your coding agent to set up skill-to-task mappings\n  intent scaffold                Print maintainer scaffold prompt\n  intent edit-package-json       Wire package.json (files, keywords) for skill publishing\n  intent setup-github-actions    Copy CI workflow templates to .github/workflows/\n  intent stale [dir] [--json]    Check skills for staleness";
 declare function main(argv?: Array<string>): Promise<number>;
 //#endregion
-export { USAGE, main };
+export { main };

package/dist/cli.mjs

@@ -1,35 +1,72 @@
 #!/usr/bin/env node
-import { t as INSTALL_PROMPT } from "./install-prompt-C0M-U3WZ.mjs";
+import { n as runInstallCommand } from "./install-BHbA_wkb.mjs";
 import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { dirname, join, relative, 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-CsDGCRDm.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-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))) };
 }
+
+//#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 +86,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) {
+async function runListCommand(options, scanIntentsOrFail$1) {
 	const { computeSkillNameWidth, printSkillTree, printTable } = await import("./display-CuCDLPP_.mjs");
-	const jsonOutput = args.includes("--json");
-	const result = await scanIntentsOrFail();
-	if (jsonOutput) {
+	const result = await scanIntentsOrFail$1();
+	if (options.json) {
 		console.log(JSON.stringify(result, null, 2));
 		return;
 	}
@@ -80,7 +103,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 +118,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 +129,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 +151,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-D7OKi0Rn.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,11 +162,145 @@ 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();
+	}
+}
+
+//#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 isInsideMonorepo(root) {
+	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;
 }
 function collectPackagingWarnings(root) {
 	const pkgJsonPath = join(root, "package.json");
@@ -160,22 +318,7 @@ 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 (!isInsideMonorepo(root) && !files.includes("!skills/_artifacts")) warnings.push("\"!skills/_artifacts\" is not in the \"files\" array — artifacts will be published unnecessarily");
 	}
 	return warnings;
 }
@@ -188,30 +331,9 @@ function resolvePackageRoot(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) {
+async function runValidateCommand(dir) {
 	const [{ parse: parseYaml }, { findSkillFiles }] = await Promise.all([import("yaml"), import("./utils-D7OKi0Rn.mjs")]);
-	const targetDir = args[0] ?? "skills";
+	const targetDir = dir ?? "skills";
 	const skillsDir = join(process.cwd(), targetDir);
 	const packageRoot = resolvePackageRoot(skillsDir);
 	if (!existsSync(skillsDir)) fail(`Skills directory not found: ${skillsDir}`);
@@ -239,10 +361,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;
 		}
@@ -299,10 +422,11 @@ 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}`
 			});
 		}
 	}
@@ -312,211 +436,76 @@ async function cmdValidate(args) {
 	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 +519,4 @@ if (isMain) {
 }
 
 //#endregion
-export { USAGE, main };
+export { main };

package/dist/index.d.mts

@@ -2,7 +2,7 @@ import { a as IntentProjectConfig, c as ScanResult, d as StalenessReport, i as I
 import { c as runEditPackageJson, r as SetupGithubActionsResult, t as EditPackageJsonResult, u as runSetupGithubActions } from "./setup-BNBVotfR.mjs";
 
 //#region src/scanner.d.ts
-declare function scanForIntents(root?: string): Promise<ScanResult>;
+declare function scanForIntents(root?: string): ScanResult;
 //#endregion
 //#region src/staleness.d.ts
 declare function checkStaleness(packageDir: string, packageName?: string): Promise<StalenessReport>;

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { a as parseFrontmatter, n as findSkillFiles, o as resolveDepDir, r as getDeps } from "./utils-BfjM1mQe.mjs";
-import { a as runEditPackageJson, s as runSetupGithubActions } from "./setup-J7F7DIP2.mjs";
-import { t as scanForIntents } from "./scanner-SHzOJKcz.mjs";
+import { a as runEditPackageJson, s as runSetupGithubActions } from "./setup-Nyfl1KTS.mjs";
+import { t as scanForIntents } from "./scanner-BCgNt-oI.mjs";
 import { t as checkStaleness } from "./staleness-DZKvsLVq.mjs";
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";

package/dist/{install-prompt-C0M-U3WZ.mjs → install-BHbA_wkb.mjs}

@@ -1,4 +1,4 @@
-//#region src/install-prompt.ts
+//#region src/commands/install.ts
 const INSTALL_PROMPT = `You are an AI assistant helping a developer set up skill-to-task mappings for their project.
 
 Follow these steps in order:
@@ -54,6 +54,9 @@ skills:
    - Keep entries concise - this block is read on every agent task
    - Preserve all content outside the block tags unchanged
    - If the user is on Deno, note that this setup is best-effort today and relies on npm interop`;
+function runInstallCommand() {
+	console.log(INSTALL_PROMPT);
+}
 
 //#endregion
-export { INSTALL_PROMPT as t };
+export { runInstallCommand as n, INSTALL_PROMPT as t };

package/dist/intent-library.mjs

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import "./utils-BfjM1mQe.mjs";
-import { t as INSTALL_PROMPT } from "./install-prompt-C0M-U3WZ.mjs";
+import { t as INSTALL_PROMPT } from "./install-BHbA_wkb.mjs";
 import { n as printSkillTree, r as printTable, t as computeSkillNameWidth } from "./display-DhsUxNJW.mjs";
-import { t as scanLibrary } from "./library-scanner-CU3ZHPYU.mjs";
+import { t as scanLibrary } from "./library-scanner-DlWy8VeZ.mjs";
 
 //#region src/intent-library.ts
-async function cmdList() {
+function cmdList() {
 	let result;
 	try {
-		result = await scanLibrary(process.argv[1]);
+		result = scanLibrary(process.argv[1]);
 	} catch (err) {
 		console.error(err.message);
 		process.exit(1);
@@ -65,7 +65,7 @@ const command = process.argv[2];
 switch (command) {
 	case "list":
 	case void 0:
-		await cmdList();
+		cmdList();
 		break;
 	case "install":
 		cmdInstall();

package/dist/{library-scanner-CU3ZHPYU.mjs → library-scanner-DlWy8VeZ.mjs}

@@ -59,7 +59,7 @@ function discoverSkills(skillsDir) {
 	walk(skillsDir);
 	return skills;
 }
-async function scanLibrary(scriptPath, _projectRoot) {
+function scanLibrary(scriptPath, _projectRoot) {
 	const packages = [];
 	const warnings = [];
 	const visited = /* @__PURE__ */ new Set();

package/dist/library-scanner.d.mts

@@ -11,6 +11,6 @@ interface LibraryScanResult {
   packages: Array<LibraryPackage>;
   warnings: Array<string>;
 }
-declare function scanLibrary(scriptPath: string, _projectRoot?: string): Promise<LibraryScanResult>;
+declare function scanLibrary(scriptPath: string, _projectRoot?: string): LibraryScanResult;
 //#endregion
 export { LibraryPackage, LibraryScanResult, scanLibrary };

package/dist/library-scanner.mjs

@@ -1,4 +1,4 @@
 import "./utils-BfjM1mQe.mjs";
-import { t as scanLibrary } from "./library-scanner-CU3ZHPYU.mjs";
+import { t as scanLibrary } from "./library-scanner-DlWy8VeZ.mjs";
 
 export { scanLibrary };

package/dist/{scanner-SHzOJKcz.mjs → scanner-BCgNt-oI.mjs}

@@ -1,5 +1,5 @@
 import { a as parseFrontmatter, i as listNodeModulesPackageDirs, o as resolveDepDir, r as getDeps, t as detectGlobalNodeModules } from "./utils-BfjM1mQe.mjs";
-import { i as resolveWorkspacePackages, n as findWorkspaceRoot, r as readWorkspacePatterns } from "./setup-J7F7DIP2.mjs";
+import { i as resolveWorkspacePackages, n as findWorkspaceRoot, r as readWorkspacePatterns } from "./setup-Nyfl1KTS.mjs";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 
@@ -169,7 +169,7 @@ function toVersionConflict(packageName, variants, chosen) {
 		variants
 	};
 }
-async function scanForIntents(root) {
+function scanForIntents(root) {
 	const projectRoot = root ?? process.cwd();
 	const packageManager = detectPackageManager(projectRoot);
 	const nodeModulesDir = join(projectRoot, "node_modules");

package/dist/scanner-CsDGCRDm.mjs

@@ -0,0 +1,5 @@
+import "./utils-BfjM1mQe.mjs";
+import "./setup-Nyfl1KTS.mjs";
+import { t as scanForIntents } from "./scanner-BCgNt-oI.mjs";
+
+export { scanForIntents };

package/dist/{setup-J7F7DIP2.mjs → setup-Nyfl1KTS.mjs}

@@ -4,6 +4,19 @@ import { basename, join, relative } from "node:path";
 import { parse } from "yaml";
 
 //#region src/setup.ts
+function isGenericWorkspaceName(name, root) {
+	const normalized = name.trim().toLowerCase();
+	return normalized.length === 0 || normalized === "unknown" || normalized === "root" || normalized === "workspace" || normalized === "monorepo" || normalized === basename(root).toLowerCase();
+}
+function deriveWorkspacePackageName(root, repo, packageDirs) {
+	const repoName = repo.split("/").filter(Boolean).pop() || basename(root);
+	for (const packageDir of packageDirs) {
+		const pkgJson = readPackageJson(packageDir);
+		const pkgName = typeof pkgJson.name === "string" ? pkgJson.name : null;
+		if (pkgName?.startsWith("@")) return `${pkgName.split("/")[0]}/${repoName}`;
+	}
+	return repoName;
+}
 function readPackageJson(root) {
 	const pkgPath = join(root, "package.json");
 	try {
@@ -41,19 +54,22 @@ function buildWatchPaths(root, packageDirs) {
 }
 function detectVars(root, packageDirs) {
 	const pkgJson = readPackageJson(root);
-	const name = typeof pkgJson.name === "string" ? pkgJson.name : "unknown";
+	const rawName = typeof pkgJson.name === "string" ? pkgJson.name : "unknown";
 	const docs = typeof pkgJson.intent?.docs === "string" ? pkgJson.intent.docs : "docs/";
-	const repo = detectRepo(pkgJson, name.replace(/^@/, "").replace(/\//, "/"));
 	const isMonorepo = packageDirs !== void 0;
-	const packageLabel = isMonorepo && name === "unknown" ? `${basename(root)} workspace` : name;
-	let srcPath = `packages/${name.replace(/^@[^/]+\//, "")}/src/**`;
-	if (existsSync(join(root, "src"))) srcPath = "src/**";
+	const repo = detectRepo(pkgJson, detectRepo((packageDirs?.[0] ? readPackageJson(packageDirs[0]) : null) ?? {}, basename(root)));
+	let packageName = rawName;
+	if (isMonorepo && isGenericWorkspaceName(rawName, root)) packageName = deriveWorkspacePackageName(root, repo, packageDirs);
+	const shortName = packageName.replace(/^@[^/]+\//, "");
+	let srcPath = isMonorepo ? "packages/*/src/**" : `packages/${shortName}/src/**`;
+	if (!isMonorepo && existsSync(join(root, "src"))) srcPath = "src/**";
+	const docsPath = isMonorepo ? "packages/*/docs/**" : docs;
 	return {
-		PACKAGE_NAME: name,
-		PACKAGE_LABEL: packageLabel,
-		PAYLOAD_PACKAGE: packageLabel,
+		PACKAGE_NAME: packageName,
+		PACKAGE_LABEL: packageName,
+		PAYLOAD_PACKAGE: packageName,
 		REPO: repo,
-		DOCS_PATH: docs.endsWith("**") ? docs : docs.replace(/\/$/, "") + "/**",
+		DOCS_PATH: docsPath.endsWith("**") ? docsPath : docsPath.replace(/\/$/, "") + "/**",
 		SRC_PATH: srcPath,
 		WATCH_PATHS: isMonorepo ? buildWatchPaths(root, packageDirs) : `      - '${docs.endsWith("**") ? docs : docs.replace(/\/$/, "") + "/**"}'\n      - '${srcPath}'`
 	};

package/dist/setup.mjs

@@ -1,4 +1,4 @@
 import "./utils-BfjM1mQe.mjs";
-import { a as runEditPackageJson, i as resolveWorkspacePackages, n as findWorkspaceRoot, o as runEditPackageJsonAll, r as readWorkspacePatterns, s as runSetupGithubActions, t as findPackagesWithSkills } from "./setup-J7F7DIP2.mjs";
+import { a as runEditPackageJson, i as resolveWorkspacePackages, n as findWorkspaceRoot, o as runEditPackageJsonAll, r as readWorkspacePatterns, s as runSetupGithubActions, t as findPackagesWithSkills } from "./setup-Nyfl1KTS.mjs";
 
 export { findPackagesWithSkills, findWorkspaceRoot, readWorkspacePatterns, resolveWorkspacePackages, runEditPackageJson, runEditPackageJsonAll, runSetupGithubActions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/intent",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "description": "Ship compositional knowledge for AI coding agents alongside your npm packages",
   "license": "MIT",
   "type": "module",
@@ -27,6 +27,7 @@
     "meta"
   ],
   "dependencies": {
+    "cac": "^6.7.14",
     "yaml": "^2.7.0"
   },
   "devDependencies": {
@@ -37,6 +38,7 @@
   "scripts": {
     "prepack": "npm run build",
     "build": "tsdown src/index.ts src/cli.ts src/setup.ts src/intent-library.ts src/library-scanner.ts --format esm --dts",
+    "test:smoke": "pnpm run build && node dist/cli.mjs --help > /dev/null",
     "test:lib": "vitest run --exclude 'tests/integration/**'",
     "test:integration": "vitest run tests/integration/",
     "test:types": "tsc --noEmit"

package/dist/scanner-RWHFrJ_C.mjs

@@ -1,5 +0,0 @@
-import "./utils-BfjM1mQe.mjs";
-import "./setup-J7F7DIP2.mjs";
-import { t as scanForIntents } from "./scanner-SHzOJKcz.mjs";
-
-export { scanForIntents };