dsh-agent-plugins-market 0.6.1 → 0.6.2

package/lib/catalog/project-config.js

@@ -0,0 +1,96 @@
+/** Read native project configuration without treating unrelated settings as server definitions. */
+import { readFile, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { validateMcpJson } from './validate.js';
+import { parse as parseToml } from 'smol-toml';
+import { normalizeCodexMcp } from './codex-mcp.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);
+    let found = false;
+    for (const file of files) {
+        const raw = await readProjectDocument(projectRoot, file, errors, format === 'codex' ? 'TOML' : 'JSON');
+        if (raw === null)
+            return undefined;
+        if (raw === undefined)
+            continue;
+        if (format === 'codex') {
+            if (raw.mcp_servers === undefined)
+                continue;
+            if (typeof raw.mcp_servers !== 'object' || raw.mcp_servers === null || Array.isArray(raw.mcp_servers)) {
+                errors.push(`${file}: mcp_servers must be a table`);
+                return undefined;
+            }
+            found = true;
+            Object.assign(servers, normalizeCodexMcp(raw.mcp_servers, errors));
+            continue;
+        }
+        const mcp = raw.mcp;
+        if (format === 'zcode' && mcp === undefined)
+            continue;
+        if (format === 'zcode' && (typeof mcp !== 'object' || mcp === null || Array.isArray(mcp))) {
+            errors.push(`${file}: mcp must be an object`);
+            return undefined;
+        }
+        if (format === 'zcode' && mcp.enabled === false)
+            return undefined;
+        const table = format === 'zcode' ? mcp.servers : raw.mcpServers;
+        if (format === 'zcode' && table === undefined)
+            continue;
+        if (table === undefined && /settings(?:\.local)?\.json$/.test(file))
+            continue;
+        if (typeof table !== 'object' || table === null || Array.isArray(table)) {
+            errors.push(`${file}: mcpServers must be an object`);
+            return undefined;
+        }
+        found = true;
+        Object.assign(servers, table);
+    }
+    if (format === 'zcode' && Object.keys(servers).length === 0)
+        return discoverProjectMcp(projectRoot, ['.agents/mcp.json'], errors);
+    if (!found)
+        return undefined;
+    for (const [key, server] of Object.entries(servers)) {
+        if (typeof server === 'object' && server !== null && server.enabled === false)
+            delete servers[key];
+    }
+    const result = await validateMcpJson(projectRoot, { mcpServers: servers }, { strict: false, pathMode: 'project' });
+    errors.push(...result.errors.map(error => `project MCP: ${error}`));
+    return result.config === undefined ? undefined : { ...result.config, root: projectRoot };
+}
+/** Missing is undefined; malformed/unreadable is null and carries a diagnostic. */
+export async function readProjectDocument(projectRoot, file, errors, format = 'JSON') {
+    const path = join(projectRoot, file);
+    let text;
+    try {
+        const [base, target] = await Promise.all([realpath(projectRoot), realpath(path)]);
+        if (!target.startsWith(`${base}/`)) {
+            errors.push(`${file}: project configuration escapes the project root`);
+            return null;
+        }
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        errors.push(`${file}: project configuration is unreadable`);
+        return null;
+    }
+    let raw;
+    try {
+        raw = format === 'TOML' ? parseToml(text) : JSON.parse(text);
+    }
+    catch {
+        errors.push(`${file}: project configuration is invalid ${format}`);
+        return null;
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        errors.push(`${file}: project configuration must be an object`);
+        return null;
+    }
+    const record = raw;
+    if (record.lspServers !== undefined || record.lsp_servers !== undefined) {
+        errors.push(`${file}: project LSP declarations are not mounted; the host LSP registry does not isolate projects`);
+    }
+    return record;
+}

package/lib/catalog/project-hooks.js

@@ -0,0 +1,108 @@
+import { readProjectDocument } from './project-config.js';
+const EVENTS = new Set(['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'SubagentStart', 'SubagentStop']);
+function object(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Merge settings layers additively, deduplicating identical event/matcher/command triples. */
+export async function discoverProjectHooks(projectRoot, files, errors, format = 'claude') {
+    const documents = [];
+    for (const file of files) {
+        const settings = await readProjectDocument(projectRoot, file, errors);
+        if (settings === null)
+            return undefined;
+        if (settings !== undefined)
+            documents.push({ file, settings });
+    }
+    return normalizeHookDocuments(projectRoot, documents, errors, format);
+}
+/** Pure validation shared by native settings and plugin file/inline declarations. */
+export function normalizeHookDocuments(projectRoot, documents, errors, format = 'claude') {
+    const events = Object.create(null);
+    const seen = new Set();
+    let disabled = false;
+    for (const { file, settings } of documents) {
+        if (settings?.disableAllHooks !== undefined) {
+            if (typeof settings.disableAllHooks !== 'boolean') {
+                errors.push(`${file}: disableAllHooks must be a boolean`);
+                return undefined;
+            }
+            disabled = settings.disableAllHooks;
+        }
+        if (settings?.hooks === undefined)
+            continue;
+        if (!object(settings.hooks)) {
+            errors.push(`${file}: hooks must be an event table`);
+            return undefined;
+        }
+        if (format === 'zcode' && settings.hooks.enabled !== true)
+            continue;
+        const eventTable = format === 'zcode' ? settings.hooks.events : settings.hooks;
+        if (!object(eventTable)) {
+            errors.push(`${file}: hooks.events must be an event table`);
+            return undefined;
+        }
+        for (const [event, groups] of Object.entries(eventTable)) {
+            if (!EVENTS.has(event)) {
+                errors.push(`${file}: unsupported project hook event ${event}`);
+                continue;
+            }
+            if (!Array.isArray(groups)) {
+                errors.push(`${file}: ${event} hook groups must be an array`);
+                return undefined;
+            }
+            for (const group of groups) {
+                if (!object(group) || !Array.isArray(group.hooks) || (group.matcher !== undefined && typeof group.matcher !== 'string')) {
+                    errors.push(`${file}: invalid ${event} hook group`);
+                    return undefined;
+                }
+                const matcher = event === 'Stop' || event === 'UserPromptSubmit' ? undefined : group.matcher;
+                if (matcher !== undefined && matcher !== '*') {
+                    try {
+                        new RegExp(matcher);
+                    }
+                    catch {
+                        errors.push(`${file}: invalid ${event} hook matcher`);
+                        return undefined;
+                    }
+                }
+                const hooks = [];
+                for (const hook of group.hooks) {
+                    if (!object(hook)) {
+                        errors.push(`${file}: invalid ${event} hook`);
+                        return undefined;
+                    }
+                    if (hook.enabled === false)
+                        continue;
+                    if (hook.type !== undefined && hook.type !== 'command') {
+                        errors.push(`${file}: unsupported ${event} hook type ${String(hook.type)}`);
+                        continue;
+                    }
+                    if (typeof hook.command !== 'string' ||
+                        hook.command.trim() === '' ||
+                        (hook.timeout !== undefined && (typeof hook.timeout !== 'number' || !Number.isFinite(hook.timeout) || hook.timeout <= 0))) {
+                        errors.push(`${file}: invalid ${event} command hook`);
+                        return undefined;
+                    }
+                    if (hook.async === true || hook.asyncRewake === true) {
+                        errors.push(`${file}: asynchronous project hooks are unsupported`);
+                        continue;
+                    }
+                    const key = JSON.stringify([event, matcher, hook.command]);
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    const timeoutMs = hook.timeoutMs ?? settings.hooks.timeoutMs;
+                    if (format === 'zcode' && timeoutMs !== undefined && (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+                        errors.push(`${file}: invalid ${event} hook timeoutMs`);
+                        return undefined;
+                    }
+                    const timeout = format === 'zcode' && typeof timeoutMs === 'number' ? timeoutMs / 1000 : hook.timeout;
+                    hooks.push({ type: 'command', command: hook.command, ...(typeof timeout === 'number' ? { timeout } : {}) });
+                }
+                if (hooks.length > 0)
+                    (events[event] ??= []).push({ ...(matcher === undefined ? {} : { matcher }), hooks });
+            }
+        }
+    }
+    return !disabled && Object.keys(events).length > 0 ? { projectRoot, events } : undefined;
+}

package/lib/catalog/scan-pipeline.js

@@ -46,5 +46,10 @@ export async function runScanChain(filters, context) {
         return resolution;
     };
     const resolution = await run(0);
-    return { suites: resolution.kind === 'resolved' ? resolution.suites : [], attempts, notes };
+    return {
+        suites: resolution.kind === 'resolved' ? resolution.suites : [],
+        attempts,
+        notes,
+        ...(context.marketplacePath === undefined ? {} : { marketplacePath: context.marketplacePath })
+    };
 }

package/lib/catalog/scan-resolvers.js

@@ -18,12 +18,13 @@
  * 3. `FlatCollectionsStrategy` — the terminal fallback: manifest-less
  *    `<root>/<name>/SKILL.md` collections.
  */
-import { readdir, stat } from 'node:fs/promises';
+import { readdir, realpath, stat } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { isDirectory, sanitizeId } from './paths.js';
-import { declaredSkillsPath, detectManifest, readManifest, readMarketplaces, syntheticManifestName, declaredLspServers } from './manifests.js';
-import { countSurfaces, discoverMcp, discoverSkills } from './surfaces.js';
-import { parseLspServers } from './lsp-spec.js';
+import { componentDeclarations, detectManifest, readManifest, readMarketplaces, syntheticManifestName } from './manifests.js';
+import { countSurfaces, discoverMcp, discoverSkills, listMdFiles } from './surfaces.js';
+import { discoverMarkdownResources } from './component-files.js';
+import { discoverSuiteHooks, discoverSuiteLsp, discoverSystemPrompt } from './suite-components.js';
 import { runScanChain } from './scan-pipeline.js';
 export { repoName } from './manifests.js';
 export { listMdFiles, discoverLspEntries } from './surfaces.js';
@@ -71,7 +72,7 @@ export function entryRemoteUrl(entry) {
         return record['url'];
     return githubRepoUrl(record);
 }
-function claimLocal(checkout, declaredPath) {
+async function claimLocal(checkout, declaredPath) {
     const dir = resolve(checkout, declaredPath);
     // Containment guard: a relative entry must stay inside the checkout.
     if (dir !== checkout && !dir.startsWith(`${checkout}/`)) {
@@ -80,6 +81,15 @@ function claimLocal(checkout, declaredPath) {
         // handlers must not reinterpret it as something else.
         return { kind: 'rejected', reason: `path "${declaredPath}" escapes the checkout` };
     }
+    try {
+        const [realCheckout, realDir] = await Promise.all([realpath(checkout), realpath(dir)]);
+        if (realDir !== realCheckout && !realDir.startsWith(`${realCheckout}/`)) {
+            return { kind: 'rejected', reason: `path "${declaredPath}" escapes the checkout through a symlink` };
+        }
+    }
+    catch {
+        return { kind: 'rejected', reason: `path "${declaredPath}" is missing or unreadable` };
+    }
     return { kind: 'local', dir };
 }
 function unclaimed(reason) {
@@ -88,7 +98,7 @@ function unclaimed(reason) {
 /** String source: a checkout-relative path (Claude Code `"./skills/x"` form). */
 const STRING_PATH_HANDLER = {
     name: 'local-string-path',
-    handle(context) {
+    async handle(context) {
         const source = context.entry.source;
         if (typeof source !== 'string')
             return unclaimed('source is not a path string');
@@ -98,11 +108,13 @@ const STRING_PATH_HANDLER = {
 /** Object source with `path`: Codex `{ source: 'local', path }` and Claude `{ path }`. */
 const OBJECT_PATH_HANDLER = {
     name: 'local-object-path',
-    handle(context) {
+    async handle(context) {
         const source = context.entry.source;
         if (source === null || typeof source !== 'object')
             return unclaimed('source is not an object');
         const record = source;
+        if (entryRemoteUrl(context.entry) !== undefined)
+            return unclaimed('path belongs to a remote source');
         if (typeof record['path'] !== 'string' || record['path'] === '')
             return unclaimed('object source carries no path');
         return claimLocal(context.checkout, record['path']);
@@ -128,7 +140,8 @@ const ENTRY_HANDLERS = [STRING_PATH_HANDLER, OBJECT_PATH_HANDLER, REMOTE_URL_HAN
 export async function resolveMarketplaceEntry(checkout, entry, sourceUrl) {
     const remoteUrl = entryRemoteUrl(entry);
     if (sourceUrl !== undefined && remoteUrl !== undefined && canonicalGitUrl(remoteUrl) === canonicalGitUrl(sourceUrl) && (await isDirectory(checkout))) {
-        return { kind: 'local', dir: checkout };
+        const source = entry.source;
+        return typeof source === 'object' && source !== null && typeof source.path === 'string' ? claimLocal(checkout, source.path) : { kind: 'local', dir: checkout };
     }
     let lastReason = 'no handler claimed the entry';
     for (const handler of ENTRY_HANDLERS) {
@@ -148,20 +161,21 @@ export async function resolveMarketplaceEntry(checkout, entry, sourceUrl) {
 export class MarketplaceStrategy {
     name = 'marketplace';
     async doScan(context, chain) {
-        const marketplaces = await readMarketplaces(context.checkout);
+        const marketplaces = await readMarketplaces(context.checkout, context.notes);
         for (const marketplace of marketplaces) {
             const roots = await this.marketplaceRoots(context, marketplace.entries);
             if (roots.length === 0) {
                 context.notes.push(`marketplace ${marketplace.path}: no entry resolved (all ${marketplace.entries.length} dropped or remote)`);
                 continue;
             }
-            const suites = await Promise.all(roots.map(async (root) => root.dir === undefined ? remoteSuite(context.sourceId, context.dimension, root) : readSuite(root.dir, context.sourceId, context.dimension, root.hint)));
+            const suites = await Promise.all(roots.map(async (root) => root.dir === undefined ? remoteSuite(context.sourceId, context.dimension, root) : readSuite(root.dir, context.sourceId, context.dimension, root.hint, context.notes)));
             const resolved = suites.filter((suite) => suite !== undefined);
             if (resolved.length === 0) {
                 context.notes.push(`marketplace ${marketplace.path}: every resolved entry failed to parse a manifest`);
                 continue;
             }
             // A productive dialect wins; supplement with containers it did not list.
+            context.marketplacePath = marketplace.path;
             for (const container of CONTAINER_DIRS) {
                 const containerDir = join(context.checkout, container);
                 if (!(await isDirectory(containerDir)))
@@ -169,7 +183,7 @@ export class MarketplaceStrategy {
                 for (const child of await listChildDirs(containerDir)) {
                     if (roots.some(root => root.dir === child) || !(await hasSuiteManifest(child)))
                         continue;
-                    const extra = await readSuite(child, context.sourceId, context.dimension, undefined);
+                    const extra = await readSuite(child, context.sourceId, context.dimension, undefined, context.notes);
                     if (extra !== undefined)
                         resolved.push(extra);
                 }
@@ -186,6 +200,8 @@ export class MarketplaceStrategy {
         const seen = new Set();
         for (const entry of entries) {
             const hint = {
+                ...componentDeclarations(entry),
+                layout: entry.layout,
                 name: entry.name,
                 version: entry.version,
                 description: entry.description,
@@ -221,13 +237,13 @@ export class RootedStrategy {
     name = 'rooted';
     async doScan(context, chain) {
         if (await hasSuiteManifest(context.checkout)) {
-            const suite = await readSuite(context.checkout, context.sourceId, context.dimension, undefined);
+            const suite = await readSuite(context.checkout, context.sourceId, context.dimension, undefined, context.notes);
             return suite === undefined ? chain.next(context) : { kind: 'resolved', suites: [suite] };
         }
         const found = await collectRoots(context.checkout, undefined, new Set());
         if (found.length === 0)
             return chain.next(context);
-        const suites = await Promise.all(found.map(async (root) => root.dir === undefined ? remoteSuite(context.sourceId, context.dimension, root) : readSuite(root.dir, context.sourceId, context.dimension, root.hint)));
+        const suites = await Promise.all(found.map(async (root) => root.dir === undefined ? remoteSuite(context.sourceId, context.dimension, root) : readSuite(root.dir, context.sourceId, context.dimension, root.hint, context.notes)));
         const resolved = suites.filter((suite) => suite !== undefined);
         return resolved.length === 0 ? chain.next(context) : { kind: 'resolved', suites: resolved };
     }
@@ -236,6 +252,10 @@ export class RootedStrategy {
 export class FlatCollectionsStrategy {
     name = 'flat-collections';
     async doScan(context) {
+        // A declared suite has already been evaluated by rooted discovery.
+        // Reinterpreting its children would bypass a rejected manifest.
+        if (await hasSuiteManifest(context.checkout))
+            return { kind: 'resolved', suites: [] };
         const collection = [];
         for (const child of await listChildDirs(context.checkout)) {
             if (await hasSkillFiles(child))
@@ -245,7 +265,7 @@ export class FlatCollectionsStrategy {
             context.notes.push('checkout declares no recognizable plugin shape');
             return { kind: 'resolved', suites: [] };
         }
-        const suites = await Promise.all(collection.map(async (root) => root.dir === undefined ? remoteSuite(context.sourceId, context.dimension, root) : readSuite(root.dir, context.sourceId, context.dimension, root.hint)));
+        const suites = await Promise.all(collection.map(async (root) => root.dir === undefined ? remoteSuite(context.sourceId, context.dimension, root) : readSuite(root.dir, context.sourceId, context.dimension, root.hint, context.notes)));
         return { kind: 'resolved', suites: suites.filter((suite) => suite !== undefined) };
     }
 }
@@ -280,7 +300,7 @@ async function collectRoots(dir, hint, seen, depth = 0) {
     // An entry carrying inline LSP declarations is a suite by declaration alone
     // (official CC lsp plugins ship only a README), but only at the marketplace
     // entry root — never deeper, so containers cannot self-declare.
-    if ((await hasSuiteManifest(dir)) || (await hasSkillFiles(dir)) || (hint?.lspServers !== undefined && depth === 0)) {
+    if ((await hasSuiteManifest(dir)) || (await hasSkillFiles(dir)) || (hint !== undefined && Object.keys(componentDeclarations(hint)).length > 0 && depth === 0)) {
         seen.add(dir);
         return [{ dir, hint }];
     }
@@ -299,6 +319,8 @@ export async function hasSkillFiles(dir) {
     const skillsDir = join(dir, 'skills');
     if (!(await isDirectory(skillsDir)))
         return false;
+    if ((await listMdFiles(skillsDir)).length > 0)
+        return true;
     for (const child of await listChildDirs(skillsDir)) {
         if (await isFile(join(child, 'SKILL.md')))
             return true;
@@ -316,15 +338,21 @@ async function listChildDirs(dir) {
     return entries.filter(entry => entry.isDirectory() && !DOT_DIRS.has(entry.name) && !entry.name.startsWith('.')).map(entry => join(dir, entry.name));
 }
 /** Read one suite root into the normalized shape, or undefined when no manifest parses. */
-export async function readSuite(root, sourceId, dimension, hint) {
+export async function readSuite(root, sourceId, dimension, hint, notes = []) {
     const errors = [];
-    let manifest = (await readManifest(root, errors, hint)) ?? (await syntheticManifest(root));
+    const declaredManifest = await hasSuiteManifest(root);
+    let manifest = declaredManifest ? await readManifest(root, errors, hint) : await syntheticManifest(root);
+    if (declaredManifest && (manifest === undefined || errors.length > 0)) {
+        notes.push(...errors, `suite ${root}: rejected declared manifest`);
+        return undefined;
+    }
     // A declaration-only suite (official CC lsp plugins ship just a README):
     // the marketplace entry's inline lspServers are its manifest.
-    if (manifest === undefined && hint?.lspServers !== undefined) {
+    if (manifest === undefined && hint !== undefined && Object.keys(componentDeclarations(hint)).length > 0) {
         const name = hint.name ?? syntheticManifestName(root);
         manifest = {
-            layout: 'claude-code',
+            layout: hint.layout ?? 'claude-code',
+            components: componentDeclarations(hint),
             path: '',
             id: sanitizeId(name),
             name,
@@ -334,16 +362,32 @@ export async function readSuite(root, sourceId, dimension, hint) {
     }
     if (manifest === undefined)
         return undefined;
-    const declared = await declaredSkillsPath(root);
+    let declared = manifest.components?.skills;
+    if (declared !== undefined && (manifest.layout === 'claude-code' || manifest.layout === 'codex') && (await isDirectory(join(root, 'skills')))) {
+        declared = ['skills', ...(Array.isArray(declared) ? declared : [declared])];
+    }
     const skills = await discoverSkills(root, errors, declared);
-    const mcp = await discoverMcp(root, errors);
-    // Inline LSP declarations: the marketplace entry wins over the manifest
-    // (Claude Code ships lspServers on the entry), and either is optional.
-    const lspRaw = hint?.lspServers ?? (await declaredLspServers(root));
-    const lspServers = parseLspServers(lspRaw, errors);
-    const lsp = Object.keys(lspServers).length > 0 ? { servers: lspServers } : undefined;
+    if (manifest.layout === 'skill-collection' && skills.length === 0) {
+        notes.push(...errors);
+        return undefined;
+    }
+    const mcp = await discoverMcp(root, errors, manifest);
+    // Effective component declarations include marketplace fallbacks and manifest overrides.
+    const lsp = await discoverSuiteLsp(root, manifest, errors);
+    const hooks = await discoverSuiteHooks(root, manifest, errors);
+    const resources = {
+        commands: await discoverMarkdownResources(root, 'commands', manifest.components?.commands, manifest.path, errors, manifest.layout === 'cursor' ? ['.md', '.mdc', '.markdown', '.txt'] : ['.md']),
+        agents: await discoverMarkdownResources(root, 'agents', manifest.components?.agents, manifest.path, errors)
+    };
+    const systemPrompt = await discoverSystemPrompt(root, manifest, errors);
     const surfaces = await countSurfaces(root, skills, mcp, lsp);
+    surfaces.commands = resources.commands.length;
+    surfaces.agents = resources.agents.length;
+    surfaces.hooks = Object.values(hooks?.events ?? {}).reduce((count, groups) => count + groups.reduce((sum, group) => sum + group.hooks.length, 0), 0);
     return {
+        resources,
+        ...(hooks === undefined ? {} : { hooks }),
+        ...(systemPrompt === undefined ? {} : { systemPrompt }),
         sourceId,
         id: manifest.id,
         root,

package/lib/catalog/source-catalog.js

@@ -17,7 +17,7 @@ export async function discoverSourceList(sources, dimension, dimensionRoot) {
     return (await discoverSourceListWithNotes(sources, dimension, dimensionRoot)).suites;
 }
 /** Discover suites plus per-source scan diagnostics for one dimension. */
-export async function discoverSourceListWithNotes(sources, dimension, dimensionRoot) {
+export async function discoverSourceListWithNotes(sources, dimension, dimensionRoot, scanProjectLayouts = true) {
     const checkoutRoot = sourcesDir(dimensionRoot);
     const listed = new Set(sources.map(source => source.id));
     const checkouts = sources.map(source => ({
@@ -52,10 +52,23 @@ export async function discoverSourceListWithNotes(sources, dimension, dimensionR
         if (entry.notes.length > 0)
             scanNotes[entry.sourceId] = entry.notes;
     }
-    if (dimension === 'project') {
+    if (dimension === 'project' && scanProjectLayouts) {
         // Native project directories live two levels above the dimension root
         // (`<projectRoot>/.dsh/agent-plugins`); read them in place.
-        suites.push(...(await discoverNativeProjectSuites(dirname(dirname(dimensionRoot)), dimension)));
+        const native = await discoverNativeProjectSuites(dirname(dirname(dimensionRoot)), dimension);
+        suites.push(...native);
+        const errors = [...new Set(native.flatMap(suite => suite.errors))];
+        if (errors.length > 0)
+            scanNotes.native = errors;
+    }
+    if (dimension === 'project') {
+        for (const suite of suites) {
+            if (suite.lsp === undefined)
+                continue;
+            const note = `suite ${suite.id}: project LSP declarations are not mounted; the host LSP registry does not isolate projects`;
+            suite.errors.push(note);
+            (scanNotes[suite.sourceId] ??= []).push(note);
+        }
     }
     return { suites, scanNotes };
 }

package/lib/catalog/suite-components.js

@@ -0,0 +1,125 @@
+/** Resolve all plugin component declarations into the same normalized resources used by runtime consumers. */
+import { readFile } from 'node:fs/promises';
+import { relative } from 'node:path';
+import { componentDocuments, componentPath, firstComponentFile, isRecord } from './component-files.js';
+import { parseLspServers } from './lsp-spec.js';
+import { normalizeHookDocuments } from './project-hooks.js';
+import { PLUGIN_ROOT_VARIABLES } from '../model/layouts.js';
+export async function discoverSuiteLsp(root, manifest, errors) {
+    const declaration = manifest.components?.lspServers;
+    const fallback = await firstComponentFile(root, manifest.layout === 'github-copilot' || manifest.layout === 'universal' ? ['lsp.json', '.github/lsp.json', 'lsp-config/servers.json', '.lsp.json'] : ['.lsp.json', 'lsp.json']);
+    if (declaration === undefined && fallback === undefined)
+        return undefined;
+    const documents = await componentDocuments(root, declaration ?? fallback, errors);
+    if (documents === undefined)
+        return undefined;
+    const servers = Object.create(null);
+    for (const { value } of documents)
+        Object.assign(servers, parseLspServers(value.lspServers ?? value, errors));
+    return Object.keys(servers).length > 0 ? { servers } : undefined;
+}
+function quote(argument) {
+    return `'${argument.replaceAll("'", "'\\''")}'`;
+}
+function rootVariables(text, root) {
+    return text.replace(/\$\{([A-Z_]+)\}/g, (match, name) => (PLUGIN_ROOT_VARIABLES.has(name) ? root : match));
+}
+const EVENT_ALIASES = {
+    sessionStart: 'SessionStart',
+    userPromptSubmitted: 'UserPromptSubmit',
+    beforeSubmitPrompt: 'UserPromptSubmit',
+    preToolUse: 'PreToolUse',
+    postToolUse: 'PostToolUse',
+    stop: 'Stop',
+    subagentStart: 'SubagentStart',
+    subagentStop: 'SubagentStop'
+};
+/** File configs and Kimi's inline array converge on the established command-hook bridge shape. */
+export async function discoverSuiteHooks(root, manifest, errors) {
+    let declaration = manifest.components?.hooks;
+    if (manifest.layout === 'kimi' && Array.isArray(declaration)) {
+        const events = Object.create(null);
+        for (const hook of declaration) {
+            if (!isRecord(hook) || typeof hook.event !== 'string' || typeof hook.command !== 'string') {
+                errors.push('invalid Kimi inline hook');
+                return undefined;
+            }
+            ;
+            (events[hook.event] ??= []).push({
+                ...(hook.matcher === undefined ? {} : { matcher: hook.matcher }),
+                hooks: [{ type: 'command', command: hook.command, ...(hook.timeout === undefined ? {} : { timeout: hook.timeout }) }]
+            });
+        }
+        declaration = { hooks: events };
+    }
+    const fallback = manifest.layout === 'kimi' ? undefined : await firstComponentFile(root, ['hooks/hooks.json', 'hooks.json']);
+    if (declaration === undefined && fallback === undefined)
+        return undefined;
+    const documents = await componentDocuments(root, declaration ?? fallback, errors, true);
+    if (documents === undefined)
+        return undefined;
+    const normalized = [];
+    for (const { path, value } of documents) {
+        const events = value.hooks ?? value;
+        if (!isRecord(events)) {
+            errors.push('hooks must contain an event table');
+            return undefined;
+        }
+        const output = {};
+        for (const [event, groups] of Object.entries(events)) {
+            const canonicalEvent = EVENT_ALIASES[event] ?? event;
+            if (!Array.isArray(groups)) {
+                output[canonicalEvent] = groups;
+                continue;
+            }
+            output[canonicalEvent] = groups.map(rawGroup => {
+                const group = isRecord(rawGroup) && !Array.isArray(rawGroup.hooks) && (typeof rawGroup.command === 'string' || typeof rawGroup.bash === 'string')
+                    ? {
+                        matcher: rawGroup.matcher,
+                        hooks: [{ ...rawGroup, type: rawGroup.type ?? 'command', command: rawGroup.command ?? rawGroup.bash, timeout: rawGroup.timeout ?? rawGroup.timeoutSec }]
+                    }
+                    : rawGroup;
+                if (!isRecord(group) || !Array.isArray(group.hooks))
+                    return group;
+                return {
+                    ...group,
+                    hooks: group.hooks.map(hook => {
+                        if (!isRecord(hook))
+                            return hook;
+                        if (hook.type !== 'process')
+                            return typeof hook.command === 'string' ? { ...hook, command: rootVariables(hook.command, root) } : hook;
+                        if (typeof hook.command !== 'string' || (hook.args !== undefined && (!Array.isArray(hook.args) || !hook.args.every(arg => typeof arg === 'string'))))
+                            return { ...hook, type: 'command', command: undefined };
+                        const argv = [hook.command, ...(hook.args ?? [])].map(arg => quote(rootVariables(arg, root)));
+                        return { ...hook, type: 'command', command: argv.join(' '), ...(typeof hook.timeoutMs === 'number' ? { timeout: hook.timeoutMs / 1000 } : {}) };
+                    })
+                };
+            });
+        }
+        normalized.push({ file: path === undefined ? manifest.path : relative(root, path), settings: { hooks: output } });
+    }
+    return normalizeHookDocuments(root, normalized, errors);
+}
+export async function discoverSystemPrompt(root, manifest, errors) {
+    const parts = [];
+    if (manifest.systemPrompt !== undefined)
+        parts.push(manifest.systemPrompt);
+    if (manifest.systemPromptPath !== undefined) {
+        const path = await componentPath(root, manifest.systemPromptPath, errors);
+        if (path === undefined)
+            return undefined;
+        try {
+            parts.push(await readFile(path, 'utf8'));
+        }
+        catch {
+            errors.push('systemPromptPath is unreadable');
+            return undefined;
+        }
+    }
+    const content = parts.join('\n\n');
+    if (Buffer.byteLength(content) > 32768) {
+        errors.push('system prompt exceeds 32 KiB');
+        return undefined;
+    }
+    return content === '' ? undefined : content;
+}