@vltpkg/graph 1.4.0 → 1.5.0

package/dist/reify/build.d.ts

@@ -9,5 +9,12 @@ import type { Node } from '../node.ts';
 export type BuildResult = {
     success: Node[];
     failure: Node[];
+    /** needed builds skipped as they have no security data */
+    skipped?: Node[];
+    /**
+     * why `skipped` builds have no security data: the request timed
+     * out, or socket.dev has not scanned them yet
+     */
+    skippedReason?: 'timeout' | 'unscanned';
 };
 export declare const build: (diff: Diff, packageJson: PackageJson, scurry: PathScurry, allowScriptsNodes: Set<DepID>) => Promise<BuildResult>;

package/dist/reify/check-needed-build.d.ts

@@ -32,3 +32,8 @@ export type CheckNeededBuildOptions = {
  * @returns {BuildData} The BuildData object containing Node objects that need building
  */
 export declare const checkNeededBuild: (options: CheckNeededBuildOptions) => BuildData;
+/**
+ * Copy build state from the actual graph onto ideal nodes that are
+ * not re-extracted, since `vlt-lock.json` does not store it.
+ */
+export declare const carryBuildState: (diff: Diff) => void;

package/dist/reify/check-needed-build.js

@@ -70,3 +70,16 @@ export const checkNeededBuild = (options) => {
     };
     return buildData;
 };
+/**
+ * Copy build state from the actual graph onto ideal nodes that are
+ * not re-extracted, since `vlt-lock.json` does not store it.
+ */
+export const carryBuildState = (diff) => {
+    for (const [id, node] of diff.to.nodes) {
+        if (diff.nodes.add.has(node))
+            continue;
+        const prev = diff.from.nodes.get(id);
+        if (prev)
+            node.buildState = prev.buildState;
+    }
+};

package/dist/reify/index.js

@@ -8,51 +8,16 @@ import { addEdges } from "./add-edges.js";
 import { addNodes } from "./add-nodes.js";
 import { build } from "./build.js";
 import { deleteEdges } from "./delete-edges.js";
-import { checkNeededBuild } from "./check-needed-build.js";
+import { carryBuildState, checkNeededBuild, } from "./check-needed-build.js";
 import { deleteNodes } from "./delete-nodes.js";
 import { internalHoist } from "./internal-hoist.js";
 import { pruneUnsupportedOptional } from "./optional-fail.js";
 import { rollback } from "./rollback.js";
 import { updatePackageJson } from "./update-importers-package-json.js";
 import { copyFileSync } from 'node:fs';
-import { Query } from '@vltpkg/query';
-import { SecurityArchive } from '@vltpkg/security-archive';
 import { binChmodAll } from "./bin-chmod.js";
+import { filterNodesByQuery } from "../filter-nodes-by-query.js";
 const limit = Math.max(availableParallelism() - 1, 1) * 8;
-/**
- * Filter nodes using a DSS query string
- */
-const filterNodesByQuery = async (graph, allowScriptsQuery) => {
-    // shortcut no packages included
-    if (allowScriptsQuery === ':not(*)' /* c8 ignore next */ ||
-        !allowScriptsQuery) {
-        return new Set();
-    }
-    // shortcut all packages included
-    if (allowScriptsQuery === '*') {
-        return new Set(graph.nodes.keys());
-    }
-    /* c8 ignore start */
-    const securityArchive = Query.hasSecuritySelectors(allowScriptsQuery) ?
-        await SecurityArchive.start({
-            nodes: [...graph.nodes.values()],
-        })
-        : undefined;
-    /* c8 ignore stop */
-    const edges = graph.edges;
-    const nodes = new Set(graph.nodes.values());
-    const importers = graph.importers;
-    const query = new Query({
-        edges,
-        nodes,
-        importers,
-        securityArchive,
-    });
-    const { nodes: resultNodes } = await query.search(allowScriptsQuery, {
-        signal: new AbortController().signal,
-    });
-    return new Set(resultNodes.map(node => node.id));
-};
 /**
  * Make the current project match the supplied graph.
  */
@@ -65,6 +30,7 @@ export const reify = async (options) => {
             loadManifests: true,
         });
     const diff = new Diff(actual, graph);
+    carryBuildState(diff);
     // normalise importer edge specs and compute the package.json changes
     // before deciding whether anything needs reifying: an add whose target
     // is already in place has no node diff but still has a saved value to
@@ -173,7 +139,7 @@ const reify_ = async (options, diff, remover, saveImportersPackageJson) => {
     await build(diff, packageJson, scurry, allowScriptsNodes);
     // set the buildQueue on the result object containing
     // an array with all the ids of nodes that need building
-    res.buildQueue = [...diff.nodes.add]
+    res.buildQueue = [...diff.to.nodes.values()]
         .filter(node => node.buildState === 'needed')
         .map(node => node.id);
     // if we had to change the actual graph along the way,

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

@@ -2,15 +2,9 @@ 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 node = graph.nodes.get(nodeId);
     if (!node) {
@@ -51,10 +45,12 @@ 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,
                 });
             }

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 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 dep of the main
+ * importer, else 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;