dsh-agent-plugins-market 0.7.1 → 0.7.2

package/lib/catalog/scan-resolvers.js

@@ -18,14 +18,17 @@
  * 3. `FlatCollectionsStrategy` — the terminal fallback: manifest-less
  *    `<root>/<name>/SKILL.md` collections.
  */
-import { realpath } from 'node:fs/promises';
+import { realpath, readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { isWithin, sanitizeId } from './paths.js';
 import { isDirectory, isFile, listChildDirs } from './fs-probes.js';
+import { EXTENSION_NAMESPACE, NAMESPACE_DIR, NAMESPACE_HOOKS_FILE, NAMESPACE_LSP_FILE } from '../model/layouts.js';
 import { componentDeclarations, hasSuiteManifest, readManifest, readMarketplaces, syntheticManifestName } from './manifests.js';
 import { countSurfaces, discoverMcp, discoverSkills, listMdFiles } from './surfaces.js';
 import { discoverMarkdownResources, isUnknownArray } from './component-files.js';
 import { discoverSuiteHooks, discoverSuiteLsp, discoverSystemPrompt } from './suite-components.js';
+import { parseLspServers } from './lsp-spec.js';
+import { normalizeHookDocuments } from './project-hooks.js';
 import { runScanChain } from './scan-pipeline.js';
 const CONTAINER_DIRS = ['plugins', 'external_plugins', 'skills'];
 /**
@@ -327,10 +330,11 @@ export async function hasSkillFiles(dir) {
 /** Read one suite root into the normalized shape, or undefined when no manifest parses. */
 export async function readSuite(root, sourceId, dimension, hint, notes = []) {
     const errors = [];
+    const manifestNotes = [];
     const fallbacks = [];
     const declaredManifest = await hasSuiteManifest(root);
-    let manifest = declaredManifest ? await readManifest(root, errors, hint, fallbacks) : await syntheticManifest(root);
-    if (declaredManifest && (manifest === undefined || errors.length > 0)) {
+    let manifest = declaredManifest ? await readManifest(root, errors, hint, fallbacks, manifestNotes) : await syntheticManifest(root);
+    if (declaredManifest && manifest === undefined) {
         notes.push(...errors, ...fallbacks, `suite ${root}: rejected declared manifest`);
         return undefined;
     }
@@ -338,6 +342,7 @@ export async function readSuite(root, sourceId, dimension, hint, notes = []) {
     // higher-priority declaration was skipped visible without failing the suite.
     if (fallbacks.length > 0)
         notes.push(`suite ${root}: a higher-priority manifest was rejected`, ...fallbacks);
+    notes.push(...manifestNotes);
     // 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 !== undefined && Object.keys(componentDeclarations(hint)).length > 0) {
@@ -354,24 +359,41 @@ export async function readSuite(root, sourceId, dimension, hint, notes = []) {
     }
     if (manifest === undefined)
         return undefined;
+    // The portable v1 dialect reads only the spec's fixed locations plus this
+    // client's extension namespace (§6.1, §8.2): skills and MCP from their
+    // fixed locations, extension surfaces from `com.deepseek.harness/`.
+    // Marketplace-entry and hint declarations carry no inline components for
+    // this dialect, so `components` stays empty and every discovery call below
+    // takes its namespace path.
+    const portable = manifest.layout === 'agent-plugin-v1';
+    // The namespace seats (manifest data and directory) open only when the
+    // suite declares our namespace with a supported contract version; an
+    // unsupported or missing declaration reads the portable core alone.
+    const namespaceOpen = portable && (manifest.harness !== undefined || manifest.schemaVersion !== undefined) && namespaceReadable(manifest);
     let declared = manifest.components?.skills;
     if (declared !== undefined && (manifest.layout === 'claude-code' || manifest.layout === 'codex') && (await isDirectory(join(root, 'skills')))) {
         declared = ['skills', ...(isUnknownArray(declared) ? declared : [declared])];
     }
-    const skills = await discoverSkills(root, errors, declared);
+    if (portable)
+        await noteUnreadRootComponents(root, notes);
+    const skills = await discoverSkills(root, errors, declared, portable);
     if (manifest.layout === 'skill-collection' && skills.length === 0) {
         notes.push(...errors);
         return undefined;
     }
-    const mcp = await discoverMcp(root, errors, manifest);
+    const mcp = await discoverMcp(root, errors, manifest, portable);
     // 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 lsp = namespaceOpen ? await discoverNamespaceLsp(root, manifest, errors, notes) : await discoverSuiteLsp(root, manifest, errors);
+    const hooks = namespaceOpen ? await discoverNamespaceHooks(root, manifest, errors, notes) : await discoverSuiteHooks(root, manifest, errors);
+    const resources = namespaceOpen
+        ? await discoverNamespaceMarkdown(root, notes)
+        : portable
+            ? { commands: [], agents: [] }
+            : {
+                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 = portable ? undefined : await discoverSystemPrompt(root, manifest, errors);
     const surfaces = await countSurfaces(root, skills, mcp, lsp);
     surfaces.commands = resources.commands.length;
     surfaces.agents = resources.agents.length;
@@ -428,3 +450,86 @@ async function syntheticManifest(root) {
         name
     };
 }
+// ---------------------------------------------------------------------------
+// Extension namespace surfaces (Agent Plugins §8.2)
+//
+// A portable v1 suite carries this client's extension surfaces in the
+// top-level directory named after the namespace. Contents outside it — the
+// dialect root directories other layouts read — are package files this
+// manager does not mount for the portable dialect, and their presence is
+// reported through scan notes rather than read silently.
+// ---------------------------------------------------------------------------
+/** Root component locations other dialects read; under v1 their presence is reported, never read. */
+const ROOT_COMPONENT_DIRS = ['commands', 'agents', 'hooks'];
+/** `.mcp.json` is an alternative MCP path the portable format forbids; `mcp.json` itself is the fixed location. */
+const ROOT_COMPONENT_FILES = ['hooks.json', 'lsp.json', '.lsp.json', '.mcp.json'];
+/**
+ * Whether the namespace contract allows reading the extension seats: the
+ * manifest must carry our namespace with a supported `schemaVersion`. A
+ * directory without manifest data stays closed until the suite declares the
+ * contract, so a name collision on the filesystem cannot silently activate
+ * extension reading.
+ */
+function namespaceReadable(manifest) {
+    return manifest.harness !== undefined;
+}
+/** Report portable-suite content this manager does not mount, so nothing fails silently. */
+async function noteUnreadRootComponents(root, notes) {
+    for (const dir of ROOT_COMPONENT_DIRS) {
+        if (await isDirectory(join(root, dir)))
+            notes.push(`suite ${root}: "${dir}/" is outside the portable layout and the ${EXTENSION_NAMESPACE} namespace; not read for this dialect`);
+    }
+    for (const file of ROOT_COMPONENT_FILES) {
+        if (await isFile(join(root, file)))
+            notes.push(`suite ${root}: "${file}" is outside the portable layout; not read for this dialect`);
+    }
+}
+/** Commands and agents from `<namespace>/commands/` and `<namespace>/agents/`. */
+async function discoverNamespaceMarkdown(root, notes) {
+    const namespaceRoot = join(root, NAMESPACE_DIR);
+    if (!(await isDirectory(namespaceRoot)))
+        return { commands: [], agents: [] };
+    const errors = [];
+    const commands = await discoverMarkdownResources(namespaceRoot, 'commands', undefined, join(namespaceRoot, 'plugin.json'), errors);
+    const agents = await discoverMarkdownResources(namespaceRoot, 'agents', undefined, join(namespaceRoot, 'plugin.json'), errors);
+    notes.push(...errors.map(error => `${EXTENSION_NAMESPACE}: ${error}`));
+    return { commands, agents };
+}
+/** Hooks from `<namespace>/hooks/hooks.json`, normalized through the command-hook bridge. */
+async function discoverNamespaceHooks(root, manifest, errors, notes) {
+    const file = join(root, NAMESPACE_HOOKS_FILE);
+    if (!(await isFile(file)))
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        notes.push(`${NAMESPACE_HOOKS_FILE}: unparsable (${error instanceof Error ? error.message : String(error)})`);
+        return undefined;
+    }
+    const events = value?.hooks ?? value;
+    if (typeof events !== 'object' || events === null) {
+        notes.push(`${NAMESPACE_HOOKS_FILE}: must contain an event table`);
+        return undefined;
+    }
+    return normalizeHookDocuments(root, [{ file: NAMESPACE_HOOKS_FILE, settings: { hooks: events } }], errors);
+}
+/** LSP servers from `<namespace>/lsp.json`. */
+async function discoverNamespaceLsp(root, manifest, errors, notes) {
+    const file = join(root, NAMESPACE_LSP_FILE);
+    if (!(await isFile(file)))
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        notes.push(`${NAMESPACE_LSP_FILE}: unparsable (${error instanceof Error ? error.message : String(error)})`);
+        return undefined;
+    }
+    const servers = Object.create(null);
+    const document = value.lspServers ?? value;
+    Object.assign(servers, parseLspServers(document, notes));
+    return Object.keys(servers).length > 0 ? { servers } : undefined;
+}

package/lib/catalog/surfaces.js

@@ -10,10 +10,10 @@
  * thrown discovery.
  */
 import { readFile, readdir, stat } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 import { parseSkillFrontmatter } from './skills-parse.js';
 import { isDirectory, isFile, listChildDirs } from './fs-probes.js';
-import { validateMcpJson } from './validate.js';
+import { validateMcpJson, pathContainmentError, recognizedSpecVersion } from './validate.js';
 import { readManifest } from './manifests.js';
 import { componentDocuments, componentPath, firstComponentFile, isUnknownArray } from './component-files.js';
 /**
@@ -38,16 +38,29 @@ async function declaredSkillDirs(root, declared, errors) {
     }
     return dirs;
 }
-/** Discover SKILL.md files under the suite's skills directory, up to 3 levels deep. */
-export async function discoverSkills(root, errors, declared) {
+/**
+ * Discover SKILL.md files under the suite's skills directory, up to 3 levels
+ * deep. Portable v1 suites (§7.1) instead discover exactly one level of
+ * `skills/` subdirectories each carrying a `SKILL.md` — the spec forbids
+ * recursive deeper search and root-level or flat skill files are outside the
+ * portable discovery shape.
+ */
+export async function discoverSkills(root, errors, declared, portable = false) {
     const skills = [];
-    const rootSkill = join(root, 'SKILL.md');
-    const rootName = root.split(/[\\/]/).at(-1) ?? 'plugin';
-    const rootParsed = await parseOneSkill(rootSkill, root, rootName, errors);
-    if (rootParsed !== undefined)
-        skills.push(rootParsed);
     const skillsDirs = await declaredSkillDirs(root, declared, errors);
-    if (declared === undefined) {
+    if (!portable) {
+        const rootSkill = join(root, 'SKILL.md');
+        const rootName = root.split(/[\\/]/).at(-1) ?? 'plugin';
+        const rootParsed = await parseOneSkill(rootSkill, root, rootName, errors);
+        if (rootParsed !== undefined)
+            skills.push(rootParsed);
+        if (declared === undefined) {
+            const fallback = join(root, 'skills');
+            if (await isDirectory(fallback))
+                skillsDirs.push(fallback);
+        }
+    }
+    else if (declared === undefined) {
         const fallback = join(root, 'skills');
         if (await isDirectory(fallback))
             skillsDirs.push(fallback);
@@ -60,6 +73,25 @@ export async function discoverSkills(root, errors, declared) {
         skills.push(skill);
     };
     for (const skillsDir of skillsDirs) {
+        if (portable) {
+            // §7.1: each immediate child directory containing `SKILL.md` is one
+            // skill; no deeper descendants are searched and flat files are not
+            // skills. Each candidate also passes a realpath containment check so a
+            // symlink pointing outside the plugin root is skipped (§4.1 boundary 3).
+            for (const child of await listChildDirs(skillsDir)) {
+                const skillFile = join(child, 'SKILL.md');
+                if (!(await isFile(skillFile)))
+                    continue;
+                const reason = await pathContainmentError(root, `./${relative(root, skillFile).replace(/\\/g, '/')}`);
+                if (reason !== undefined) {
+                    errors.push(`skill "${child.split(/[\\/]/).at(-1) ?? ''}": ${reason}`);
+                    continue;
+                }
+                const name = child.split(/[\\/]/).at(-1) ?? '';
+                pushUnique(await parseOneSkill(skillFile, child, name, errors));
+            }
+            continue;
+        }
         if (await isFile(skillsDir)) {
             pushUnique(await parseOneSkill(skillsDir, dirname(skillsDir), '', errors));
             continue;
@@ -145,23 +177,34 @@ async function parseOneSkill(file, directory, fallbackName, errors) {
     }
     return { ...verdict, directory };
 }
-/** Read the suite's MCP config: `mcp.json` or `.mcp.json`, else the winning manifest's inline `mcpServers`. */
-export async function discoverMcp(root, errors, manifest) {
+/**
+ * Read the suite's MCP config: `mcp.json` or `.mcp.json`, else the winning
+ * manifest's inline `mcpServers`. Portable v1 suites read only `mcp.json` at
+ * the plugin root (§7.2.1: no alternative core path, no inline declarations).
+ */
+export async function discoverMcp(root, errors, manifest, portable = false) {
     const resolved = manifest ?? (await readManifest(root, errors, undefined));
     const layout = resolved?.layout;
-    const names = layout === 'zcode'
-        ? ['.mcp.json']
-        : layout === 'qoder'
-            ? ['.mcp.json', 'mcp.json']
-            : layout === 'github-copilot' || layout === 'universal'
-                ? ['.mcp.json', '.github/mcp.json', 'mcp.json']
-                : layout === 'codex' || layout === 'claude-code'
-                    ? ['.mcp.json', 'mcp.json']
-                    : layout === 'cursor'
-                        ? ['mcp.json']
-                        : ['mcp.json', '.mcp.json'];
-    const declared = resolved?.components?.mcpServers;
-    const fallback = layout === 'kimi' ? undefined : await firstComponentFile(root, names);
+    const names = portable
+        ? ['mcp.json']
+        : layout === 'zcode'
+            ? ['.mcp.json']
+            : layout === 'qoder'
+                ? ['.mcp.json', 'mcp.json']
+                : layout === 'github-copilot' || layout === 'universal'
+                    ? ['.mcp.json', '.github/mcp.json', 'mcp.json']
+                    : layout === 'codex' || layout === 'claude-code'
+                        ? ['.mcp.json', 'mcp.json']
+                        : layout === 'cursor'
+                            ? ['mcp.json']
+                            : ['mcp.json', '.mcp.json'];
+    const declared = portable ? undefined : resolved?.components?.mcpServers;
+    // Portable mode reads exactly the fixed location `mcp.json` (§7.2.1), so
+    // the candidate list is the location itself rather than a fallback probe.
+    // The file is optional for portable suites too — §7.2 fixes its location,
+    // not its presence — so an absent file resolves to zero servers without a
+    // diagnostic; an existing but unreadable path still fails loudly below.
+    const fallback = portable ? ((await isFile(join(root, 'mcp.json'))) ? 'mcp.json' : undefined) : layout === 'kimi' ? undefined : await firstComponentFile(root, names);
     const additive = layout === 'zcode' || layout === 'claude-code';
     const values = declared === undefined
         ? fallback === undefined
@@ -177,8 +220,11 @@ export async function discoverMcp(root, errors, manifest) {
     let schema = '';
     for (const document of documents) {
         const isBareFile = document.path === join(root, 'mcp.json');
-        const strict = isBareFile && (layout === 'agent-plugin-v1' || (declared === undefined && layout !== 'cursor' && layout !== 'qoder'));
-        const result = await validateMcpJson(root, document.value, { strict });
+        const strict = portable || (isBareFile && (layout === 'agent-plugin-v1' || (declared === undefined && layout !== 'cursor' && layout !== 'qoder')));
+        const result = await validateMcpJson(root, document.value, {
+            strict,
+            ...(portable && resolved?.schemaVersion !== undefined ? { manifestVersion: recognizedSpecVersion(resolved.schemaVersion)?.version } : {})
+        });
         errors.push(...result.errors);
         if (result.config === undefined)
             return undefined;