feat: add dependency-walked discovery and source-aware package reporting (#112)

LadyBluenotes · autofix-ci[bot] · KyleAMathews · web-flow · commit 36e696beb80f · 2026-04-13T09:30:28.000-07:00
* feat: enhance scanForIntents to include global packages

* fix: update scanForIntents calls to toggle global package inclusion

* feat: modify scanIntentsOrFail to accept options for global package inclusion

* feat: add source attribute to package registration for local and global distinction

* test: verify package source distinction between local and global

* feat: refactor package registration logic into createPackageRegistrar

* feat: implement dependency walker to streamline transitive dependency discovery

* feat: reorder report check and enhance global package handling in CLI tests

* feat: consolidate discovery exports into a single index file

* refactor: remove unused walkDeps function from walk.ts

* update some docs

* update some docs

* update some docs

* ci: apply automated fixes

* fix tests

* Apply code simplification and review fixes

- Simplify walk.ts/register.ts (extract helpers, unify walkDeps variants)
- Restore ENOENT-discriminated warnings for malformed root/workspace
  package.json (prevents silent failures when config is corrupt)
- Tighten CreateDependencyWalkerOptions.packages to IntentPackage[] to
  make shared mutable state between registrar and walker explicit
- Add coverage for local-over-global precedence in list --json and for
  stale scoping to local packages when globals are configured

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;

* Add changeset for discovery-engine

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: autofix-ci[bot] &lt;114827586+autofix-ci[bot]@users.noreply.github.com&gt;
Co-authored-by: Kyle Mathews &lt;mathews.kyle@gmail.com&gt;
Co-authored-by: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.changeset/discovery-engine.md b/.changeset/discovery-engine.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/intent': patch
+---
+
+Refactor package discovery into a dedicated registrar and dependency walker so project, workspace, and transitive dependencies are scanned consistently. Track local vs. global package sources and surface that in `intent list` via a `SOURCE` column. `intent stale` is now scoped to local and workspace packages; global packages are only included by `intent list` (which explicitly opts in). A new `scanForIntents` option `includeGlobal` controls global scanning for programmatic callers — this replaces the previous implicit behavior where setting `INTENT_GLOBAL_NODE_MODULES` caused all commands to scan globals.
diff --git a/docs/cli/intent-install.md b/docs/cli/intent-install.md
@@ -24,14 +24,14 @@ skills:
 <!-- intent-skills:end -->
 ```
 
-They also ask you to:
-
-1. Check for an existing block first
-2. Run `intent list` to discover installed skills
-3. Ask whether you want a config target other than `AGENTS.md`
-4. Update an existing block in place when one already exists
-5. Add task-to-skill mappings
-6. Preserve all content outside the tagged block
+They also ask you to:
+
+1. Check for an existing block first
+2. Run `intent list` to discover installed skills, including any packages surfaced by the command's explicit global scan
+3. Ask whether you want a config target other than `AGENTS.md`
+4. Update an existing block in place when one already exists
+5. Add task-to-skill mappings
+6. Preserve all content outside the tagged block
 
 If no existing block is found, `AGENTS.md` is the default target.
 
diff --git a/docs/cli/intent-list.md b/docs/cli/intent-list.md
@@ -15,15 +15,17 @@ npx @tanstack/intent@latest list [--json]
 
 ## What you get
 
-- Scans installed dependencies for intent-enabled packages and skills
+- Scans project and workspace dependencies for intent-enabled packages and skills
+- Intentionally includes accessible global packages when listing installed skills
 - Includes warnings from discovery
 - If no packages are discovered, prints `No intent-enabled packages found.`
 - Summary line with package count, skill count, and detected package manager
-- Package table columns: `PACKAGE`, `VERSION`, `SKILLS`, `REQUIRES`
+- Package table columns: `PACKAGE`, `SOURCE`, `VERSION`, `SKILLS`, `REQUIRES`
 - Skill tree grouped by package
 - Optional warnings section (`⚠ ...` per warning)
 
 `REQUIRES` uses `intent.requires` values joined by `, `; empty values render as `–`.
+`SOURCE` is a lightweight indicator showing whether the selected package came from local discovery or explicit global scanning.
 
 ## JSON output
 
@@ -36,6 +38,7 @@ npx @tanstack/intent@latest list [--json]
     {
       "name": "string",
       "version": "string",
+      "source": "local | global",
       "intent": {
         "version": 1,
         "repo": "string",
@@ -57,7 +60,7 @@ npx @tanstack/intent@latest list [--json]
 }
 ```
 
-`packages` are ordered using `intent.requires` when possible.
+`packages` are ordered using `intent.requires` when possible. When the same package exists both locally and globally, `intent list` prefers the local package.
 
 ## Common errors
 
diff --git a/docs/cli/intent-stale.md b/docs/cli/intent-stale.md
@@ -15,7 +15,8 @@ npx @tanstack/intent@latest stale [--json]
 
 ## Behavior
 
-- Scans installed intent-enabled packages
+- Checks the current package by default, or all skill-bearing packages in the current workspace when run from a monorepo root
+- When `dir` is provided, scopes the check to the targeted package or skills directory
 - Computes one staleness report per package
 - Prints text output by default or JSON with `--json`
 - If no packages are found, prints `No intent-enabled packages found.`
diff --git a/docs/getting-started/quick-start-maintainers.md b/docs/getting-started/quick-start-maintainers.md
@@ -162,6 +162,8 @@ Manually check which skills need updates with:
 npx @tanstack/intent@latest stale
 ```
 
+When run from a package, this checks that package's shipped skills. When run from a monorepo root, it checks the workspace packages that ship skills.
+
 This detects:
 - **Version drift** — skill targets an older library version than currently installed
 - **New sources** — sources declared in frontmatter that weren't tracked before
diff --git a/docs/overview.md b/docs/overview.md
@@ -5,7 +5,7 @@ id: overview
 
 `@tanstack/intent` is a CLI for shipping and consuming Agent Skills as package artifacts.
 
-Skills are markdown documents that teach AI coding agents how to use your library correctly. Intent versions them with your releases, ships them inside npm packages, discovers them from local and accessible global `node_modules`, and helps agents load them automatically when working on matching tasks.
+Skills are markdown documents that teach AI coding agents how to use your library correctly. Intent versions them with your releases, ships them inside npm packages, discovers them from your project and workspace by default, and helps agents load them automatically when working on matching tasks.
 
 ## What Intent does
 
@@ -30,7 +30,7 @@ Intent provides tooling for two workflows:
 npx @tanstack/intent@latest list
 ```
 
-Scans local `node_modules` and any accessible global `node_modules` for intent-enabled packages, preferring local packages when both exist.
+Scans the current project's `node_modules` and workspace dependencies for intent-enabled packages. The CLI intentionally includes accessible global packages for this command and still prefers local packages when both exist.
 
 ```bash
 npx @tanstack/intent@latest install
diff --git a/packages/intent/src/cli-support.ts b/packages/intent/src/cli-support.ts
@@ -3,7 +3,7 @@ import { dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { fail } from './cli-error.js'
 import { resolveProjectContext } from './core/project-context.js'
-import type { ScanResult, StalenessReport } from './types.js'
+import type { ScanOptions, ScanResult, StalenessReport } from './types.js'
 
 export function printWarnings(warnings: Array<string>): void {
   if (warnings.length === 0) return
@@ -19,11 +19,13 @@ export function getMetaDir(): string {
   return join(thisDir, '..', 'meta')
 }
 
-export async function scanIntentsOrFail(): Promise<ScanResult> {
+export async function scanIntentsOrFail(
+  options?: ScanOptions,
+): Promise<ScanResult> {
   const { scanForIntents } = await import('./scanner.js')
 
   try {
-    return scanForIntents()
+    return scanForIntents(undefined, options)
   } catch (err) {
     fail(err instanceof Error ? err.message : String(err))
   }
diff --git a/packages/intent/src/cli.ts b/packages/intent/src/cli.ts
@@ -23,13 +23,18 @@ function createCli(): CAC {
   cli.usage('<command> [options]')
 
   cli
-    .command('list', 'Discover intent-enabled packages')
+    .command(
+      'list',
+      'Discover intent-enabled packages from the project, workspace, and explicit global scan',
+    )
     .usage('list [--json]')
     .option('--json', 'Output JSON')
     .example('list')
     .example('list --json')
     .action(async (options: { json?: boolean }) => {
-      await runListCommand(options, scanIntentsOrFail)
+      await runListCommand(options, () =>
+        scanIntentsOrFail({ includeGlobal: true }),
+      )
     })
 
   cli
@@ -68,7 +73,10 @@ function createCli(): CAC {
     })
 
   cli
-    .command('stale [dir]', 'Check skills for staleness')
+    .command(
+      'stale [dir]',
+      'Check skills for staleness in the current package or workspace',
+    )
     .usage('stale [dir] [--json]')
     .option('--json', 'Output JSON')
     .example('stale')
diff --git a/packages/intent/src/commands/list.ts b/packages/intent/src/commands/list.ts
@@ -33,15 +33,16 @@ export async function runListCommand(
   options: { json?: boolean },
   scanIntentsOrFail: () => Promise<ScanResult>,
 ): Promise<void> {
-  const { computeSkillNameWidth, printSkillTree, printTable } =
-    await import('../display.js')
   const result = await scanIntentsOrFail()
 
   if (options.json) {
     console.log(JSON.stringify(result, null, 2))
     return
   }
 
+  const { computeSkillNameWidth, printSkillTree, printTable } =
+    await import('../display.js')
+
   const scanCoverage = formatScanCoverage(result)
 
   if (result.packages.length === 0) {
@@ -69,11 +70,12 @@ export async function runListCommand(
 
   const rows = result.packages.map((pkg) => [
     pkg.name,
+    pkg.source,
     pkg.version,
     String(pkg.skills.length),
     pkg.intent.requires?.join(', ') || '–',
   ])
-  printTable(['PACKAGE', 'VERSION', 'SKILLS', 'REQUIRES'], rows)
+  printTable(['PACKAGE', 'SOURCE', 'VERSION', 'SKILLS', 'REQUIRES'], rows)
 
   printVersionConflicts(result)
 
diff --git a/packages/intent/src/commands/stale.ts b/packages/intent/src/commands/stale.ts
@@ -9,13 +9,13 @@ export async function runStaleCommand(
 ): Promise<void> {
   const { reports } = await resolveStaleTargets(targetDir)
 
-  if (reports.length === 0) {
-    console.log('No intent-enabled packages found.')
+  if (options.json) {
+    console.log(JSON.stringify(reports, null, 2))
     return
   }
 
-  if (options.json) {
-    console.log(JSON.stringify(reports, null, 2))
+  if (reports.length === 0) {
+    console.log('No intent-enabled packages found.')
     return
   }
 
diff --git a/packages/intent/src/discovery/index.ts b/packages/intent/src/discovery/index.ts
@@ -0,0 +1,2 @@
+export { createPackageRegistrar } from './register.js'
+export { createDependencyWalker } from './walk.js'
diff --git a/packages/intent/src/discovery/register.ts b/packages/intent/src/discovery/register.ts
@@ -0,0 +1,147 @@
+import { existsSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+import { listNodeModulesPackageDirs, toPosixPath } from '../utils.js'
+import type {
+  IntentConfig,
+  IntentPackage,
+  NodeModulesScanTarget,
+  SkillEntry,
+} from '../types.js'
+
+type PackageJson = Record<string, unknown>
+
+function isLocalToProject(dirPath: string, projectRoot: string): boolean {
+  return (
+    dirPath.startsWith(projectRoot + sep) ||
+    dirPath.startsWith(projectRoot + '/')
+  )
+}
+
+/**
+ * Rewrite absolute skill paths to stable relative paths. Prefers
+ * `node_modules/<name>/...` when a top-level symlink exists, otherwise
+ * falls back to a path relative to the project root.
+ */
+function rewriteSkillPaths(
+  skills: Array<SkillEntry>,
+  dirPath: string,
+  name: string,
+  projectRoot: string,
+): void {
+  const hasStableSymlink =
+    name !== '' && existsSync(join(projectRoot, 'node_modules', name))
+  for (const skill of skills) {
+    if (hasStableSymlink) {
+      const relFromPkg = toPosixPath(relative(dirPath, skill.path))
+      skill.path = `node_modules/${name}/${relFromPkg}`
+    } else {
+      skill.path = toPosixPath(relative(projectRoot, skill.path))
+    }
+  }
+}
+
+export interface CreatePackageRegistrarOptions {
+  comparePackageVersions: (a: string, b: string) => number
+  deriveIntentConfig: (pkgJson: PackageJson) => IntentConfig | null
+  discoverSkills: (skillsDir: string, baseName: string) => Array<SkillEntry>
+  getPackageDepth: (packageRoot: string, projectRoot: string) => number
+  packageIndexes: Map<string, number>
+  packages: Array<IntentPackage>
+  projectRoot: string
+  readPkgJson: (dirPath: string) => PackageJson | null
+  rememberVariant: (pkg: IntentPackage) => void
+  validateIntentField: (pkgName: string, intent: unknown) => IntentConfig | null
+  warnings: Array<string>
+}
+
+export function createPackageRegistrar(opts: CreatePackageRegistrarOptions) {
+  function scanTarget(
+    target: NodeModulesScanTarget,
+    source: IntentPackage['source'] = 'local',
+  ): void {
+    if (!target.path || !target.exists || target.scanned) return
+    target.scanned = true
+
+    for (const dirPath of listNodeModulesPackageDirs(target.path)) {
+      tryRegister(dirPath, 'unknown', source)
+    }
+  }
+
+  function tryRegister(
+    dirPath: string,
+    fallbackName: string,
+    source: IntentPackage['source'] = 'local',
+  ): boolean {
+    const skillsDir = join(dirPath, 'skills')
+    if (!existsSync(skillsDir)) return false
+
+    const pkgJson = opts.readPkgJson(dirPath)
+    if (!pkgJson) {
+      opts.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 =
+      opts.validateIntentField(name, pkgJson.intent) ??
+      opts.deriveIntentConfig(pkgJson)
+    if (!intent) {
+      opts.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 skills = opts.discoverSkills(skillsDir, name)
+
+    if (isLocalToProject(dirPath, opts.projectRoot)) {
+      rewriteSkillPaths(skills, dirPath, name, opts.projectRoot)
+    }
+
+    const candidate: IntentPackage = {
+      name,
+      version,
+      intent,
+      skills,
+      packageRoot: dirPath,
+      source,
+    }
+    const existingIndex = opts.packageIndexes.get(name)
+    if (existingIndex === undefined) {
+      opts.rememberVariant(candidate)
+      opts.packageIndexes.set(name, opts.packages.push(candidate) - 1)
+      return true
+    }
+
+    const existing = opts.packages[existingIndex]!
+    if (existing.packageRoot === candidate.packageRoot) {
+      return false
+    }
+
+    opts.rememberVariant(existing)
+    opts.rememberVariant(candidate)
+
+    const existingDepth = opts.getPackageDepth(
+      existing.packageRoot,
+      opts.projectRoot,
+    )
+    const candidateDepth = opts.getPackageDepth(
+      candidate.packageRoot,
+      opts.projectRoot,
+    )
+    const shouldReplace =
+      candidateDepth < existingDepth ||
+      (candidateDepth === existingDepth &&
+        opts.comparePackageVersions(candidate.version, existing.version) > 0)
+
+    if (shouldReplace) {
+      opts.packages[existingIndex] = candidate
+    }
+
+    return true
+  }
+
+  return { scanTarget, tryRegister }
+}
diff --git a/packages/intent/src/discovery/walk.ts b/packages/intent/src/discovery/walk.ts
diff --git a/packages/intent/src/index.ts b/packages/intent/src/index.ts
diff --git a/packages/intent/src/scanner.ts b/packages/intent/src/scanner.ts
diff --git a/packages/intent/src/types.ts b/packages/intent/src/types.ts
diff --git a/packages/intent/tests/cli.test.ts b/packages/intent/tests/cli.test.ts
diff --git a/packages/intent/tests/scanner.test.ts b/packages/intent/tests/scanner.test.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@tanstack/intent': patch
 +---
++
 +Refactor package discovery into a dedicated registrar and dependency walker so project, workspace, and transitive dependencies are scanned consistently. Track local vs. global package sources and surface that in `intent list` via a `SOURCE` column. `intent stale` is now scoped to local and workspace packages; global packages are only included by `intent list` (which explicitly opts in). A new `scanForIntents` option `includeGlobal` controls global scanning for programmatic callers — this replaces the previous implicit behavior where setting `INTENT_GLOBAL_NODE_MODULES` caused all commands to scan globals.