@aragon-agent/cli 0.4.3

package/dist/skills/lock.js

@@ -0,0 +1,223 @@
+/**
+ * Per-root advisory install lock (spec §7).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHAT THIS PREVENTS: two aragon processes installing at once can DELETE a
+ * skill, and the path that does it reports success.
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * `commitDirectory()` is `existsSync(target) → rename(target → .trash) →
+ * rename(staging → target)`. Interleave two of those (§7.1):
+ *
+ *   A: existsSync = true  → moves the old version to .trash
+ *   B: existsSync = false → decides there is no backup to take
+ *   A: rename(stagingA → target)
+ *   B: rename(stagingB → target)     ← overwrites A; A's backup is now orphaned
+ *   A: rmSync(backup)                ← deletes the user's previous version
+ *
+ * If B then fails, its rollback is a no-op because it believes `backup === null`
+ * — and the skill is gone. Nothing in that sequence throws.
+ *
+ * The lock is ADVISORY and PER WRITABLE ROOT (D-A9), not per skill: the danger
+ * is the shared `.staging/.trash` bookkeeping, which a per-skill lock would not
+ * cover. Serialising installs costs a few seconds of queueing on a command a
+ * human typed.
+ *
+ * KNOWN LIMIT (RA4): `wx` is atomic on local filesystems and on SMB, but not
+ * reliably on every NFS implementation. The TTL and the 5-second ceiling below
+ * mean the worst case there is the CURRENT behaviour (no mutual exclusion) — a
+ * deadlock is not reachable.
+ */
+import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import process from 'node:process';
+/**
+ * A FILE, and dot-prefixed. `discover()` only considers `isDirectory` entries
+ * and already skips dotfiles, so the lock is invisible to the scanner twice
+ * over — asserted by `lock.test.ts` rather than left to reasoning (AC-A16).
+ */
+export const LOCK_FILENAME = '.aragon-skills.lock';
+/** A lock older than this is presumed abandoned. */
+export const LOCK_TTL_MS = 60_000;
+export const LOCK_RETRY_MS = 250;
+/** Total time spent waiting before giving up with a readable message. */
+export const LOCK_MAX_WAIT_MS = 5_000;
+/**
+ * Consecutive unreadable reads required before a lock is presumed abandoned.
+ *
+ * MUST BE > 1. `tryCreate()` creates the file and writes its payload as two
+ * separate syscalls, so a competing process can legitimately observe a
+ * zero-byte lock that is microseconds old. Treating that single observation as
+ * "corrupt, therefore abandoned" would delete a lock that is about to become
+ * valid and leave two processes both believing they own the root — precisely
+ * the race this module exists to close, and one that only appears under the
+ * contention the lock was written for. Re-reading a retry later costs 250 ms in
+ * the genuinely-corrupt case and removes the window in every other.
+ */
+export const LOCK_UNREADABLE_CONFIRMATIONS = 2;
+export class SkillLockError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SkillLockError';
+    }
+}
+/** Busy-wait. Deliberate: this runs in a CLI command, and there is nothing else to do. */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Is `pid` still running?
+ *
+ * `ESRCH` means gone. `EPERM` means the process EXISTS but belongs to another
+ * user — treating that as dead would let one user steal another's lock, so it
+ * reports alive.
+ */
+function defaultIsProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== 'ESRCH';
+    }
+}
+function readLock(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        if (typeof parsed.pid !== 'number' || typeof parsed.startedAt !== 'number')
+            return null;
+        if (typeof parsed.uuid !== 'string' || typeof parsed.host !== 'string')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Write the lock file exclusively, or report that someone else holds it. */
+function tryCreate(path, payload) {
+    let fd;
+    try {
+        // `wx` — atomic exclusive create. This single call is the entire
+        // correctness argument; everything else is recovery policy.
+        fd = openSync(path, 'wx');
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return false;
+        throw err;
+    }
+    try {
+        writeSync(fd, JSON.stringify(payload));
+    }
+    finally {
+        // Closed IMMEDIATELY: on Windows an open handle blocks `unlink`, so holding
+        // it would make our own release fail and turn every lock into a 60-second
+        // stall for the next process.
+        closeSync(fd);
+    }
+    return true;
+}
+/**
+ * Take the install lock for `root`, blocking until it is free or the ceiling
+ * elapses.
+ *
+ * @throws {SkillLockError} when another live process holds it for longer than
+ *   `LOCK_MAX_WAIT_MS`. The message names the pid and the time so the user can
+ *   tell "my other terminal" from "a crashed process".
+ */
+export function acquireRootLock(root, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? sleepSync;
+    const isAlive = opts.isProcessAlive ?? defaultIsProcessAlive;
+    mkdirSync(root, { recursive: true });
+    const path = join(root, LOCK_FILENAME);
+    const payload = {
+        pid: process.pid,
+        host: hostname(),
+        startedAt: now(),
+        uuid: randomUUID(),
+    };
+    const deadline = now() + LOCK_MAX_WAIT_MS;
+    let unreadableProbes = 0;
+    for (;;) {
+        if (tryCreate(path, payload))
+            return makeHandle(path, payload.uuid);
+        const holder = readLock(path);
+        let stale;
+        if (holder === null) {
+            // See LOCK_UNREADABLE_CONFIRMATIONS: one unreadable read is indistinguishable
+            // from a lock that is mid-creation, so it is not evidence of abandonment.
+            unreadableProbes += 1;
+            stale = unreadableProbes >= LOCK_UNREADABLE_CONFIRMATIONS;
+        }
+        else {
+            unreadableProbes = 0;
+            stale =
+                now() - holder.startedAt > LOCK_TTL_MS ||
+                    (holder.host === payload.host && !isAlive(holder.pid));
+        }
+        let preempted = false;
+        if (stale) {
+            try {
+                unlinkSync(path);
+                preempted = true;
+            }
+            catch {
+                // Either another process won the race to clean it up, or the file is
+                // pinned (a scanner holding a handle open on Windows). Fall through to
+                // the timed wait rather than retrying immediately: an unlink that keeps
+                // failing would otherwise spin here forever, and a CLI that never
+                // returns is a worse outcome than one that reports a busy lock.
+            }
+        }
+        // Evaluated on EVERY iteration, including the preemption path, so that no
+        // branch of this loop can run unbounded.
+        if (now() >= deadline)
+            throw lockBusyError(holder);
+        // A successful preemption goes straight back to `tryCreate` rather than
+        // assuming ownership: two processes can judge the same lock stale at the
+        // same moment, and `wx` is the only thing entitled to decide between them.
+        if (!preempted)
+            sleep(LOCK_RETRY_MS);
+    }
+}
+/** The give-up message. Names the holder when there is one to name. */
+function lockBusyError(holder) {
+    const who = holder
+        ? `pid ${holder.pid} since ${new Date(holder.startedAt).toISOString()}`
+        : 'an unreadable lock file that could not be cleared';
+    return new SkillLockError(`another aragon process is installing skills (lock held by ${who}); retry in a moment`);
+}
+/**
+ * Release only OUR lock (D-A10).
+ *
+ * The uuid check is not defensive padding. If this process was judged stale and
+ * preempted, an unconditional `unlink` here would delete the NEW holder's lock
+ * and open a second concurrency window — the classic file-lock bug, and one
+ * that only shows up under exactly the contention the lock exists to handle.
+ */
+function makeHandle(path, uuid) {
+    let released = false;
+    return {
+        release() {
+            if (released)
+                return;
+            released = true;
+            try {
+                const holder = readLock(path);
+                if (holder?.uuid !== uuid)
+                    return;
+                unlinkSync(path);
+            }
+            catch {
+                // A failed release costs at most one TTL of waiting for the next
+                // process. Letting it throw would end a SUCCESSFUL install in an error.
+            }
+        },
+    };
+}

package/dist/skills/manifest.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `.aragon-skill.json` — the install manifest (spec §10.2 / D15).
+ *
+ * Records provenance (where this skill came from) and a sha256 per file. That
+ * pays for three things at once: `/skills info` can answer "where did this come
+ * from", `skills doctor` can spot tampering, and an uninstall can remove
+ * exactly what was installed instead of nuking a directory the user may have
+ * added their own files to.
+ */
+import type { SkillManifest, SkillManifestSource } from '@aragon-agent/core/skills';
+export declare const MANIFEST_FILENAME = ".aragon-skill.json";
+export declare const MANIFEST_SCHEMA = 1;
+export declare function sha256File(path: string): string;
+/**
+ * Read a manifest, or `null` when it is absent, unreadable, or written by a
+ * newer schema. An unknown schema is deliberately NOT an error: the skill still
+ * works, we just cannot make provenance claims about it.
+ */
+export declare function readManifest(path: string): SkillManifest | null;
+export declare function writeManifest(dir: string, manifest: SkillManifest): void;
+/**
+ * Build a manifest by hashing every file that was just installed.
+ *
+ * `updatedAt` / `previousVersion` are written only by `skills update`, which
+ * also carries `installedAt` FORWARD from the old manifest: "when did I first
+ * install this" and "when was it last changed" answer different questions, and
+ * collapsing them loses the one the user actually asks during an incident.
+ */
+export declare function buildManifest(input: {
+    dir: string;
+    files: string[];
+    name: string;
+    version: string;
+    installer: string;
+    source: SkillManifestSource;
+    installedAt: number;
+    updatedAt?: number;
+    previousVersion?: string;
+}): SkillManifest;
+/** sha256 of an in-memory buffer — the same digest `sha256File` produces. */
+export declare function sha256Buffer(buffer: Buffer): string;
+export interface TamperReport {
+    missing: string[];
+    modified: string[];
+}
+/** Compare a manifest against what is actually on disk (`skills doctor`). */
+export declare function checkManifest(dir: string, manifest: SkillManifest): TamperReport;

package/dist/skills/manifest.js

@@ -0,0 +1,95 @@
+/**
+ * `.aragon-skill.json` — the install manifest (spec §10.2 / D15).
+ *
+ * Records provenance (where this skill came from) and a sha256 per file. That
+ * pays for three things at once: `/skills info` can answer "where did this come
+ * from", `skills doctor` can spot tampering, and an uninstall can remove
+ * exactly what was installed instead of nuking a directory the user may have
+ * added their own files to.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+export const MANIFEST_FILENAME = '.aragon-skill.json';
+export const MANIFEST_SCHEMA = 1;
+export function sha256File(path) {
+    return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+/**
+ * Read a manifest, or `null` when it is absent, unreadable, or written by a
+ * newer schema. An unknown schema is deliberately NOT an error: the skill still
+ * works, we just cannot make provenance claims about it.
+ */
+export function readManifest(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        if (parsed.schema !== MANIFEST_SCHEMA)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeManifest(dir, manifest) {
+    writeFileSync(join(dir, MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}\n`, {
+        encoding: 'utf-8',
+    });
+}
+/**
+ * Build a manifest by hashing every file that was just installed.
+ *
+ * `updatedAt` / `previousVersion` are written only by `skills update`, which
+ * also carries `installedAt` FORWARD from the old manifest: "when did I first
+ * install this" and "when was it last changed" answer different questions, and
+ * collapsing them loses the one the user actually asks during an incident.
+ */
+export function buildManifest(input) {
+    const files = [];
+    let totalBytes = 0;
+    for (const absolute of input.files) {
+        const rel = relative(input.dir, absolute).replace(/\\/g, '/');
+        if (rel === MANIFEST_FILENAME)
+            continue;
+        const bytes = statSync(absolute).size;
+        totalBytes += bytes;
+        files.push({ path: rel, bytes, sha256: sha256File(absolute) });
+    }
+    files.sort((a, b) => a.path.localeCompare(b.path, 'en'));
+    return {
+        schema: MANIFEST_SCHEMA,
+        name: input.name,
+        version: input.version,
+        installedAt: input.installedAt,
+        installer: input.installer,
+        source: input.source,
+        files,
+        totalBytes,
+        // Written only when present, so a fresh install's manifest is byte-identical
+        // to what iteration 1 produced.
+        ...(input.updatedAt !== undefined ? { updatedAt: input.updatedAt } : {}),
+        ...(input.previousVersion !== undefined ? { previousVersion: input.previousVersion } : {}),
+    };
+}
+/** sha256 of an in-memory buffer — the same digest `sha256File` produces. */
+export function sha256Buffer(buffer) {
+    return createHash('sha256').update(buffer).digest('hex');
+}
+/** Compare a manifest against what is actually on disk (`skills doctor`). */
+export function checkManifest(dir, manifest) {
+    const missing = [];
+    const modified = [];
+    for (const file of manifest.files) {
+        const absolute = join(dir, file.path);
+        try {
+            if (sha256File(absolute) !== file.sha256)
+                modified.push(file.path);
+        }
+        catch {
+            missing.push(file.path);
+        }
+    }
+    return { missing, modified };
+}

package/dist/skills/node-host.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The Node implementation of core's `SkillHost` port (spec §11.3 / D1).
+ *
+ * This file is the ONLY reason `@aragon-agent/core` can stay free of `node:*`:
+ * every filesystem touch the skills engine needs arrives through here.
+ *
+ * ERROR CONTRACT (§10.1): these methods deliberately let fs exceptions escape.
+ * Swallowing ENOENT / EACCES here would turn "your skill directory is
+ * unreadable" into "your skill silently has no content"; the callers that must
+ * not throw (the `skill` tool's `execute()`) catch it themselves and produce a
+ * diagnosable message.
+ */
+import type { SkillHost, SkillPlatform } from '@aragon-agent/core';
+/**
+ * Which shell family the `bash` tool will actually use here (D-G14).
+ *
+ * THE SINGLE PLACE `process.platform` is read for skills rendering. Core takes
+ * `platform` as a parameter instead of looking it up, which is what allows one
+ * machine's test run to cover both branches of the Level 3 guidance — a renderer
+ * that read `process` could only ever be snapshot-tested on the OS it ran on.
+ */
+export declare const currentPlatform: () => SkillPlatform;
+export declare function createNodeSkillHost(): SkillHost;

package/dist/skills/node-host.js

@@ -0,0 +1,59 @@
+/**
+ * The Node implementation of core's `SkillHost` port (spec §11.3 / D1).
+ *
+ * This file is the ONLY reason `@aragon-agent/core` can stay free of `node:*`:
+ * every filesystem touch the skills engine needs arrives through here.
+ *
+ * ERROR CONTRACT (§10.1): these methods deliberately let fs exceptions escape.
+ * Swallowing ENOENT / EACCES here would turn "your skill directory is
+ * unreadable" into "your skill silently has no content"; the callers that must
+ * not throw (the `skill` tool's `execute()`) catch it themselves and produce a
+ * diagnosable message.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+import process from 'node:process';
+/**
+ * Which shell family the `bash` tool will actually use here (D-G14).
+ *
+ * THE SINGLE PLACE `process.platform` is read for skills rendering. Core takes
+ * `platform` as a parameter instead of looking it up, which is what allows one
+ * machine's test run to cover both branches of the Level 3 guidance — a renderer
+ * that read `process` could only ever be snapshot-tested on the OS it ran on.
+ */
+export const currentPlatform = () => process.platform === 'win32' ? 'win32' : 'posix';
+export function createNodeSkillHost() {
+    return {
+        readTextFile(path) {
+            return readFileSync(path, 'utf-8');
+        },
+        listDir(path) {
+            return readdirSync(path, { withFileTypes: true }).map((entry) => {
+                let bytes = 0;
+                if (entry.isFile()) {
+                    try {
+                        bytes = statSync(join(path, entry.name)).size;
+                    }
+                    catch {
+                        // A file that vanished between readdir and stat is reported as 0
+                        // bytes rather than aborting the whole listing.
+                        bytes = 0;
+                    }
+                }
+                return { name: entry.name, isDirectory: entry.isDirectory(), bytes };
+            });
+        },
+        exists(path) {
+            return existsSync(path);
+        },
+        join(...parts) {
+            return join(...parts);
+        },
+        relative(from, to) {
+            return relative(from, to);
+        },
+        isAbsolute(p) {
+            return isAbsolute(p);
+        },
+    };
+}

package/dist/skills/paths.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Skill root resolution — the four scopes of spec §6.1, in ASCENDING precedence.
+ *
+ *   bundled  <pkg>/skills          shipped with the npm package, read-only
+ *   user     <data>/skills         where `aragon skills install` writes
+ *   project  <cwd>/.aragon/skills   + <cwd>/.claude/skills (read-only)
+ *   env      ARAGON_SKILLS_PATH     debugging / CI override, read-only
+ *
+ * Same layering the config resolver already uses (defaults › file › env ›
+ * flags), so there is no second mental model to learn.
+ */
+import type { SkillScope } from '@aragon-agent/core';
+export interface SkillRoot {
+    dir: string;
+    scope: SkillScope;
+    /** False for bundled / env / `.claude/skills` — install and remove refuse these. */
+    writable: boolean;
+}
+/** `<data>` — the per-user data root. Parent of `skills/`, and where sidecar state lives. */
+export declare function getUserDataDir(): string;
+/** `<data>/skills` — the default install target. */
+export declare function getUserSkillsDir(): string;
+/** `<data>/skills/.staging` — scratch space for in-flight installs (§8.3). */
+export declare function getStagingDir(): string;
+/** `<data>/skills/.staging/.trash` — where a replaced skill is parked (P1-6). */
+export declare function getTrashDir(): string;
+/**
+ * `<pkg>/skills` — the DATA directory of bundled skills.
+ *
+ * Not to be confused with `<pkg>/dist/skills`, which is the compiled output of
+ * `src/skills/*.ts`. This module lives at `src/skills/paths.ts` in dev and at
+ * `dist/skills/paths.js` after a build, so `'..', '..'` resolves to `<pkg>` in
+ * BOTH states — no `isPackaged`-style branch is needed or wanted.
+ */
+export declare function getBundledSkillsDir(): string;
+/**
+ * Project roots for a working directory. `.claude/skills` is included for
+ * drop-in Claude Code interop (D8) and is marked read-only: `--scope project`
+ * always writes to `.aragon/skills`, never into another tool's directory.
+ */
+export declare function resolveProjectSkillDirs(cwd: string, projectDirs?: string[]): SkillRoot[];
+/** Roots listed in `ARAGON_SKILLS_PATH`, split on the platform delimiter. */
+export declare function resolveEnvSkillDirs(value?: string | undefined): SkillRoot[];
+/**
+ * All roots in ascending precedence. Non-existent directories are kept in the
+ * list — the scanner skips them — so callers can report "where would this go?"
+ * without a second resolution pass.
+ */
+export declare function resolveSkillRoots(cwd: string, projectDirs?: string[]): SkillRoot[];
+/**
+ * Canonical form of a directory for `trustedProjectDirs` comparison (P2-7).
+ *
+ * Without this, `C:\Repo\` and `c:\repo` are two different entries and the user
+ * gets asked to trust the same folder over and over — which trains them to
+ * click "yes" without reading, a strictly worse outcome than never asking.
+ * Returns `null` when the path cannot be resolved (deleted directory), so the
+ * caller skips it rather than persisting a stale entry.
+ */
+export declare function normalizeTrustPath(dir: string): string | null;
+/** True when `dir` exists and is a directory (never throws). */
+export declare function isDirectory(dir: string): boolean;

package/dist/skills/paths.js

@@ -0,0 +1,107 @@
+/**
+ * Skill root resolution — the four scopes of spec §6.1, in ASCENDING precedence.
+ *
+ *   bundled  <pkg>/skills          shipped with the npm package, read-only
+ *   user     <data>/skills         where `aragon skills install` writes
+ *   project  <cwd>/.aragon/skills   + <cwd>/.claude/skills (read-only)
+ *   env      ARAGON_SKILLS_PATH     debugging / CI override, read-only
+ *
+ * Same layering the config resolver already uses (defaults › file › env ›
+ * flags), so there is no second mental model to learn.
+ */
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { delimiter, dirname, join, resolve, sep } from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { appPaths as paths } from '../config/app-paths.js';
+/** `<data>` — the per-user data root. Parent of `skills/`, and where sidecar state lives. */
+export function getUserDataDir() {
+    return paths.data;
+}
+/** `<data>/skills` — the default install target. */
+export function getUserSkillsDir() {
+    return join(paths.data, 'skills');
+}
+/** `<data>/skills/.staging` — scratch space for in-flight installs (§8.3). */
+export function getStagingDir() {
+    return join(getUserSkillsDir(), '.staging');
+}
+/** `<data>/skills/.staging/.trash` — where a replaced skill is parked (P1-6). */
+export function getTrashDir() {
+    return join(getStagingDir(), '.trash');
+}
+/**
+ * `<pkg>/skills` — the DATA directory of bundled skills.
+ *
+ * Not to be confused with `<pkg>/dist/skills`, which is the compiled output of
+ * `src/skills/*.ts`. This module lives at `src/skills/paths.ts` in dev and at
+ * `dist/skills/paths.js` after a build, so `'..', '..'` resolves to `<pkg>` in
+ * BOTH states — no `isPackaged`-style branch is needed or wanted.
+ */
+export function getBundledSkillsDir() {
+    return join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'skills');
+}
+/**
+ * Project roots for a working directory. `.claude/skills` is included for
+ * drop-in Claude Code interop (D8) and is marked read-only: `--scope project`
+ * always writes to `.aragon/skills`, never into another tool's directory.
+ */
+export function resolveProjectSkillDirs(cwd, projectDirs = ['.aragon/skills', '.claude/skills']) {
+    return projectDirs.map((rel) => ({
+        dir: resolve(cwd, rel),
+        scope: 'project',
+        writable: rel.replace(/\\/g, '/').startsWith('.aragon/'),
+    }));
+}
+/** Roots listed in `ARAGON_SKILLS_PATH`, split on the platform delimiter. */
+export function resolveEnvSkillDirs(value = process.env.ARAGON_SKILLS_PATH) {
+    if (!value || value.trim().length === 0)
+        return [];
+    return value
+        .split(delimiter)
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0)
+        .map((p) => ({ dir: resolve(p), scope: 'env', writable: false }));
+}
+/**
+ * All roots in ascending precedence. Non-existent directories are kept in the
+ * list — the scanner skips them — so callers can report "where would this go?"
+ * without a second resolution pass.
+ */
+export function resolveSkillRoots(cwd, projectDirs) {
+    return [
+        { dir: getBundledSkillsDir(), scope: 'bundled', writable: false },
+        { dir: getUserSkillsDir(), scope: 'user', writable: true },
+        ...resolveProjectSkillDirs(cwd, projectDirs),
+        ...resolveEnvSkillDirs(),
+    ];
+}
+/**
+ * Canonical form of a directory for `trustedProjectDirs` comparison (P2-7).
+ *
+ * Without this, `C:\Repo\` and `c:\repo` are two different entries and the user
+ * gets asked to trust the same folder over and over — which trains them to
+ * click "yes" without reading, a strictly worse outcome than never asking.
+ * Returns `null` when the path cannot be resolved (deleted directory), so the
+ * caller skips it rather than persisting a stale entry.
+ */
+export function normalizeTrustPath(dir) {
+    try {
+        let real = realpathSync.native(resolve(dir));
+        while (real.length > 1 && real.endsWith(sep))
+            real = real.slice(0, -1);
+        return process.platform === 'win32' ? real.toLowerCase() : real;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when `dir` exists and is a directory (never throws). */
+export function isDirectory(dir) {
+    try {
+        return existsSync(dir) && statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}