@vltpkg/graph 1.4.0 → 1.6.0

package/dist/skills/gitignore.d.ts

@@ -0,0 +1,18 @@
+export declare const GITIGNORE_BEGIN = "# >>> vlt agent skills (links into node_modules)";
+export declare const GITIGNORE_END = "# <<< vlt agent skills";
+/**
+ * Keep a `/<name>` line per vlt link in a marked block of
+ * `<dir>/.gitignore`: add `add`, drop `remove`. Other lines are kept.
+ * Written only when changed, created only to add a line, never
+ * removed. `'refused'`: `.gitignore` is not a regular file, or an fs
+ * error.
+ */
+export declare const editGitignore: (dir: string, edit: {
+    add: string[];
+    remove: string[];
+}) => "ok" | "refused";
+/**
+ * Names in vlt's block of `<dir>/.gitignore`: vlt's record of its links
+ * in `dir`. Empty if none or unreadable.
+ */
+export declare const gitignoreNames: (dir: string) => Set<string>;

package/dist/skills/gitignore.js

@@ -0,0 +1,82 @@
+import { lstatSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const GITIGNORE_BEGIN = '# >>> vlt agent skills (links into node_modules)';
+export const GITIGNORE_END = '# <<< vlt agent skills';
+const sorted = (names) => [...names]
+    .sort((a, b) => a.localeCompare(b, 'en'))
+    .map(n => `/${n}`);
+// vlt's block: `end` is -1 if none
+const findBlock = (lines) => {
+    const begin = lines.findIndex(l => l.trim() === GITIGNORE_BEGIN);
+    const end = lines.findIndex((l, i) => begin !== -1 && i > begin && l.trim() === GITIGNORE_END);
+    return { begin, end };
+};
+const update = (file, { add, remove }) => {
+    const st = lstatSync(file, { throwIfNoEntry: false });
+    if (st && !st.isFile())
+        return 'refused';
+    const text = st ? readFileSync(file, 'utf8') : '';
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    const lines = text.split(eol);
+    const { begin, end } = findBlock(lines);
+    let out;
+    if (end === -1) {
+        if (!add.length)
+            return 'ok';
+        out =
+            (text && !text.endsWith(eol) ? text + eol : text) +
+                [GITIGNORE_BEGIN, ...sorted(add), GITIGNORE_END].join(eol) +
+                eol;
+    }
+    else {
+        const rm = new Set(sorted(remove));
+        const block = lines
+            .slice(begin + 1, end)
+            .filter(l => !rm.has(l.trim()));
+        const have = new Set(block.map(l => l.trim()));
+        lines.splice(begin + 1, end - begin - 1, ...block, ...sorted(add).filter(l => !have.has(l)));
+        out = lines.join(eol);
+    }
+    if (out !== text)
+        writeFileSync(file, out);
+    return 'ok';
+};
+/**
+ * Keep a `/<name>` line per vlt link in a marked block of
+ * `<dir>/.gitignore`: add `add`, drop `remove`. Other lines are kept.
+ * Written only when changed, created only to add a line, never
+ * removed. `'refused'`: `.gitignore` is not a regular file, or an fs
+ * error.
+ */
+export const editGitignore = (dir, edit) => {
+    try {
+        return update(join(dir, '.gitignore'), edit);
+    }
+    catch {
+        return 'refused';
+    }
+};
+/**
+ * Names in vlt's block of `<dir>/.gitignore`: vlt's record of its links
+ * in `dir`. Empty if none or unreadable.
+ */
+export const gitignoreNames = (dir) => {
+    try {
+        const file = join(dir, '.gitignore');
+        if (!lstatSync(file, { throwIfNoEntry: false })?.isFile()) {
+            return new Set();
+        }
+        const lines = readFileSync(file, 'utf8').split(/\r?\n/);
+        const { begin, end } = findBlock(lines);
+        if (end === -1)
+            return new Set();
+        return new Set(lines
+            .slice(begin + 1, end)
+            .map(l => l.trim())
+            .filter(l => l.startsWith('/'))
+            .map(l => l.slice(1)));
+    }
+    catch {
+        return new Set();
+    }
+};

package/dist/skills/index.d.ts

@@ -0,0 +1,124 @@
+import type { LoadOptions } from '../actual/load.ts';
+import type { Graph } from '../graph.ts';
+import type { Skill } from './discover.ts';
+import type { UnmatchedPattern } from './mask.ts';
+export * from './discover.ts';
+export type { SkillMount, MountResult } from './mounts.ts';
+export type { SkillsDir } from './dirs.ts';
+export type { UnmatchedPattern } from './mask.ts';
+/**
+ * Options for {@link listSkills} and {@link linkSkills}.
+ */
+export type SkillsOptions = LoadOptions & {
+    /**
+     * DSS query selecting packages, selectors may end with `:skill()`;
+     * default `*`
+     */
+    target?: string;
+    /** graph to use instead of loading the actual one */
+    graph?: Graph;
+    /**
+     * agent skill dirs, relative to projectRoot. Unset: detect; `[]`:
+     * none
+     */
+    skillsDirs?: string[];
+    /** env read by detection; default `process.env` */
+    env?: Record<string, string | undefined>;
+};
+/**
+ * Options for {@link linkSkills}.
+ */
+export type LinkSkillsOptions = SkillsOptions & {
+    /** DSS query selecting packages */
+    target: string;
+    /**
+     * also remove every vlt link this selection does not make, in every
+     * scanned dir (`vlt skills link`). Default: only add links and remove
+     * links whose skill is gone (installs)
+     */
+    apply?: boolean;
+};
+/**
+ * A skill linked in one dir.
+ */
+export type SkillRow = Skill & {
+    /** the dir */
+    dir: string;
+    /** `<dir>/<skill>` */
+    mount: string;
+};
+/**
+ * Skills left out as their packages have no security data (fail
+ * closed).
+ */
+export type UnscannedSkills = {
+    /** `<skill> (<package>)` */
+    unscanned?: string[];
+    /** why: the request timed out, or socket.dev has not scanned them */
+    unscannedReason?: 'timeout' | 'unscanned';
+};
+/**
+ * Result of {@link listSkills}.
+ */
+export type ListSkillsResult = UnscannedSkills & {
+    /** main importer name, the tree root */
+    project: string;
+    /** the graph the skills were found in */
+    graph: Graph;
+    skills: Skill[];
+    /** target dirs */
+    dirs: string[];
+    /** targets dropped: `<dir> (<reason>)` */
+    skipped?: string[];
+};
+/**
+ * Result of {@link linkSkills}.
+ */
+export type LinkSkillsResult = UnscannedSkills & {
+    /** links created or re-pointed */
+    linked: SkillRow[];
+    /** selected skills already linked */
+    unchanged: SkillRow[];
+    /**
+     * vlt links removed (skill gone, or with `apply`: not selected or dir
+     * no longer a target): `/`-separated relative paths
+     */
+    removed: string[];
+    /**
+     * skipped per dir: path in use (`<mount>`), or name taken by another
+     * package (`<mount> (<package>)`)
+     */
+    conflicts: string[];
+    /** target dirs */
+    dirs: string[];
+    /** targets dropped: `<dir> (<reason>)` */
+    skipped?: string[];
+    /** `<dir>/.gitignore` files not updated: not a regular file, fs error */
+    gitignore?: string[];
+    /** `:skill()` patterns that matched no skill of their packages */
+    unmatched?: UnmatchedPattern[];
+};
+/**
+ * List the agent skills shipped by installed packages (`:skill()`
+ * applied, `unscanned` left out), and the agent skill dirs. Creates
+ * nothing.
+ */
+export declare const listSkills: (o: SkillsOptions) => Promise<ListSkillsResult>;
+/**
+ * Link the agent skills of the selected packages into each of the
+ * project's agent skill dirs (see `skillsDirs`), created only when a
+ * skill is picked. `target` selectors may end with `:skill()`. One
+ * package per name, among picked skills, in every dir: the package of
+ * the first existing link (in dir order), else rank (workspace or main
+ * importer dep, importer dep, transitive), then DepID; the others are
+ * reported. Installs keep a dir's link to another installed skill.
+ * A link follows its package to the picked version, in every scanned
+ * dir. Then remove vlt links whose skill is no longer installed (with
+ * `apply`: every vlt link not made here), and keep each dir's
+ * `.gitignore` block in sync (also vlt's record of workspace links).
+ * Linked packages get private copies of files hardlinked from the
+ * global store. Security queries fail closed: skills of packages with
+ * no security data are not linked, and reported in `unscanned` unless
+ * still linked.
+ */
+export declare const linkSkills: (o: LinkSkillsOptions) => Promise<LinkSkillsResult>;

package/dist/skills/index.js

@@ -0,0 +1,254 @@
+import { existsSync } from 'node:fs';
+import { Monorepo } from '@vltpkg/workspaces';
+import { load as loadActual } from "../actual/load.js";
+import { filterNodesByQueryParts } from "../filter-nodes-by-query.js";
+import { unshare } from "../reify/unshare.js";
+import { skillsDirs } from "./dirs.js";
+import { discoverSkills } from "./discover.js";
+import { editGitignore } from "./gitignore.js";
+import { maskSkills } from "./mask.js";
+import { mountSkill, packageKey, readMounts, realOr, samePath, unmountSkill, } from "./mounts.js";
+export * from "./discover.js";
+const lc = (s) => s.toLowerCase();
+const selectNodes = async (o) => {
+    const graph = o.graph ?? loadActual({ ...o, loadManifests: true });
+    const { ids, parts, unscanned } = await filterNodesByQueryParts(graph, o.target ?? '*');
+    const nodes = [...graph.nodes.values()].filter(n => ids.has(n.id));
+    return { graph, nodes, parts, unscanned };
+};
+const dirsOf = (o, create = false) => skillsDirs({
+    projectRoot: o.projectRoot,
+    configured: o.skillsDirs,
+    env: o.env,
+    create,
+});
+// every workspace, selected or not: owners of vlt links
+const workspaceDirs = (graph, scurry) => [...graph.importers]
+    .filter(n => !n.mainImporter)
+    .map(n => ({
+    id: n.id,
+    path: realOr(n.resolvedLocation(scurry)),
+}));
+// every workspace, loaded or not (`-w`)
+const allWorkspaces = (m) => m ?
+    [
+        ...Monorepo.load(m.projectRoot, {
+            config: m.config,
+            scurry: m.scurry,
+            packageJson: m.packageJson,
+        }).values(),
+    ].map(ws => ({ id: ws.id, path: realOr(ws.fullpath) }))
+    : [];
+// packages behind live vlt links
+const liveOwners = (mounts) => mounts.flatMap(m => m.owner && existsSync(m.target) ? [m.owner] : []);
+// private copies of store-hardlinked files: edits via skill links
+// must not reach the global store
+const unshareSkills = async (graph, ids, scurry) => {
+    for (const id of new Set(ids)) {
+        const node = graph.nodes.get(id);
+        if (node?.inVltStore())
+            await unshare(node.resolvedLocation(scurry));
+    }
+};
+// `vlt ls` style
+const label = (s) => {
+    const pkg = s.version ? `${s.name}@${s.version}` : s.name;
+    return s.alias ? `${s.alias} (${pkg})` : pkg;
+};
+// apply the mask; fail closed: skills of `unscanned` pkgs are dropped,
+// and reported unless another package's skill takes the name
+const pick = (found, parts, unscanned) => {
+    const { skills: masked, unmatched } = maskSkills(found, parts);
+    const ok = (s) => !unscanned?.ids.has(s.id);
+    const picked = masked.filter(ok);
+    const names = new Set(picked.map(s => lc(s.skill)));
+    const dropped = masked.filter(s => !ok(s) && !names.has(lc(s.skill)));
+    return { skills: found.filter(ok), picked, unmatched, dropped };
+};
+const report = (dropped, unscanned) => unscanned && dropped.length ?
+    {
+        unscanned: dropped.map(s => `${s.skill} (${label(s)})`),
+        unscannedReason: unscanned.reason,
+    }
+    : {};
+/**
+ * List the agent skills shipped by installed packages (`:skill()`
+ * applied, `unscanned` left out), and the agent skill dirs. Creates
+ * nothing.
+ */
+export const listSkills = async (o) => {
+    const { graph, nodes, parts, unscanned } = await selectNodes(o);
+    const { targets, scan, skipped } = dirsOf(o);
+    const { skills } = discoverSkills(nodes, o.scurry, readMounts(scan, { workspaces: workspaceDirs(graph, o.scurry) }));
+    const { picked, dropped } = pick(skills, parts, unscanned);
+    return {
+        project: graph.mainImporter.name,
+        graph,
+        skills: picked,
+        dirs: targets.map(d => d.dir),
+        ...(skipped.length ? { skipped } : null),
+        ...report(dropped, unscanned),
+    };
+};
+/**
+ * Link the agent skills of the selected packages into each of the
+ * project's agent skill dirs (see `skillsDirs`), created only when a
+ * skill is picked. `target` selectors may end with `:skill()`. One
+ * package per name, among picked skills, in every dir: the package of
+ * the first existing link (in dir order), else rank (workspace or main
+ * importer dep, importer dep, transitive), then DepID; the others are
+ * reported. Installs keep a dir's link to another installed skill.
+ * A link follows its package to the picked version, in every scanned
+ * dir. Then remove vlt links whose skill is no longer installed (with
+ * `apply`: every vlt link not made here), and keep each dir's
+ * `.gitignore` block in sync (also vlt's record of workspace links).
+ * Linked packages get private copies of files hardlinked from the
+ * global store. Security queries fail closed: skills of packages with
+ * no security data are not linked, and reported in `unscanned` unless
+ * still linked.
+ */
+export const linkSkills = async (o) => {
+    const { graph, nodes, parts, unscanned } = await selectNodes(o);
+    const { skills: found, scanned } = discoverSkills(nodes, o.scurry);
+    const { skills, picked, unmatched, dropped } = pick(found, parts, unscanned);
+    const inMask = new Set(picked);
+    const { targets, scan, skipped } = dirsOf(o, picked.length > 0);
+    const res = {
+        linked: [],
+        unchanged: [],
+        removed: [],
+        conflicts: [],
+        dirs: targets.map(d => d.dir),
+    };
+    const workspaces = workspaceDirs(graph, o.scurry);
+    const mounts = readMounts(scan, { workspaces });
+    const byName = new Map(mounts.map(m => [`${m.dir.dir}\0${lc(m.name)}`, m]));
+    // the link's skill is no longer installed: dangling, orphan owner,
+    // or a scanned owner that no longer ships it
+    const stale = (m) => !m.owner ||
+        !graph.nodes.has(m.owner) ||
+        !existsSync(m.target) ||
+        scanned
+            .get(m.owner)
+            ?.some(f => lc(f.skill) === lc(m.name) && samePath(f.path, m.target)) === false;
+    const groups = new Map();
+    for (const s of skills) {
+        const k = lc(s.skill);
+        groups.set(k, [...(groups.get(k) ?? []), s]);
+    }
+    // the link at `<dir>/<k>`, and its package's skill in `group`
+    const at = (dir, k, group) => {
+        const m = byName.get(`${dir.dir}\0${k}`);
+        const key = m?.owner && packageKey(m.owner);
+        return { m, own: group.find(s => packageKey(s.id) === key) };
+    };
+    // picked skills only: the others never take a name
+    const cands = (group) => group.filter(s => inMask.has(s));
+    // one per name: the first linked package keeps it, re-pointed if needed
+    const first = new Map([...groups].map(([k, group]) => {
+        const c = cands(group);
+        return [
+            k,
+            targets.map(d => at(d, k, c).own).find(s => !!s) ?? c[0],
+        ];
+    }));
+    const isTarget = new Set(targets);
+    const picks = [];
+    for (const dir of scan) {
+        for (const [k, group] of groups) {
+            const { m, own } = at(dir, k, group);
+            if (isTarget.has(dir)) {
+                // installs keep a link to another installed skill
+                const winner = o.apply ?
+                    first.get(k)
+                    : (own ?? (m && !stale(m) ? undefined : first.get(k)));
+                picks.push({
+                    dir,
+                    winner,
+                    losers: cands(group).filter(s => s !== winner),
+                    m,
+                });
+            }
+            else if (own && !o.apply) {
+                // no longer a target: only re-pointed
+                picks.push({ dir, winner: own, losers: [], m });
+            }
+        }
+    }
+    await unshareSkills(graph, [
+        ...picks.flatMap(({ winner }) => (winner ? [winner.id] : [])),
+        ...liveOwners(mounts),
+    ], o.scurry);
+    const gone = [];
+    // names taken over by entries not vlt's
+    const foreign = [];
+    const kept = new Set();
+    // links made here, recorded even if not yet in `.gitignore`
+    const made = new Set();
+    const where = new Map();
+    let every;
+    for (const { dir, winner, losers, m } of picks) {
+        if (winner) {
+            // replaced link named in another case (case-sensitive fs)
+            if (m && m.name !== winner.skill) {
+                unmountSkill(m);
+                gone.push(m);
+            }
+            const mount = `${dir.dir}/${winner.skill}`;
+            const r = mountSkill(winner, dir, m?.name === winner.skill);
+            if (r === 'linked')
+                made.add(mount);
+            if (r === 'conflict') {
+                res.conflicts.push(mount);
+                // vlt's link into a workspace not loaded (`-w`) keeps its line
+                every ??= allWorkspaces(o.monorepo);
+                if (!readMounts([dir], { workspaces: every }).some(l => l.name === winner.skill)) {
+                    foreign.push({ dir, name: winner.skill });
+                }
+            }
+            else {
+                const k = `${winner.id}\0${winner.skill}`;
+                const linked = where.get(k) ?? [];
+                linked.push(dir.dir);
+                where.set(k, linked);
+                res[r].push({ ...winner, linked, dir: dir.dir, mount });
+                kept.add(mount);
+            }
+        }
+        for (const s of losers)
+            res.conflicts.push(`${dir.dir}/${s.skill} (${label(s)})`);
+    }
+    const after = readMounts(scan, { workspaces, made });
+    const present = [];
+    for (const m of after) {
+        if (o.apply ? kept.has(m.mount) : !stale(m)) {
+            present.push(m);
+            continue;
+        }
+        unmountSkill(m);
+        gone.push(m);
+        res.removed.push(m.mount);
+    }
+    const gitignore = [];
+    for (const dir of scan) {
+        const add = present.filter(m => m.dir === dir).map(m => m.name);
+        const remove = [...gone, ...foreign]
+            .filter(m => m.dir === dir && !add.includes(m.name))
+            .map(m => m.name);
+        if ((add.length || remove.length) &&
+            editGitignore(dir.real, { add, remove }) === 'refused') {
+            gitignore.push(`${dir.dir}/.gitignore`);
+        }
+    }
+    if (skipped.length)
+        res.skipped = skipped;
+    if (gitignore.length)
+        res.gitignore = gitignore;
+    if (unmatched.length)
+        res.unmatched = unmatched;
+    // not left out: still linked in every dir (installs keep links)
+    const left = dropped.filter(s => !targets.every(d => present.some(m => m.dir === d &&
+        m.owner === s.id &&
+        lc(m.name) === lc(s.skill))));
+    return Object.assign(res, report(left, unscanned));
+};

package/dist/skills/lazy.d.ts

@@ -0,0 +1,8 @@
+import type { HasSkills } from '@vltpkg/query';
+import type * as Skills from './index.ts';
+/** `listSkills`, loading the skills code on first use. */
+export declare const listSkills: typeof Skills.listSkills;
+/** `linkSkills`, loading the skills code on first use. */
+export declare const linkSkills: typeof Skills.linkSkills;
+/** `:skills` provider: loads the skills code on first `Node`. */
+export declare const hasSkills: HasSkills;

package/dist/skills/lazy.js

@@ -0,0 +1,8 @@
+import { isNode } from "../node.js";
+const load = () => import("./index.js");
+/** `listSkills`, loading the skills code on first use. */
+export const listSkills = async (o) => (await load()).listSkills(o);
+/** `linkSkills`, loading the skills code on first use. */
+export const linkSkills = async (o) => (await load()).linkSkills(o);
+/** `:skills` provider: loads the skills code on first `Node`. */
+export const hasSkills = async (node) => isNode(node) && (await load()).shipsSkills(node);

package/dist/skills/mask.d.ts

@@ -0,0 +1,26 @@
+import type { QueryPartIds } from '../filter-nodes-by-query.ts';
+import type { Skill } from './discover.ts';
+/**
+ * A `:skill()` pattern that matched no skill of its selector's
+ * packages.
+ */
+export type UnmatchedPattern = {
+    pattern: string;
+    /** skills those packages ship, sorted; unset: no package selected */
+    skills?: string[];
+};
+/**
+ * Whole-name, case-insensitive; `*` = any run of characters (incl.
+ * none).
+ */
+export declare const globRegExp: (pattern: string) => RegExp;
+/**
+ * Apply an `allow-skills` mask. A skill is picked when some part matched
+ * its package (any version) and has no patterns, or one of its patterns
+ * matches the skill (parts are a union). Also returns the patterns that
+ * matched nothing.
+ */
+export declare const maskSkills: (skills: Skill[], parts: QueryPartIds[]) => {
+    skills: Skill[];
+    unmatched: UnmatchedPattern[];
+};

package/dist/skills/mask.js

@@ -0,0 +1,43 @@
+import { packageKey } from "./mounts.js";
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Whole-name, case-insensitive; `*` = any run of characters (incl.
+ * none).
+ */
+export const globRegExp = (pattern) => new RegExp(`^${pattern.split('*').map(escape).join('.*')}$`, 'i');
+const matches = (re, s) => re.test(s.skill) ||
+    (!!s.frontmatterName && re.test(s.frontmatterName));
+/**
+ * Apply an `allow-skills` mask. A skill is picked when some part matched
+ * its package (any version) and has no patterns, or one of its patterns
+ * matches the skill (parts are a union). Also returns the patterns that
+ * matched nothing.
+ */
+export const maskSkills = (skills, parts) => {
+    const compiled = parts.map(p => ({
+        keys: new Set([...p.ids].map(packageKey)),
+        patterns: p.patterns?.map(pattern => ({
+            pattern,
+            re: globRegExp(pattern),
+        })),
+    }));
+    const picked = skills.filter(s => compiled.some(p => p.keys.has(packageKey(s.id)) &&
+        (!p.patterns || p.patterns.some(({ re }) => matches(re, s)))));
+    const unmatched = [];
+    for (const p of compiled) {
+        if (!p.patterns)
+            continue;
+        const own = skills.filter(s => p.keys.has(packageKey(s.id)));
+        for (const { pattern, re } of p.patterns) {
+            if (own.some(s => matches(re, s)))
+                continue;
+            unmatched.push({
+                pattern,
+                ...(p.keys.size > 0 && {
+                    skills: [...new Set(own.map(s => s.skill))].sort((a, b) => a.localeCompare(b, 'en')),
+                }),
+            });
+        }
+    }
+    return { skills: picked, unmatched };
+};

package/dist/skills/mounts.d.ts

@@ -0,0 +1,78 @@
+import type { Stats } from 'node:fs';
+import type { DepID } from '@vltpkg/dep-id';
+import type { SkillsDir } from './dirs.ts';
+import type { Skill } from './discover.ts';
+/**
+ * A vlt link in an agent skills dir.
+ */
+export type SkillMount = {
+    /** the dir holding the link */
+    dir: SkillsDir;
+    /** entry name */
+    name: string;
+    /** `<dir>/<name>`, `/`-separated, relative to projectRoot */
+    mount: string;
+    /** absolute link path, in the real dir */
+    link: string;
+    /** absolute resolved link target */
+    target: string;
+    /** DepID of the store dir or workspace the link points into */
+    owner?: DepID;
+};
+/**
+ * A workspace of the project.
+ */
+export type WorkspaceDir = {
+    id: DepID;
+    /** realpath */
+    path: string;
+};
+/**
+ * Outcome of mounting a single skill.
+ */
+export type MountResult = 'linked' | 'unchanged' | 'conflict';
+/** `lstat`, undefined when missing or unreadable (eg, ENOTDIR) */
+export declare const lstat: (path: string) => Stats | undefined;
+/** Resolved path, lowercased on win32. */
+export declare const norm: (p: string) => string;
+/** realpath, else the resolved path when missing. */
+export declare const realOr: (p: string) => string;
+/**
+ * Same real path? Case-insensitive on win32.
+ */
+export declare const samePath: (a: string, b: string) => boolean;
+/**
+ * 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 declare const mountTarget: (link: string) => string | undefined;
+/**
+ * The DepID of the last `node_modules/.vlt/<DepID>` segment of a raw
+ * link target, if valid.
+ */
+export declare const ownerOf: (target: string) => DepID | undefined;
+/**
+ * One key per package: registry + name, else the DepID w/o its extra.
+ */
+export declare const packageKey: (id: DepID) => string;
+/**
+ * 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 declare const readMounts: (scan: SkillsDir[], { workspaces, made, }?: {
+    workspaces?: WorkspaceDir[];
+    made?: Set<string>;
+}) => SkillMount[];
+/**
+ * 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 declare const mountSkill: (skill: Pick<Skill, "skill" | "path">, dir: SkillsDir, owned?: boolean) => MountResult;
+/**
+ * Remove a vlt link. Its dir is kept.
+ */
+export declare const unmountSkill: (m: SkillMount) => void;