@vltpkg/graph 1.3.8 → 1.5.0

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;

package/dist/skills/discover.js

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

package/dist/skills/gitignore.d.ts

@@ -0,0 +1,13 @@
+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";

package/dist/skills/gitignore.js

@@ -0,0 +1,53 @@
+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}`);
+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 = lines.findIndex(l => l.trim() === GITIGNORE_BEGIN);
+    const end = lines.findIndex((l, i) => begin !== -1 && i > begin && l.trim() === GITIGNORE_END);
+    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';
+    }
+};

package/dist/skills/index.d.ts

@@ -0,0 +1,123 @@
+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 (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. 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>;