@tanstack/intent 0.0.29 → 0.0.32

package/dist/install-BmVqcbEi.mjs

@@ -0,0 +1,506 @@
+import { i as parseSkillUse, n as formatSkillUse } from "./skill-use-CXOnncWK.mjs";
+import { t as resolveProjectContext } from "./project-context-CKG-q4rD.mjs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { parse } from "yaml";
+import { fileURLToPath } from "node:url";
+
+//#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" && CLI_FAILURE in value;
+}
+
+//#endregion
+//#region src/cli-output.ts
+function printWarnings(warnings) {
+	if (warnings.length === 0) return;
+	console.log("Warnings:");
+	for (const warning of warnings) console.log(`  ⚠ ${warning}`);
+}
+
+//#endregion
+//#region src/cli-support.ts
+function getMetaDir() {
+	return join(dirname(fileURLToPath(import.meta.url)), "..", "meta");
+}
+async function scanIntentsOrFail(options) {
+	const { scanForIntents } = await import("./scanner-CRZITpcY.mjs");
+	try {
+		return scanForIntents(void 0, options);
+	} catch (err) {
+		fail(err instanceof Error ? err.message : String(err));
+	}
+}
+function scanOptionsFromGlobalFlags(options) {
+	if (options.global && options.globalOnly) fail("Use either --global or --global-only, not both.");
+	if (options.globalOnly) return { scope: "global" };
+	if (options.global) return { scope: "local-and-global" };
+	return { scope: "local" };
+}
+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 ? resolve(process.cwd(), targetDir) : process.cwd();
+	const context = resolveProjectContext({
+		cwd: process.cwd(),
+		targetPath: targetDir
+	});
+	const { checkStaleness } = await import("./staleness-NF-lxfXf.mjs");
+	if (context.packageRoot && (context.targetSkillsDir !== null || resolvedRoot !== context.workspaceRoot)) return { reports: [await checkStaleness(context.packageRoot, readPackageName(context.packageRoot))] };
+	if (existsSync(join(resolvedRoot, "skills"))) return { reports: [await checkStaleness(resolvedRoot, readPackageName(resolvedRoot))] };
+	const { findPackagesWithSkills, findWorkspaceRoot } = await import("./workspace-patterns-DbnA0peB.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/install-writer.ts
+const INTENT_SKILLS_START = "<!-- intent-skills:start -->";
+const INTENT_SKILLS_END = "<!-- intent-skills:end -->";
+const SUPPORTED_AGENT_CONFIG_FILES = [
+	"AGENTS.md",
+	"CLAUDE.md",
+	".cursorrules",
+	".github/copilot-instructions.md"
+];
+const NON_ACTIONABLE_SKILL_TYPES = new Set([
+	"maintainer",
+	"maintainer-only",
+	"meta",
+	"reference"
+]);
+function normalizeBlock(content) {
+	return content.replace(/\r\n/g, "\n").trimEnd();
+}
+function readManagedBlock(content) {
+	const start = content.indexOf(INTENT_SKILLS_START);
+	const errors = [];
+	if (start === -1) errors.push("Missing intent-skills start marker.");
+	const endMarkerStart = start === -1 ? content.indexOf(INTENT_SKILLS_END) : content.indexOf(INTENT_SKILLS_END, start);
+	if (endMarkerStart === -1) errors.push("Missing intent-skills end marker.");
+	const hasMarker = start !== -1 || endMarkerStart !== -1;
+	if (errors.length > 0 || start === -1 || endMarkerStart === -1) return {
+		errors,
+		hasMarker,
+		managedBlock: null
+	};
+	const end = endMarkerStart + 26;
+	return {
+		errors,
+		hasMarker,
+		managedBlock: {
+			end,
+			start,
+			text: content.slice(start, end)
+		}
+	};
+}
+function parseSkillsList(block) {
+	const yamlBody = normalizeBlock(block).split("\n").filter((line) => line !== INTENT_SKILLS_START && line !== INTENT_SKILLS_END).join("\n");
+	try {
+		const parsed = parse(yamlBody);
+		if (!parsed || !Array.isArray(parsed.skills)) return {
+			errors: ["Managed block must contain a skills list."],
+			skills: []
+		};
+		return {
+			errors: [],
+			skills: parsed.skills
+		};
+	} catch (err) {
+		return {
+			errors: [`Managed block contains invalid YAML: ${err instanceof Error ? err.message : String(err)}`],
+			skills: []
+		};
+	}
+}
+function verifyIntentSkillsBlockFile({ expectedBlock, expectedMappingCount, targetPath }) {
+	const errors = [];
+	if (!existsSync(targetPath)) return {
+		errors: [`Agent config file was not created: ${targetPath}`],
+		ok: false
+	};
+	const { managedBlock, errors: markerErrors } = readManagedBlock(readFileSync(targetPath, "utf8"));
+	errors.push(...markerErrors);
+	if (!managedBlock) return {
+		errors,
+		ok: false
+	};
+	const block = managedBlock.text;
+	if (normalizeBlock(block) !== normalizeBlock(expectedBlock)) errors.push("Managed block does not match generated mappings.");
+	if (expectedMappingCount === void 0) return {
+		errors,
+		ok: errors.length === 0
+	};
+	const { skills, errors: parseErrors } = parseSkillsList(block);
+	errors.push(...parseErrors);
+	if (skills.length !== expectedMappingCount) errors.push(`Expected ${expectedMappingCount} skill mappings, found ${skills.length}.`);
+	for (const skill of skills) {
+		if (!skill || typeof skill !== "object") {
+			errors.push("Each skill mapping must be an object.");
+			continue;
+		}
+		const mapping = skill;
+		if (mapping.load !== void 0) errors.push("Skill mappings must use compact `use` entries, not `load`.");
+		if (typeof mapping.when !== "string" || mapping.when.trim() === "") errors.push("Each skill mapping must include a non-empty `when` field.");
+		if (typeof mapping.use !== "string") errors.push("Each skill mapping must include a `use` field.");
+		else try {
+			parseSkillUse(mapping.use);
+		} catch (err) {
+			errors.push(err instanceof Error ? err.message : String(err));
+		}
+	}
+	return {
+		errors,
+		ok: errors.length === 0
+	};
+}
+function resolveIntentSkillsBlockTargetPath(root, mappingCount) {
+	if (mappingCount === 0) return null;
+	return findExistingConfigWithManagedBlock(root)?.filePath ?? join(root, "AGENTS.md");
+}
+function compareNames(a, b) {
+	return a.name.localeCompare(b.name);
+}
+function quoteYamlString(value) {
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t")}"`;
+}
+function isActionableSkill(skill) {
+	const type = skill.type?.trim().toLowerCase();
+	return !type || !NON_ACTIONABLE_SKILL_TYPES.has(type);
+}
+function formatWhen(packageName, skill) {
+	return skill.description.replace(/\s+/g, " ").trim() || `Use ${packageName} ${skill.name}`;
+}
+function buildIntentSkillsBlock(scanResult) {
+	const lines = [
+		INTENT_SKILLS_START,
+		"# Skill mappings - load `use` with `npx @tanstack/intent@latest load <use>`.",
+		"skills:"
+	];
+	let mappingCount = 0;
+	for (const pkg of [...scanResult.packages].sort(compareNames)) for (const skill of [...pkg.skills].sort(compareNames)) {
+		if (!isActionableSkill(skill)) continue;
+		mappingCount++;
+		lines.push(`  - when: ${quoteYamlString(formatWhen(pkg.name, skill))}`);
+		lines.push(`    use: ${quoteYamlString(formatSkillUse(pkg.name, skill.name))}`);
+	}
+	if (mappingCount === 0) lines[2] = "skills: []";
+	lines.push(INTENT_SKILLS_END);
+	return {
+		block: `${lines.join("\n")}\n`,
+		mappingCount
+	};
+}
+function buildIntentSkillGuidanceBlock() {
+	return {
+		block: `${[
+			INTENT_SKILLS_START,
+			"## Skill Loading",
+			"",
+			"Before substantial work:",
+			"- Skill check: run `npx @tanstack/intent@latest list`, or use skills already listed in context.",
+			"- Skill guidance: if one local skill clearly matches the task, run `npx @tanstack/intent@latest load <package>#<skill>` and follow the returned `SKILL.md`.",
+			"- Monorepos: when working across packages, run the skill check from the workspace root and prefer the local skill for the package being changed.",
+			"- Multiple matches: prefer the most specific local skill for the package or concern you are changing; load additional skills only when the task spans multiple packages or concerns.",
+			INTENT_SKILLS_END
+		].join("\n")}\n`,
+		mappingCount: 0
+	};
+}
+function detectNewline(content) {
+	return content.includes("\r\n") ? "\r\n" : "\n";
+}
+function withNewlineStyle(content, newline) {
+	return newline === "\n" ? content : content.replace(/\n/g, newline);
+}
+function findExistingConfigWithManagedBlock(root) {
+	for (const file of SUPPORTED_AGENT_CONFIG_FILES) {
+		const filePath = join(root, file);
+		if (!existsSync(filePath)) continue;
+		const content = readFileSync(filePath, "utf8");
+		const { managedBlock, errors, hasMarker } = readManagedBlock(content);
+		if (managedBlock) return {
+			content,
+			filePath,
+			managedBlock
+		};
+		if (hasMarker) throw new Error(`Invalid intent-skills block in ${filePath}: ${errors.join(" ")}`);
+	}
+	return null;
+}
+function replaceManagedBlock(content, managedBlock, block) {
+	const newline = detectNewline(content);
+	const styledBlock = withNewlineStyle(block.trimEnd(), newline);
+	return `${content.slice(0, managedBlock.start)}${styledBlock}${content.slice(managedBlock.end)}`;
+}
+function writeIntentSkillsBlock({ block, mappingCount, root, skipWhenEmpty = true }) {
+	if (mappingCount === 0 && skipWhenEmpty) return {
+		mappingCount,
+		status: "skipped",
+		targetPath: null
+	};
+	const existingTarget = findExistingConfigWithManagedBlock(root);
+	const targetPath = existingTarget?.filePath ?? join(root, "AGENTS.md");
+	if (existingTarget) {
+		const nextContent = replaceManagedBlock(existingTarget.content, existingTarget.managedBlock, block);
+		if (nextContent === existingTarget.content) return {
+			mappingCount,
+			status: "unchanged",
+			targetPath
+		};
+		writeFileSync(targetPath, nextContent);
+		return {
+			mappingCount,
+			status: "updated",
+			targetPath
+		};
+	}
+	if (existsSync(targetPath)) {
+		const currentContent = readFileSync(targetPath, "utf8");
+		const newline = detectNewline(currentContent);
+		const separator = currentContent === "" ? "" : newline;
+		writeFileSync(targetPath, `${withNewlineStyle(block, newline)}${separator}${currentContent}`);
+		return {
+			mappingCount,
+			status: "updated",
+			targetPath
+		};
+	}
+	mkdirSync(dirname(targetPath), { recursive: true });
+	writeFileSync(targetPath, block);
+	return {
+		mappingCount,
+		status: "created",
+		targetPath
+	};
+}
+
+//#endregion
+//#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.
+
+Goal: create or update one agent config file with an intent-skills mapping block.
+
+Hard rules:
+- Do not report success until a file was created or updated, or an existing mapping block was confirmed.
+- If skills are discovered and no mapping block exists, create AGENTS.md unless the user asks for another supported config file.
+- If a mapping block already exists in a supported config file, update that file.
+- Preserve all content outside the managed block unchanged.
+- Store compact \`use\` values in the managed block; do not write \`load\` paths.
+- Never write absolute local file paths, node_modules paths, or package-manager-internal paths in the managed block.
+- Verify the target file before your final response.
+
+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 scans project-local node_modules by default and outputs each package and skill's name,
+   description, and source.
+   If the user explicitly wants globally installed skills included, run:
+   \`npx @tanstack/intent@latest list --global\`
+   This works best in Node-compatible environments (npm, pnpm, Bun, or Deno npm interop
+   with node_modules enabled).
+   If no skills are found, do not create a config file. Report: "No intent-enabled skills found."
+
+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.)
+
+   Mapping coverage rule:
+   - Create mappings for all discovered actionable skills.
+   - Do not omit an actionable skill only because the repo does not currently appear to use it.
+   - Do not map reference, meta, maintainer, or maintainer-only skills by default.
+   - Include slash-named sub-skills when no parent mapping exists, or when they describe distinct user tasks.
+   - If the proposed block would exceed 12 mappings, show the full discovered list and ask which packages
+     or skill groups to include before writing.
+   - Add one fallback note telling the agent to run \`npx @tanstack/intent@latest list\` for less common local skills.
+
+   Based on the repository scan and the coverage rule, propose the 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.
+   - Do not stop after discovery. If skills were found, the task is incomplete until this file exists
+     and contains the managed block.
+
+   Use this exact block:
+
+<!-- intent-skills:start -->
+# Skill mappings - load \`use\` with \`npx @tanstack/intent@latest load <use>\`.
+skills:
+  - when: "describe the task or code area here"
+    use: "@scope/package#skill-name"
+<!-- intent-skills:end -->
+
+   Rules:
+   - Use the user's own words for \`when\` descriptions
+   - Use compact \`use\` values in \`<package>#<skill>\` format
+   - Do not include \`load\`
+   - Do not include machine-specific directories such as \`/Users/...\`, \`/home/...\`, \`/private/...\`,
+     drive letters, temp workspace paths, \`.pnpm/\`, \`.bun/\`, or \`.yarn/\`.
+   - Agents should load \`use\` at runtime with \`npx @tanstack/intent@latest load <use>\`
+   - 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
+
+5. VERIFY AND REPORT
+   Before reporting completion:
+   - Confirm the target file exists
+   - Confirm it contains both managed block markers
+   - Confirm every mapping has \`when\` and \`use\`
+   - Confirm every \`use\` parses as \`<package>#<skill>\`
+   - Confirm no mapping includes \`load\`
+   - Confirm no path-like machine-specific values are stored in the managed block
+   - Confirm every discovered actionable skill is mapped, skipped by rule, or deferred by user choice
+
+   Final response must include:
+   - The target file path
+   - Whether it was created, updated, or already contained a valid block
+   - The number of mappings
+   - The verification result`;
+function formatTargetPath(targetPath) {
+	return relative(process.cwd(), targetPath) || targetPath;
+}
+function formatMappingCount(mappingCount) {
+	return `${mappingCount} ${mappingCount === 1 ? "mapping" : "mappings"}`;
+}
+function printNoActionableSkills(warnings) {
+	console.log("No intent-enabled skills found.");
+	printWarnings(warnings);
+}
+function printPlacementTip(targetPath) {
+	console.log(`Tip: Keep the intent-skills block near the top of ${formatTargetPath(targetPath)} so agents read it before task-specific instructions.`);
+}
+function printWriteResult({ mappingCount, status, targetPath }) {
+	const target = formatTargetPath(targetPath);
+	if (mappingCount === 0) {
+		switch (status) {
+			case "created":
+				console.log(`Created ${target} with skill loading guidance.`);
+				break;
+			case "updated":
+				console.log(`Updated ${target} with skill loading guidance.`);
+				break;
+			case "unchanged":
+				console.log(`No changes to ${target}; skill loading guidance already current.`);
+				break;
+		}
+		return;
+	}
+	switch (status) {
+		case "created":
+			console.log(`Created ${target} with ${formatMappingCount(mappingCount)}.`);
+			break;
+		case "updated":
+			console.log(`Updated ${target} with ${formatMappingCount(mappingCount)}.`);
+			break;
+		case "unchanged":
+			console.log(`No changes to ${target}; ${formatMappingCount(mappingCount)} already current.`);
+			break;
+	}
+}
+async function runInstallCommand(options, scanIntentsOrFail$1) {
+	if (options.printPrompt) {
+		console.log(INSTALL_PROMPT);
+		return;
+	}
+	scanOptionsFromGlobalFlags(options);
+	if (!options.map) {
+		const generated$1 = buildIntentSkillGuidanceBlock();
+		if (options.dryRun) {
+			const targetPath = resolveIntentSkillsBlockTargetPath(process.cwd(), 1);
+			console.log(`Generated skill loading guidance for ${formatTargetPath(targetPath)}.`);
+			console.log(generated$1.block);
+			return;
+		}
+		const result$1 = writeIntentSkillsBlock({
+			...generated$1,
+			root: process.cwd(),
+			skipWhenEmpty: false
+		});
+		if (!result$1.targetPath) fail("Install guidance target was not created.");
+		const verification$1 = verifyIntentSkillsBlockFile({
+			expectedBlock: generated$1.block,
+			targetPath: result$1.targetPath
+		});
+		const target$1 = formatTargetPath(result$1.targetPath);
+		if (!verification$1.ok) fail([`Install verification failed for ${target$1}:`, ...verification$1.errors.map((error) => `- ${error}`)].join("\n"));
+		printWriteResult(result$1);
+		printPlacementTip(result$1.targetPath);
+		return;
+	}
+	const scanResult = await scanIntentsOrFail$1(scanOptionsFromGlobalFlags(options));
+	const generated = buildIntentSkillsBlock(scanResult);
+	if (options.dryRun) {
+		const targetPath = resolveIntentSkillsBlockTargetPath(process.cwd(), generated.mappingCount);
+		if (!targetPath) {
+			printNoActionableSkills(scanResult.warnings);
+			return;
+		}
+		console.log(`Generated ${formatMappingCount(generated.mappingCount)} for ${formatTargetPath(targetPath)}.`);
+		console.log(generated.block);
+		printWarnings(scanResult.warnings);
+		return;
+	}
+	const result = writeIntentSkillsBlock({
+		...generated,
+		root: process.cwd()
+	});
+	if (!result.targetPath) {
+		printNoActionableSkills(scanResult.warnings);
+		return;
+	}
+	const target = formatTargetPath(result.targetPath);
+	const verification = verifyIntentSkillsBlockFile({
+		expectedBlock: generated.block,
+		expectedMappingCount: generated.mappingCount,
+		targetPath: result.targetPath
+	});
+	if (!verification.ok) fail([`Install verification failed for ${target}:`, ...verification.errors.map((error) => `- ${error}`)].join("\n"));
+	printWriteResult(result);
+	printPlacementTip(result.targetPath);
+	printWarnings(scanResult.warnings);
+}
+
+//#endregion
+export { scanIntentsOrFail as a, fail as c, resolveStaleTargets as i, isCliFailure as l, runInstallCommand as n, scanOptionsFromGlobalFlags as o, getMetaDir as r, printWarnings as s, INSTALL_PROMPT as t };

package/dist/intent-library.mjs

@@ -1,14 +1,17 @@
 #!/usr/bin/env node
 import "./utils-COlDcU72.mjs";
-import { t as INSTALL_PROMPT } from "./install-BzDmD5yI.mjs";
-import { n as printSkillTree, r as printTable, t as computeSkillNameWidth } from "./display-hdsqb4w-.mjs";
-import { t as scanLibrary } from "./library-scanner-B51qV5aX.mjs";
+import "./skill-paths-8k9K9y26.mjs";
+import "./workspace-patterns-U35B5AO-.mjs";
+import "./project-context-CKG-q4rD.mjs";
+import { t as INSTALL_PROMPT } from "./install-BmVqcbEi.mjs";
+import { n as printSkillTree, r as printTable, t as computeSkillNameWidth } from "./display-DUgtRJkt.mjs";
+import { t as scanLibrary } from "./library-scanner-DFFreLjW.mjs";
 
 //#region src/intent-library.ts
 function cmdList() {
 	let result;
 	try {
-		result = scanLibrary(process.argv[1]);
+		result = scanLibrary(process.argv[1], process.cwd());
 	} catch (err) {
 		console.error(err.message);
 		process.exit(1);
@@ -39,6 +42,7 @@ function cmdList() {
 		console.log(`  ${pkg.name}`);
 		printSkillTree(pkg.skills, {
 			nameWidth,
+			packageName: pkg.name,
 			showTypes
 		});
 		console.log();
@@ -60,7 +64,7 @@ const USAGE = `TanStack Intent
 Usage:
   intent list        List all available skills from this library and its dependencies
   intent install     Print a skill that guides your coding agent to scan the project
-                     and set up skill-to-task mappings in your agent config`;
+                     and set up skill loading guidance in your agent config`;
 const command = process.argv[2];
 switch (command) {
 	case "list":

package/dist/{library-scanner-B51qV5aX.mjs → library-scanner-DFFreLjW.mjs}

@@ -1,4 +1,5 @@
 import { a as parseFrontmatter, o as resolveDepDir, r as getDeps, s as toPosixPath } from "./utils-COlDcU72.mjs";
+import { r as rewriteSkillLoadPaths } from "./skill-paths-8k9K9y26.mjs";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 
@@ -52,14 +53,14 @@ function discoverSkills(skillsDir) {
 					type: typeof fm?.type === "string" ? fm.type : void 0,
 					framework: typeof fm?.framework === "string" ? fm.framework : void 0
 				});
-				walk(childDir);
 			}
+			walk(childDir);
 		}
 	}
 	walk(skillsDir);
 	return skills;
 }
-function scanLibrary(scriptPath, _projectRoot) {
+function scanLibrary(scriptPath, projectRoot) {
 	const packages = [];
 	const warnings = [];
 	const visited = /* @__PURE__ */ new Set();
@@ -74,6 +75,7 @@ function scanLibrary(scriptPath, _projectRoot) {
 		warnings: ["Could not read home package.json"]
 	};
 	const homeName = typeof homePkg.name === "string" ? homePkg.name : "";
+	const scanRoot = projectRoot ?? homeDir;
 	function processPackage(name, dir) {
 		if (visited.has(name)) return;
 		visited.add(name);
@@ -84,7 +86,12 @@ function scanLibrary(scriptPath, _projectRoot) {
 		}
 		const skillsDir = join(dir, "skills");
 		const skills = existsSync(skillsDir) ? discoverSkills(skillsDir) : [];
-		if (name) for (const skill of skills) skill.path = `node_modules/${name}/${toPosixPath(relative(dir, skill.path))}`;
+		rewriteSkillLoadPaths({
+			packageName: name,
+			packageRoot: dir,
+			projectRoot: scanRoot,
+			skills
+		});
 		packages.push({
 			name,
 			version: typeof pkg.version === "string" ? pkg.version : "0.0.0",

package/dist/library-scanner.d.mts

@@ -1,4 +1,4 @@
-import { l as SkillEntry } from "./types-BTQ9efv-.mjs";
+import { u as SkillEntry } from "./types-CsySN6Vw.mjs";
 
 //#region src/library-scanner.d.ts
 interface LibraryPackage {
@@ -11,6 +11,6 @@ interface LibraryScanResult {
   packages: Array<LibraryPackage>;
   warnings: Array<string>;
 }
-declare function scanLibrary(scriptPath: string, _projectRoot?: string): LibraryScanResult;
+declare function scanLibrary(scriptPath: string, projectRoot?: string): LibraryScanResult;
 //#endregion
 export { LibraryPackage, LibraryScanResult, scanLibrary };

package/dist/library-scanner.mjs

@@ -1,4 +1,5 @@
 import "./utils-COlDcU72.mjs";
-import { t as scanLibrary } from "./library-scanner-B51qV5aX.mjs";
+import "./skill-paths-8k9K9y26.mjs";
+import { t as scanLibrary } from "./library-scanner-DFFreLjW.mjs";
 
 export { scanLibrary };

package/dist/{project-context-D6A5sBBO.mjs → project-context-CKG-q4rD.mjs}

@@ -1,4 +1,4 @@
-import { n as findWorkspaceRoot, r as readWorkspacePatterns } from "./workspace-patterns-Cndd-7vB.mjs";
+import { n as findWorkspaceRoot, r as readWorkspacePatterns } from "./workspace-patterns-U35B5AO-.mjs";
 import { existsSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 

package/dist/resolver-aFigTqXi.mjs

@@ -0,0 +1,70 @@
+import { i as parseSkillUse } from "./skill-use-CXOnncWK.mjs";
+
+//#region src/resolver.ts
+var ResolveSkillUseError = class extends Error {
+	constructor({ availablePackages = [], availableSkills = [], code, packageName, skillName, use }) {
+		super(formatResolveSkillUseErrorMessage({
+			availablePackages,
+			availableSkills,
+			code,
+			packageName,
+			skillName,
+			use
+		}));
+		this.name = "ResolveSkillUseError";
+		this.availablePackages = availablePackages;
+		this.availableSkills = availableSkills;
+		this.code = code;
+		this.packageName = packageName;
+		this.skillName = skillName;
+		this.use = use;
+	}
+};
+function isResolveSkillUseError(error) {
+	return error instanceof ResolveSkillUseError;
+}
+function resolveSkillUse(use, scanResult) {
+	const { packageName, skillName } = parseSkillUse(use);
+	const packages = scanResult.packages.filter((pkg$1) => pkg$1.name === packageName);
+	const pkg = packages.find((candidate) => candidate.source === "local") ?? packages[0];
+	if (!pkg) throw new ResolveSkillUseError({
+		availablePackages: scanResult.packages.map((candidate) => candidate.name),
+		code: "package-not-found",
+		packageName,
+		skillName,
+		use
+	});
+	const skill = pkg.skills.find((candidate) => candidate.name === skillName);
+	if (!skill) throw new ResolveSkillUseError({
+		availableSkills: pkg.skills.map((candidate) => candidate.name),
+		code: "skill-not-found",
+		packageName,
+		skillName,
+		use
+	});
+	const conflict = scanResult.conflicts.find((candidate) => candidate.packageName === packageName) ?? null;
+	return {
+		packageName,
+		skillName,
+		path: skill.path,
+		source: pkg.source,
+		version: pkg.version,
+		packageRoot: pkg.packageRoot,
+		warnings: scanResult.warnings.filter((warning) => {
+			const idx = warning.indexOf(packageName);
+			if (idx === -1) return false;
+			const after = warning[idx + packageName.length];
+			return after === void 0 || /[^a-zA-Z0-9_-]/.test(after);
+		}),
+		conflict
+	};
+}
+function formatResolveSkillUseErrorMessage({ availablePackages, availableSkills, code, packageName, skillName, use }) {
+	switch (code) {
+		case "package-not-found": return `Cannot resolve skill use "${use}": package "${packageName}" was not found.${availablePackages.length > 0 ? ` Available packages: ${availablePackages.join(", ")}.` : ""}`;
+		case "skill-not-found": return `Cannot resolve skill use "${use}": skill "${skillName}" was not found in package "${packageName}".${availableSkills.length > 0 ? ` Available skills: ${availableSkills.join(", ")}.` : ""}`;
+	}
+}
+
+//#endregion
+export { isResolveSkillUseError as n, resolveSkillUse as r, ResolveSkillUseError as t };