@tanstack/intent 0.0.14 → 0.0.19

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { a as IntentProjectConfig, c as ScanResult, d as StalenessReport, i as IntentPackage, l as SkillEntry, n as FeedbackPayload, o as MetaFeedbackPayload, r as IntentConfig, s as MetaSkillName, t as AgentName, u as SkillStaleness } from "./types-BmnI8kFB.mjs";
-import { a as runEditPackageJson, i as runAddLibraryBin, n as EditPackageJsonResult, o as runSetupGithubActions, r as SetupGithubActionsResult, t as AddLibraryBinResult } from "./setup-CANkTz55.mjs";
+import { a as IntentProjectConfig, c as ScanResult, d as StalenessReport, i as IntentPackage, l as SkillEntry, n as FeedbackPayload, o as MetaFeedbackPayload, r as IntentConfig, s as MetaSkillName, t as AgentName, u as SkillStaleness } from "./types-ddLtccfV.mjs";
+import { c as runAddLibraryBin, f as runSetupGithubActions, i as SetupGithubActionsResult, n as EditPackageJsonResult, t as AddLibraryBinResult, u as runEditPackageJson } from "./setup-6m3IfxyO.mjs";
 
 //#region src/scanner.d.ts
 declare function scanForIntents(root?: string): Promise<ScanResult>;
@@ -13,11 +13,11 @@ declare function hasGhCli(): boolean;
 declare function resolveFrequency(root: string): string;
 declare function validatePayload(payload: unknown): {
   valid: boolean;
-  errors: string[];
+  errors: Array<string>;
 };
 declare function validateMetaPayload(payload: unknown): {
   valid: boolean;
-  errors: string[];
+  errors: Array<string>;
 };
 declare function metaToMarkdown(payload: MetaFeedbackPayload): string;
 declare function toMarkdown(payload: FeedbackPayload): string;
@@ -38,19 +38,19 @@ declare function submitMetaFeedback(payload: MetaFeedbackPayload, opts: {
 /**
  * Recursively find all SKILL.md files under a directory.
  */
-declare function findSkillFiles(dir: string): string[];
+declare function findSkillFiles(dir: string): Array<string>;
 /**
  * Read dependencies and peerDependencies (and optionally devDependencies) from
  * a parsed package.json object.
  */
-declare function getDeps(pkgJson: Record<string, unknown>, includeDevDeps?: boolean): string[];
+declare function getDeps(pkgJson: Record<string, unknown>, includeDevDeps?: boolean): Array<string>;
 /**
  * Resolve the directory of a dependency by name. First checks the top-level
  * node_modules (hoisted layout — npm, yarn, bun), then resolves through the
  * parent package's real path to handle pnpm's virtual store layout where
  * transitive deps are siblings in the .pnpm virtual store node_modules.
  */
-declare function resolveDepDir(depName: string, parentDir: string, parentName: string, nodeModulesDir: string): string | null;
+declare function resolveDepDir(depName: string, parentDir: string, parentName: string, nodeModulesDirs: string | Array<string>): string | null;
 /**
  * Parse YAML frontmatter from a file. Returns null if no frontmatter or on error.
  */

package/dist/index.mjs

@@ -1,7 +1,7 @@
-import { i as resolveDepDir, n as getDeps, r as parseFrontmatter, t as findSkillFiles } from "./utils-CDJzAdjD.mjs";
-import { t as scanForIntents } from "./scanner-CY40iozO.mjs";
-import { t as checkStaleness } from "./staleness-DJfMKH62.mjs";
-import { n as runEditPackageJson, r as runSetupGithubActions, t as runAddLibraryBin } from "./setup-Nif1-nhS.mjs";
+import { a as parseFrontmatter, n as findSkillFiles, o as resolveDepDir, r as getDeps } from "./utils-DY1eH2E_.mjs";
+import { t as scanForIntents } from "./scanner-f82qRq7h.mjs";
+import { t as checkStaleness } from "./staleness-D_ZiK4Tf.mjs";
+import { c as runSetupGithubActions, i as runAddLibraryBin, o as runEditPackageJson } from "./setup-CncHbQlb.mjs";
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { execFileSync, execSync } from "node:child_process";
@@ -31,17 +31,26 @@ function hasGhCli() {
 function getHomeConfigDir() {
 	return process.env.XDG_CONFIG_HOME ?? join(process.env.HOME ?? process.env.USERPROFILE ?? "", ".config");
 }
-function resolveFrequency(root) {
-	const userConfigPath = join(getHomeConfigDir(), "intent", "config.json");
-	try {
-		const userCfg = JSON.parse(readFileSync(userConfigPath, "utf8"));
-		if (userCfg.feedback?.frequency) return userCfg.feedback.frequency;
-	} catch {}
-	const projectConfigPath = join(root, "intent.config.json");
+function parseFrequency(value) {
+	if (value === "always" || value === "never") return value;
+	if (typeof value !== "string") return null;
+	const match = /^every-(\d+)$/.exec(value);
+	if (!match) return null;
+	const count = Number(match[1]);
+	return Number.isInteger(count) && count > 0 ? `every-${count}` : null;
+}
+function readFrequency(filePath) {
 	try {
-		const projCfg = JSON.parse(readFileSync(projectConfigPath, "utf8"));
-		if (projCfg.feedback?.frequency) return projCfg.feedback.frequency;
-	} catch {}
+		return parseFrequency(JSON.parse(readFileSync(filePath, "utf8")).feedback?.frequency);
+	} catch {
+		return null;
+	}
+}
+function resolveFrequency(root) {
+	const userFrequency = readFrequency(join(getHomeConfigDir(), "intent", "config.json"));
+	if (userFrequency) return userFrequency;
+	const projectFrequency = readFrequency(join(root, "intent.config.json"));
+	if (projectFrequency) return projectFrequency;
 	return "every-5";
 }
 const REQUIRED_FIELDS = [
@@ -102,6 +111,18 @@ const VALID_QUALITY_RATINGS = [
 	"mixed",
 	"bad"
 ];
+const VALID_INTERVIEW_QUALITY_RATINGS = [
+	"good",
+	"mixed",
+	"bad",
+	"skipped"
+];
+const VALID_FAILURE_MODE_QUALITY_RATINGS = [
+	"good",
+	"mixed",
+	"bad",
+	"not-applicable"
+];
 function validateMetaPayload(payload) {
 	const errors = [];
 	if (!payload || typeof payload !== "object") return {
@@ -114,6 +135,8 @@ function validateMetaPayload(payload) {
 	if (obj.agentUsed && !VALID_AGENTS.includes(obj.agentUsed)) errors.push(`agentUsed must be one of: ${VALID_AGENTS.join(", ")}`);
 	if (obj.artifactQuality && !VALID_QUALITY_RATINGS.includes(obj.artifactQuality)) errors.push("artifactQuality must be one of: good, mixed, bad");
 	if (obj.userRating && !VALID_QUALITY_RATINGS.includes(obj.userRating)) errors.push("userRating must be one of: good, mixed, bad");
+	if (obj.interviewQuality && !VALID_INTERVIEW_QUALITY_RATINGS.includes(obj.interviewQuality)) errors.push("interviewQuality must be one of: good, mixed, bad, skipped");
+	if (obj.failureModeQuality && !VALID_FAILURE_MODE_QUALITY_RATINGS.includes(obj.failureModeQuality)) errors.push("failureModeQuality must be one of: good, mixed, bad, not-applicable");
 	if (containsSecrets(Object.values(obj).filter((v) => typeof v === "string").join("\n"))) errors.push("Payload appears to contain secrets or tokens — submission rejected");
 	return {
 		valid: errors.length === 0,

package/dist/install-prompt-C0M-U3WZ.mjs

@@ -0,0 +1,59 @@
+//#region src/install-prompt.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:
+
+1. CHECK FOR EXISTING MAPPINGS
+   Search the project's agent config files (AGENTS.md, CLAUDE.md, .cursorrules,
+   .github/copilot-instructions.md) for a block delimited by:
+     <!-- intent-skills:start -->
+     <!-- intent-skills:end -->
+   - If found: show the user the current mappings, keep that file as the source of truth,
+     and ask "What would you like to update?" Then skip to step 4 with their requested changes.
+   - If not found: continue to step 2.
+
+2. DISCOVER AVAILABLE SKILLS
+   Run: \`npx @tanstack/intent@latest list\`
+   This outputs each skill's name, description, full path, and whether it was found in
+   project-local node_modules or accessible global node_modules.
+   This works best in Node-compatible environments (npm, pnpm, Bun, or Deno npm interop
+   with node_modules enabled).
+
+3. SCAN THE REPOSITORY
+   Build a picture of the project's structure and patterns:
+   - Read package.json for library dependencies
+   - Survey the directory layout (src/, app/, routes/, components/, api/, etc.)
+   - Note recurring patterns (routing, data fetching, auth, UI components, etc.)
+
+   Based on this, propose 3-5 skill-to-task mappings. For each one explain:
+   - The task or code area (in plain language the user would recognise)
+   - Which skill applies and why
+
+   Then ask: "What other tasks do you commonly use AI coding agents for?
+   I'll create mappings for those too."
+   Also ask: "I'll default to AGENTS.md unless you want another supported config file.
+   Do you have a preference?"
+
+4. WRITE THE MAPPINGS BLOCK
+   Once you have the full set of mappings, write or update the agent config file.
+   - If you found an existing intent-skills block, update that file in place.
+   - Otherwise prefer AGENTS.md by default, unless the user asked for another supported file.
+
+   Use this exact block:
+
+<!-- intent-skills:start -->
+# Skill mappings - when working in these areas, load the linked skill file into context.
+skills:
+  - task: "describe the task or code area here"
+    load: "node_modules/package-name/skills/skill-name/SKILL.md"
+<!-- intent-skills:end -->
+
+   Rules:
+   - Use the user's own words for task descriptions
+   - Include the exact path from \`npx @tanstack/intent@latest list\` output so agents can load it directly
+   - 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`;
+
+//#endregion
+export { INSTALL_PROMPT as t };

package/dist/intent-library.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import "./utils-CDJzAdjD.mjs";
-import { n as printSkillTree, r as printTable, t as computeSkillNameWidth } from "./display-D_XzuGnu.mjs";
-import { t as scanLibrary } from "./library-scanner-B1tmOzwf.mjs";
+import "./utils-DY1eH2E_.mjs";
+import { t as INSTALL_PROMPT } from "./install-prompt-C0M-U3WZ.mjs";
+import { n as printSkillTree, r as printTable, t as computeSkillNameWidth } from "./display-DhsUxNJW.mjs";
+import { t as scanLibrary } from "./library-scanner-CU0OozQE.mjs";
 
 //#region src/intent-library.ts
 async function cmdList() {
@@ -52,52 +53,7 @@ async function cmdList() {
 	}
 }
 function cmdInstall() {
-	console.log(`You are an AI assistant helping a developer set up skill-to-task mappings for their project.
-
-Follow these steps in order:
-
-1. CHECK FOR EXISTING MAPPINGS
-   Search the project's agent config files (CLAUDE.md, AGENTS.md, .cursorrules,
-   .github/copilot-instructions.md) for a block delimited by:
-     <!-- intent-skills:start -->
-     <!-- intent-skills:end -->
-   - If found: show the user the current mappings and ask "What would you like to update?"
-     Then skip to step 4 with their requested changes.
-   - If not found: continue to step 2.
-
-2. DISCOVER AVAILABLE SKILLS
-   Run: intent list
-   This outputs each skill's name, description, and full path — grouped by package.
-
-3. SCAN THE REPOSITORY
-   Build a picture of the project's structure and patterns:
-   - Read package.json for library dependencies
-   - Survey the directory layout (src/, app/, routes/, components/, api/, etc.)
-   - Note recurring patterns (routing, data fetching, auth, UI components, etc.)
-
-   Based on this, propose 3–5 skill-to-task mappings. For each one explain:
-   - The task or code area (in plain language the user would recognise)
-   - Which skill applies and why
-
-   Then ask: "What other tasks do you commonly use AI coding agents for?
-   I'll create mappings for those too."
-
-4. WRITE THE MAPPINGS BLOCK
-   Once you have the full set of mappings, write or update the agent config file
-   (prefer CLAUDE.md; create it if none exists) with this exact block:
-
-<!-- intent-skills:start -->
-# Skill mappings — when working in these areas, load the linked skill file into context.
-skills:
-  - task: "describe the task or code area here"
-    load: "node_modules/package-name/skills/skill-name/SKILL.md"
-<!-- intent-skills:end -->
-
-   Rules:
-   - Use the user's own words for task descriptions
-   - Include the exact path from \`intent list\` output so agents can load it directly
-   - Keep entries concise — this block is read on every agent task
-   - Preserve all content outside the block tags unchanged`);
+	console.log(INSTALL_PROMPT);
 }
 const USAGE = `TanStack Intent
 

package/dist/{library-scanner-B1tmOzwf.mjs → library-scanner-CU0OozQE.mjs}

@@ -1,4 +1,4 @@
-import { i as resolveDepDir, n as getDeps, r as parseFrontmatter } from "./utils-CDJzAdjD.mjs";
+import { a as parseFrontmatter, o as resolveDepDir, r as getDeps } from "./utils-DY1eH2E_.mjs";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
 
@@ -12,7 +12,7 @@ function readPkgJson(dir) {
 }
 function findHomeDir(scriptPath) {
 	let dir = dirname(scriptPath);
-	while (true) {
+	for (;;) {
 		if (existsSync(join(dir, "package.json"))) return dir;
 		const parent = dirname(dir);
 		if (parent === dir) return null;

package/dist/library-scanner.d.mts

@@ -1,15 +1,15 @@
-import { l as SkillEntry } from "./types-BmnI8kFB.mjs";
+import { l as SkillEntry } from "./types-ddLtccfV.mjs";
 
 //#region src/library-scanner.d.ts
 interface LibraryPackage {
   name: string;
   version: string;
   description: string;
-  skills: SkillEntry[];
+  skills: Array<SkillEntry>;
 }
 interface LibraryScanResult {
-  packages: LibraryPackage[];
-  warnings: string[];
+  packages: Array<LibraryPackage>;
+  warnings: Array<string>;
 }
 declare function scanLibrary(scriptPath: string, projectRoot?: string): Promise<LibraryScanResult>;
 //#endregion

package/dist/library-scanner.mjs

@@ -1,4 +1,4 @@
-import "./utils-CDJzAdjD.mjs";
-import { t as scanLibrary } from "./library-scanner-B1tmOzwf.mjs";
+import "./utils-DY1eH2E_.mjs";
+import { t as scanLibrary } from "./library-scanner-CU0OozQE.mjs";
 
 export { scanLibrary };

package/dist/scanner-B1UvuEBQ.mjs

@@ -0,0 +1,4 @@
+import "./utils-DY1eH2E_.mjs";
+import { t as scanForIntents } from "./scanner-f82qRq7h.mjs";
+
+export { scanForIntents };

package/dist/scanner-f82qRq7h.mjs

@@ -0,0 +1,338 @@
+import { a as parseFrontmatter, i as listNodeModulesPackageDirs, o as resolveDepDir, r as getDeps, t as detectGlobalNodeModules } from "./utils-DY1eH2E_.mjs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+//#region src/scanner.ts
+function detectPackageManager(root) {
+	if (existsSync(join(root, ".pnp.cjs")) || existsSync(join(root, ".pnp.js"))) throw new Error("Yarn PnP is not yet supported. Add `nodeLinker: node-modules` to your .yarnrc.yml to use intent.");
+	if (existsSync(join(root, "deno.json")) && !existsSync(join(root, "node_modules"))) throw new Error("Deno without node_modules is not yet supported. Add `\"nodeModulesDir\": \"auto\"` to your deno.json to use intent.");
+	if (existsSync(join(root, "pnpm-lock.yaml"))) return "pnpm";
+	if (existsSync(join(root, "bun.lockb")) || existsSync(join(root, "bun.lock"))) return "bun";
+	if (existsSync(join(root, "yarn.lock"))) return "yarn";
+	if (existsSync(join(root, "package-lock.json"))) return "npm";
+	return "unknown";
+}
+function validateIntentField(_pkgName, intent) {
+	if (!intent || typeof intent !== "object") return null;
+	const pb = intent;
+	if (pb.version !== 1) return null;
+	if (typeof pb.repo !== "string" || !pb.repo) return null;
+	if (typeof pb.docs !== "string" || !pb.docs) return null;
+	const requires = Array.isArray(pb.requires) ? pb.requires.filter((r) => typeof r === "string") : void 0;
+	return {
+		version: 1,
+		repo: pb.repo,
+		docs: pb.docs,
+		requires
+	};
+}
+/**
+* Derive an IntentConfig from standard package.json fields when no explicit
+* `intent` field is present. A package with a `skills/` directory signals
+* intent support; `repo` and `docs` are derived from `repository` and
+* `homepage`.
+*/
+function deriveIntentConfig(pkgJson) {
+	let repo = null;
+	if (typeof pkgJson.repository === "string") repo = pkgJson.repository;
+	else if (pkgJson.repository && typeof pkgJson.repository === "object" && typeof pkgJson.repository.url === "string") {
+		repo = pkgJson.repository.url;
+		repo = repo.replace(/^git\+/, "").replace(/\.git$/, "").replace(/^https?:\/\/github\.com\//, "");
+	}
+	const docs = typeof pkgJson.homepage === "string" ? pkgJson.homepage : void 0;
+	if (!repo) return null;
+	const intentPartial = pkgJson.intent;
+	const requires = intentPartial && Array.isArray(intentPartial.requires) ? intentPartial.requires.filter((r) => typeof r === "string") : void 0;
+	return {
+		version: 1,
+		repo,
+		docs: docs ?? "",
+		requires
+	};
+}
+function discoverSkills(skillsDir, _baseName) {
+	const skills = [];
+	function walk(dir) {
+		let entries;
+		try {
+			entries = readdirSync(dir, {
+				withFileTypes: true,
+				encoding: "utf8"
+			});
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			const childDir = join(dir, entry.name);
+			const skillFile = join(childDir, "SKILL.md");
+			if (existsSync(skillFile)) {
+				const fm = parseFrontmatter(skillFile);
+				const relName = relative(skillsDir, childDir).split(sep).join("/");
+				const desc = typeof fm?.description === "string" ? fm.description.replace(/\s+/g, " ").trim() : "";
+				skills.push({
+					name: typeof fm?.name === "string" ? fm.name : relName,
+					path: skillFile,
+					description: desc,
+					type: typeof fm?.type === "string" ? fm.type : void 0,
+					framework: typeof fm?.framework === "string" ? fm.framework : void 0
+				});
+				walk(childDir);
+			}
+		}
+	}
+	walk(skillsDir);
+	return skills;
+}
+function topoSort(packages) {
+	const byName = new Map(packages.map((p) => [p.name, p]));
+	const visited = /* @__PURE__ */ new Set();
+	const sorted = [];
+	function visit(name) {
+		if (visited.has(name)) return;
+		visited.add(name);
+		const pkg = byName.get(name);
+		if (!pkg) return;
+		for (const dep of pkg.intent.requires ?? []) visit(dep);
+		sorted.push(pkg);
+	}
+	for (const pkg of packages) visit(pkg.name);
+	return sorted;
+}
+function getPackageDepth(packageRoot, projectRoot) {
+	return relative(projectRoot, packageRoot).split(sep).length;
+}
+function parseSemver(version) {
+	const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
+	if (!match) return null;
+	const prerelease = match[4] ? match[4].split(".").map((identifier) => {
+		return /^\d+$/.test(identifier) ? Number(identifier) : identifier;
+	}) : [];
+	return {
+		major: Number(match[1]),
+		minor: Number(match[2]),
+		patch: Number(match[3]),
+		prerelease
+	};
+}
+function comparePrereleaseIdentifiers(a, b) {
+	if (a === void 0) return b === void 0 ? 0 : 1;
+	if (b === void 0) return -1;
+	if (typeof a === "number" && typeof b === "number") return a - b;
+	if (typeof a === "number") return -1;
+	if (typeof b === "number") return 1;
+	return a.localeCompare(b);
+}
+function comparePackageVersions(a, b) {
+	const parsedA = parseSemver(a);
+	const parsedB = parseSemver(b);
+	if (!parsedA || !parsedB) {
+		if (parsedA) return 1;
+		if (parsedB) return -1;
+		return 0;
+	}
+	for (const key of [
+		"major",
+		"minor",
+		"patch"
+	]) {
+		const diff = parsedA[key] - parsedB[key];
+		if (diff !== 0) return diff;
+	}
+	const length = Math.max(parsedA.prerelease.length, parsedB.prerelease.length);
+	for (let i = 0; i < length; i++) {
+		const diff = comparePrereleaseIdentifiers(parsedA.prerelease[i], parsedB.prerelease[i]);
+		if (diff !== 0) return diff;
+	}
+	return 0;
+}
+function formatVariantWarning(name, variants, chosen) {
+	const uniqueVersions = new Set(variants.map((variant) => variant.version));
+	if (uniqueVersions.size <= 1) return null;
+	const details = variants.map((variant) => `${variant.version} at ${variant.packageRoot}`).join(", ");
+	return `Found ${variants.length} installed variants of ${name} across ${uniqueVersions.size} versions (${details}). Using ${chosen.version} from ${chosen.packageRoot}.`;
+}
+function toVersionConflict(packageName, variants, chosen) {
+	if (new Set(variants.map((variant) => variant.version)).size <= 1) return null;
+	return {
+		packageName,
+		chosen: {
+			version: chosen.version,
+			packageRoot: chosen.packageRoot
+		},
+		variants
+	};
+}
+async function scanForIntents(root) {
+	const projectRoot = root ?? process.cwd();
+	const packageManager = detectPackageManager(projectRoot);
+	const nodeModulesDir = join(projectRoot, "node_modules");
+	const explicitGlobalNodeModules = process.env.INTENT_GLOBAL_NODE_MODULES?.trim() || null;
+	const packages = [];
+	const warnings = [];
+	const conflicts = [];
+	const nodeModules = {
+		local: {
+			path: nodeModulesDir,
+			detected: true,
+			exists: existsSync(nodeModulesDir),
+			scanned: false
+		},
+		global: {
+			path: explicitGlobalNodeModules,
+			detected: Boolean(explicitGlobalNodeModules),
+			exists: explicitGlobalNodeModules ? existsSync(explicitGlobalNodeModules) : false,
+			scanned: false,
+			source: explicitGlobalNodeModules ? "INTENT_GLOBAL_NODE_MODULES" : void 0
+		}
+	};
+	const resolutionRoots = [nodeModulesDir];
+	const packageIndexes = /* @__PURE__ */ new Map();
+	const packageJsonCache = /* @__PURE__ */ new Map();
+	const packageVariants = /* @__PURE__ */ new Map();
+	function rememberVariant(pkg) {
+		let variants = packageVariants.get(pkg.name);
+		if (!variants) {
+			variants = /* @__PURE__ */ new Map();
+			packageVariants.set(pkg.name, variants);
+		}
+		variants.set(pkg.packageRoot, {
+			version: pkg.version,
+			packageRoot: pkg.packageRoot
+		});
+	}
+	function ensureGlobalNodeModules() {
+		if (!nodeModules.global.path && !explicitGlobalNodeModules) {
+			const detected = detectGlobalNodeModules(packageManager);
+			nodeModules.global.path = detected.path;
+			nodeModules.global.source = detected.source;
+			nodeModules.global.detected = Boolean(detected.path);
+			nodeModules.global.exists = detected.path ? existsSync(detected.path) : false;
+		}
+		if (nodeModules.global.exists && nodeModules.global.path && nodeModules.global.path !== nodeModulesDir && !resolutionRoots.includes(nodeModules.global.path)) resolutionRoots.push(nodeModules.global.path);
+	}
+	function readPkgJson(dirPath) {
+		if (packageJsonCache.has(dirPath)) return packageJsonCache.get(dirPath) ?? null;
+		try {
+			const pkgJson = JSON.parse(readFileSync(join(dirPath, "package.json"), "utf8"));
+			packageJsonCache.set(dirPath, pkgJson);
+			return pkgJson;
+		} catch {
+			packageJsonCache.set(dirPath, null);
+			return null;
+		}
+	}
+	function scanTarget(target) {
+		if (!target.path || !target.exists || target.scanned) return;
+		target.scanned = true;
+		for (const dirPath of listNodeModulesPackageDirs(target.path)) tryRegister(dirPath, "unknown");
+	}
+	/**
+	* Try to register a package with a skills/ directory. Reads its
+	* package.json, validates intent config, discovers skills, and pushes
+	* to `packages`. Returns true if the package was registered.
+	*/
+	function tryRegister(dirPath, fallbackName) {
+		const skillsDir = join(dirPath, "skills");
+		if (!existsSync(skillsDir)) return false;
+		const pkgJson = readPkgJson(dirPath);
+		if (!pkgJson) {
+			warnings.push(`Could not read package.json for ${dirPath}`);
+			return false;
+		}
+		const name = typeof pkgJson.name === "string" ? pkgJson.name : fallbackName;
+		const version = typeof pkgJson.version === "string" ? pkgJson.version : "0.0.0";
+		const intent = validateIntentField(name, pkgJson.intent) ?? deriveIntentConfig(pkgJson);
+		if (!intent) {
+			warnings.push(`${name} has a skills/ directory but could not determine repo/docs from package.json (add a "repository" field or explicit "intent" config)`);
+			return false;
+		}
+		const candidate = {
+			name,
+			version,
+			intent,
+			skills: discoverSkills(skillsDir, name),
+			packageRoot: dirPath
+		};
+		const existingIndex = packageIndexes.get(name);
+		if (existingIndex === void 0) {
+			rememberVariant(candidate);
+			packageIndexes.set(name, packages.push(candidate) - 1);
+			return true;
+		}
+		const existing = packages[existingIndex];
+		if (existing.packageRoot === candidate.packageRoot) return false;
+		rememberVariant(existing);
+		rememberVariant(candidate);
+		const existingDepth = getPackageDepth(existing.packageRoot, projectRoot);
+		const candidateDepth = getPackageDepth(candidate.packageRoot, projectRoot);
+		if (candidateDepth < existingDepth || candidateDepth === existingDepth && comparePackageVersions(candidate.version, existing.version) > 0) packages[existingIndex] = candidate;
+		return true;
+	}
+	scanTarget(nodeModules.local);
+	const walkVisited = /* @__PURE__ */ new Set();
+	function walkDeps(pkgDir, pkgName) {
+		if (walkVisited.has(pkgDir)) return;
+		walkVisited.add(pkgDir);
+		const pkgJson = readPkgJson(pkgDir);
+		if (!pkgJson) {
+			warnings.push(`Could not read package.json for ${pkgName} (skipping dependency walk)`);
+			return;
+		}
+		for (const depName of getDeps(pkgJson)) {
+			const depDir = resolveDepDir(depName, pkgDir, pkgName, resolutionRoots);
+			if (!depDir || walkVisited.has(depDir)) continue;
+			tryRegister(depDir, depName);
+			walkDeps(depDir, depName);
+		}
+	}
+	function walkKnownPackages() {
+		for (const pkg of [...packages]) walkDeps(pkg.packageRoot, pkg.name);
+	}
+	function walkProjectDeps() {
+		let projectPkg = null;
+		try {
+			projectPkg = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf8"));
+		} catch (err) {
+			if (!(err && typeof err === "object" && "code" in err && err.code === "ENOENT")) warnings.push(`Could not read project package.json: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (!projectPkg) return;
+		for (const depName of getDeps(projectPkg, true)) {
+			const depDir = resolveDepDir(depName, projectRoot, depName, resolutionRoots);
+			if (depDir && !walkVisited.has(depDir)) walkDeps(depDir, depName);
+		}
+	}
+	walkKnownPackages();
+	walkProjectDeps();
+	if (explicitGlobalNodeModules || packages.length === 0 || !nodeModules.local.exists) {
+		ensureGlobalNodeModules();
+		scanTarget(nodeModules.global);
+		walkKnownPackages();
+		walkProjectDeps();
+	}
+	if (!nodeModules.local.exists && !nodeModules.global.exists) return {
+		packageManager,
+		packages,
+		warnings,
+		conflicts,
+		nodeModules
+	};
+	for (const pkg of packages) {
+		const variants = packageVariants.get(pkg.name);
+		if (!variants) continue;
+		const conflict = toVersionConflict(pkg.name, [...variants.values()], pkg);
+		if (conflict) conflicts.push(conflict);
+		const warning = formatVariantWarning(pkg.name, [...variants.values()], pkg);
+		if (warning) warnings.push(warning);
+	}
+	return {
+		packageManager,
+		packages: topoSort(packages),
+		warnings,
+		conflicts,
+		nodeModules
+	};
+}
+
+//#endregion
+export { scanForIntents as t };

package/dist/setup-6m3IfxyO.d.mts

@@ -0,0 +1,30 @@
+//#region src/setup.d.ts
+interface AddLibraryBinResult {
+  shim: string | null;
+  skipped: string | null;
+}
+interface EditPackageJsonResult {
+  added: Array<string>;
+  alreadyPresent: Array<string>;
+}
+interface SetupGithubActionsResult {
+  workflows: Array<string>;
+  skipped: Array<string>;
+}
+interface MonorepoResult<T> {
+  package: string;
+  result: T;
+}
+declare function runAddLibraryBin(root: string): AddLibraryBinResult;
+declare function runEditPackageJson(root: string): EditPackageJsonResult;
+declare function readWorkspacePatterns(root: string): Array<string> | null;
+declare function findWorkspaceRoot(start: string): string | null;
+/**
+ * Find workspace packages that contain at least one SKILL.md file.
+ */
+declare function findPackagesWithSkills(root: string): Array<string>;
+declare function runEditPackageJsonAll(root: string): Array<MonorepoResult<EditPackageJsonResult>> | EditPackageJsonResult;
+declare function runAddLibraryBinAll(root: string): Array<MonorepoResult<AddLibraryBinResult>> | AddLibraryBinResult;
+declare function runSetupGithubActions(root: string, metaDir: string): SetupGithubActionsResult;
+//#endregion
+export { findPackagesWithSkills as a, runAddLibraryBin as c, runEditPackageJsonAll as d, runSetupGithubActions as f, SetupGithubActionsResult as i, runAddLibraryBinAll as l, EditPackageJsonResult as n, findWorkspaceRoot as o, MonorepoResult as r, readWorkspacePatterns as s, AddLibraryBinResult as t, runEditPackageJson as u };