@vltpkg/graph 1.4.0 → 1.6.0

package/dist/skills/mounts.js

@@ -0,0 +1,162 @@
+import { existsSync, lstatSync, readdirSync, readlinkSync, realpathSync, unlinkSync, } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { baseDepID, isDepID, joinDepIDTuple, splitDepID, } from '@vltpkg/dep-id';
+import { symlinkSyncMkdirp } from "../reify/symlink-sync.js";
+import { gitignoreNames } from "./gitignore.js";
+/** `lstat`, undefined when missing or unreadable (eg, ENOTDIR) */
+export const lstat = (path) => {
+    try {
+        return lstatSync(path, { throwIfNoEntry: false });
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Resolved path, lowercased on win32. */
+export const norm = (p) => {
+    const r = resolve(p);
+    return process.platform === 'win32' ? r.toLowerCase() : r;
+};
+/** realpath, else the resolved path when missing. */
+export const realOr = (p) => {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+};
+/**
+ * Same real path? Case-insensitive on win32.
+ */
+export const samePath = (a, b) => norm(realOr(a)) === norm(realOr(b));
+const storeSeg = `${sep}node_modules${sep}.vlt${sep}`;
+// resolved target of a symlink (or junction)
+const linkTarget = (link) => {
+    if (!lstat(link)?.isSymbolicLink())
+        return undefined;
+    let raw = readlinkSync(link);
+    if (raw.startsWith('\\\\?\\'))
+        raw = raw.slice(4);
+    return resolve(dirname(link), raw);
+};
+/**
+ * The target of `link` if it is a symlink (or junction) pointing into
+ * a `node_modules/.vlt` store, otherwise undefined. Any store, not just
+ * the project's: win32 junctions are absolute, so they point to the old
+ * store after the project is moved or copied.
+ */
+export const mountTarget = (link) => {
+    const target = linkTarget(link);
+    return target && norm(target).includes(storeSeg) ?
+        target
+        : undefined;
+};
+// the deepest workspace holding `target`
+const workspaceOf = (target, workspaces) => {
+    const t = norm(realOr(target));
+    return workspaces
+        .filter(({ path }) => {
+        const p = norm(path);
+        return t === p || t.startsWith(p + sep);
+    })
+        .sort((a, b) => b.path.length - a.path.length)[0];
+};
+/**
+ * The DepID of the last `node_modules/.vlt/<DepID>` segment of a raw
+ * link target, if valid.
+ */
+export const ownerOf = (target) => {
+    const parts = target.split(sep);
+    const seg = (i) => process.platform === 'win32' ? parts[i]?.toLowerCase() : parts[i];
+    for (let i = parts.length - 3; i >= 0; i--) {
+        if (seg(i) === 'node_modules' && seg(i + 1) === '.vlt') {
+            const id = parts[i + 2];
+            return isDepID(id) ? id : undefined;
+        }
+    }
+    return undefined;
+};
+/**
+ * One key per package: registry + name, else the DepID w/o its extra.
+ */
+export const packageKey = (id) => {
+    const t = splitDepID(id);
+    if (t[0] !== 'registry')
+        return baseDepID(id);
+    const spec = t[2];
+    const at = spec.lastIndexOf('@');
+    return joinDepIDTuple([
+        'registry',
+        t[1],
+        at > 0 ? spec.slice(0, at) : spec,
+    ]);
+};
+/**
+ * All vlt links in the given dirs: links into a `node_modules/.vlt`
+ * store, and links listed in the dir's `.gitignore` block (or `made`)
+ * into a workspace or dangling. Anything else is ignored.
+ */
+export const readMounts = (scan, { workspaces = [], made, } = {}) => {
+    const mounts = [];
+    for (const dir of scan) {
+        let entries;
+        try {
+            entries = readdirSync(dir.real);
+        }
+        catch {
+            continue;
+        }
+        const listed = gitignoreNames(dir.real);
+        for (const name of entries) {
+            const link = join(dir.real, name);
+            const mount = `${dir.dir}/${name}`;
+            const m = { dir, name, mount, link };
+            const target = mountTarget(link);
+            if (target) {
+                mounts.push({ ...m, target, owner: ownerOf(target) });
+                continue;
+            }
+            const wsTarget = (listed.has(name) || made?.has(mount)) && linkTarget(link);
+            if (!wsTarget)
+                continue;
+            if (!existsSync(wsTarget)) {
+                mounts.push({ ...m, target: wsTarget });
+                continue;
+            }
+            const ws = workspaceOf(wsTarget, workspaces);
+            if (ws)
+                mounts.push({ ...m, target: wsTarget, owner: ws.id });
+        }
+    }
+    return mounts.sort((a, b) => a.mount.localeCompare(b.mount, 'en'));
+};
+/**
+ * Link a skill at `<dir>/<skill>`. `'unchanged'` if the entry already
+ * is the skill. Never touches anything not managed by vlt (a store
+ * link, or `owned`): returns `'conflict'` instead.
+ */
+export const mountSkill = (skill, dir, owned = false) => {
+    const link = join(dir.real, skill.skill);
+    if (lstat(link)) {
+        if (samePath(link, skill.path))
+            return 'unchanged';
+        if (!owned && !mountTarget(link))
+            return 'conflict';
+        unlinkSync(link);
+    }
+    // junctions need no admin rights, but want an absolute target
+    if (process.platform === 'win32') {
+        symlinkSyncMkdirp(skill.path, link, 'junction');
+    }
+    else {
+        symlinkSyncMkdirp(relative(dir.real, skill.path), link, 'dir');
+    }
+    return 'linked';
+};
+/**
+ * Remove a vlt link. Its dir is kept.
+ */
+export const unmountSkill = (m) => {
+    unlinkSync(m.link);
+};

package/dist/uninstall.d.ts

@@ -1,14 +1,34 @@
+import type { DepID } from '@vltpkg/dep-id';
 import type { PackageInfoClient } from '@vltpkg/package-info';
 import type { LoadOptions } from './actual/load.ts';
 import type { RemoveImportersDependenciesMap } from './dependencies.ts';
+import type { ReifyResult } from './reify/index.ts';
+import type { Graph } from './graph.ts';
+import type { LinkSkillsResult } from './skills/index.ts';
 export type UninstallOptions = LoadOptions & {
     packageInfo: PackageInfoClient;
     allowScripts: string;
+    /**
+     * DSS query: packages whose agent skills get linked into the
+     * project's agent skill dirs after uninstall. Selectors may end with
+     * `:skill()`. Unset or `:not(*)`: none.
+     */
+    allowSkills?: string;
+    /**
+     * agent skill dirs, relative to projectRoot. Unset: detect; `[]`:
+     * none
+     */
+    skillsDirs?: string[];
+    /** store dirs of these nodes are never removed, eg the running vlt */
+    keepNodes?: ReadonlySet<DepID>;
 };
-export declare const uninstall: (options: UninstallOptions, remove?: RemoveImportersDependenciesMap) => Promise<{
-    graph: import("./graph.ts").Graph;
-    diff: undefined;
-} | {
-    graph: import("./graph.ts").Graph;
-    diff: import("./reify/index.ts").ReifyResult;
-}>;
+/**
+ * Result of {@link uninstall}.
+ */
+export type UninstallResult = {
+    graph: Graph;
+    diff?: ReifyResult;
+    /** skill links added or removed, if any */
+    skills?: LinkSkillsResult;
+};
+export declare const uninstall: (options: UninstallOptions, remove?: RemoveImportersDependenciesMap) => Promise<UninstallResult>;

package/dist/uninstall.js

@@ -8,7 +8,19 @@ import { RollbackRemove } from '@vltpkg/rollback-remove';
 import { Monorepo } from '@vltpkg/workspaces';
 import { existsSync, rmSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { assertQuery } from "./filter-nodes-by-query.js";
+import { assertSkillsDirs } from "./skills/dirs.js";
 export const uninstall = async (options, remove) => {
+    // unset or `:not(*)`: no skills work at all, the skills code never
+    // loads
+    const allowSkills = options.allowSkills === ':not(*)' ?
+        undefined
+        : options.allowSkills;
+    // fail before uninstalling, not after
+    if (allowSkills) {
+        await assertQuery(allowSkills, 'allow-skills', ['skill']);
+        assertSkillsDirs(options.projectRoot, options.skillsDirs);
+    }
     const mainManifest = options.packageJson.read(options.projectRoot);
     const modifiers = GraphModifier.maybeLoad(options);
     const remover = new RollbackRemove();
@@ -17,6 +29,7 @@ export const uninstall = async (options, remove) => {
         packageJson: options.packageJson,
         scurry: options.scurry,
     });
+    let result;
     try {
         // Load the actual graph before building the ideal graph so that
         // manifest data from installed packages can be used to hydrate
@@ -55,6 +68,7 @@ export const uninstall = async (options, remove) => {
                     ...options,
                     remove,
                     graph,
+                    modifiers,
                 })
                 : undefined;
             saveImportersPackageJson?.();
@@ -71,7 +85,7 @@ export const uninstall = async (options, remove) => {
             modifiers,
             remover,
         });
-        return { graph, diff };
+        result = { graph, diff };
         /* c8 ignore start */
     }
     catch (err) {
@@ -87,4 +101,14 @@ export const uninstall = async (options, remove) => {
         throw err;
     }
     /* c8 ignore stop */
+    // after the try: a link failure must not roll back the uninstall
+    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/update.d.ts

@@ -1,12 +1,32 @@
 import type { PackageInfoClient } from '@vltpkg/package-info';
 import type { LoadOptions } from './actual/load.ts';
 import { Graph } from './graph.ts';
+import type { DepID } from '@vltpkg/dep-id';
+import type { Diff } from './diff.ts';
+import type { LinkSkillsResult } from './skills/index.ts';
 export type UpdateOptions = LoadOptions & {
     packageInfo: PackageInfoClient;
     allowScripts: string;
+    /**
+     * DSS query: packages whose agent skills get linked into the
+     * project's agent skill dirs after update. 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 update: (options: UpdateOptions) => Promise<{
-    buildQueue: import("@vltpkg/dep-id").DepID[] | undefined;
+/**
+ * Result of {@link update}.
+ */
+export type UpdateResult = {
+    buildQueue?: DepID[];
     graph: Graph;
-    diff: import("./diff.ts").Diff;
-}>;
+    diff?: Diff;
+    /** skill links added or removed, if any */
+    skills?: LinkSkillsResult;
+};
+export declare const update: (options: UpdateOptions) => Promise<UpdateResult>;

package/dist/update.js

@@ -12,6 +12,8 @@ import { RollbackRemove } from '@vltpkg/rollback-remove';
 import { Monorepo } from '@vltpkg/workspaces';
 import { existsSync, rmSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { assertQuery } from "./filter-nodes-by-query.js";
+import { assertSkillsDirs } from "./skills/dirs.js";
 /**
  * Graph to update from. `-w` filtered: the lockfile (else installed)
  * graph minus the selected workspaces' deps, so only those re-resolve
@@ -45,6 +47,16 @@ const startingGraph = (options, monorepo) => {
     return graph;
 };
 export const update = async (options) => {
+    // unset or `:not(*)`: no skills work at all, the skills code never
+    // loads
+    const allowSkills = options.allowSkills === ':not(*)' ?
+        undefined
+        : options.allowSkills;
+    // fail before updating, not after
+    if (allowSkills) {
+        await assertQuery(allowSkills, 'allow-skills', ['skill']);
+        assertSkillsDirs(options.projectRoot, options.skillsDirs);
+    }
     let mainManifest = undefined;
     try {
         mainManifest = options.packageJson.read(options.projectRoot);
@@ -66,6 +78,7 @@ export const update = async (options) => {
         packageJson: options.packageJson,
         scurry: options.scurry,
     });
+    let result;
     try {
         const done = graphStep('build');
         const graph = await buildIdealFromStartingGraph({
@@ -94,7 +107,7 @@ export const update = async (options) => {
             remover,
             update: true,
         });
-        return { buildQueue, graph, diff };
+        result = { buildQueue, graph, diff };
         /* c8 ignore start */
     }
     catch (err) {
@@ -110,4 +123,14 @@ export const update = async (options) => {
         throw err;
     }
     /* c8 ignore stop */
+    // after the try: a link failure must not roll back the update
+    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/visualization/mermaid-output.d.ts

@@ -1,9 +1,17 @@
+import type { DepID } from '@vltpkg/dep-id';
 import type { EdgeLike, NodeLike } from '@vltpkg/types';
+/** A leaf drawn under a graph node: node label, optional edge label. */
+export type MermaidChild = {
+    label: string;
+    edge?: string;
+};
 export type MermaidOutputGraph = {
     edges: EdgeLike[];
     importers: Set<NodeLike>;
     nodes: NodeLike[];
     highlightSelection?: boolean;
+    /** leaves to draw under included nodes (class `b`), eg: skills */
+    children?: Map<DepID, MermaidChild[]>;
 };
 /**
  * Generates a short identifier for a given index following the pattern:

package/dist/visualization/mermaid-output.js

@@ -1,6 +1,7 @@
 import { Edge } from "../edge.js";
 import { Node } from "../node.js";
 let missingCount = 0;
+const escapeLabel = (s) => s.replaceAll('"', '#quot;').replaceAll('@', '#64;');
 const isSelected = (options, edge, node) => (!node || options.nodes.includes(node)) &&
     /* c8 ignore next */ (!edge || options.edges.includes(edge));
 /**
@@ -72,7 +73,7 @@ const nodeRef = (node, labeledNodes, depIdMapping, options) => {
     labeledNodes.add(node.id);
     return `${shortId}("${String(node).replaceAll('@', '#64;')}")${selectedClass}`;
 };
-function parseNode(seenNodes, labeledNodes, includedItems, depIdMapping, options, node, isImporter = false) {
+function parseNode(seenNodes, labeledNodes, includedItems, depIdMapping, options, leaves, node, isImporter = false) {
     if (seenNodes.has(node.id) || !includedItems.get(node)) {
         return '';
     }
@@ -87,8 +88,10 @@ function parseNode(seenNodes, labeledNodes, includedItems, depIdMapping, options
         ...node.edgesOut.values(),
         ...(node.workspaces?.values() ?? []),
     ];
-    const edges = allEdges
-        .map(e => parseEdge(seenNodes, labeledNodes, includedItems, depIdMapping, options, e))
+    const edges = [
+        leaves.get(node.id),
+        ...allEdges.map(e => parseEdge(seenNodes, labeledNodes, includedItems, depIdMapping, options, leaves, e)),
+    ]
         .filter(Boolean)
         .join('\n');
     // Only render node standalone for importers, others are rendered as part of edges
@@ -98,7 +101,7 @@ function parseNode(seenNodes, labeledNodes, includedItems, depIdMapping, options
     }
     return edges;
 }
-function parseEdge(seenNodes, labeledNodes, includedItems, depIdMapping, options, edge) {
+function parseEdge(seenNodes, labeledNodes, includedItems, depIdMapping, options, leaves, edge) {
     if (!includedItems.get(edge)) {
         return '';
     }
@@ -112,14 +115,14 @@ function parseEdge(seenNodes, labeledNodes, includedItems, depIdMapping, options
     // Label the target node first so that if it's referenced again later in the graph,
     // it will use the short identifier instead of repeating the full label.
     const toRef = nodeRef(edge.to, labeledNodes, depIdMapping, options);
-    const childEdges = parseNode(seenNodes, labeledNodes, includedItems, depIdMapping, options, edge.to);
+    const childEdges = parseNode(seenNodes, labeledNodes, includedItems, depIdMapping, options, leaves, edge.to);
     return edgeResult + toRef + (childEdges ? '\n' + childEdges : '');
 }
 /**
  * Returns a mermaid string representation of the graph.
  */
 export function mermaidOutput(options) {
-    const { edges, importers, nodes, highlightSelection } = options;
+    const { edges, importers, nodes, highlightSelection, children } = options;
     const seen = new Set();
     const includedItems = new Map();
     const traverse = new Set([...importers].map(i => ({ self: i, parent: undefined })));
@@ -157,14 +160,28 @@ export function mermaidOutput(options) {
     }
     // Create DepID to short identifier mapping
     const depIdMapping = createDepIdMapping(importers);
+    // leaf lines per node, ids after the graph's
+    const leaves = new Map();
+    let leafIndex = depIdMapping.size;
+    for (const [id, items] of children ?? []) {
+        const from = depIdMapping.get(id);
+        if (!from || !items.length)
+            continue;
+        leaves.set(id, items
+            .map(({ label, edge }) => `${from} -->${edge === undefined ? '' : `|"${escapeLabel(edge)}"|`} ${generateShortId(leafIndex++)}("${escapeLabel(label)}"):::b`)
+            .join('\n'));
+    }
     // Track nodes that have had their label printed (shared across all importers)
     const labeledNodes = new Set();
     // Track nodes that have been processed (shared across all importers to avoid duplicates)
     const seenNodes = new Set();
     const graphOutput = [...importers]
-        .map(i => parseNode(seenNodes, labeledNodes, includedItems, depIdMapping, options, i, true))
+        .map(i => parseNode(seenNodes, labeledNodes, includedItems, depIdMapping, options, leaves, i, true))
         .filter(Boolean)
         .join('\n');
-    const styleDefinition = highlightSelection ? '\nclassDef a fill:gold,color:#242424' : '';
+    const styleDefinition = (highlightSelection ?
+        '\nclassDef a fill:gold,color:#242424'
+        : '') +
+        (leaves.size ? '\nclassDef b fill:turquoise,color:#242424' : '');
     return 'flowchart TD\n' + graphOutput + styleDefinition;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/graph",
   "description": "A library that helps understanding & expressing what happens on an install",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -13,26 +13,26 @@
     "url": "http://vlt.sh"
   },
   "dependencies": {
-    "@vltpkg/cmd-shim": "1.4.0",
-    "@vltpkg/dep-id": "1.4.0",
-    "@vltpkg/dss-breadcrumb": "1.4.0",
-    "@vltpkg/error-cause": "1.4.0",
-    "@vltpkg/fast-split": "1.4.0",
-    "@vltpkg/graph-run": "1.4.0",
-    "@vltpkg/init": "1.4.0",
-    "@vltpkg/output": "1.4.0",
-    "@vltpkg/package-info": "1.4.0",
-    "@vltpkg/package-json": "1.4.0",
-    "@vltpkg/pick-manifest": "1.4.0",
-    "@vltpkg/query": "1.4.0",
-    "@vltpkg/rollback-remove": "1.4.0",
-    "@vltpkg/run": "1.4.0",
-    "@vltpkg/satisfies": "1.4.0",
-    "@vltpkg/security-archive": "1.4.0",
-    "@vltpkg/spec": "1.4.0",
-    "@vltpkg/types": "1.4.0",
-    "@vltpkg/vlt-json": "1.4.0",
-    "@vltpkg/workspaces": "1.4.0",
+    "@vltpkg/cmd-shim": "1.6.0",
+    "@vltpkg/dep-id": "1.6.0",
+    "@vltpkg/dss-breadcrumb": "1.6.0",
+    "@vltpkg/error-cause": "1.6.0",
+    "@vltpkg/fast-split": "1.6.0",
+    "@vltpkg/graph-run": "1.6.0",
+    "@vltpkg/init": "1.6.0",
+    "@vltpkg/output": "1.6.0",
+    "@vltpkg/package-info": "1.6.0",
+    "@vltpkg/package-json": "1.6.0",
+    "@vltpkg/pick-manifest": "1.6.0",
+    "@vltpkg/query": "1.6.0",
+    "@vltpkg/rollback-remove": "1.6.0",
+    "@vltpkg/run": "1.6.0",
+    "@vltpkg/satisfies": "1.6.0",
+    "@vltpkg/security-archive": "1.6.0",
+    "@vltpkg/spec": "1.6.0",
+    "@vltpkg/types": "1.6.0",
+    "@vltpkg/vlt-json": "1.6.0",
+    "@vltpkg/workspaces": "1.6.0",
     "path-scurry": "^2.0.1",
     "promise-call-limit": "^3.0.2"
   },