@tanstack/intent 0.0.29 → 0.0.32

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -34,20 +34,32 @@ If you use Deno, support is best-effort today via `npm:` interop with `node_modu
 
 ### For library consumers
 
-Set up skill-to-task mappings in your project's agent config files (CLAUDE.md, .cursorrules, etc.):
+Set up skill loading guidance in your project's agent config files (CLAUDE.md, .cursorrules, etc.):
 
 ```bash
 npx @tanstack/intent@latest install
 ```
 
-No per-library setup. No hunting for rules files. Install the package, run `npx @tanstack/intent@latest install` through your preferred command runner, and the agent understands the tool. Update the package, and skills update too.
+No per-library setup. No hunting for rules files. Install the package, run `npx @tanstack/intent@latest install` through your preferred command runner, and Intent writes guidance that tells your agent to discover and load matching package skills. Update the package, and skills update too. Pass `--map` if you want explicit task-to-skill mappings in your agent config.
 
-List available skills from installed packages:
+List available skills from local installed packages:
 
 ```bash
 npx @tanstack/intent@latest list
 ```
 
+Include global packages explicitly:
+
+```bash
+npx @tanstack/intent@latest list --global
+```
+
+Load an installed skill:
+
+```bash
+npx @tanstack/intent@latest load @tanstack/query#fetching
+```
+
 ### For library maintainers
 
 Generate skills for your library by telling your AI coding agent to run:
@@ -111,8 +123,9 @@ The feedback loop runs both directions. `npx @tanstack/intent@latest feedback` l
 
 | Command                                            | Description                                         |
 | -------------------------------------------------- | --------------------------------------------------- |
-| `npx @tanstack/intent@latest install`              | Set up skill-to-task mappings in agent config files |
-| `npx @tanstack/intent@latest list [--json]`        | Discover intent-enabled packages                    |
+| `npx @tanstack/intent@latest install`              | Set up skill loading guidance in agent config files |
+| `npx @tanstack/intent@latest list [--json]`        | Discover local intent-enabled packages              |
+| `npx @tanstack/intent@latest load <use>`           | Load `<package>#<skill>` SKILL.md content           |
 | `npx @tanstack/intent@latest meta`                 | List meta-skills for library maintainers            |
 | `npx @tanstack/intent@latest scaffold`             | Print the guided skill generation prompt            |
 | `npx @tanstack/intent@latest validate [dir]`       | Validate SKILL.md files                             |

package/dist/cli.mjs

@@ -1,72 +1,15 @@
 #!/usr/bin/env node
 import "./utils-COlDcU72.mjs";
-import "./workspace-patterns-Cndd-7vB.mjs";
-import { t as resolveProjectContext } from "./project-context-D6A5sBBO.mjs";
-import { n as runInstallCommand } from "./install-BzDmD5yI.mjs";
+import "./workspace-patterns-U35B5AO-.mjs";
+import { i as parseSkillUse } from "./skill-use-CXOnncWK.mjs";
+import { r as resolveSkillUse } from "./resolver-aFigTqXi.mjs";
+import { t as resolveProjectContext } from "./project-context-CKG-q4rD.mjs";
+import { a as scanIntentsOrFail, c as fail, i as resolveStaleTargets, l as isCliFailure, n as runInstallCommand, o as scanOptionsFromGlobalFlags, r as getMetaDir, s as printWarnings } from "./install-BmVqcbEi.mjs";
 import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { cac } from "cac";
 
-//#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-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-CP4U8F_n.mjs");
-	try {
-		return scanForIntents();
-	} catch (err) {
-		fail(err instanceof Error ? err.message : String(err));
-	}
-}
-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-LRbiWWZK.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-D_y6rlqX.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");
@@ -95,12 +38,12 @@ function printVersionConflicts(result) {
 	}
 }
 async function runListCommand(options, scanIntentsOrFail$1) {
-	const { computeSkillNameWidth, printSkillTree, printTable } = await import("./display-DdmZXLZm.mjs");
-	const result = await scanIntentsOrFail$1();
+	const result = await scanIntentsOrFail$1(scanOptionsFromGlobalFlags(options));
 	if (options.json) {
 		console.log(JSON.stringify(result, null, 2));
 		return;
 	}
+	const { computeSkillNameWidth, printSkillTree, printTable } = await import("./display-DCRCp4-C.mjs");
 	const scanCoverage = formatScanCoverage(result);
 	if (result.packages.length === 0) {
 		console.log("No intent-enabled packages found.");
@@ -116,11 +59,13 @@ async function runListCommand(options, scanIntentsOrFail$1) {
 	if (scanCoverage) console.log(`Scanned: ${scanCoverage}${result.nodeModules.global.scanned ? " (local packages take precedence)" : ""}\n`);
 	printTable([
 		"PACKAGE",
+		"SOURCE",
 		"VERSION",
 		"SKILLS",
 		"REQUIRES"
 	], result.packages.map((pkg) => [
 		pkg.name,
+		pkg.source,
 		pkg.version,
 		String(pkg.skills.length),
 		pkg.intent.requires?.join(", ") || "–"
@@ -133,6 +78,7 @@ async function runListCommand(options, scanIntentsOrFail$1) {
 		console.log(`  ${pkg.name}`);
 		printSkillTree(pkg.skills, {
 			nameWidth,
+			packageName: pkg.name,
 			showTypes
 		});
 		console.log();
@@ -144,6 +90,46 @@ async function runListCommand(options, scanIntentsOrFail$1) {
 	printWarnings(result.warnings);
 }
 
+//#endregion
+//#region src/commands/load.ts
+function resolveFromCwd(path) {
+	return resolve(process.cwd(), path);
+}
+function isPathInsidePackageRoot(path, packageRoot) {
+	const relativePath = relative(resolveFromCwd(packageRoot), resolveFromCwd(path));
+	return relativePath === "" || !relativePath.startsWith("..") && !isAbsolute(relativePath);
+}
+async function runLoadCommand(use, options, scanIntentsOrFail$1) {
+	if (!use) fail("Missing skill use. Expected: intent load <package>#<skill>");
+	if (options.json && options.path) fail("Use either --json or --path, not both.");
+	parseSkillUse(use);
+	const resolved = resolveSkillUse(use, await scanIntentsOrFail$1(scanOptionsFromGlobalFlags(options)));
+	const resolvedPath = resolveFromCwd(resolved.path);
+	if (!isPathInsidePackageRoot(resolved.path, resolved.packageRoot)) fail(`Resolved skill path for "${use}" is outside package root: ${resolved.path}`);
+	if (!existsSync(resolvedPath)) fail(`Resolved skill file was not found: ${resolved.path}`);
+	if (options.path) {
+		console.log(resolved.path);
+		for (const warning of resolved.warnings) console.error(`Warning: ${warning}`);
+		return;
+	}
+	const content = readFileSync(resolvedPath, "utf8");
+	if (options.json) {
+		console.log(JSON.stringify({
+			package: resolved.packageName,
+			skill: resolved.skillName,
+			path: resolved.path,
+			packageRoot: resolved.packageRoot,
+			source: resolved.source,
+			version: resolved.version,
+			content,
+			warnings: resolved.warnings
+		}, null, 2));
+		return;
+	}
+	process.stdout.write(content);
+	for (const warning of resolved.warnings) console.error(`Warning: ${warning}`);
+}
+
 //#endregion
 //#region src/commands/meta.ts
 async function runMetaCommand(name, metaDir) {
@@ -260,14 +246,14 @@ async function runSetupGithubActionsCommand(root, metaDir) {
 //#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;
 	}
+	if (reports.length === 0) {
+		console.log("No intent-enabled packages found.");
+		return;
+	}
 	for (const report of reports) {
 		const driftLabel = report.versionDrift ? ` [${report.versionDrift} drift]` : "";
 		const vLabel = report.skillVersion && report.currentVersion ? ` (${report.skillVersion} → ${report.currentVersion})` : "";
@@ -429,22 +415,25 @@ async function runValidateCommand(dir) {
 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) => {
+	cli.command("list", "Discover intent-enabled packages from the project or workspace").usage("list [--json] [--global] [--global-only]").option("--json", "Output JSON").option("--global", "Include global packages after project packages").option("--global-only", "List global packages only").example("list").example("list --json").example("list --global").action(async (options) => {
 		await runListCommand(options, scanIntentsOrFail);
 	});
+	cli.command("load [use]", "Load a compact skill use and print its SKILL.md").usage("load <use> [--path] [--json] [--global] [--global-only]").option("--path", "Print the resolved skill path instead of file content").option("--json", "Output JSON").option("--global", "Load from project packages, then global packages").option("--global-only", "Load from global packages only").example("load @tanstack/query#core").example("load @tanstack/query#core --path").action(async (use, options) => {
+		await runLoadCommand(use, 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("install", "Create or update skill loading guidance in an agent config file").usage("install [--map] [--dry-run] [--print-prompt] [--global] [--global-only]").option("--map", "Write explicit skill-to-task mappings").option("--dry-run", "Print the generated block without writing").option("--print-prompt", "Print the legacy agent setup prompt instead of writing").option("--global", "Include global packages after project packages").option("--global-only", "Install mappings from global packages only").example("install").example("install --map").example("install --dry-run").example("install --print-prompt").example("install --global").action(async (options) => {
+		await runInstallCommand(options, scanIntentsOrFail);
 	});
 	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) => {
+	cli.command("stale [dir]", "Check skills for staleness in the current package or workspace").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 () => {

package/dist/display-DCRCp4-C.mjs

@@ -0,0 +1,5 @@
+import "./utils-COlDcU72.mjs";
+import "./skill-paths-8k9K9y26.mjs";
+import { n as printSkillTree, r as printTable, t as computeSkillNameWidth } from "./display-DUgtRJkt.mjs";
+
+export { computeSkillNameWidth, printSkillTree, printTable };

package/dist/{display-hdsqb4w-.mjs → display-DUgtRJkt.mjs}

@@ -1,3 +1,5 @@
+import { n as isStableLoadPath, t as formatRuntimeSkillLookupHint } from "./skill-paths-8k9K9y26.mjs";
+
 //#region src/display.ts
 function padColumn(text, width) {
 	return text.length >= width ? text + "  " : text.padEnd(width);
@@ -15,7 +17,14 @@ function printSkillLine(displayName, skill, indent, opts) {
 	const padding = " ".repeat(Math.max(2, opts.nameWidth - nameStr.length));
 	const typeCol = opts.showTypes ? (skill.type ? `[${skill.type}]` : "").padEnd(14) : "";
 	console.log(`${nameStr}${padding}${typeCol}${skill.description}`);
-	if (skill.path) console.log(`${" ".repeat(indent + 2)}${skill.path}`);
+	if (skill.path) {
+		const pathIndent = " ".repeat(indent + 2);
+		if (isStableLoadPath(skill.path)) console.log(`${pathIndent}${skill.path}`);
+		else console.log(`${pathIndent}${formatRuntimeSkillLookupHint({
+			packageName: opts.packageName,
+			skillName: skill.name
+		})}`);
+	}
 }
 function printSkillTree(skills, opts) {
 	const roots = [];

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-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-BTQ9efv-.mjs";
-import { i as runEditPackageJson, o as runSetupGithubActions, r as SetupGithubActionsResult, t as EditPackageJsonResult } from "./setup-BA9RkENh.mjs";
+import { a as IntentProjectConfig, c as ScanOptions, d as SkillStaleness, f as StalenessReport, i as IntentPackage, l as ScanResult, n as FeedbackPayload, o as MetaFeedbackPayload, p as VersionConflict, r as IntentConfig, s as MetaSkillName, t as AgentName, u as SkillEntry } from "./types-CsySN6Vw.mjs";
+import { i as runEditPackageJson, o as runSetupGithubActions, r as SetupGithubActionsResult, t as EditPackageJsonResult } from "./setup-DDoOLriA.mjs";
 
 //#region src/scanner.d.ts
-declare function scanForIntents(root?: string): ScanResult;
+declare function scanForIntents(root?: string, options?: ScanOptions): ScanResult;
 //#endregion
 //#region src/staleness.d.ts
 declare function checkStaleness(packageDir: string, packageName?: string): Promise<StalenessReport>;
@@ -55,4 +55,57 @@ declare function resolveDepDir(depName: string, parentDir: string): string | nul
  */
 declare function parseFrontmatter(filePath: string): Record<string, unknown> | null;
 //#endregion
-export { type AgentName, type EditPackageJsonResult, type FeedbackPayload, type IntentConfig, type IntentPackage, type IntentProjectConfig, type MetaFeedbackPayload, type MetaSkillName, type ScanResult, type SetupGithubActionsResult, type SkillEntry, type SkillStaleness, type StalenessReport, checkStaleness, containsSecrets, findSkillFiles, getDeps, hasGhCli, metaToMarkdown, parseFrontmatter, resolveDepDir, resolveFrequency, runEditPackageJson, runSetupGithubActions, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };
+//#region src/skill-use.d.ts
+interface SkillUse {
+  packageName: string;
+  skillName: string;
+}
+type SkillUseParseErrorCode = 'missing-separator' | 'empty-package' | 'empty-skill';
+declare class SkillUseParseError extends Error {
+  readonly code: SkillUseParseErrorCode;
+  readonly value: string;
+  constructor(code: SkillUseParseErrorCode, value: string);
+}
+declare function isSkillUseParseError(error: unknown): error is SkillUseParseError;
+declare function formatSkillUse(packageName: string, skillName: string): string;
+declare function parseSkillUse(value: string): SkillUse;
+//#endregion
+//#region src/resolver.d.ts
+interface ResolveSkillResult {
+  packageName: string;
+  skillName: string;
+  path: string;
+  source: IntentPackage['source'];
+  version: string;
+  packageRoot: string;
+  warnings: Array<string>;
+  conflict: VersionConflict | null;
+}
+type ResolveSkillUseErrorCode = 'package-not-found' | 'skill-not-found';
+declare class ResolveSkillUseError extends Error {
+  readonly code: ResolveSkillUseErrorCode;
+  readonly use: string;
+  readonly packageName: string;
+  readonly skillName: string;
+  readonly availablePackages: Array<string>;
+  readonly availableSkills: Array<string>;
+  constructor({
+    availablePackages,
+    availableSkills,
+    code,
+    packageName,
+    skillName,
+    use
+  }: {
+    availablePackages?: Array<string>;
+    availableSkills?: Array<string>;
+    code: ResolveSkillUseErrorCode;
+    packageName: string;
+    skillName: string;
+    use: string;
+  });
+}
+declare function isResolveSkillUseError(error: unknown): error is ResolveSkillUseError;
+declare function resolveSkillUse(use: string, scanResult: ScanResult): ResolveSkillResult;
+//#endregion
+export { type AgentName, type EditPackageJsonResult, type FeedbackPayload, type IntentConfig, type IntentPackage, type IntentProjectConfig, type MetaFeedbackPayload, type MetaSkillName, type ResolveSkillResult, ResolveSkillUseError, type ResolveSkillUseErrorCode, type ScanOptions, type ScanResult, type SetupGithubActionsResult, type SkillEntry, type SkillStaleness, type SkillUse, SkillUseParseError, type SkillUseParseErrorCode, type StalenessReport, checkStaleness, containsSecrets, findSkillFiles, formatSkillUse, getDeps, hasGhCli, isResolveSkillUseError, isSkillUseParseError, metaToMarkdown, parseFrontmatter, parseSkillUse, resolveDepDir, resolveFrequency, resolveSkillUse, runEditPackageJson, runSetupGithubActions, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };

package/dist/index.mjs

@@ -1,9 +1,12 @@
 import { a as parseFrontmatter, n as findSkillFiles, o as resolveDepDir, r as getDeps } from "./utils-COlDcU72.mjs";
-import "./workspace-patterns-Cndd-7vB.mjs";
-import { t as scanForIntents } from "./scanner-B-bbXBLY.mjs";
-import { t as checkStaleness } from "./staleness-SY7-mZMH.mjs";
-import "./project-context-D6A5sBBO.mjs";
-import { r as runSetupGithubActions, t as runEditPackageJson } from "./setup-B4ZwN5Hg.mjs";
+import "./skill-paths-8k9K9y26.mjs";
+import { t as scanForIntents } from "./scanner-DKL8v8is.mjs";
+import "./workspace-patterns-U35B5AO-.mjs";
+import { t as checkStaleness } from "./staleness-DorwfGrf.mjs";
+import { i as parseSkillUse, n as formatSkillUse, r as isSkillUseParseError, t as SkillUseParseError } from "./skill-use-CXOnncWK.mjs";
+import { n as isResolveSkillUseError, r as resolveSkillUse, t as ResolveSkillUseError } from "./resolver-aFigTqXi.mjs";
+import "./project-context-CKG-q4rD.mjs";
+import { r as runSetupGithubActions, t as runEditPackageJson } from "./setup-JJvjiGkM.mjs";
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { execFileSync, execSync } from "node:child_process";
@@ -271,4 +274,4 @@ function submitMetaFeedback(payload, opts) {
 }
 
 //#endregion
-export { checkStaleness, containsSecrets, findSkillFiles, getDeps, hasGhCli, metaToMarkdown, parseFrontmatter, resolveDepDir, resolveFrequency, runEditPackageJson, runSetupGithubActions, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };
+export { ResolveSkillUseError, SkillUseParseError, checkStaleness, containsSecrets, findSkillFiles, formatSkillUse, getDeps, hasGhCli, isResolveSkillUseError, isSkillUseParseError, metaToMarkdown, parseFrontmatter, parseSkillUse, resolveDepDir, resolveFrequency, resolveSkillUse, runEditPackageJson, runSetupGithubActions, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };