dsh-agent-plugins-market 0.6.2 → 0.7.0

package/lib/catalog/archive.js

@@ -19,6 +19,8 @@ import { mkdir, open, readdir, readFile, readlink, rename, rm, stat } from 'node
 import { join, resolve } from 'node:path';
 import { promisify } from 'node:util';
 import { Unzip, UnzipInflate } from 'fflate';
+import { archiveFormatOf } from '../model/types.js';
+import { isWithin } from './paths.js';
 const run = promisify(execFile);
 /** Hard cap on archive download size (mirrors Claude Code's archive limit). */
 export const ARCHIVE_MAX_BYTES = 256 * 1024 * 1024;
@@ -29,17 +31,8 @@ export const ARCHIVE_MAX_ENTRIES = 20_000;
 /** Hard cap on the decompressed size of a single archive entry. */
 export const ARCHIVE_MAX_ENTRY_BYTES = 128 * 1024 * 1024;
 export const DEFAULT_ARCHIVE_TIMEOUT_MS = 180_000;
-/** Classify an archive URL by extension; undefined when unsupported. */
-export function archiveFormatOf(url) {
-    const clean = url.trim().toLowerCase();
-    if (clean.endsWith('.zip'))
-        return 'zip';
-    if (clean.endsWith('.tar.gz') || clean.endsWith('.tgz'))
-        return 'targz';
-    if (clean.endsWith('.tar'))
-        return 'tar';
-    return undefined;
-}
+/** Archive vocabulary (format kinds and URL classification) shared with the model layer. */
+export { archiveFormatOf };
 /** Download the payload to a temp file, enforcing the size cap and digest. */
 export async function downloadArchive(url, tempFile, options = {}) {
     const trimmed = url.trim();
@@ -143,7 +136,21 @@ async function extractZip(archiveFile, dest) {
     };
     const unzip = new Unzip();
     unzip.register(UnzipInflate);
-    const writes = [];
+    // Entry writes go through a fixed set of slots. The stream drives `onfile`
+    // synchronously, so an unbounded fan-out opens one descriptor per entry and
+    // hits the process limit before the entry cap does — on Windows, around the
+    // 8192nd member of a whole-archive zip. A failure recorded during the stream
+    // turns writes that have not started yet into no-ops, and a failed write lands
+    // in the same `failure` slot, so the first error is the one reported.
+    const WRITE_SLOTS = 32;
+    const writes = Array.from({ length: WRITE_SLOTS }, () => Promise.resolve());
+    let writeSlot = 0;
+    const queueWrite = (target, chunks) => {
+        const slot = writeSlot++ % WRITE_SLOTS;
+        writes[slot] = writes[slot].then(() => (failure === undefined ? writeZipEntry(target, chunks) : undefined)).catch((error) => {
+            fail(error instanceof Error ? error : new Error(String(error)));
+        });
+    };
     unzip.onfile = file => {
         if (failure !== undefined)
             return;
@@ -163,7 +170,7 @@ async function extractZip(archiveFile, dest) {
             return;
         }
         const target = join(dest, normalized);
-        if (target !== dest && !target.startsWith(`${dest}/`)) {
+        if (!isWithin(dest, target)) {
             fail(new Error(`zip entry escapes the extraction root: ${file.name}`));
             return;
         }
@@ -186,7 +193,7 @@ async function extractZip(archiveFile, dest) {
             }
             chunks.push(Buffer.from(data));
             if (final)
-                writes.push(writeZipEntry(target, chunks));
+                queueWrite(target, chunks);
         };
         file.start();
     };
@@ -196,9 +203,13 @@ async function extractZip(archiveFile, dest) {
     for (let offset = 0; offset < view.length && failure === undefined; offset += slice) {
         unzip.push(view.subarray(offset, Math.min(offset + slice, view.length)), offset + slice >= view.length);
     }
+    // Report only once every write has settled: the caller removes the staging
+    // directory in its own cleanup, and a write still in flight would recreate
+    // entries underneath that removal. A failure set during the stream makes the
+    // writes that have not started yet no-ops.
+    await Promise.all(writes);
     if (failure !== undefined)
         throw failure;
-    await Promise.all(writes);
 }
 /** Write one buffered zip entry to disk after its data completed inflating. */
 async function writeZipEntry(target, chunks) {
@@ -237,6 +248,8 @@ async function assertBoundedTree(root) {
     let totalBytes = 0;
     while (stack.length > 0) {
         const dir = stack.pop();
+        if (dir === undefined)
+            break;
         let dirents;
         try {
             dirents = await readdir(dir, { withFileTypes: true });
@@ -278,6 +291,8 @@ async function assertNoEscapingSymlinks(root) {
     const stack = [root];
     while (stack.length > 0) {
         const dir = stack.pop();
+        if (dir === undefined)
+            break;
         let entries;
         try {
             entries = await readdir(dir, { withFileTypes: true });
@@ -293,7 +308,7 @@ async function assertNoEscapingSymlinks(root) {
                 // bogus in-root path and the escape survives extraction.
                 const target = await readlink(path, 'utf8').catch(() => '');
                 const resolved = resolve(dir, target);
-                if (resolved !== root && !resolved.startsWith(`${root}/`)) {
+                if (!isWithin(root, resolved)) {
                     throw new Error(`archive contains a symlink escaping the extraction root: ${entry.name} -> ${target}`);
                 }
                 continue;
@@ -303,13 +318,12 @@ async function assertNoEscapingSymlinks(root) {
         }
     }
 }
-/** Test seam: run the symlink-containment walk against a prepared tree. */
-export const assertNoEscapingSymlinksForTest = assertNoEscapingSymlinks;
 /** If the extraction produced exactly one top-level directory and nothing else, use it as the root. */
 async function unwrapSingleRoot(extractDir) {
     const entries = await readdir(extractDir, { withFileTypes: true });
-    if (entries.length === 1 && entries[0].isDirectory())
-        return join(extractDir, entries[0].name);
+    const soleEntry = entries.length === 1 ? entries[0] : undefined;
+    if (soleEntry !== undefined && soleEntry.isDirectory())
+        return join(extractDir, soleEntry.name);
     return extractDir;
 }
 async function copyTree(from, to) {
@@ -330,12 +344,3 @@ async function copyTree(from, to) {
         }
     }
 }
-/** Probe whether a path exists and is a directory. */
-export async function isDirectory(path) {
-    try {
-        return (await stat(path)).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}

package/lib/catalog/component-files.js

@@ -1,23 +1,31 @@
 /** Resolve declared component files once; all consumers use the same contained resource paths. */
 import { readFile, readdir, realpath, stat } from 'node:fs/promises';
-import { extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { extname, join, relative, resolve } from 'node:path';
 import { PLUGIN_ROOT_VARIABLES } from '../model/layouts.js';
+import { isFile } from './fs-probes.js';
+import { isWithin } from './paths.js';
 export function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/** `Array.isArray` narrows to `any[]`; declarations are untrusted, so the elements stay `unknown`. */
+export function isUnknownArray(value) {
+    return Array.isArray(value);
+}
+/** True only for an array whose every element is a string. */
+export function isStringArray(value) {
+    return Array.isArray(value) && value.every(entry => typeof entry === 'string');
+}
 /** Reject both lexical and symlink escapes. Optional defaults may be absent without a diagnostic. */
 export async function componentPath(root, value, errors, required = true) {
     const clean = value.replace(/^\$\{([A-Z_]+)\}\//, (match, name) => (PLUGIN_ROOT_VARIABLES.has(name) ? './' : match));
     const path = resolve(root, clean);
-    const rel = relative(resolve(root), path);
-    if (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`)) {
+    if (!isWithin(resolve(root), path)) {
         errors.push(`component path ${value}: escapes the suite root`);
         return undefined;
     }
     try {
         const [base, target] = await Promise.all([realpath(root), realpath(path)]);
-        const actual = relative(base, target);
-        if (isAbsolute(actual) || actual === '..' || actual.startsWith(`..${sep}`)) {
+        if (!isWithin(base, target)) {
             errors.push(`component path ${value}: escapes the suite root through a symlink`);
             return undefined;
         }
@@ -135,7 +143,7 @@ export async function componentDocuments(root, declaration, errors, allowDirecto
 }
 export async function firstComponentFile(root, candidates) {
     for (const path of candidates)
-        if ((await stat(join(root, path)).catch(() => undefined))?.isFile())
+        if (await isFile(join(root, path)))
             return path;
     return undefined;
 }

package/lib/catalog/fs-probes.js

@@ -0,0 +1,43 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Dot-directories and dependency trees that never hold suite content. */
+export const DOT_DIRS = new Set(['.git', '.github', '.claude', '.cursor', '.kimi', '.plugin', '.sources', 'node_modules']);
+/** Whether `path` is an existing directory (symlinks followed for the final component). */
+export async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether `path` is an existing regular file. */
+export async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether any entry (file, directory, symlink) exists at `path`. */
+export async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Absolute paths of the non-hidden child directories of `dir`, in readdir order. */
+export async function listChildDirs(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries.filter(entry => entry.isDirectory() && !DOT_DIRS.has(entry.name) && !entry.name.startsWith('.')).map(entry => join(dir, entry.name));
+}

package/lib/catalog/manifests.js

@@ -18,26 +18,31 @@
  * present, while surfaces (skills/commands/agents/hooks/mcp) are scanned from
  * the directories regardless of which dialect won.
  */
-import { readFile, stat } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { sanitizeId } from './paths.js';
+import { isFile } from './fs-probes.js';
+import { isRecord } from './component-files.js';
 import { isRecognizedSchema, validatePluginManifest } from './validate.js';
 import { PLUGIN_LAYOUTS, MANIFEST_ALIASES, MARKETPLACE_PATHS } from '../model/layouts.js';
-/** The highest-precedence manifest file a directory carries, if any. */
-export async function detectManifest(dir) {
+/**
+ * Every manifest file a directory carries, in selection order: highest
+ * precedence first, aliases of one dialect in their own listed order.
+ */
+export async function detectManifests(dir) {
+    const found = [];
     for (const { kind, manifest } of PLUGIN_LAYOUTS) {
         for (const relative of [...(MANIFEST_ALIASES[kind] ?? []), manifest]) {
             const path = join(dir, relative);
-            try {
-                if ((await stat(path)).isFile())
-                    return { kind, path };
-            }
-            catch {
-                // try the next candidate
-            }
+            if (await isFile(path))
+                found.push({ kind, path });
         }
     }
-    return undefined;
+    return found;
+}
+/** The highest-precedence manifest file a directory carries, if any. */
+export async function detectManifest(dir) {
+    return (await detectManifests(dir))[0];
 }
 /** Whether a directory carries any known suite manifest. */
 export async function hasSuiteManifest(dir) {
@@ -52,14 +57,33 @@ export function componentDeclarations(record) {
     return Object.fromEntries(['skills', 'commands', 'agents', 'hooks', 'mcpServers', 'lspServers'].filter(key => value[key] !== undefined).map(key => [key, value[key]]));
 }
 /**
- * Parse one manifest document into a normalized SuiteManifest. The v1 dialect
- * is schema-validated (fail-closed); the others are structurally read with
- * light tolerance, and `hint` (a marketplace plugin entry) fills in gaps.
+ * Read a suite manifest by walking the layout priority list from the top.
+ *
+ * A candidate that cannot be parsed or validated fails closed *for itself*:
+ * its diagnostics are recorded and the next candidate by priority is tried.
+ * Diagnostics of a rejected candidate that a lower-priority manifest replaced
+ * go to `fallbacks`, so the winner stays usable while the caller can still
+ * report why the higher-priority declaration was ignored. The winner's own
+ * diagnostics stay in `errors` and remain fatal.
  */
-export async function readManifest(root, errors, hint) {
-    const candidate = await detectManifest(root);
-    if (candidate === undefined)
-        return undefined;
+export async function readManifest(root, errors, hint, fallbacks = []) {
+    const candidates = await detectManifests(root);
+    for (const [index, candidate] of candidates.entries()) {
+        const attempt = [];
+        const manifest = await readOneManifest(root, candidate, attempt, hint);
+        if (manifest !== undefined) {
+            errors.push(...attempt);
+            return manifest;
+        }
+        if (index === candidates.length - 1)
+            errors.push(...attempt);
+        else
+            fallbacks.push(...attempt);
+    }
+    return undefined;
+}
+/** Parse one manifest candidate; undefined when this candidate is unusable. */
+async function readOneManifest(root, candidate, errors, hint) {
     let raw;
     try {
         raw = JSON.parse(await readFile(candidate.path, 'utf8'));
@@ -107,7 +131,10 @@ export async function readManifest(root, errors, hint) {
         }
     }
     const problems = kind === 'agent-plugin-v1' ? await validatePluginManifest(raw) : [];
-    errors.push(...problems.map(problem => `${candidate.path}: ${problem}`));
+    if (problems.length > 0) {
+        errors.push(...problems.map(problem => `${candidate.path}: ${problem}`));
+        return undefined;
+    }
     const name = pickString(record.name) ?? hint?.name ?? syntheticManifestName(root);
     const version = pickString(record.version) ?? hint?.version;
     const description = pickString(record.description) ?? hint?.description;
@@ -165,8 +192,8 @@ async function readOneMarketplace(path, errors) {
     const rawPlugins = record['plugins'];
     const plugins = Array.isArray(rawPlugins)
         ? rawPlugins
-        : typeof rawPlugins === 'object' && rawPlugins !== null
-            ? Object.entries(rawPlugins).map(([name, entry]) => (typeof entry === 'object' && entry !== null && !Array.isArray(entry) ? { ...entry, name } : entry))
+        : isRecord(rawPlugins)
+            ? Object.entries(rawPlugins).map(([name, entry]) => (isRecord(entry) ? { ...entry, name } : entry))
             : undefined;
     if (plugins === undefined) {
         errors.push(`marketplace ${path}: "plugins" is not an array`);
@@ -226,20 +253,10 @@ export async function readMarketplaces(checkoutDir, errors = []) {
     return results;
 }
 /** Read the highest-precedence marketplace manifest, or undefined when absent. */
-export async function readMarketplace(checkoutDir) {
+async function readMarketplace(checkoutDir) {
     const results = await readMarketplaces(checkoutDir);
     return results[0];
 }
-/** Resolve one marketplace entry to a local checkout-relative directory, or
- *  `undefined` for remote-URL entries that are not present in the clone. */
-export function marketplaceEntryDir(checkoutDir, entry) {
-    const source = entry.source;
-    if (typeof source === 'string')
-        return resolve(checkoutDir, source);
-    if (source?.path !== undefined)
-        return resolve(checkoutDir, source.path);
-    return undefined;
-}
 /**
  * Resolve a repo-level name for source-id derivation, in precedence order:
  * marketplace plugin entry name > marketplace name > root manifest name >
@@ -250,20 +267,16 @@ export async function repoName(checkoutDir) {
     const marketplace = await readMarketplace(checkoutDir);
     if (marketplace !== undefined) {
         const entries = marketplace.entries;
-        if (entries.length === 1) {
+        const soleEntry = entries.length === 1 ? entries[0] : undefined;
+        if (soleEntry !== undefined) {
             // A single-suite marketplace: the plugin entry names the repo (vercel → vercel-plugin).
-            const entryName = pickString(entries[0].name);
+            const entryName = pickString(soleEntry.name);
             if (entryName !== undefined)
                 return entryName;
         }
         const marketplaceName = pickString(marketplace.name);
         if (marketplaceName !== undefined)
             return marketplaceName;
-        if (entries.length === 1) {
-            const entryName = pickString(entries[0].name);
-            if (entryName !== undefined)
-                return entryName;
-        }
     }
     const candidate = await detectManifest(checkoutDir);
     if (candidate !== undefined) {
@@ -281,55 +294,3 @@ export async function repoName(checkoutDir) {
     }
     return syntheticManifestName(checkoutDir);
 }
-/** The winning manifest's declared `skills` path (string or array), or undefined. */
-export async function declaredSkillsPath(root) {
-    const candidate = await detectManifest(root);
-    if (candidate === undefined)
-        return undefined;
-    try {
-        const raw = JSON.parse(await readFile(candidate.path, 'utf8'));
-        if (typeof raw === 'object' && raw !== null) {
-            return raw['skills'];
-        }
-    }
-    catch {
-        return undefined;
-    }
-    return undefined;
-}
-/** The winning manifest's inline `mcpServers`, or undefined. */
-export async function declaredMcpServers(root) {
-    const candidate = await detectManifest(root);
-    if (candidate === undefined)
-        return undefined;
-    try {
-        const raw = JSON.parse(await readFile(candidate.path, 'utf8'));
-        if (typeof raw === 'object' && raw !== null) {
-            const servers = raw['mcpServers'];
-            if (typeof servers === 'object' && servers !== null)
-                return servers;
-        }
-    }
-    catch {
-        return undefined;
-    }
-    return undefined;
-}
-/** The winning manifest's inline `lspServers`, or undefined. */
-export async function declaredLspServers(root) {
-    const candidate = await detectManifest(root);
-    if (candidate === undefined)
-        return undefined;
-    try {
-        const raw = JSON.parse(await readFile(candidate.path, 'utf8'));
-        if (typeof raw === 'object' && raw !== null) {
-            const servers = raw['lspServers'];
-            if (typeof servers === 'object' && servers !== null)
-                return servers;
-        }
-    }
-    catch {
-        return undefined;
-    }
-    return undefined;
-}

package/lib/catalog/native-project.js

@@ -10,8 +10,8 @@
  * installed, uninstalled, or mutated by this manager.
  */
 import { join } from 'node:path';
-import { stat } from 'node:fs/promises';
 import { sanitizeId } from './paths.js';
+import { isFile } from './fs-probes.js';
 import { countSurfaces, discoverSkills } from './surfaces.js';
 import { PROJECT_LAYOUTS } from '../model/layouts.js';
 import { discoverProjectMcp } from './project-config.js';
@@ -46,7 +46,7 @@ export async function discoverNativeProjectSuites(projectRoot, dimension) {
         if (native.dirName === '.github')
             lspFiles.push('lsp.json');
         for (const path of lspFiles) {
-            if ((await stat(join(projectRoot, path)).catch(() => undefined))?.isFile()) {
+            if (await isFile(join(projectRoot, path))) {
                 errors.push(`${path}: project LSP configuration is not mounted; the host LSP registry does not isolate projects`);
             }
         }

package/lib/catalog/paths.js

@@ -1,38 +1,57 @@
 /**
- * Root path resolution for the two install dimensions.
+ * Root path resolution for the two install dimensions plus the shared
+ * user-level Agent layout root.
  *
- * User dimension: `~/.dsh/agent-plugins/` (or `$DSH_HOME/agent-plugins`).
+ * User dimension: `~/.dsh/agent-plugins/` (or `$DSH_HOME/agent-plugins`) —
+ * `.sources/` (checkouts), `state.json` (install state), and `data/`
+ * (`overrides/`, suite `${PLUGIN_DATA}` directories, and the LSP enable set
+ * with the feedback rate-limit stamp).
  * Project dimension: `<projectRoot>/.dsh/agent-plugins/`, where the project
  * root is the nearest ancestor containing `.git`.
  *
- * Everything the plugin persists lives under one root per dimension —
- * `.sources/` (checkouts) and `state.json` (install state) alongside `data/`
- * (suite `${PLUGIN_DATA}` directories) and `overrides/` (MCP configuration
- * rewrites) — so no sibling `agent-plugins-data` root exists.
+ * Content the user authors, and the services they declare by hand, live in the
+ * cross-tool Agent layout root instead: `~/.agents/{skills,commands,agents}/`
+ * and `~/.agents/{mcp,lsp}.json`. That is the same directory shape the plugin
+ * already reads from a project's `.agents/`, so user-authored resources are
+ * plain Markdown and ordinary JSON that other Agent tools can consume too.
  */
 import { existsSync } from 'node:fs';
-import { stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { expandHomePath, resolveDshHome as resolveHarnessHome } from '@deepseek-ai/dsh-home-paths';
+import { stripArchiveSuffix } from '../model/types.js';
 /** Source checkouts live under `<dimensionRoot>/.sources/<sourceId>/`. */
 export const SOURCES_DIR_NAME = '.sources';
-/** Per-suite mutable data directory (the `${PLUGIN_DATA}` placeholder). */
-export const DATA_DIR_NAME = 'data';
 export const STATE_FILE_NAME = 'state.json';
-/** Expand a leading `~/` (or `~\` on Windows) to the home directory; other values pass through. */
-export function expandHome(path) {
-    if (path === '~' || path.startsWith('~/') || path.startsWith('~\\'))
-        return join(homedir(), path.slice(2));
-    return path;
-}
-/** Resolve the harness home (`$DSH_HOME` or `~/.dsh`). */
+/**
+ * Expand a leading `~`, `~/`, or `~\` to the OS home; other values pass
+ * through. The harness helper owns the platform rules, so a configured path is
+ * read back the same way on every host.
+ */
+export const expandHome = expandHomePath;
+/**
+ * Resolve the harness home (`$DSH_HOME` or `~/.dsh`) through the harness
+ * helper: precedence and tilde expansion stay the harness's, and a blank
+ * `$DSH_HOME` reads as unset rather than resolving the home to the current
+ * working directory.
+ */
 export function resolveDshHome() {
-    return process.env.DSH_HOME === undefined ? join(homedir(), '.dsh') : resolve(process.env.DSH_HOME);
+    return resolveHarnessHome();
 }
 /** Resolve the canonical user-dimension root. Legacy overrides are migration inputs only. */
 export function resolveUserRoot(_configUserRoot) {
     return join(resolveDshHome(), 'agent-plugins');
 }
+/**
+ * Resolve the shared user-level Agent layout root (`$DSH_AGENTS_HOME` or
+ * `~/.agents`): where this plugin stores the resources and service
+ * declarations the user authors by hand. A blank override reads as unset, the
+ * same rule the harness applies to its own home.
+ */
+export function resolveAgentsRoot() {
+    const configured = process.env.DSH_AGENTS_HOME;
+    return configured === undefined || configured.trim().length === 0 ? join(homedir(), '.agents') : resolve(expandHome(configured));
+}
 /**
  * Resolve the suite data root hosting `${PLUGIN_DATA}` directories and the
  * MCP overrides. Defaults under the user root so the whole plugin persists
@@ -57,18 +76,14 @@ export async function findProjectRoot(cwd) {
 export async function resolveProjectRoot(cwd) {
     return join(await findProjectRoot(cwd), '.dsh', 'agent-plugins');
 }
-/** Source checkout directory for one source id. */
+/** Directory holding every source checkout of one dimension root. */
 export function sourcesDir(dimensionRoot) {
     return join(dimensionRoot, SOURCES_DIR_NAME);
 }
-/** Source checkout directory for one source id. */
+/** Checkout directory of one source inside a dimension root. */
 export function sourceCheckoutDir(dimensionRoot, sourceId) {
     return join(sourcesDir(dimensionRoot), sourceId);
 }
-/** Per-suite data directory for `${PLUGIN_DATA}`. */
-export function suiteDataDir(dataRoot, suiteId) {
-    return join(dataRoot, DATA_DIR_NAME, suiteId);
-}
 /**
  * Suite-qualified key: `${sourceId}/${suiteId}`. Suite ids are unique within a
  * source only (two sources may both ship a suite named "utils"), so every
@@ -78,25 +93,29 @@ export function suiteDataDir(dataRoot, suiteId) {
 export function qualifiedSuiteId(sourceId, suiteId) {
     return `${sourceId}/${suiteId}`;
 }
-/** Async existence probe that follows symlinks for a final component. */
-export async function isDirectory(path) {
-    try {
-        const info = await stat(path);
-        return info.isDirectory();
-    }
-    catch {
-        return false;
-    }
+/**
+ * Whether `candidate` is `root` itself or a path below it, compared on whole
+ * path segments by `flavor`'s rules so a sibling whose name merely starts with
+ * the root's (`/a/bc` against `/a/b`) does not count as contained.
+ *
+ * `relative` resolves both operands with those rules before comparing, so the
+ * answer never depends on how each side was spelled: a checkout read from
+ * configuration as `C:/x/y` and an entry resolved to `C:\x\y\plugins\a` stay
+ * contained, Windows compares drive letters and segments case-insensitively,
+ * and an unnormalized `..` inside the candidate is resolved rather than
+ * trusted as text. On POSIX a backslash stays the ordinary filename character
+ * it is — folding separators there would invent containment that does not
+ * exist.
+ *
+ * `flavor` is injectable so the win32 rules stay covered by a POSIX test run.
+ */
+export function isWithinUnder(flavor, root, candidate) {
+    const rel = flavor.relative(root, candidate);
+    return rel === '' || (!rel.startsWith(`..${flavor.sep}`) && rel !== '..' && !flavor.isAbsolute(rel));
 }
-/** Async existence probe for any entry (file, directory, symlink). */
-export async function pathExists(path) {
-    try {
-        await stat(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
+/** Whether `candidate` is `root` itself or a path below it, by the host's path rules. */
+export function isWithin(root, candidate) {
+    return isWithinUnder({ relative, isAbsolute, sep }, root, candidate);
 }
 /** Sanitize a plugin or server id into `[a-z0-9-]` (lowercased). */
 export function sanitizeId(raw) {
@@ -107,19 +126,10 @@ export function sanitizeId(raw) {
         .replace(/-{2,}/g, '-');
     return cleaned === '' ? 'unnamed' : cleaned;
 }
-/** Archive extensions stripped from a URL basename before id derivation. */
-const ARCHIVE_SUFFIX_PATTERN = /\.(zip|tgz|tar\.gz|tar)$/i;
 /** Strip a trailing `.git` or archive suffix (`plugin-0.1.zip` → `plugin-0-1`). */
 function stripSourceSuffix(base) {
-    if (base.endsWith('.git'))
-        base = base.slice(0, -4);
-    return base.replace(ARCHIVE_SUFFIX_PATTERN, '');
-}
-/** Derive a source id from a repository URL or local path: last path segment, `.git` stripped. */
-export function deriveSourceId(url) {
-    const trimmed = url.trim().replace(/\/+$/, '');
-    const base = trimmed.split(/[/\\]/).at(-1) ?? '';
-    return sanitizeId(stripSourceSuffix(base));
+    const withoutGit = base.endsWith('.git') ? base.slice(0, -4) : base;
+    return stripArchiveSuffix(withoutGit);
 }
 /**
  * Derive candidate source ids from a git URL or local path, most preferred
@@ -137,8 +147,9 @@ export function deriveSourceIdCandidates(url) {
     if (isRemote) {
         const hostPath = trimmed.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '').replace(/^[\w.-]+@([\w.-]+):/, '$1/');
         const segments = hostPath.split(/[/\\]/).filter(Boolean);
-        if (segments.length >= 2) {
-            const owner = sanitizeId(segments[segments.length - 2]);
+        const ownerSegment = segments.at(-2);
+        if (ownerSegment !== undefined) {
+            const owner = sanitizeId(ownerSegment);
             if (owner !== '' && owner !== primary)
                 candidates.push(`${owner}-${primary}`);
         }

package/lib/catalog/project-config.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { validateMcpJson } from './validate.js';
 import { parse as parseToml } from 'smol-toml';
 import { normalizeCodexMcp } from './codex-mcp.js';
+import { isWithin } from './paths.js';
 /** Later files override earlier keys; a malformed layer invalidates the whole layout's table. */
 export async function discoverProjectMcp(projectRoot, files, errors, format = 'mcpServers') {
     const servers = Object.create(null);
@@ -64,7 +65,7 @@ export async function readProjectDocument(projectRoot, file, errors, format = 'J
     let text;
     try {
         const [base, target] = await Promise.all([realpath(projectRoot), realpath(path)]);
-        if (!target.startsWith(`${base}/`)) {
+        if (!isWithin(base, target)) {
             errors.push(`${file}: project configuration escapes the project root`);
             return null;
         }