@tanstack/intent 0.0.6 → 0.0.8

package/README.md

@@ -16,10 +16,10 @@ pnpm add -D @tanstack/intent
 
 ### For library consumers
 
-Set up intent discovery in your project's agent config files (CLAUDE.md, .cursorrules, etc.):
+Set up skill-to-task mappings in your project's agent config files (CLAUDE.md, .cursorrules, etc.):
 
 ```bash
-npx intent init
+npx intent install
 ```
 
 List available skills from installed packages:
@@ -50,16 +50,15 @@ npx intent setup
 
 ## CLI Commands
 
-| Command                 | Description                                     |
-| ----------------------- | ----------------------------------------------- |
-| `intent init`           | Inject intent discovery into agent config files |
-| `intent list [--json]`  | Discover intent-enabled packages                |
-| `intent meta`           | List meta-skills for library maintainers        |
-| `intent scaffold`       | Print the guided skill generation prompt        |
-| `intent validate [dir]` | Validate SKILL.md files                         |
-| `intent setup`          | Copy CI workflow templates                      |
-| `intent stale [--json]` | Check skills for version drift                  |
-| `intent feedback`       | Submit skill feedback                           |
+| Command                 | Description                                         |
+| ----------------------- | --------------------------------------------------- |
+| `intent install`        | Set up skill-to-task mappings in agent config files |
+| `intent list [--json]`  | Discover intent-enabled packages                    |
+| `intent meta`           | List meta-skills for library maintainers            |
+| `intent scaffold`       | Print the guided skill generation prompt            |
+| `intent validate [dir]` | Validate SKILL.md files                             |
+| `intent setup`          | Copy CI templates, generate shim, create labels     |
+| `intent stale [--json]` | Check skills for version drift                      |
 
 ## License
 

package/dist/cli.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { n as parseFrontmatter, t as findSkillFiles } from "./utils-DH3jY3CI.mjs";
 import { t as scanForIntents } from "./scanner-OmHt14bs.mjs";
+import { n as printSkillTree, r as printTable, t as computeSkillNameWidth } from "./display-D_XzuGnu.mjs";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
 import { parse } from "yaml";
@@ -10,55 +11,6 @@ import { fileURLToPath } from "node:url";
 function getMetaDir() {
 	return join(dirname(fileURLToPath(import.meta.url)), "..", "meta");
 }
-function padColumn(text, width) {
-	return text.length >= width ? text + "  " : text.padEnd(width);
-}
-function printTable(headers, rows) {
-	const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)) + 2);
-	const headerLine = headers.map((h, i) => padColumn(h, widths[i])).join("");
-	const separator = widths.map((w) => "─".repeat(w)).join("");
-	console.log(headerLine);
-	console.log(separator);
-	for (const row of rows) console.log(row.map((cell, i) => padColumn(cell, widths[i])).join(""));
-}
-function printSkillTree(skills, opts) {
-	const roots = [];
-	const children = /* @__PURE__ */ new Map();
-	for (const skill of skills) {
-		const slashIdx = skill.name.indexOf("/");
-		if (slashIdx === -1) roots.push(skill.name);
-		else {
-			const parent = skill.name.slice(0, slashIdx);
-			if (!children.has(parent)) children.set(parent, []);
-			children.get(parent).push(skill);
-		}
-	}
-	if (roots.length === 0) {
-		for (const skill of skills) if (!roots.includes(skill.name)) roots.push(skill.name);
-	}
-	for (const rootName of roots) {
-		const rootSkill = skills.find((s) => s.name === rootName);
-		if (!rootSkill) continue;
-		printSkillLine(rootName, rootSkill, 4, opts);
-		for (const sub of children.get(rootName) ?? []) printSkillLine(sub.name.slice(sub.name.indexOf("/") + 1), sub, 6, opts);
-	}
-}
-function printSkillLine(displayName, skill, indent, opts) {
-	const nameStr = " ".repeat(indent) + displayName;
-	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}`);
-}
-function computeSkillNameWidth(allPackageSkills) {
-	let max = 0;
-	for (const skills of allPackageSkills) for (const s of skills) {
-		const slashIdx = s.name.indexOf("/");
-		const displayName = slashIdx === -1 ? s.name : s.name.slice(slashIdx + 1);
-		const indent = slashIdx === -1 ? 4 : 6;
-		max = Math.max(max, indent + displayName.length);
-	}
-	return max + 2;
-}
 async function cmdList(args) {
 	const jsonOutput = args.includes("--json");
 	let result;
@@ -106,8 +58,7 @@ async function cmdList(args) {
 	}
 	console.log(`Feedback:`);
 	console.log(`  After completing your task, collect feedback on skill usage.`);
-	console.log(`  Instructions: node_modules/@tanstack/intent/meta/feedback-collection/SKILL.md`);
-	console.log(`  Submit: npx intent feedback --submit --file intent-feedback.json`);
+	console.log(`  Load: node_modules/@tanstack/intent/meta/feedback-collection/SKILL.md`);
 	console.log();
 	if (result.warnings.length > 0) {
 		console.log(`Warnings:`);
@@ -136,6 +87,29 @@ function cmdMeta() {
 	console.log(`\nUsage: load the SKILL.md into your AI agent conversation.`);
 	console.log(`Path: node_modules/@tanstack/intent/meta/<name>/SKILL.md`);
 }
+function collectPackagingWarnings(root) {
+	const pkgJsonPath = join(root, "package.json");
+	if (!existsSync(pkgJsonPath)) return [];
+	let pkgJson;
+	try {
+		pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+	} catch (err) {
+		return [`Could not parse package.json: ${err instanceof Error ? err.message : String(err)}`];
+	}
+	const warnings = [];
+	if (!pkgJson.devDependencies?.["@tanstack/intent"]) warnings.push("@tanstack/intent is not in devDependencies");
+	if (!pkgJson.bin?.intent) warnings.push("Missing \"bin\": { \"intent\": ... } entry in package.json");
+	const shimJs = join(root, "bin", "intent.js");
+	const shimMjs = join(root, "bin", "intent.mjs");
+	if (!existsSync(shimJs) && !existsSync(shimMjs)) warnings.push("No bin/intent.js or bin/intent.mjs shim found (run: npx @tanstack/intent setup --shim)");
+	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 (!files.includes("bin")) warnings.push("\"bin\" is not in the \"files\" array — shim won't be published");
+		if (!files.includes("!skills/_artifacts")) warnings.push("\"!skills/_artifacts\" is not in the \"files\" array — artifacts will be published unnecessarily");
+	}
+	return warnings;
+}
 function cmdValidate(args) {
 	const targetDir = args[0] ?? "skills";
 	const skillsDir = join(process.cwd(), targetDir);
@@ -192,6 +166,10 @@ function cmdValidate(args) {
 				message: `name "${fm.name}" does not match directory path "${expectedPath}"`
 			});
 		}
+		if (typeof fm.description === "string" && fm.description.length > 1024) errors.push({
+			file: rel,
+			message: `Description exceeds 1024 character limit (${fm.description.length} chars)`
+		});
 		if (fm.type === "framework" && !Array.isArray(fm.requires)) errors.push({
 			file: rel,
 			message: "Framework skills must have a \"requires\" field"
@@ -233,67 +211,90 @@ function cmdValidate(args) {
 			});
 		}
 	}
+	const warnings = collectPackagingWarnings(process.cwd());
+	const printWarnings = (log) => {
+		if (warnings.length === 0) return;
+		log(`\n⚠ Packaging warnings:`);
+		for (const w of warnings) log(`  ${w}`);
+	};
 	if (errors.length > 0) {
 		console.error(`\n❌ Validation failed with ${errors.length} error(s):\n`);
 		for (const { file, message } of errors) console.error(`  ${file}: ${message}`);
+		printWarnings(console.error);
 		process.exit(1);
 	}
 	console.log(`✅ Validated ${skillFiles.length} skill files — all passed`);
+	printWarnings(console.log);
 }
 function cmdScaffold() {
-	console.log(`You are an AI assistant helping a library maintainer scaffold Intent skills.
-You MUST use the Intent meta skills in this exact order and follow their output requirements.
-
-Before you start, ask the maintainer:
-1. Skills root path (default: skills/). If custom, replace "skills/" in all paths below.
-2. Is this a monorepo? If yes, you need the following layout:
-   - Domain map artifacts live at the REPO ROOT: _artifacts/domain_map.yaml, _artifacts/skill_spec.md, _artifacts/skill_tree.yaml
-   - Skills live INSIDE EACH PACKAGE: packages/<pkg>/skills/<domain>/<skill>/SKILL.md
-   - Each publishable package needs:
-     a. @tanstack/intent as a devDependency
-     b. A bin entry: "bin": { "intent": "./bin/intent.js" }
-     c. The shim file at bin/intent.js (run npx @tanstack/intent setup --shim in each package)
-     d. "skills" and "bin" in the package.json "files" array, with "!skills/_artifacts" to exclude artifacts
-   - Ask the maintainer which packages should get skills (usually client SDKs and primary framework adapters)
-
-1) Meta skill: domain-discovery
-   - Input: library name, repo URL, docs URL(s), scope constraints, target audience.
-   - Output files:
-     - Single-repo: skills/_artifacts/domain_map.yaml, skills/_artifacts/skill_spec.md
-     - Monorepo: _artifacts/domain_map.yaml, _artifacts/skill_spec.md (at repo root)
-   - Domain discovery covers the WHOLE library. One domain map for the entire monorepo.
-   - These artifacts are maintainer-owned and should be committed to the repo.
-
-2) Meta skill: tree-generator
-   - Input: domain map + skill spec artifacts
-   - Output file: _artifacts/skill_tree.yaml (same location as domain map)
-   - The skill tree must specify which PACKAGE each skill belongs to.
-   - For monorepos, the tree maps skills to packages: each skill entry should include
-     a "package" field (e.g. packages/client, packages/react-client).
-
-3) Meta skill: generate-skill
-   - Input: skill tree
-   - Output files:
-     - Single-repo: skills/<domain>/<skill>/SKILL.md
-     - Monorepo: packages/<pkg>/skills/<domain>/<skill>/SKILL.md
-   - Skills are written into the package they describe, not a shared root.
-
-Guidance for the maintainer:
-- If any input is missing, ask for it.
-- After each step, clearly tell the maintainer what files to create and where to save them.
-- Do not skip steps.
-- Use the library's actual terminology from docs and source.
-
-At the end, produce a single Markdown feedback doc with three sections (Domain Discovery, Tree Generator, Generate Skill).
-Ask if the maintainer wants to edit it, then submit it via: npx @tanstack/intent feedback --meta --submit --file <path>
-
-Finish with a short checklist:
-- Run npx @tanstack/intent validate in each package directory (or for single-repo: at the root)
-- Commit skills/ and artifacts
-- Exclude artifacts from package publishing (add "!skills/_artifacts" to the "files" array in each package.json)
-- For monorepos: ensure each package has @tanstack/intent as devDependency, bin entry, and shim
-- Add README snippet: If you use an AI agent, run npx @tanstack/intent init
-`);
+	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 \`npx @tanstack/intent validate\` in each package directory
+2. Commit skills/ and artifacts
+3. For each publishable package, run: \`npx @tanstack/intent setup --shim\`
+4. Ensure each package has \`@tanstack/intent\` as a devDependency
+5. Add \`"skills"\`, \`"bin"\` to the \`"files"\` array in each package.json
+6. Add \`"!skills/_artifacts"\` to exclude artifacts from publishing
+7. Create a \`feedback:<skill-name>\` label on the GitHub repo for each skill (use \`gh label create\`)
+8. Add a README note: "If you use an AI agent, run \`npx @tanstack/intent install\`"
+`;
+	console.log(prompt);
 }
 const USAGE = `TanStack Intent CLI
 
@@ -301,12 +302,10 @@ Usage:
   intent list [--json]           Discover intent-enabled packages
   intent meta                    List meta-skills for maintainers
   intent validate [<dir>]        Validate skill files (default: skills/)
-  intent init                    Set up intent discovery in agent configs
+  intent install                  Print a skill that guides your coding agent to set up skill-to-task mappings
   intent scaffold                Print maintainer scaffold prompt
-  intent setup [--workflows] [--all]  Copy CI templates into your repo
-  intent stale                   Check skills for staleness
-  intent feedback --submit --file <path>           Submit skill feedback
-  intent feedback --meta --submit --file <path>    Submit meta-skill feedback`;
+  intent setup [--workflows] [--shim] [--all]  Copy CI templates and generate shim
+  intent stale                   Check skills for staleness`;
 const command = process.argv[2];
 const commandArgs = process.argv.slice(3);
 switch (command) {
@@ -319,22 +318,54 @@ switch (command) {
 	case "validate":
 		cmdValidate(commandArgs);
 		break;
-	case "init": {
-		const { runInit, detectAgentConfigs } = await import("./init-BU1ZnUbK.mjs");
-		const initRoot = process.cwd();
-		const result = runInit(initRoot);
-		for (const f of result.injected) console.log(`✓ Added intent block to ${f}`);
-		for (const f of result.skipped) console.log(`  Already present in ${f}`);
-		for (const f of result.created) console.log(`✓ Created ${f}`);
-		if (result.injected.length === 0 && result.skipped.length === 0) {
-			if (detectAgentConfigs(initRoot).length === 0) {
-				console.log("No agent config files found (AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md).");
-				console.log("Create one of these files and run intent init again.");
-			}
-		}
-		console.log(`✓ Config: ${result.configPath}`);
+	case "install":
+		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`);
 		break;
-	}
 	case "scaffold":
 		cmdScaffold();
 		break;
@@ -371,11 +402,6 @@ switch (command) {
 		}
 		break;
 	}
-	case "feedback": {
-		const { runFeedback } = await import("./feedback-PR8JNBfM.mjs");
-		runFeedback(commandArgs);
-		break;
-	}
 	case "setup": {
 		const { runSetup } = await import("./setup.mjs");
 		runSetup(process.cwd(), getMetaDir(), commandArgs);

package/dist/display-D_XzuGnu.mjs

@@ -0,0 +1,54 @@
+//#region src/display.ts
+function padColumn(text, width) {
+	return text.length >= width ? text + "  " : text.padEnd(width);
+}
+function printTable(headers, rows) {
+	const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)) + 2);
+	const headerLine = headers.map((h, i) => padColumn(h, widths[i])).join("");
+	const separator = widths.map((w) => "─".repeat(w)).join("");
+	console.log(headerLine);
+	console.log(separator);
+	for (const row of rows) console.log(row.map((cell, i) => padColumn(cell, widths[i])).join(""));
+}
+function printSkillLine(displayName, skill, indent, opts) {
+	const nameStr = " ".repeat(indent) + displayName;
+	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}`);
+}
+function printSkillTree(skills, opts) {
+	const roots = [];
+	const children = /* @__PURE__ */ new Map();
+	for (const skill of skills) {
+		const slashIdx = skill.name.indexOf("/");
+		if (slashIdx === -1) roots.push(skill.name);
+		else {
+			const parent = skill.name.slice(0, slashIdx);
+			if (!children.has(parent)) children.set(parent, []);
+			children.get(parent).push(skill);
+		}
+	}
+	if (roots.length === 0) {
+		for (const skill of skills) if (!roots.includes(skill.name)) roots.push(skill.name);
+	}
+	for (const rootName of roots) {
+		const rootSkill = skills.find((s) => s.name === rootName);
+		if (!rootSkill) continue;
+		printSkillLine(rootName, rootSkill, 4, opts);
+		for (const sub of children.get(rootName) ?? []) printSkillLine(sub.name.slice(sub.name.indexOf("/") + 1), sub, 6, opts);
+	}
+}
+function computeSkillNameWidth(allPackageSkills) {
+	let max = 0;
+	for (const skills of allPackageSkills) for (const s of skills) {
+		const slashIdx = s.name.indexOf("/");
+		const displayName = slashIdx === -1 ? s.name : s.name.slice(slashIdx + 1);
+		const indent = slashIdx === -1 ? 4 : 6;
+		max = Math.max(max, indent + displayName.length);
+	}
+	return max + 2;
+}
+
+//#endregion
+export { printSkillTree as n, printTable as r, computeSkillNameWidth as t };

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-B20LP96b.mjs";
-import { n as runSetup } from "./setup-D2Bwubpw.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-BmnI8kFB.mjs";
+import { n as runSetup } from "./setup-BJ4giTKA.mjs";
 
 //#region src/scanner.d.ts
 declare function scanForIntents(root?: string): Promise<ScanResult>;
@@ -34,20 +34,6 @@ declare function submitMetaFeedback(payload: MetaFeedbackPayload, opts: {
   outputPath?: string;
 }): SubmitResult;
 //#endregion
-//#region src/init.d.ts
-declare function detectAgentConfigs(root: string): string[];
-declare function hasIntentBlock(filePath: string): boolean;
-declare function injectIntentBlock(filePath: string): boolean;
-declare function writeProjectConfig(root: string): string;
-declare function readProjectConfig(root: string): IntentProjectConfig | null;
-interface InitResult {
-  injected: string[];
-  skipped: string[];
-  created: string[];
-  configPath: string;
-}
-declare function runInit(root: string): InitResult;
-//#endregion
 //#region src/utils.d.ts
 /**
  * Recursively find all SKILL.md files under a directory.
@@ -58,4 +44,4 @@ declare function findSkillFiles(dir: string): string[];
  */
 declare function parseFrontmatter(filePath: string): Record<string, unknown> | null;
 //#endregion
-export { type AgentName, type FeedbackPayload, type IntentConfig, type IntentPackage, type IntentProjectConfig, type MetaFeedbackPayload, type MetaSkillName, type ScanResult, type SkillEntry, type SkillStaleness, type StalenessReport, checkStaleness, containsSecrets, detectAgentConfigs, findSkillFiles, hasGhCli, hasIntentBlock, injectIntentBlock, metaToMarkdown, parseFrontmatter, readProjectConfig, resolveFrequency, runInit, runSetup, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload, writeProjectConfig };
+export { type AgentName, type FeedbackPayload, type IntentConfig, type IntentPackage, type IntentProjectConfig, type MetaFeedbackPayload, type MetaSkillName, type ScanResult, type SkillEntry, type SkillStaleness, type StalenessReport, checkStaleness, containsSecrets, findSkillFiles, hasGhCli, metaToMarkdown, parseFrontmatter, resolveFrequency, runSetup, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };