dsh-agent-plugins-market 0.5.2 → 0.6.0

package/lib/catalog/lsp-spec.js

@@ -0,0 +1,87 @@
+/** Claude Code-specific keys this integration intentionally ignores. */
+const CC_ONLY_KEYS = new Set(['startupTimeout']);
+/** Keys accepted by the normalized spec; anything else is reported as ignored. */
+const KNOWN_KEYS = new Set(['command', 'args', 'extensionToLanguage', 'env', 'initializationOptions', 'configuration', ...CC_ONLY_KEYS]);
+/** Parse one inline `lspServers` table into normalized specs plus diagnostics. */
+export function parseLspServers(raw, errors) {
+    if (typeof raw !== 'object' || raw === null) {
+        if (raw !== undefined)
+            errors.push('lspServers: not an object');
+        return {};
+    }
+    const specs = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const spec = parseOneServer(key, value, errors);
+        if (spec !== undefined)
+            specs[key] = spec;
+    }
+    return specs;
+}
+function parseOneServer(key, raw, errors) {
+    if (typeof raw !== 'object' || raw === null) {
+        errors.push(`lspServers.${key}: server entry is not an object`);
+        return undefined;
+    }
+    const record = raw;
+    for (const field of Object.keys(record)) {
+        if (!KNOWN_KEYS.has(field))
+            errors.push(`lspServers.${key}: ignoring unknown field "${field}"`);
+    }
+    const command = record['command'];
+    if (typeof command !== 'string' || command.trim() === '') {
+        errors.push(`lspServers.${key}: "command" must be a non-empty string`);
+        return undefined;
+    }
+    const args = record['args'];
+    if (args !== undefined && (!Array.isArray(args) || args.some(entry => typeof entry !== 'string'))) {
+        errors.push(`lspServers.${key}: "args" must be an array of strings`);
+        return undefined;
+    }
+    const mapping = parseExtensionToLanguage(key, record['extensionToLanguage'], errors);
+    if (mapping === undefined)
+        return undefined;
+    const env = record['env'];
+    if (env !== undefined && (typeof env !== 'object' || env === null || Array.isArray(env) || Object.values(env).some(value => typeof value !== 'string'))) {
+        errors.push(`lspServers.${key}: "env" must be an object of strings`);
+        return undefined;
+    }
+    return {
+        key,
+        command,
+        args: Array.isArray(args) ? args : [],
+        extensionToLanguage: mapping,
+        ...(typeof env === 'object' && env !== null && !Array.isArray(env) ? { env: env } : {}),
+        ...(record['initializationOptions'] !== undefined ? { initializationOptions: record['initializationOptions'] } : {}),
+        ...(record['configuration'] !== undefined ? { configuration: record['configuration'] } : {})
+    };
+}
+/** Normalize and validate `extensionToLanguage`: lowercase leading-dot keys, non-empty ids. */
+function parseExtensionToLanguage(key, raw, errors) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        errors.push(`lspServers.${key}: "extensionToLanguage" must be a non-empty object`);
+        return undefined;
+    }
+    const mapping = {};
+    for (const [rawExt, languageId] of Object.entries(raw)) {
+        const ext = rawExt.toLowerCase();
+        const normalized = ext.startsWith('.') ? ext : `.${ext}`;
+        if (!/^\.[^.\\/]+$/.test(normalized)) {
+            errors.push(`lspServers.${key}: invalid extension "${rawExt}"`);
+            return undefined;
+        }
+        if (typeof languageId !== 'string' || languageId.trim() === '') {
+            errors.push(`lspServers.${key}: extension "${normalized}" maps to an empty language id`);
+            return undefined;
+        }
+        // Case-variant spellings of one extension (clangd's `.c`/`.C`) collapse
+        // silently: normalization makes them the same key, and the first id wins.
+        if (mapping[normalized] !== undefined)
+            continue;
+        mapping[normalized] = languageId;
+    }
+    if (Object.keys(mapping).length === 0) {
+        errors.push(`lspServers.${key}: "extensionToLanguage" must not be empty`);
+        return undefined;
+    }
+    return mapping;
+}

package/lib/catalog/manifests.js

@@ -73,22 +73,31 @@ export async function readManifest(root, errors, hint) {
         return undefined;
     }
     const record = raw;
-    const problems = candidate.kind === 'agent-plugin-v1' ? await validatePluginManifest(raw) : [];
+    // The v1 dialect is identified by position AND declaration: the spec's
+    // schema requires `$schema`, so a root `plugin.json` without it is not a
+    // v1 manifest. Real-world single-repo marketplaces (agent-skills) ship a
+    // plain metadata object at the root alongside their Claude dialect
+    // manifests; reading that as strict v1 would fail-closed on a repo that
+    // is perfectly usable. Such a file is read leniently as the Claude
+    // layout instead — strict validation only ever applies to manifests
+    // that actually declare the v1 schema.
+    const kind = candidate.kind === 'agent-plugin-v1' && !isRecognizedSchema(record.$schema) ? 'claude-code' : candidate.kind;
+    const problems = kind === 'agent-plugin-v1' ? await validatePluginManifest(raw) : [];
     errors.push(...problems.map(problem => `${candidate.path}: ${problem}`));
     const name = pickString(record.name) ?? hint?.name ?? syntheticManifestName(root);
     const version = pickString(record.version) ?? hint?.version;
     const description = pickString(record.description) ?? hint?.description;
     const author = record.author;
     return {
-        layout: candidate.kind === 'agent-plugin-v1'
+        layout: kind === 'agent-plugin-v1'
             ? 'agent-plugin-v1'
-            : candidate.kind === 'universal'
+            : kind === 'universal'
                 ? 'universal'
-                : candidate.kind === 'claude-code'
+                : kind === 'claude-code'
                     ? 'claude-code'
-                    : candidate.kind === 'cursor'
+                    : kind === 'cursor'
                         ? 'cursor'
-                        : candidate.kind === 'kimi'
+                        : kind === 'kimi'
                             ? 'kimi'
                             : 'codex',
         path: candidate.path,
@@ -106,34 +115,59 @@ function pickString(value) {
 }
 /** Marketplace manifest locations per dialect (Claude Code, Codex). */
 const MARKETPLACE_PATHS = ['.claude-plugin/marketplace.json', '.agents/plugins/marketplace.json'];
-/** Read a marketplace manifest from a checkout root, or undefined when absent. */
-export async function readMarketplace(checkoutDir) {
+/** Read one marketplace manifest file; malformed documents are diagnosed, not thrown. */
+async function readOneMarketplace(path, errors) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        errors.push(`marketplace ${path} unparsable: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        errors.push(`marketplace ${path}: manifest is not a JSON object`);
+        return undefined;
+    }
+    const record = parsed;
+    const plugins = record['plugins'];
+    if (!Array.isArray(plugins)) {
+        errors.push(`marketplace ${path}: "plugins" is not an array`);
+        return undefined;
+    }
+    return {
+        ...(typeof record['name'] === 'string' ? { name: record['name'] } : {}),
+        entries: plugins,
+        path
+    };
+}
+/**
+ * Read every marketplace manifest the checkout carries, in dialect
+ * precedence order (Claude Code before Codex). Both dialects can coexist
+ * (e.g. a repo shipping one marketplace per agent); callers decide which
+ * dialect's entries win, so no dialect is silently shadowed.
+ */
+export async function readMarketplaces(checkoutDir) {
+    const results = [];
+    const errors = [];
     for (const relative of MARKETPLACE_PATHS) {
-        let text;
-        try {
-            text = await readFile(join(checkoutDir, relative), 'utf8');
-        }
-        catch {
-            continue;
-        }
-        try {
-            const parsed = JSON.parse(text);
-            if (typeof parsed !== 'object' || parsed === null)
-                continue;
-            const record = parsed;
-            const plugins = record['plugins'];
-            if (!Array.isArray(plugins))
-                continue;
-            return {
-                ...(typeof record['name'] === 'string' ? { name: record['name'] } : {}),
-                entries: plugins
-            };
-        }
-        catch {
-            continue;
-        }
+        const result = await readOneMarketplace(join(checkoutDir, relative), errors);
+        if (result !== undefined)
+            results.push(result);
     }
-    return undefined;
+    return results;
+}
+/** Read the highest-precedence marketplace manifest, or undefined when absent. */
+export 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. */
@@ -220,3 +254,21 @@ export async function declaredMcpServers(root) {
     }
     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/paths.js

@@ -4,6 +4,11 @@
  * User dimension: `~/.dsh/agent-plugins/` (or `$DSH_HOME/agent-plugins`).
  * 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.
  */
 import { existsSync } from 'node:fs';
 import { stat } from 'node:fs/promises';
@@ -28,9 +33,13 @@ export function resolveDshHome() {
 export function resolveUserRoot(configUserRoot) {
     return resolve(expandHome(configUserRoot ?? join(resolveDshHome(), 'agent-plugins')));
 }
-/** Resolve the suite data root hosting `${PLUGIN_DATA}` directories. */
-export function resolveDataRoot(configDataRoot) {
-    return resolve(expandHome(configDataRoot ?? join(resolveDshHome(), 'agent-plugins-data')));
+/**
+ * Resolve the suite data root hosting `${PLUGIN_DATA}` directories and the
+ * MCP overrides. Defaults under the user root so the whole plugin persists
+ * into one directory; an explicit `dataRoot` config still wins.
+ */
+export function resolveDataRoot(configDataRoot, configUserRoot) {
+    return resolve(expandHome(configDataRoot ?? join(configUserRoot ?? resolveUserRoot(), 'data')));
 }
 /** Resolve a project root from a workspace cwd: nearest ancestor with `.git`. */
 export async function findProjectRoot(cwd) {
@@ -60,6 +69,15 @@ export function sourceCheckoutDir(dimensionRoot, sourceId) {
 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
+ * state, override, data-directory, and mount key must be source-scoped — a
+ * bare suite id silently collides across sources.
+ */
+export function qualifiedSuiteId(sourceId, suiteId) {
+    return `${sourceId}/${suiteId}`;
+}
 /** Async existence probe that follows symlinks for a final component. */
 export async function isDirectory(path) {
     try {
@@ -70,6 +88,16 @@ export async function isDirectory(path) {
         return false;
     }
 }
+/** Async existence probe for any entry (file, directory, symlink). */
+export async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Sanitize a plugin or server id into `[a-z0-9-]` (lowercased). */
 export function sanitizeId(raw) {
     const cleaned = raw
@@ -79,11 +107,41 @@ 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(/\/+$/, '');
-    let base = trimmed.split(/[/\\]/).at(-1) ?? '';
-    if (base.endsWith('.git'))
-        base = base.slice(0, -4);
-    return sanitizeId(base);
+    const base = trimmed.split(/[/\\]/).at(-1) ?? '';
+    return sanitizeId(stripSourceSuffix(base));
+}
+/**
+ * Derive candidate source ids from a git URL or local path, most preferred
+ * first: the sanitized basename, then an owner-prefixed variant (`owner-repo`)
+ * for remote URLs so same-named repositories from different owners
+ * (`cloudflare/skills`, `mattpocock/skills`) degrade to readable ids instead
+ * of numeric suffixes. Local paths yield the basename only.
+ */
+export function deriveSourceIdCandidates(url) {
+    const trimmed = url.trim().replace(/\/+$/, '');
+    const base = stripSourceSuffix(trimmed.split(/[/\\]/).at(-1) ?? '');
+    const primary = sanitizeId(base);
+    const isRemote = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) || /^[\w.-]+@[\w.-]+:/.test(trimmed);
+    const candidates = [primary];
+    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]);
+            if (owner !== '' && owner !== primary)
+                candidates.push(`${owner}-${primary}`);
+        }
+    }
+    return [...new Set(candidates)];
 }

package/lib/catalog/scan-pipeline.js

@@ -0,0 +1,50 @@
+/** Drive one checkout through the filter chain, recording every attempt. */
+export async function runScanChain(filters, context) {
+    const attempts = [];
+    const notes = context.notes;
+    const run = async (index) => {
+        const filter = filters[index];
+        if (filter === undefined) {
+            // Terminal: the chain must always answer. A checkout that reaches the
+            // end declares nothing this manager understands.
+            return { kind: 'resolved', suites: [] };
+        }
+        const productive = (resolution) => resolution.kind === 'resolved' && resolution.suites.length > 0;
+        // A filter that delegates has no answer of its own: recording its
+        // delegation as an abstention keeps the attempt trace complete.
+        let delegated = false;
+        const remaining = {
+            next: _ctx => {
+                delegated = true;
+                return run(index + 1);
+            }
+        };
+        const resolution = await filter.doScan(context, remaining);
+        // A delegated resolution was already recorded by the inner filter that
+        // produced it: mark this filter's delegation and pass the answer through.
+        if (delegated) {
+            attempts.push({ filter: filter.name, outcome: 'abstain', detail: 'delegated', suiteIds: [] });
+            return resolution;
+        }
+        const hit = productive(resolution);
+        attempts.push({
+            filter: filter.name,
+            outcome: hit ? 'resolved' : 'abstain',
+            detail: hit ? `${resolution.suites.length} suite(s)` : resolution.kind === 'abstain' ? resolution.reason : '0 suite(s)',
+            suiteIds: hit ? resolution.suites.map(suite => suite.id) : []
+        });
+        if (!hit) {
+            if (resolution.kind === 'abstain') {
+                notes.push(`filter "${filter.name}" abstained: ${resolution.reason}`);
+            }
+            else {
+                notes.push(`filter "${filter.name}" recognized the checkout but produced no suites; falling through`);
+            }
+            // Recognized but unproductive: later strategies still get their chance.
+            return run(index + 1);
+        }
+        return resolution;
+    };
+    const resolution = await run(0);
+    return { suites: resolution.kind === 'resolved' ? resolution.suites : [], attempts, notes };
+}