dsh-agent-plugins-market 0.6.2 → 0.7.1

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,37 @@ 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;
-    }
+/**
+ * The data directory `${PLUGIN_DATA}` resolves to for one suite: a
+ * source-qualified directory under the plugin storage root, shared by every
+ * surface of that suite so MCP servers, skills and commands see one location.
+ */
+export function suiteDataDir(dataRoot, sourceId, suiteId) {
+    return `${dataRoot.replace(/[\\/]$/, '')}/${qualifiedSuiteId(sourceId, suiteId)}`;
 }
-/** 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, 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));
+}
+/** 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 +134,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 +155,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/plugin-variables.js

@@ -0,0 +1,38 @@
+/**
+ * Path-variable expansion for author-written suite text.
+ *
+ * A suite authored for Claude Code or its dialects writes `${CLAUDE_PLUGIN_ROOT}`
+ * (or the dialect's own spelling) into command bodies, agent personas, hook
+ * commands, LSP declarations, startup instructions and skill prose, and uses
+ * `${CLAUDE_PLUGIN_DATA}`, `${CLAUDE_PROJECT_DIR}` and `${CLAUDE_SKILL_DIR}` the
+ * same way. Its home ecosystem replaces those variables before the text reaches
+ * the model or a process; every surface here has to do the same, or the command
+ * runs with an empty path. One implementation keeps the surfaces agreeing on
+ * what each spelling means.
+ *
+ * A variable whose value the calling layer does not hold is left exactly as
+ * written: an author's `${NAME:-default}`-style intent is never silently
+ * emptied, and a surface that cannot supply a session directory does not
+ * invent one.
+ */
+import { PLUGIN_DATA_VARIABLES, PLUGIN_ROOT_VARIABLES, PROJECT_DIR_VARIABLES, SKILL_DIR_VARIABLE } from '../model/layouts.js';
+/** The suite root `${PLUGIN_ROOT}` and its dialect aliases resolve to. */
+export function pluginRootOf(suite) {
+    // Project-native directories are the repository's own files, read in place;
+    // no plugin root exists for them, so the variable stays as the author wrote it.
+    return suite.manifest.layout === 'project-native' ? undefined : suite.root;
+}
+/** Replace every path variable the context can resolve; other text stays exactly as written. */
+export function expandPluginPaths(text, context) {
+    return text.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (match, name) => {
+        if (PLUGIN_ROOT_VARIABLES.has(name))
+            return context.root ?? match;
+        if (PLUGIN_DATA_VARIABLES.has(name))
+            return context.data ?? match;
+        if (name === SKILL_DIR_VARIABLE)
+            return context.skillDir ?? match;
+        if (PROJECT_DIR_VARIABLES.has(name))
+            return context.projectDir ?? match;
+        return match;
+    });
+}

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;
         }

package/lib/catalog/project-hooks.js

@@ -3,6 +3,27 @@ const EVENTS = new Set(['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostT
 function object(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * Render a declared hook field inside a diagnostic. Declarations are
+ * untrusted JSON, so the value is whatever the file carried — including an
+ * object, which reads as `[object Object]` in the message.
+ */
+function declarationText(value) {
+    return String(value);
+}
+/**
+ * Present one read document as the settings shape the shared validator reads:
+ * a standalone hook file may carry the bare event table instead of a `hooks`
+ * key. A recognized top-level event name is the marker — a document with no
+ * event name at the top stays verbatim, so an ordinary settings file missing
+ * `hooks` is still not accepted as a bare event table.
+ */
+function settingsDocument(settings, format) {
+    if (format !== 'claude' || settings.hooks !== undefined)
+        return settings;
+    const isEventTable = Object.keys(settings).some(key => EVENTS.has(key));
+    return isEventTable ? { ...settings, hooks: settings } : settings;
+}
 /** Merge settings layers additively, deduplicating identical event/matcher/command triples. */
 export async function discoverProjectHooks(projectRoot, files, errors, format = 'claude') {
     const documents = [];
@@ -11,7 +32,7 @@ export async function discoverProjectHooks(projectRoot, files, errors, format =
         if (settings === null)
             return undefined;
         if (settings !== undefined)
-            documents.push({ file, settings });
+            documents.push({ file, settings: settingsDocument(settings, format) });
     }
     return normalizeHookDocuments(projectRoot, documents, errors, format);
 }
@@ -74,7 +95,7 @@ export function normalizeHookDocuments(projectRoot, documents, errors, format =
                     if (hook.enabled === false)
                         continue;
                     if (hook.type !== undefined && hook.type !== 'command') {
-                        errors.push(`${file}: unsupported ${event} hook type ${String(hook.type)}`);
+                        errors.push(`${file}: unsupported ${event} hook type ${declarationText(hook.type)}`);
                         continue;
                     }
                     if (typeof hook.command !== 'string' ||