@vltpkg/graph 1.4.0 → 1.6.0

package/dist/reify/update-importers-package-json.d.ts

@@ -1,6 +1,7 @@
 import type { PackageJson } from '@vltpkg/package-json';
 import type { AddImportersDependenciesMap, RemoveImportersDependenciesMap } from '../dependencies.ts';
 import type { Graph } from '../graph.ts';
+import type { GraphModifier } from '../modifiers.ts';
 export type UpdatePackageJsonOptions = {
     /**
      * A `Map` in which keys are {@link DepID} linking to another `Map` in which
@@ -37,9 +38,13 @@ export type UpdatePackageJsonOptions = {
      * Defaults to `^` if not specified. Ignored when `saveExact` is true.
      */
     savePrefix?: string;
+    /**
+     * Graph modifiers, importer edges they govern keep the modifier value.
+     */
+    modifiers?: GraphModifier;
 };
 /**
  * Updates nodes of a provided {@link Graph} accordingly to the
  * provided add or remove arguments.
  */
-export declare const updatePackageJson: ({ add, graph, packageJson, remove, saveExact, savePrefix, }: UpdatePackageJsonOptions) => () => void;
+export declare const updatePackageJson: ({ add, graph, packageJson, remove, saveExact, savePrefix, modifiers, }: UpdatePackageJsonOptions) => () => void;

package/dist/reify/update-importers-package-json.js

@@ -2,16 +2,10 @@ import { splitDepID } from '@vltpkg/dep-id';
 import { error } from '@vltpkg/error-cause';
 import { Spec } from '@vltpkg/spec';
 import { longDependencyTypes } from '@vltpkg/types';
+import { longDependencyTypeNames } from "../dependencies.js";
 import { resolveSaveType } from "../resolve-save-type.js";
 import { calculateSaveValue } from "./calculate-save-value.js";
-const depTypesMap = new Map([
-    ['prod', 'dependencies'],
-    ['dev', 'devDependencies'],
-    ['peer', 'peerDependencies'],
-    ['peerOptional', 'peerDependencies'],
-    ['optional', 'optionalDependencies'],
-]);
-const addOrRemoveDeps = (nodeId, graph, addOrRemove, saveExact, savePrefix) => {
+const addOrRemoveDeps = (nodeId, graph, addOrRemove, saveExact, savePrefix, modifiers) => {
     const node = graph.nodes.get(nodeId);
     if (!node) {
         throw error('Failed to retrieve node', {
@@ -51,16 +45,21 @@ const addOrRemoveDeps = (nodeId, graph, addOrRemove, saveExact, savePrefix) => {
             const [name, dep] = deleteNameOrAddItem;
             // peerOptional also needs to add peerDependenciesMeta entry
             const depTypeShort = resolveSaveType(node, name, dep.type);
-            const depType = depTypesMap.get(depTypeShort);
+            const depType = Object.hasOwn(longDependencyTypeNames, depTypeShort) ?
+                longDependencyTypeNames[depTypeShort]
+                : undefined;
             if (!depType) {
                 throw error('Failed to retrieve dependency type', {
-                    validOptions: [...depTypesMap.keys()],
+                    validOptions: Object.keys(longDependencyTypeNames),
                     found: dep.type,
                 });
             }
             const edge = node.edgesOut.get(name);
             if (!edge?.to) {
-                throw error('Dependency node could not be found');
+                throw error(`Dependency node could not be found: ${name}`, {
+                    spec: dep.spec,
+                    from: node.location,
+                });
             }
             const n = edge.to;
             const [nodeType] = splitDepID(n.id);
@@ -94,8 +93,10 @@ const addOrRemoveDeps = (nodeId, graph, addOrRemove, saveExact, savePrefix) => {
             // the lockfile has to carry the value package.json carries, or a
             // later install reads back `latest` where the manifest says
             // `^1.2.3`. anything keyed by the old spec from here on must be
-            // invalidated at this point.
-            if (saveValue !== edge.spec.bareSpec) {
+            // invalidated at this point. governed edges keep the modifier
+            // value instead.
+            if (saveValue !== edge.spec.bareSpec &&
+                !modifiers?.targetsImporterEdge(node, dep.spec)) {
                 edge.spec = Spec.parse(name, saveValue, dep.spec.options);
                 graph.lockfileStale = true;
             }
@@ -107,7 +108,7 @@ const addOrRemoveDeps = (nodeId, graph, addOrRemove, saveExact, savePrefix) => {
  * Updates nodes of a provided {@link Graph} accordingly to the
  * provided add or remove arguments.
  */
-export const updatePackageJson = ({ add, graph, packageJson, remove, saveExact, savePrefix, }) => {
+export const updatePackageJson = ({ add, graph, packageJson, remove, saveExact, savePrefix, modifiers, }) => {
     const manifestsToUpdate = new Set();
     const operations = new Set([add, remove]);
     for (const operation of operations) {
@@ -116,7 +117,7 @@ export const updatePackageJson = ({ add, graph, packageJson, remove, saveExact,
             // that are nested folders from which the user can also add new
             // dependencies to
             for (const nodeId of operation.keys()) {
-                const manifest = addOrRemoveDeps(nodeId, graph, operation, saveExact, savePrefix);
+                const manifest = addOrRemoveDeps(nodeId, graph, operation, saveExact, savePrefix, modifiers);
                 if (manifest) {
                     manifestsToUpdate.add(manifest);
                 }

package/dist/skills/dirs.d.ts

@@ -0,0 +1,58 @@
+/** Always a target when detecting: read by most agents. */
+export declare const AGENTS_SKILLS = ".agents/skills";
+/** Set (non-empty) inside Claude Code. */
+export declare const CLAUDE_ENV: readonly ["CLAUDECODE", "CLAUDE_CODE"];
+/**
+ * Agent folder at the project root → its skills dir.
+ */
+export declare const AGENT_ROOTS: readonly (readonly [
+    marker: string,
+    dir: string
+])[];
+/**
+ * An agent skills dir.
+ */
+export type SkillsDir = {
+    /** `/`-separated, relative to projectRoot */
+    dir: string;
+    /** realpath (a missing tail appended as is) */
+    real: string;
+    /** `<dev>:<ino>` (no inode: the path); unset when missing */
+    id?: string;
+};
+/**
+ * Result of {@link skillsDirs}.
+ */
+export type SkillsDirs = {
+    /** dirs to link into */
+    targets: SkillsDir[];
+    /** existing dirs to look for vlt links in: targets first */
+    scan: SkillsDir[];
+    /** targets dropped: `<dir> (<reason>)` */
+    skipped: string[];
+};
+/**
+ * Options for {@link skillsDirs}.
+ */
+export type SkillsDirsOptions = {
+    projectRoot: string;
+    /** `skills-dir`: replaces detection; `[]` none */
+    configured?: string[];
+    /** default `process.env` */
+    env?: Record<string, string | undefined>;
+    /** create missing targets */
+    create?: boolean;
+};
+/**
+ * Throw EUSAGE unless each entry is a dir inside projectRoot, not in
+ * `node_modules`.
+ */
+export declare const assertSkillsDirs: (projectRoot: string, list?: string[]) => void;
+/**
+ * The project's agent skill dirs. `configured` replaces detection:
+ * `.agents/skills`, plus `<folder>/skills` for each agent folder at
+ * the root, `.claude/skills` inside Claude Code, and existing
+ * `.<name>/skills` dirs. Dirs must resolve inside projectRoot, not in
+ * `node_modules`; the same dir is listed once.
+ */
+export declare const skillsDirs: ({ projectRoot, configured, env, create, }: SkillsDirsOptions) => SkillsDirs;

package/dist/skills/dirs.js

@@ -0,0 +1,211 @@
+import { error } from '@vltpkg/error-cause';
+import { lstatSync, mkdirSync, readdirSync, realpathSync, statSync, } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { norm } from "./mounts.js";
+/** Always a target when detecting: read by most agents. */
+export const AGENTS_SKILLS = '.agents/skills';
+/** Set (non-empty) inside Claude Code. */
+export const CLAUDE_ENV = ['CLAUDECODE', 'CLAUDE_CODE'];
+/**
+ * Agent folder at the project root → its skills dir.
+ */
+// vercel-labs/skills v1.7.2 src/agents.ts: skillsDir per agent (line), dot roots only
+export const AGENT_ROOTS = [
+    ['.adal', '.adal/skills'], // 813
+    ['.aider-desk', '.aider-desk/skills'], // 84
+    ['.augment', '.augment/skills'], // 140
+    ['.autohand', '.autohand/skills'], // 131
+    ['.bob', '.bob/skills'], // 149
+    ['.claude', '.claude/skills'], // 158
+    ['.codeartsdoer', '.codeartsdoer/skills'], // 191
+    ['.codebuddy', '.codebuddy/skills'], // 200
+    ['.codemaker', '.codemaker/skills'], // 209
+    ['.codestudio', '.codestudio/skills'], // 218
+    ['.commandcode', '.commandcode/skills'], // 236
+    ['.continue', '.continue/skills'], // 245
+    ['.cortex', '.cortex/skills'], // 254
+    ['.crush', '.crush/skills'], // 263
+    ['.devin', '.devin/skills'], // 291
+    ['.forge', '.forge/skills'], // 345
+    ['.goose', '.goose/skills'], // 382
+    ['.grok', '.grok/skills'], // 391
+    ['.hermes', '.hermes/skills'], // 400
+    ['.iflow', '.iflow/skills'], // 436
+    ['.inferencesh', '.inferencesh/skills'], // 409
+    ['.jazz', '.jazz/skills'], // 418
+    ['.junie', '.junie/skills'], // 427
+    ['.kimchi', '.kimchi/skills'], // 456
+    ['.kiro', '.kiro/skills'], // 474
+    ['.kode', '.kode/skills'], // 483
+    ['.lingma', '.lingma/skills'], // 492
+    ['.mcpjam', '.mcpjam/skills'], // 511
+    ['.minimax', '.minimax/skills'], // 520
+    ['.moxby', '.moxby/skills'], // 538
+    ['.mux', '.mux/skills'], // 547
+    ['.neovate', '.neovate/skills'], // 782
+    ['.ona', '.ona/skills'], // 574
+    ['.openhands', '.openhands/skills'], // 565
+    ['.pochi', '.pochi/skills'], // 791
+    ['.posit/assistant', '.posit/assistant/skills'], // 595
+    ['.qoder', '.qoder/skills'], // 604,613
+    ['.qwen', '.qwen/skills'], // 622
+    ['.reasonix', '.reasonix/skills'], // 641
+    ['.roo', '.roo/skills'], // 659
+    ['.rovodev', '.rovodev/skills'], // 650
+    ['.tabnine', '.tabnine/agent/skills'], // 678
+    ['.terramind', '.terramind/skills'], // 687
+    ['.tinycloud', '.tinycloud/skills'], // 696
+    ['.trae', '.trae/skills'], // 705,714
+    ['.vibe', '.vibe/skills'], // 529
+    ['.windsurf', '.windsurf/skills'], // 732
+    ['.zcode', '.zcode/skills'], // 755
+    ['.zencoder', '.zencoder/skills'], // 764,773
+];
+// strictly below root
+const inside = (root, p) => {
+    const r = relative(root, p);
+    return (!!r && r !== '..' && !r.startsWith('..' + sep) && !isAbsolute(r));
+};
+// a `node_modules` segment below root
+const inNodeModules = (root, p) => relative(root, p)
+    .split(sep)
+    .some(s => s.toLowerCase() === 'node_modules');
+const isDir = (path) => {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Throw EUSAGE unless each entry is a dir inside projectRoot, not in
+ * `node_modules`.
+ */
+export const assertSkillsDirs = (projectRoot, list = []) => {
+    for (const e of list) {
+        const p = resolve(projectRoot, e);
+        if (e &&
+            (!inside(projectRoot, p) || inNodeModules(projectRoot, p))) {
+            throw error('Invalid --skills-dir: must be a dir inside the project, not in node_modules', { code: 'EUSAGE', found: e }, assertSkillsDirs);
+        }
+    }
+};
+// walk `dir` from the real root, one component at a time, so a
+// symlink out of the project is caught before anything is made in it.
+// A string is the reason it was skipped (fs errors: the code)
+const walk = (realRoot, dir, create) => {
+    const parts = dir.split('/');
+    let real = realRoot;
+    try {
+        for (const [i, part] of parts.entries()) {
+            const next = join(real, part);
+            let st = lstatSync(next, { throwIfNoEntry: false });
+            if (!st) {
+                if (!create)
+                    return { dir, real: join(real, ...parts.slice(i)) };
+                try {
+                    mkdirSync(next);
+                }
+                catch (er) {
+                    if (er.code !== 'EEXIST')
+                        throw er;
+                }
+                st = lstatSync(next);
+            }
+            if (st.isSymbolicLink()) {
+                let r;
+                try {
+                    r = realpathSync(next);
+                }
+                catch {
+                    return 'not a directory';
+                }
+                if (!inside(realRoot, r))
+                    return 'outside the project';
+                if (inNodeModules(realRoot, r))
+                    return 'inside node_modules';
+                if (!isDir(r))
+                    return 'not a directory';
+                real = r;
+            }
+            else if (st.isDirectory()) {
+                real = next;
+            }
+            else {
+                return 'not a directory';
+            }
+        }
+        const { dev, ino } = statSync(real, { bigint: true });
+        // some filesystems report no inode: compare paths
+        return { dir, real, id: ino ? `${dev}:${ino}` : norm(real) };
+    }
+    catch (er) {
+        return String(er.code);
+    }
+};
+/**
+ * The project's agent skill dirs. `configured` replaces detection:
+ * `.agents/skills`, plus `<folder>/skills` for each agent folder at
+ * the root, `.claude/skills` inside Claude Code, and existing
+ * `.<name>/skills` dirs. Dirs must resolve inside projectRoot, not in
+ * `node_modules`; the same dir is listed once.
+ */
+export const skillsDirs = ({ projectRoot, configured, env = process.env, create = false, }) => {
+    const realRoot = realpathSync(projectRoot);
+    const res = { targets: [], scan: [], skipped: [] };
+    const dots = readdirSync(realRoot)
+        .filter(e => e.startsWith('.'))
+        .sort((a, b) => a.localeCompare(b, 'en'))
+        .map(e => `${e}/skills`);
+    let list;
+    if (configured) {
+        assertSkillsDirs(projectRoot, configured);
+        list = configured.filter(Boolean);
+    }
+    else {
+        const found = new Set();
+        for (const [marker, d] of AGENT_ROOTS) {
+            if (isDir(join(realRoot, marker)))
+                found.add(d);
+        }
+        if (CLAUDE_ENV.some(k => env[k]))
+            found.add('.claude/skills');
+        for (const d of dots) {
+            if (isDir(join(realRoot, d)))
+                found.add(d);
+        }
+        list = [
+            AGENTS_SKILLS,
+            ...[...found].sort((a, b) => a.localeCompare(b, 'en')),
+        ];
+    }
+    const dirs = new Set(list.map(e => relative(projectRoot, resolve(projectRoot, e))
+        .split(sep)
+        .join('/')));
+    const seen = new Set();
+    for (const dir of dirs) {
+        const d = walk(realRoot, dir, create);
+        if (typeof d === 'string') {
+            res.skipped.push(`${dir} (${d})`);
+        }
+        else if (!seen.has(d.id ?? d.real)) {
+            seen.add(d.id ?? d.real);
+            res.targets.push(d);
+            if (d.id)
+                res.scan.push(d);
+        }
+    }
+    for (const dir of [
+        AGENTS_SKILLS,
+        ...AGENT_ROOTS.map(([, d]) => d),
+        ...dots,
+    ]) {
+        const d = walk(realRoot, dir, false);
+        if (typeof d !== 'string' && d.id && !seen.has(d.id)) {
+            seen.add(d.id);
+            res.scan.push(d);
+        }
+    }
+    return res;
+};

package/dist/skills/discover.d.ts

@@ -0,0 +1,73 @@
+import type { DepID } from '@vltpkg/dep-id';
+import type { PathScurry } from 'path-scurry';
+import type { Node } from '../node.ts';
+import type { SkillMount } from './mounts.ts';
+/**
+ * An agent skill (a dir with a `SKILL.md`) shipped by an installed
+ * package. See https://agentskills.io/specification
+ */
+export type Skill = {
+    /** package name, e.g. `@s/bar` */
+    name: string;
+    /**
+     * name a direct dep is installed under, when not `name`, as `vlt ls`
+     * shows it
+     */
+    alias?: string;
+    /** package version */
+    version?: string;
+    /** package DepID */
+    id: DepID;
+    /**
+     * skill name: its dir name (`skills/<dir>`, `dist/skills/<dir>`,
+     * `.agents/skills/<dir>`), or the root SKILL.md `name`
+     */
+    skill: string;
+    /**
+     * `SKILL.md` frontmatter `name`, when it differs from `skill`
+     * (matched by `:skill()`)
+     */
+    frontmatterName?: string;
+    /** frontmatter description (folded to one line, control chars stripped) */
+    description?: string;
+    /** realpath of the dir holding SKILL.md */
+    path: string;
+    /** dirs holding a vlt link named `skill` to `path` */
+    linked: string[];
+};
+/**
+ * Result of `discoverSkills`.
+ */
+export type DiscoveredSkills = {
+    /** skills of the picked version of each package, sorted by name */
+    skills: Skill[];
+    /** every scanned package version, w/ the skills it ships */
+    scanned: Map<DepID, Pick<Skill, 'skill' | 'path'>[]>;
+};
+/**
+ * The `SKILL.md` frontmatter fields vlt reads.
+ */
+export type SkillFrontmatter = {
+    name?: string;
+    description?: string;
+};
+/**
+ * Read `name` and `description` from a `SKILL.md` YAML frontmatter.
+ * Minimal line reader: top-level keys, plain/quoted/folded values.
+ */
+export declare const readFrontmatter: (file: string) => SkillFrontmatter;
+/** Ships agent skills, as `discoverSkills` finds them. */
+export declare const shipsSkills: (node: Node) => boolean;
+/**
+ * Find the agent skills shipped by the given installed packages.
+ *
+ * Only packages in the vlt store and the project's workspaces (not its
+ * root) are scanned, for a root `SKILL.md`, then `<dir>/SKILL.md` in
+ * `skills/`, `dist/skills/` and `.agents/skills/`: the first skill of a
+ * name wins. One version per package is picked, even if it ships none:
+ * a workspace or dep of the main importer, else a dep of any importer,
+ * else the highest version, then DepID. Same-name skills of different
+ * packages are all returned, sorted by rank then DepID (`linkSkills`
+ * resolves them). `mounts` set each skill's `linked` dirs.
+ */
+export declare const discoverSkills: (nodes: Iterable<Node>, scurry: PathScurry, mounts?: SkillMount[]) => DiscoveredSkills;

package/dist/skills/discover.js

@@ -0,0 +1,238 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { splitDepID } from '@vltpkg/dep-id';
+import { parse } from '@vltpkg/semver';
+import { lstat, norm, packageKey, realOr } from "./mounts.js";
+// safe single path segment, no dotfiles or scopes
+const skillDirName = /^[a-z0-9][a-z0-9._-]*$/i;
+// agentskills.io `name`
+const specName = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const topKey = /^([A-Za-z0-9_-]+):/;
+const blockIndicator = /^[>|][-+1-9]*$/;
+const fold = (inline, more) => {
+    let value = [blockIndicator.test(inline) ? '' : inline, ...more]
+        .filter(Boolean)
+        .join(' ');
+    const q = value[0];
+    if (value.length > 1 &&
+        (q === '"' || q === "'") &&
+        value.endsWith(q)) {
+        value = value.slice(1, -1).trim();
+    }
+    return value || undefined;
+};
+/**
+ * Read `name` and `description` from a `SKILL.md` YAML frontmatter.
+ * Minimal line reader: top-level keys, plain/quoted/folded values.
+ */
+export const readFrontmatter = (file) => {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    const lines = text.split(/\r?\n/);
+    if (lines[0]?.trim() !== '---')
+        return {};
+    const end = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+    if (end === -1)
+        return {};
+    const fm = {};
+    let key;
+    let inline = '';
+    let more = [];
+    const flush = () => {
+        if (key)
+            fm[key] = fold(inline, more);
+        key = undefined;
+    };
+    for (const line of lines.slice(1, end)) {
+        if (!line.trim())
+            continue;
+        const m = topKey.exec(line);
+        if (m) {
+            flush();
+            const k = m[1];
+            if (k === 'name' || k === 'description') {
+                key = k;
+                inline = line.slice(k.length + 1).trim();
+                // drop a ` # comment` from unquoted values
+                const hash = inline.search(/(?:^|\s)#/);
+                if (hash !== -1 && !/^["']/.test(inline)) {
+                    inline = inline.slice(0, hash).trim();
+                }
+                more = [];
+            }
+        }
+        else if (/^\s/.test(line)) {
+            if (key)
+                more.push(line.trim());
+        }
+        else {
+            flush();
+        }
+    }
+    flush();
+    return fm;
+};
+// package-controlled text printed to terminals
+const sanitize = (s) => {
+    const clean = s
+        ?.replace(/\p{Cc}/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return clean ? clean.slice(0, 1024) : undefined;
+};
+const lc = (s) => s.toLowerCase();
+const isDir = (path) => !!lstat(path)?.isDirectory();
+const isFile = (path) => !!lstat(path)?.isFile();
+// `skills/SKILL.md` would make the dir look like a skill
+const isSkillMd = (name) => name.toLowerCase() === 'skill.md';
+// where packages ship skills, in precedence order (a name found first
+// wins), after a root SKILL.md
+const shipDirs = ['skills', 'dist/skills', '.agents/skills'];
+// a real dir, no symlink on the way: skills stay inside the package
+const subdir = (dir, sub) => {
+    let path = dir;
+    for (const seg of sub.split('/')) {
+        path = resolve(path, seg);
+        if (!isDir(path))
+            return undefined;
+    }
+    return path;
+};
+const scan = (dir, pkgName) => {
+    const found = [];
+    const has = (skill) => found.some(f => lc(f.skill) === lc(skill));
+    const root = resolve(dir, 'SKILL.md');
+    if (isFile(root)) {
+        const { name, description } = readFrontmatter(root);
+        const skill = name && name.length <= 64 && specName.test(name) ?
+            name
+            : pkgName.slice(pkgName.lastIndexOf('/') + 1);
+        if (skillDirName.test(skill) && !isSkillMd(skill)) {
+            found.push({ skill, path: dir, name, description });
+        }
+    }
+    for (const sub of shipDirs) {
+        const skillsDir = subdir(dir, sub);
+        if (!skillsDir)
+            continue;
+        // one per name, any case
+        for (const d of readdirSync(skillsDir).sort()) {
+            if (!skillDirName.test(d) || isSkillMd(d) || has(d))
+                continue;
+            const path = resolve(skillsDir, d);
+            const file = resolve(path, 'SKILL.md');
+            if (!isDir(path) || !isFile(file))
+                continue;
+            const { name, description } = readFrontmatter(file);
+            found.push({ skill: d, path, name, description });
+        }
+    }
+    return found;
+};
+// 0: a workspace or dep of the main importer, 1: dep of any
+// importer, 2: transitive
+const rank = (node) => {
+    if (node.importer)
+        return 0;
+    let r = 2;
+    for (const { from } of node.edgesIn) {
+        if (from.mainImporter)
+            return 0;
+        if (from.importer)
+            r = 1;
+    }
+    return r;
+};
+const ver = (node) => node.version ? parse(node.version) : undefined;
+// higher version first, if both valid
+const byVersion = (a, b) => {
+    const va = ver(a);
+    const vb = ver(b);
+    return va && vb ? vb.compare(va) : 0;
+};
+const compare = (a, b) => rank(a) - rank(b) ||
+    byVersion(a, b) ||
+    a.id.localeCompare(b.id, 'en');
+// the name a direct dep is installed under, if not its own
+const aliasOf = (node) => {
+    const edges = [...node.edgesIn];
+    const n = (edges.find(e => e.from.mainImporter) ??
+        edges.find(e => e.from.importer))?.name;
+    return n === node.name ? undefined : n;
+};
+// store pkgs and workspaces, not the project root; lockfile keeps a
+// tarball's path as its location
+const scannable = (node) => node.importer ?
+    !node.mainImporter
+    : node.inVltStore() && splitDepID(node.id)[0] !== 'file';
+/** Ships agent skills, as `discoverSkills` finds them. */
+export const shipsSkills = (node) => scannable(node) &&
+    scan(realOr(resolve(node.projectRoot, node.location)), node.name)
+        .length > 0;
+/**
+ * Find the agent skills shipped by the given installed packages.
+ *
+ * Only packages in the vlt store and the project's workspaces (not its
+ * root) are scanned, for a root `SKILL.md`, then `<dir>/SKILL.md` in
+ * `skills/`, `dist/skills/` and `.agents/skills/`: the first skill of a
+ * name wins. One version per package is picked, even if it ships none:
+ * a workspace or dep of the main importer, else a dep of any importer,
+ * else the highest version, then DepID. Same-name skills of different
+ * packages are all returned, sorted by rank then DepID (`linkSkills`
+ * resolves them). `mounts` set each skill's `linked` dirs.
+ */
+export const discoverSkills = (nodes, scurry, mounts = []) => {
+    const key = (name, path) => `${lc(name)}\0${norm(path)}`;
+    const linkedIn = new Map();
+    for (const m of mounts) {
+        const k = key(m.name, realOr(m.target));
+        const dirs = linkedIn.get(k) ?? [];
+        if (!dirs.includes(m.dir.dir))
+            dirs.push(m.dir.dir);
+        linkedIn.set(k, dirs);
+    }
+    const scanned = new Map();
+    const byPkg = new Map();
+    for (const node of nodes) {
+        if (!scannable(node))
+            continue;
+        const found = scan(realOr(node.resolvedLocation(scurry)), node.name);
+        scanned.set(node.id, found.map(({ skill, path }) => ({ skill, path })));
+        const key = packageKey(node.id);
+        const list = byPkg.get(key) ?? [];
+        list.push({ node, found });
+        byPkg.set(key, list);
+    }
+    const rows = [];
+    for (const list of byPkg.values()) {
+        const { node, found } = list.reduce((a, b) => compare(a.node, b.node) <= 0 ? a : b);
+        for (const { skill, path, name, description } of found) {
+            const fm = sanitize(name);
+            rows.push([
+                {
+                    name: node.name,
+                    alias: aliasOf(node),
+                    version: node.version,
+                    id: node.id,
+                    skill,
+                    ...(fm && lc(fm) !== lc(skill) && { frontmatterName: fm }),
+                    description: sanitize(description),
+                    path,
+                    linked: linkedIn.get(key(skill, path)) ?? [],
+                },
+                rank(node),
+            ]);
+        }
+    }
+    const skills = rows
+        .sort(([a, ra], [b, rb]) => lc(a.skill).localeCompare(lc(b.skill), 'en') ||
+        ra - rb ||
+        a.id.localeCompare(b.id, 'en'))
+        .map(([s]) => s);
+    return { skills, scanned };
+};