@vltpkg/graph 1.4.0 → 1.5.0

package/README.md

@@ -78,15 +78,71 @@ minimal filesystem changes (creating/deleting links, writing
 lockfiles, hoisting, lifecycle scripts) to make the on-disk install
 match the Ideal graph. Returns `{ diff, buildQueue }`.
 
-### `install(options, add?): Promise<{ graph, diff, buildQueue }>`
+### `install(options, add?): Promise<{ graph, diff, buildQueue, skills? }>`
 
 High-level install orchestration that handles graph building, reify,
 and lockfile management. Supports `--frozen-lockfile`,
-`--clean-install`, and `--lockfile-only` modes.
+`--clean-install`, and `--lockfile-only` modes. With `allowSkills` (a
+DSS query whose selectors may end with `:skill()`, validated up
+front), links the agent skills of matching packages afterwards (see
+`linkSkills`) into `skillsDirs` (unset: detected) and returns the
+result as `skills`. Unset or `:not(*)`: no skills work, the skills
+code is not loaded. `update` and `uninstall` take `allowSkills` too.
+
+### `listSkills(options): Promise<{ project, graph, skills, dirs, skipped? }>`
+
+Lists the agent skills (dirs with a `SKILL.md`, see
+https://agentskills.io/specification) shipped by installed packages in
+the vlt store (a root `SKILL.md`, then `<dir>/SKILL.md` in `skills/`,
+`dist/skills/` and `.agents/skills/`; the first skill of a name wins),
+from one version per package (a direct dep, else the highest), with
+the agent skill dirs each is linked in, `project`: the main importer
+name, and the `graph`. `options.target` is a DSS query selecting
+packages (default `*`); a selector ending with `:skill(<name>, …)`
+keeps only those skills of its packages. Creates nothing.
+
+### `linkSkills(options): Promise<LinkSkillsResult>`
+
+Links the skills picked by `options.target` (as in `listSkills`; comma
+lists are a union) into each agent skill dir (junctions on Windows):
+`options.skillsDirs`, else `.agents/skills`, plus `<folder>/skills`
+for each agent folder at the project root, `.claude/skills` inside
+Claude Code (`options.env`), and existing `.<name>/skills` dirs. Dirs
+must resolve inside the project, not in `node_modules` (else
+`skipped`, as are fs errors) and are created only when a skill is
+picked. One package per name, among picked skills, in every dir: the
+one the first existing link points to while its skill is installed,
+else a direct dep, then DepID; the others are reported in `conflicts`
+as `<mount> (<package>)`. Installs keep a dir's link to another
+installed skill. A link follows its package to the picked version.
+Then removes links whose skill is no longer installed: dangling,
+package not in the graph, or no longer shipped. With `options.apply`,
+also removes every other vlt link in the scanned dirs. Only links
+pointing into a `node_modules/.vlt` store are ever replaced or
+removed; anything else in the way is reported in `conflicts`. Keeps a
+marked block of link names in each dir's `.gitignore` (`gitignore`
+lists the ones it could not edit). Linked packages get private copies
+of files hardlinked from the global store. `:skill()` patterns that
+match no skill of their packages are returned in `unmatched`. Security
+queries fail closed: skills of npm registry packages with no security
+data are left out (in `listSkills` too) and returned in `unscanned`
+with `unscannedReason` (by `linkSkills`: unless still linked).
+
+### `assertQuery(selector, flag, partSelectors?): Promise<void>`
+
+Throws `EUSAGE` unless `selector` is a valid DSS query.
+`partSelectors` (e.g. `['skill']`) allows `:skill()`.
+
+### `hasSkills(node): Promise<boolean>`
+
+`:skills` provider for `Query`: true when an installed package ships
+agent skills, as `listSkills` finds them.
 
 ### `mermaidOutput(graph): string`
 
-Generates Mermaid flowchart syntax from graph data.
+Generates Mermaid flowchart syntax from graph data. `graph.children`
+(`Map<DepID, { label, edge? }[]>`) draws leaves under nodes, e.g.
+`vlt skills list` skills.
 
 ### `humanReadableOutput(graph, options): string`
 

package/dist/actual/load.js

@@ -2,7 +2,7 @@ import { asDepID, hydrate, joinDepIDTuple, joinExtra, splitDepID, splitExtra, }
 import { Spec } from '@vltpkg/spec';
 import { graphStep } from '@vltpkg/output';
 import { isObject } from '@vltpkg/types';
-import { shorten, getRawDependencies, getDependencies, } from "../dependencies.js";
+import { shorten, getRawDependencies, getDependencies, asDependencySpecError, } from "../dependencies.js";
 import { Graph } from "../graph.js";
 import { loadHidden } from "../lockfile/load.js";
 import { saveHidden } from "../lockfile/save.js";
@@ -178,13 +178,19 @@ const parseDir = (options, scurry, packageJson, depsFound, graph, fromNode, curr
             const type = deps?.type || 'dependencies';
             const bareSpec = deps?.bareSpec || '*';
             const depType = shorten(type, alias, fromNode.manifest);
-            let spec = Spec.parse(alias, bareSpec, {
-                ...options,
-                // fall back to options.registry (which the lockfile merges into)
-                // so importer-level edges don't silently revert to the default
-                // npm registry. see vltpkg/vltpkg#1580.
-                registry: fromNode.registry ?? options.registry,
-            });
+            let spec;
+            try {
+                spec = Spec.parse(alias, bareSpec, {
+                    ...options,
+                    // fall back to options.registry (which the lockfile merges into)
+                    // so importer-level edges don't silently revert to the default
+                    // npm registry. see vltpkg/vltpkg#1580.
+                    registry: fromNode.registry ?? options.registry,
+                });
+            }
+            catch (er) {
+                throw asDependencySpecError(er, fromNode, depType);
+            }
             // Check for active modifiers and replace spec if a modifier is complete
             const { spec: modifiedSpec, queryModifier } = maybeApplyModifierToSpec(spec, alias, modifierRefs);
             spec = modifiedSpec;
@@ -240,10 +246,16 @@ const parseDir = (options, scurry, packageJson, depsFound, graph, fromNode, curr
     for (const { name, type, bareSpec } of dependencies.values()) {
         if (!seenDeps.has(name)) {
             const depType = shorten(type, name, fromNode.manifest);
-            let spec = Spec.parse(name, bareSpec, {
-                ...options,
-                registry: fromNode.registry ?? options.registry,
-            });
+            let spec;
+            try {
+                spec = Spec.parse(name, bareSpec, {
+                    ...options,
+                    registry: fromNode.registry ?? options.registry,
+                });
+            }
+            catch (er) {
+                throw asDependencySpecError(er, fromNode, depType);
+            }
             // Check for active modifiers and replace spec for missing dependencies
             const { spec: modifiedSpec, queryModifier } = maybeApplyModifierToSpec(spec, name, modifierRefs);
             // a `-` modifier removes the dependency, so it is not missing

package/dist/build.js

@@ -4,10 +4,12 @@ import { build as reifyBuild } from "./reify/build.js";
 import { Diff } from "./diff.js";
 import { Graph } from "./graph.js";
 import { Query } from '@vltpkg/query';
-import { SecurityArchive } from '@vltpkg/security-archive';
+import { SecurityArchive, usesNpmRegistry, } from '@vltpkg/security-archive';
 import { saveHidden } from "./lockfile/save.js";
+import { hasSkills } from "./skills/lazy.js";
 /**
- * Filter nodes using a DSS query string
+ * Filter nodes using a DSS query string. `skipped` holds matched nodes
+ * left out because they have no security data, `skippedReason` says why.
  */
 const filterNodesByQuery = async (targetQuery, graph) => {
     /* c8 ignore start */
@@ -25,11 +27,30 @@ const filterNodesByQuery = async (targetQuery, graph) => {
         nodes,
         importers,
         securityArchive,
+        hasSkills,
     });
     const { nodes: resultNodes } = await query.search(targetQuery, {
         signal: new AbortController().signal,
     });
-    return new Set(resultNodes.map(node => node.id));
+    // fail closed: never run scripts of pkgs with no security data, be it
+    // from a timed out request or not scanned by socket.dev yet
+    const allowed = new Set();
+    const skipped = new Set();
+    for (const node of resultNodes) {
+        if (securityArchive &&
+            !securityArchive.has(node.id) &&
+            usesNpmRegistry(node)) {
+            skipped.add(node.id);
+        }
+        else {
+            allowed.add(node.id);
+        }
+    }
+    return {
+        allowed,
+        skipped,
+        skippedReason: securityArchive?.timedOut ? 'timeout' : 'unscanned',
+    };
 };
 /**
  * Build the project based on actual graph state and build state from lockfile
@@ -54,7 +75,7 @@ export const build = async (options) => {
         loadManifests: true,
     });
     // Filter nodes using target query provided
-    const targetFilteredNodes = await filterNodesByQuery(target, actualGraph);
+    const { allowed: targetFilteredNodes, skipped, skippedReason, } = await filterNodesByQuery(target, actualGraph);
     // Create a total diff including the actual graph as 'to'
     const diff = new Diff(new Graph({
         ...options,
@@ -83,5 +104,9 @@ export const build = async (options) => {
             graph: actualGraph,
         });
     }
-    return buildResult;
+    // needed builds left out for lack of security data
+    const skippedNodes = [...diff.nodes.add].filter(node => skipped.has(node.id));
+    return skippedNodes.length ?
+        { ...buildResult, skipped: skippedNodes, skippedReason }
+        : buildResult;
 };

package/dist/dependencies.d.ts

@@ -74,6 +74,17 @@ export declare const shorten: (typeLong: DependencyTypeLong, name?: string, mani
  */
 export declare const shouldInstallDepType: (node: NodeLike, depType: DependencyTypeLong) => boolean;
 export declare const getRawDependencies: (node: NodeLike) => Map<string, RawDependency>;
+/**
+ * Maps short dependency types to the `package.json` field declaring them.
+ */
+export declare const longDependencyTypeNames: Record<DependencyTypeShort, DependencyTypeLong>;
+/**
+ * Point an `ECONFIG` spec error (eg: an undefined `catalog:`) at the
+ * package.json & dependency type that declared it. `source` names the
+ * file the spec was read from when not the manifest (eg: a lockfile).
+ * Other values are returned as is.
+ */
+export declare const asDependencySpecError: (er: unknown, from: NodeLike, type: DependencyTypeShort, source?: string) => unknown;
 /**
  * Retrieves a map of all dependencies, of all types, that can be inferred
  * from a given node manifest, including missing dependencies.

package/dist/dependencies.js

@@ -1,6 +1,6 @@
 import { error } from '@vltpkg/error-cause';
 import { Spec } from '@vltpkg/spec/browser';
-import { dependencyTypes, longDependencyTypes, shortDependencyTypes, } from '@vltpkg/types';
+import { isErrorWithCause, isObject, dependencyTypes, longDependencyTypes, shortDependencyTypes, } from '@vltpkg/types';
 export const isDependencyTypeShort = (obj) => shortDependencyTypes.has(obj);
 export const isDependencySaveType = (obj) => shortDependencyTypes.has(obj) ||
     obj === 'implicit';
@@ -113,6 +113,40 @@ export const getRawDependencies = (node) => {
     }
     return dependencies;
 };
+/**
+ * Maps short dependency types to the `package.json` field declaring them.
+ */
+export const longDependencyTypeNames = {
+    prod: 'dependencies',
+    dev: 'devDependencies',
+    optional: 'optionalDependencies',
+    peer: 'peerDependencies',
+    peerOptional: 'peerDependencies',
+};
+// `./`-relative unless already relative or absolute
+const manifestPath = ({ location = '.' }) => `${/^(?:\.\.?(?:\/|$)|\/|[a-z]:)/i.test(location) ? '' : './'}${location}/package.json`;
+/**
+ * Point an `ECONFIG` spec error (eg: an undefined `catalog:`) at the
+ * package.json & dependency type that declared it. `source` names the
+ * file the spec was read from when not the manifest (eg: a lockfile).
+ * Other values are returned as is.
+ */
+export const asDependencySpecError = (er, from, type, source) => {
+    if (!isErrorWithCause(er) ||
+        !isObject(er.cause) ||
+        er.cause.code !== 'ECONFIG') {
+        return er;
+    }
+    const pj = manifestPath(from);
+    const depType = longDependencyTypeNames[type];
+    return error(er.message, {
+        ...er.cause,
+        from: source ?
+            `${source} (${pj} ${depType})`
+            : `${pj} (${depType})`,
+        cause: er,
+    }, asDependencySpecError);
+};
 /**
  * Retrieves a map of all dependencies, of all types, that can be inferred
  * from a given node manifest, including missing dependencies.
@@ -122,12 +156,18 @@ export const getDependencies = (node, options) => {
     const dependencies = getRawDependencies(node);
     for (const { name, type, bareSpec } of dependencies.values()) {
         const depType = shorten(type, name, node.manifest);
-        const spec = Spec.parse(name, bareSpec, {
-            ...options,
-            // fall back to options.registry so deps don't lose the configured
-            // registry when the node itself has none. see vltpkg/vltpkg#1580.
-            registry: node.registry ?? options.registry,
-        });
+        let spec;
+        try {
+            spec = Spec.parse(name, bareSpec, {
+                ...options,
+                // fall back to options.registry so deps don't lose the configured
+                // registry when the node itself has none. see vltpkg/vltpkg#1580.
+                registry: node.registry ?? options.registry,
+            });
+        }
+        catch (er) {
+            throw asDependencySpecError(er, node, depType);
+        }
         res.set(name, {
             spec,
             type: depType,

package/dist/filter-nodes-by-query.d.ts

@@ -0,0 +1,39 @@
+import type { QueryOptions } from '@vltpkg/query';
+import type { DepID } from '@vltpkg/dep-id';
+import type { Graph } from './graph.ts';
+/**
+ * One top-level selector of a query: the ids it matched, and its
+ * `:skill()` patterns (unset: every skill).
+ */
+export type QueryPartIds = {
+    ids: Set<DepID>;
+    patterns?: string[];
+};
+/**
+ * Matched npm registry pkgs with no security data, and why: the
+ * request timed out, or socket.dev has not scanned them yet.
+ */
+export type Unscanned = {
+    ids: Set<DepID>;
+    reason: 'timeout' | 'unscanned';
+};
+/**
+ * Filter nodes using a DSS query string
+ */
+export declare const filterNodesByQuery: (graph: Graph, selector?: string) => Promise<Set<DepID>>;
+/**
+ * {@link filterNodesByQuery} for `allow-skills`: accepts `:skill()`,
+ * and also returns one entry per top-level selector. Unlike it, keeps
+ * `unscanned` pkgs: callers must drop them (fail closed).
+ */
+export declare const filterNodesByQueryParts: (graph: Graph, selector?: string) => Promise<{
+    ids: Set<DepID>;
+    parts: QueryPartIds[];
+    unscanned?: Unscanned;
+}>;
+/**
+ * Throw `EUSAGE` unless `selector` is a valid DSS query. Runs it on an
+ * empty graph: no fs, network or security data needed. `partSelectors`
+ * allows e.g. `:skill()`.
+ */
+export declare const assertQuery: (selector: string, flag: string, partSelectors?: QueryOptions["partSelectors"]) => Promise<void>;

package/dist/filter-nodes-by-query.js

@@ -0,0 +1,100 @@
+import { error } from '@vltpkg/error-cause';
+import { Query } from '@vltpkg/query';
+import { SecurityArchive, usesNpmRegistry, } from '@vltpkg/security-archive';
+import { asError } from '@vltpkg/types';
+import { hasSkills } from "./skills/lazy.js";
+const toIds = (nodes) => new Set(nodes.map(n => n.id));
+const search = async (graph, selector, partSelectors) => {
+    /* c8 ignore start */
+    const securityArchive = Query.hasSecuritySelectors(selector) ?
+        await SecurityArchive.start({
+            nodes: [...graph.nodes.values()],
+        })
+        : undefined;
+    /* c8 ignore stop */
+    const res = await new Query({
+        edges: graph.edges,
+        nodes: new Set(graph.nodes.values()),
+        importers: graph.importers,
+        securityArchive,
+        hasSkills,
+        partSelectors,
+    }).search(selector, { signal: new AbortController().signal });
+    if (!securityArchive)
+        return res;
+    // fail closed: callers skip pkgs with no security data, be it from a
+    // timed out request or not scanned by socket.dev yet
+    const ids = toIds(res.nodes.filter(n => !securityArchive.has(n.id) && usesNpmRegistry(n)));
+    if (!ids.size)
+        return res;
+    const reason = securityArchive.timedOut ? 'timeout' : 'unscanned';
+    return { ...res, unscanned: { ids, reason } };
+};
+/**
+ * Filter nodes using a DSS query string
+ */
+export const filterNodesByQuery = async (graph, selector) => {
+    // shortcut no packages included
+    if (selector === ':not(*)' /* c8 ignore next */ || !selector) {
+        return new Set();
+    }
+    // shortcut all packages included
+    if (selector === '*') {
+        return new Set(graph.nodes.keys());
+    }
+    const { nodes, unscanned } = await search(graph, selector);
+    return toIds(nodes.filter(n => !unscanned?.ids.has(n.id)));
+};
+/**
+ * {@link filterNodesByQuery} for `allow-skills`: accepts `:skill()`,
+ * and also returns one entry per top-level selector. Unlike it, keeps
+ * `unscanned` pkgs: callers must drop them (fail closed).
+ */
+export const filterNodesByQueryParts = async (graph, selector) => {
+    if (!selector || selector === ':not(*)') {
+        return { ids: new Set(), parts: [] };
+    }
+    if (selector === '*') {
+        const ids = new Set(graph.nodes.keys());
+        return { ids, parts: [{ ids }] };
+    }
+    const res = await search(graph, selector, ['skill']);
+    return {
+        ids: toIds(res.nodes),
+        /* c8 ignore next -- always set when opted in */
+        parts: (res.parts ?? []).map(p => ({
+            ids: toIds(p.nodes),
+            ...(p.patterns && { patterns: p.patterns }),
+        })),
+        ...(res.unscanned && { unscanned: res.unscanned }),
+    };
+};
+/**
+ * Throw `EUSAGE` unless `selector` is a valid DSS query. Runs it on an
+ * empty graph: no fs, network or security data needed. `partSelectors`
+ * allows e.g. `:skill()`.
+ */
+export const assertQuery = async (selector, flag, partSelectors) => {
+    try {
+        await new Query({
+            edges: new Set(),
+            nodes: new Set(),
+            importers: new Set(),
+            securityArchive: new Map(),
+            hasSkills,
+            partSelectors,
+        }).search(selector, { signal: new AbortController().signal });
+    }
+    catch (cause) {
+        const { message, cause: c } = asError(cause);
+        // a typo's suggestions, e.g. `:skill` for `:skills`
+        const validOptions = c?.validOptions ??
+            (c?.wanted === undefined ? undefined : [c.wanted]);
+        throw error(`Invalid --${flag} query: ${message}`, {
+            code: 'EUSAGE',
+            found: selector,
+            cause,
+            ...(validOptions && { validOptions }),
+        }, assertQuery);
+    }
+};

package/dist/ideal/append-nodes.js

@@ -5,7 +5,7 @@ import { satisfies } from '@vltpkg/satisfies';
 import { parse as parseVersion } from '@vltpkg/semver';
 import { longDependencyTypes, normalizeManifest } from '@vltpkg/types';
 import { fixupAddedNames } from "../fixup-added-names.js";
-import { addKey, shorten, shouldInstallDepType, } from "../dependencies.js";
+import { addKey, asDependencySpecError, shorten, shouldInstallDepType, } from "../dependencies.js";
 import { removeOptionalSubgraph } from "../remove-optional-subgraph.js";
 import { isPathSecurityError } from "../path-security-error.js";
 import { extractNode } from "../reify/extract-node.js";
@@ -549,15 +549,20 @@ const processPlacementTasks = async (graph, options, placementTasks, add, modifi
                     // might need to skip already placed peer deps here
                     if (bundled.has(name))
                         continue;
-                    const dep = {
-                        type: shorten(depTypeName, name, manifest),
-                        spec: Spec.parse(name, bareSpec, {
+                    const type = shorten(depTypeName, name, manifest);
+                    let depSpec;
+                    try {
+                        depSpec = Spec.parse(name, bareSpec, {
                             ...options,
                             // git/file/remote parents have no spec.registry, so fall
                             // back to the configured one. see vltpkg/vltpkg#1580.
                             registry: spec.registry ?? options.registry,
-                        }),
-                    };
+                        });
+                    }
+                    catch (er) {
+                        throw asDependencySpecError(er, node, type);
+                    }
+                    const dep = { type, spec: depSpec };
                     if (depTypeName === 'peerDependencies') {
                         nextPeerDeps.set(name, dep);
                     }

package/dist/ideal/get-importer-specs.js

@@ -1,5 +1,5 @@
 import { longDependencyTypes } from '@vltpkg/types';
-import { shorten, asDependency } from "../dependencies.js";
+import { shorten, asDependency, asDependencySpecError, } from "../dependencies.js";
 import { removeSatisfiedSpecs } from "./remove-satisfied-specs.js";
 import { Spec } from '@vltpkg/spec';
 const hasDepName = (importer, edge) => {
@@ -72,7 +72,13 @@ export const getImporterSpecs = (options) => {
                 edge.type === type) {
                 continue;
             }
-            const spec = Spec.parse(depName, depSpec, options);
+            let spec;
+            try {
+                spec = Spec.parse(depName, depSpec, options);
+            }
+            catch (er) {
+                throw asDependencySpecError(er, importer, type);
+            }
             // a `-` modifier removes this dependency, nothing to place; an
             // edge from before (e.g. a qualifier now matching) has to go
             if (options.modifiers?.removesImporterEdge(importer, spec)) {
@@ -137,11 +143,15 @@ export const getImporterSpecs = (options) => {
                     if (edge?.to && edge.spec.bareSpec === depSpec)
                         continue;
                     // add the dependency to the addDeps map
-                    const dependency = asDependency({
-                        spec: Spec.parse(depName, depSpec, options),
-                        type: shorten(depType, depName, manifest),
-                    });
-                    addDeps.set(depName, dependency);
+                    const type = shorten(depType, depName, manifest);
+                    let spec;
+                    try {
+                        spec = Spec.parse(depName, depSpec, options);
+                    }
+                    catch (er) {
+                        throw asDependencySpecError(er, node, type);
+                    }
+                    addDeps.set(depName, asDependency({ spec, type }));
                 }
             }
             // store in transientAdd if there are any dependencies

package/dist/index.d.ts

@@ -15,6 +15,9 @@ export * from './update.ts';
 export * from './diff.ts';
 export * from './modifiers.ts';
 export * from './virtual-root.ts';
+export type { DiscoveredSkills, LinkSkillsOptions, LinkSkillsResult, ListSkillsResult, MountResult, Skill, SkillFrontmatter, SkillMount, SkillRow, SkillsDir, SkillsOptions, UnmatchedPattern, UnscannedSkills, } from './skills/index.ts';
+export { hasSkills, linkSkills, listSkills } from './skills/lazy.ts';
+export { assertQuery } from './filter-nodes-by-query.ts';
 import type { LoadOptions as ActualLoadOptions } from './actual/load.ts';
 export declare const actual: {
     load: (options: ActualLoadOptions) => import("./graph.ts").Graph;

package/dist/index.js

@@ -15,6 +15,8 @@ export * from "./update.js";
 export * from "./diff.js";
 export * from "./modifiers.js";
 export * from "./virtual-root.js";
+export { hasSkills, linkSkills, listSkills } from "./skills/lazy.js";
+export { assertQuery } from "./filter-nodes-by-query.js";
 import { load as actualLoad } from "./actual/load.js";
 export const actual = { load: actualLoad };
 import { load as lockfileLoad, loadData as lockfileLoadData, } from "./lockfile/load.js";

package/dist/install.d.ts

@@ -3,19 +3,34 @@ import type { LoadOptions } from './actual/load.ts';
 import type { AddImportersDependenciesMap } from './dependencies.ts';
 import type { DepID } from '@vltpkg/dep-id';
 import type { Graph } from './index.ts';
+import type { Diff } from './diff.ts';
+import type { LinkSkillsResult } from './skills/index.ts';
 export type InstallOptions = LoadOptions & {
     packageInfo: PackageInfoClient;
     cleanInstall?: boolean;
     allowScripts: string;
     saveExact?: boolean;
     savePrefix?: string;
+    /**
+     * DSS query: packages whose agent skills get linked into the
+     * project's agent skill dirs after install. Selectors may end with
+     * `:skill()`. Unset or `:not(*)`: none.
+     */
+    allowSkills?: string;
+    /**
+     * agent skill dirs, relative to projectRoot. Unset: detect; `[]`:
+     * none
+     */
+    skillsDirs?: string[];
 };
-export declare const install: (options: InstallOptions, add?: AddImportersDependenciesMap) => Promise<{
+/**
+ * Result of {@link install}.
+ */
+export type InstallResult = {
+    buildQueue?: DepID[];
     graph: Graph;
-    diff: undefined;
-    buildQueue?: undefined;
-} | {
-    buildQueue: DepID[] | undefined;
-    graph: Graph;
-    diff: import("./diff.ts").Diff;
-}>;
+    diff?: Diff;
+    /** skill links added or removed, if any */
+    skills?: LinkSkillsResult;
+};
+export declare const install: (options: InstallOptions, add?: AddImportersDependenciesMap) => Promise<InstallResult>;

package/dist/install.js

@@ -16,11 +16,23 @@ import { getImporterSpecs } from "./ideal/get-importer-specs.js";
 import { lockfile } from "./index.js";
 import { updatePackageJson } from "./reify/update-importers-package-json.js";
 import { Monorepo } from '@vltpkg/workspaces';
+import { assertSkillsDirs } from "./skills/dirs.js";
+import { assertQuery } from "./filter-nodes-by-query.js";
 export const install = async (options, add) => {
     // Validate incompatible options
     if (options.lockfileOnly && options.cleanInstall) {
         throw error('Cannot use --lockfile-only with --clean-install (ci command). Clean install requires filesystem operations.');
     }
+    // unset or `:not(*)`: no skills work at all, the skills code never
+    // loads
+    const allowSkills = options.allowSkills === ':not(*)' ?
+        undefined
+        : options.allowSkills;
+    // fail before installing, not after
+    if (allowSkills) {
+        await assertQuery(allowSkills, 'allow-skills', ['skill']);
+        assertSkillsDirs(options.projectRoot, options.skillsDirs);
+    }
     if (options.expectLockfile || options.frozenLockfile) {
         const lockfilePath = resolve(options.projectRoot, 'vlt-lock.json');
         if (!existsSync(lockfilePath)) {
@@ -178,6 +190,7 @@ export const install = async (options, add) => {
             remover.confirm();
         }
     }
+    let result;
     try {
         const remove = Object.assign(new Map(), {
             modifiedDependencies: false,
@@ -247,7 +260,7 @@ export const install = async (options, add) => {
             remove,
             remover,
         });
-        return { buildQueue, graph, diff };
+        result = { buildQueue, graph, diff };
     }
     catch (err) {
         /* c8 ignore next */
@@ -262,4 +275,14 @@ export const install = async (options, add) => {
         catch { }
         throw err;
     }
+    // after the try: a link failure must not roll back the install
+    if (!allowSkills)
+        return result;
+    const { linkSkills } = await import("./skills/index.js");
+    result.skills = await linkSkills({
+        ...options,
+        graph: result.graph,
+        target: allowSkills,
+    });
+    return result;
 };

package/dist/lockfile/load-edges.js

@@ -3,7 +3,7 @@ import { error } from '@vltpkg/error-cause';
 import { fastSplit } from '@vltpkg/fast-split';
 import { Spec } from '@vltpkg/spec/browser';
 import { longDependencyTypes } from '@vltpkg/types';
-import { isDependencyTypeShort } from "../dependencies.js";
+import { asDependencySpecError, isDependencyTypeShort, } from "../dependencies.js";
 const retrieveNodeFromGraph = (key, value, graph, fromId, seenNodes) => {
     const foundNode = graph.nodes.get(asDepID(fromId));
     if (!foundNode) {
@@ -104,7 +104,15 @@ export const loadEdges = (graph, edges, options, cache) => {
         // loaded), so overriding here would always inject `undefined`
         // and silently revert to the default npm registry.
         // See vltpkg/vltpkg#1580.
-        const spec = parseEdgeSpec(specName, valRest.substring(0, vrSplit), options, cache);
+        let spec;
+        try {
+            spec = parseEdgeSpec(specName, valRest.substring(0, vrSplit), options, cache);
+        }
+        catch (er) {
+            // spec text is the lockfile's; hidden lockfile errors are
+            // swallowed, so only vlt-lock.json surfaces here
+            throw asDependencySpecError(er, fromNode, depType, 'vlt-lock.json');
+        }
         if (useOptimizations) {
             edgeProcessingQueue.push({
                 fromNode,