@vltpkg/graph 1.3.8 → 1.5.0

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

@@ -7,6 +7,7 @@ import { error } from '@vltpkg/error-cause';
 import { asError } from '@vltpkg/types';
 import { getDependencies } from "./dependencies.js";
 import { RollbackRemove } from '@vltpkg/rollback-remove';
+import { joinDepIDTuple } from '@vltpkg/dep-id';
 import { existsSync, rmSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { load as loadVirtual, loadData } from "./lockfile/load.js";
@@ -15,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)) {
@@ -109,6 +122,7 @@ export const install = async (options, add) => {
         }
         if (importerSpecs.add.modifiedDependencies ||
             importerSpecs.remove.modifiedDependencies ||
+            importerSpecs.removedEdges.size > 0 ||
             specChanges.length > 0 ||
             lockfileGraph.optionsChanged) {
             const details = [];
@@ -141,6 +155,9 @@ export const install = async (options, add) => {
                     details.push(`  ${location}: ${deps.size} ${depLabelRemove} to remove (${depNames.join(', ')})`);
                 }
             }
+            for (const edge of importerSpecs.removedEdges) {
+                details.push(`  ${edge.from.location}: ${edge.name} is removed by a graph modifier`);
+            }
             const lockfilePath = resolve(options.projectRoot, 'vlt-lock.json');
             throw error('Lockfile is out of sync with package.json. Run "vlt install" to update.\n' +
                 details.join('\n'), {
@@ -148,6 +165,23 @@ export const install = async (options, add) => {
             });
         }
     }
+    // an explicit add of a dep a `-` modifier removes fails before
+    // anything on disk is touched
+    if (modifiers && add?.modifiedDependencies) {
+        const wsIds = new Set([...(fullMonorepo?.values() ?? [])].map(ws => ws.id));
+        for (const [id, deps] of add) {
+            const mainImporter = id === joinDepIDTuple(['file', '.']);
+            // nested folders are no importers, appendNodes checks those
+            if (!mainImporter && !wsIds.has(id))
+                continue;
+            for (const { spec } of deps.values()) {
+                const found = modifiers.removesImporterEdge({ importer: true, mainImporter }, spec);
+                if (found) {
+                    throw error(`Cannot add ${spec.name}: it is removed by a graph modifier`, { code: 'ECONFIG', found });
+                }
+            }
+        }
+    }
     const remover = new RollbackRemove();
     if (options.cleanInstall) {
         const nodeModulesPath = resolve(options.projectRoot, 'node_modules');
@@ -156,6 +190,7 @@ export const install = async (options, add) => {
             remover.confirm();
         }
     }
+    let result;
     try {
         const remove = Object.assign(new Map(), {
             modifiedDependencies: false,
@@ -225,7 +260,7 @@ export const install = async (options, add) => {
             remove,
             remover,
         });
-        return { buildQueue, graph, diff };
+        result = { buildQueue, graph, diff };
     }
     catch (err) {
         /* c8 ignore next */
@@ -240,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) {
@@ -52,11 +52,9 @@ export const loadEdges = (graph, edges, options, cache) => {
         const [depType, valRest] = fastSplit(value, ' ', 2);
         const vrSplit = valRest?.lastIndexOf(' ') ?? -1;
         // not a valid edge record
-        /* c8 ignore start */
         if (!valRest || !depType || !fromId || !specName || vrSplit < 1) {
             continue;
         }
-        /* c8 ignore stop */
         // Validate dependency type early
         if (!isDependencyTypeShort(depType)) {
             throw error('Found unsupported dependency type in lockfile', {
@@ -106,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,

package/dist/modifiers.d.ts

@@ -126,6 +126,13 @@ export declare class GraphModifier {
      * root's own b edge is still the manifest's to validate and heal.
      */
     targetsImporterEdge(importer: Node, spec: Spec): boolean;
+    /**
+     * Selector of the modifier that wins the direct `importer -> spec.name`
+     * edge, if it removes it (value `-`). Same pick as tryNewDependency:
+     * complete entries whose qualifier accepts the spec, highest
+     * specificity, importer-anchored before lone on ties.
+     */
+    removesImporterEdge(importer: Pick<Node, 'importer' | 'mainImporter'>, spec: Spec): string | undefined;
     /**
      * Loads the modifiers defined in `vlt.json` into memory.
      */

package/dist/modifiers.js

@@ -115,6 +115,30 @@ export class GraphModifier {
         }
         return false;
     }
+    /**
+     * Selector of the modifier that wins the direct `importer -> spec.name`
+     * edge, if it removes it (value `-`). Same pick as tryNewDependency:
+     * complete entries whose qualifier accepts the spec, highest
+     * specificity, importer-anchored before lone on ties.
+     */
+    removesImporterEdge(importer, spec) {
+        const anchored = [];
+        const lone = [];
+        for (const mod of this.#modifiers) {
+            const { last } = mod.breadcrumb;
+            if (last.name !== spec.name || !matchesQualifier(last, spec))
+                continue;
+            const { prev } = last;
+            if (!prev)
+                lone.push(mod);
+            else if (!prev.prev && matchesImporter(prev, importer))
+                anchored.push(mod);
+        }
+        const all = [...anchored, ...lone];
+        const [winner] = specificitySort(all.map(m => m.breadcrumb));
+        const mod = all.find(m => m.breadcrumb === winner);
+        return mod?.value === '-' ? mod.query : undefined;
+    }
     /**
      * Loads the modifiers defined in `vlt.json` into memory.
      */

package/dist/reify/build.d.ts

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

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

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

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

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

package/dist/reify/index.js

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

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

@@ -2,15 +2,9 @@ import { splitDepID } from '@vltpkg/dep-id';
 import { error } from '@vltpkg/error-cause';
 import { Spec } from '@vltpkg/spec';
 import { longDependencyTypes } from '@vltpkg/types';
+import { longDependencyTypeNames } from "../dependencies.js";
 import { resolveSaveType } from "../resolve-save-type.js";
 import { calculateSaveValue } from "./calculate-save-value.js";
-const depTypesMap = new Map([
-    ['prod', 'dependencies'],
-    ['dev', 'devDependencies'],
-    ['peer', 'peerDependencies'],
-    ['peerOptional', 'peerDependencies'],
-    ['optional', 'optionalDependencies'],
-]);
 const addOrRemoveDeps = (nodeId, graph, addOrRemove, saveExact, savePrefix) => {
     const node = graph.nodes.get(nodeId);
     if (!node) {
@@ -51,10 +45,12 @@ const addOrRemoveDeps = (nodeId, graph, addOrRemove, saveExact, savePrefix) => {
             const [name, dep] = deleteNameOrAddItem;
             // peerOptional also needs to add peerDependenciesMeta entry
             const depTypeShort = resolveSaveType(node, name, dep.type);
-            const depType = depTypesMap.get(depTypeShort);
+            const depType = Object.hasOwn(longDependencyTypeNames, depTypeShort) ?
+                longDependencyTypeNames[depTypeShort]
+                : undefined;
             if (!depType) {
                 throw error('Failed to retrieve dependency type', {
-                    validOptions: [...depTypesMap.keys()],
+                    validOptions: Object.keys(longDependencyTypeNames),
                     found: dep.type,
                 });
             }

package/dist/skills/dirs.d.ts

@@ -0,0 +1,58 @@
+/** Always a target when detecting: read by most agents. */
+export declare const AGENTS_SKILLS = ".agents/skills";
+/** Set (non-empty) inside Claude Code. */
+export declare const CLAUDE_ENV: readonly ["CLAUDECODE", "CLAUDE_CODE"];
+/**
+ * Agent folder at the project root → its skills dir.
+ */
+export declare const AGENT_ROOTS: readonly (readonly [
+    marker: string,
+    dir: string
+])[];
+/**
+ * An agent skills dir.
+ */
+export type SkillsDir = {
+    /** `/`-separated, relative to projectRoot */
+    dir: string;
+    /** realpath (a missing tail appended as is) */
+    real: string;
+    /** `<dev>:<ino>` (no inode: the path); unset when missing */
+    id?: string;
+};
+/**
+ * Result of {@link skillsDirs}.
+ */
+export type SkillsDirs = {
+    /** dirs to link into */
+    targets: SkillsDir[];
+    /** existing dirs to look for vlt links in: targets first */
+    scan: SkillsDir[];
+    /** targets dropped: `<dir> (<reason>)` */
+    skipped: string[];
+};
+/**
+ * Options for {@link skillsDirs}.
+ */
+export type SkillsDirsOptions = {
+    projectRoot: string;
+    /** `skills-dir`: replaces detection; `[]` none */
+    configured?: string[];
+    /** default `process.env` */
+    env?: Record<string, string | undefined>;
+    /** create missing targets */
+    create?: boolean;
+};
+/**
+ * Throw EUSAGE unless each entry is a dir inside projectRoot, not in
+ * `node_modules`.
+ */
+export declare const assertSkillsDirs: (projectRoot: string, list?: string[]) => void;
+/**
+ * The project's agent skill dirs. `configured` replaces detection:
+ * `.agents/skills`, plus `<folder>/skills` for each agent folder at
+ * the root, `.claude/skills` inside Claude Code, and existing
+ * `.<name>/skills` dirs. Dirs must resolve inside projectRoot, not in
+ * `node_modules`; the same dir is listed once.
+ */
+export declare const skillsDirs: ({ projectRoot, configured, env, create, }: SkillsDirsOptions) => SkillsDirs;

package/dist/skills/dirs.js

@@ -0,0 +1,211 @@
+import { error } from '@vltpkg/error-cause';
+import { lstatSync, mkdirSync, readdirSync, realpathSync, statSync, } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { norm } from "./mounts.js";
+/** Always a target when detecting: read by most agents. */
+export const AGENTS_SKILLS = '.agents/skills';
+/** Set (non-empty) inside Claude Code. */
+export const CLAUDE_ENV = ['CLAUDECODE', 'CLAUDE_CODE'];
+/**
+ * Agent folder at the project root → its skills dir.
+ */
+// vercel-labs/skills v1.7.2 src/agents.ts: skillsDir per agent (line), dot roots only
+export const AGENT_ROOTS = [
+    ['.adal', '.adal/skills'], // 813
+    ['.aider-desk', '.aider-desk/skills'], // 84
+    ['.augment', '.augment/skills'], // 140
+    ['.autohand', '.autohand/skills'], // 131
+    ['.bob', '.bob/skills'], // 149
+    ['.claude', '.claude/skills'], // 158
+    ['.codeartsdoer', '.codeartsdoer/skills'], // 191
+    ['.codebuddy', '.codebuddy/skills'], // 200
+    ['.codemaker', '.codemaker/skills'], // 209
+    ['.codestudio', '.codestudio/skills'], // 218
+    ['.commandcode', '.commandcode/skills'], // 236
+    ['.continue', '.continue/skills'], // 245
+    ['.cortex', '.cortex/skills'], // 254
+    ['.crush', '.crush/skills'], // 263
+    ['.devin', '.devin/skills'], // 291
+    ['.forge', '.forge/skills'], // 345
+    ['.goose', '.goose/skills'], // 382
+    ['.grok', '.grok/skills'], // 391
+    ['.hermes', '.hermes/skills'], // 400
+    ['.iflow', '.iflow/skills'], // 436
+    ['.inferencesh', '.inferencesh/skills'], // 409
+    ['.jazz', '.jazz/skills'], // 418
+    ['.junie', '.junie/skills'], // 427
+    ['.kimchi', '.kimchi/skills'], // 456
+    ['.kiro', '.kiro/skills'], // 474
+    ['.kode', '.kode/skills'], // 483
+    ['.lingma', '.lingma/skills'], // 492
+    ['.mcpjam', '.mcpjam/skills'], // 511
+    ['.minimax', '.minimax/skills'], // 520
+    ['.moxby', '.moxby/skills'], // 538
+    ['.mux', '.mux/skills'], // 547
+    ['.neovate', '.neovate/skills'], // 782
+    ['.ona', '.ona/skills'], // 574
+    ['.openhands', '.openhands/skills'], // 565
+    ['.pochi', '.pochi/skills'], // 791
+    ['.posit/assistant', '.posit/assistant/skills'], // 595
+    ['.qoder', '.qoder/skills'], // 604,613
+    ['.qwen', '.qwen/skills'], // 622
+    ['.reasonix', '.reasonix/skills'], // 641
+    ['.roo', '.roo/skills'], // 659
+    ['.rovodev', '.rovodev/skills'], // 650
+    ['.tabnine', '.tabnine/agent/skills'], // 678
+    ['.terramind', '.terramind/skills'], // 687
+    ['.tinycloud', '.tinycloud/skills'], // 696
+    ['.trae', '.trae/skills'], // 705,714
+    ['.vibe', '.vibe/skills'], // 529
+    ['.windsurf', '.windsurf/skills'], // 732
+    ['.zcode', '.zcode/skills'], // 755
+    ['.zencoder', '.zencoder/skills'], // 764,773
+];
+// strictly below root
+const inside = (root, p) => {
+    const r = relative(root, p);
+    return (!!r && r !== '..' && !r.startsWith('..' + sep) && !isAbsolute(r));
+};
+// a `node_modules` segment below root
+const inNodeModules = (root, p) => relative(root, p)
+    .split(sep)
+    .some(s => s.toLowerCase() === 'node_modules');
+const isDir = (path) => {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Throw EUSAGE unless each entry is a dir inside projectRoot, not in
+ * `node_modules`.
+ */
+export const assertSkillsDirs = (projectRoot, list = []) => {
+    for (const e of list) {
+        const p = resolve(projectRoot, e);
+        if (e &&
+            (!inside(projectRoot, p) || inNodeModules(projectRoot, p))) {
+            throw error('Invalid --skills-dir: must be a dir inside the project, not in node_modules', { code: 'EUSAGE', found: e }, assertSkillsDirs);
+        }
+    }
+};
+// walk `dir` from the real root, one component at a time, so a
+// symlink out of the project is caught before anything is made in it.
+// A string is the reason it was skipped (fs errors: the code)
+const walk = (realRoot, dir, create) => {
+    const parts = dir.split('/');
+    let real = realRoot;
+    try {
+        for (const [i, part] of parts.entries()) {
+            const next = join(real, part);
+            let st = lstatSync(next, { throwIfNoEntry: false });
+            if (!st) {
+                if (!create)
+                    return { dir, real: join(real, ...parts.slice(i)) };
+                try {
+                    mkdirSync(next);
+                }
+                catch (er) {
+                    if (er.code !== 'EEXIST')
+                        throw er;
+                }
+                st = lstatSync(next);
+            }
+            if (st.isSymbolicLink()) {
+                let r;
+                try {
+                    r = realpathSync(next);
+                }
+                catch {
+                    return 'not a directory';
+                }
+                if (!inside(realRoot, r))
+                    return 'outside the project';
+                if (inNodeModules(realRoot, r))
+                    return 'inside node_modules';
+                if (!isDir(r))
+                    return 'not a directory';
+                real = r;
+            }
+            else if (st.isDirectory()) {
+                real = next;
+            }
+            else {
+                return 'not a directory';
+            }
+        }
+        const { dev, ino } = statSync(real, { bigint: true });
+        // some filesystems report no inode: compare paths
+        return { dir, real, id: ino ? `${dev}:${ino}` : norm(real) };
+    }
+    catch (er) {
+        return String(er.code);
+    }
+};
+/**
+ * The project's agent skill dirs. `configured` replaces detection:
+ * `.agents/skills`, plus `<folder>/skills` for each agent folder at
+ * the root, `.claude/skills` inside Claude Code, and existing
+ * `.<name>/skills` dirs. Dirs must resolve inside projectRoot, not in
+ * `node_modules`; the same dir is listed once.
+ */
+export const skillsDirs = ({ projectRoot, configured, env = process.env, create = false, }) => {
+    const realRoot = realpathSync(projectRoot);
+    const res = { targets: [], scan: [], skipped: [] };
+    const dots = readdirSync(realRoot)
+        .filter(e => e.startsWith('.'))
+        .sort((a, b) => a.localeCompare(b, 'en'))
+        .map(e => `${e}/skills`);
+    let list;
+    if (configured) {
+        assertSkillsDirs(projectRoot, configured);
+        list = configured.filter(Boolean);
+    }
+    else {
+        const found = new Set();
+        for (const [marker, d] of AGENT_ROOTS) {
+            if (isDir(join(realRoot, marker)))
+                found.add(d);
+        }
+        if (CLAUDE_ENV.some(k => env[k]))
+            found.add('.claude/skills');
+        for (const d of dots) {
+            if (isDir(join(realRoot, d)))
+                found.add(d);
+        }
+        list = [
+            AGENTS_SKILLS,
+            ...[...found].sort((a, b) => a.localeCompare(b, 'en')),
+        ];
+    }
+    const dirs = new Set(list.map(e => relative(projectRoot, resolve(projectRoot, e))
+        .split(sep)
+        .join('/')));
+    const seen = new Set();
+    for (const dir of dirs) {
+        const d = walk(realRoot, dir, create);
+        if (typeof d === 'string') {
+            res.skipped.push(`${dir} (${d})`);
+        }
+        else if (!seen.has(d.id ?? d.real)) {
+            seen.add(d.id ?? d.real);
+            res.targets.push(d);
+            if (d.id)
+                res.scan.push(d);
+        }
+    }
+    for (const dir of [
+        AGENTS_SKILLS,
+        ...AGENT_ROOTS.map(([, d]) => d),
+        ...dots,
+    ]) {
+        const d = walk(realRoot, dir, false);
+        if (typeof d !== 'string' && d.id && !seen.has(d.id)) {
+            seen.add(d.id);
+            res.scan.push(d);
+        }
+    }
+    return res;
+};