dsh-agent-plugins-market 0.4.3

package/lib/validate.js

@@ -0,0 +1,199 @@
+/**
+ * agent-plugins.org v1.0.0 validation: vendored JSON Schemas plus the
+ * specification's semantic filesystem rules.
+ *
+ * The schemas live under `schemas/1.0.0/` and are bundled into the package —
+ * the spec forbids retrieving a schema while loading a plugin. Schema
+ * validation is one failure boundary (per server / per manifest); the
+ * semantic pass then enforces §4 path containment, `$schema` recognition, and
+ * the `${PLUGIN_ROOT}` / `${PLUGIN_DATA}` expansion the spec makes mandatory.
+ */
+import { readFile, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// The 2020-12 dist build's d.ts resolves to a CJS namespace under NodeNext;
+// the runtime default export is the class itself (module.exports = Ajv2020).
+import Ajv2020Default from 'ajv/dist/2020.js';
+const SCHEMAS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'schemas', '1.0.0');
+const Ajv2020Class = Ajv2020Default;
+export const PLUGIN_SCHEMA_ID = 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json';
+export const MCP_SCHEMA_ID = 'https://agent-plugins.org/schemas/1.0.0/mcp.schema.json';
+let ajvPromise;
+/** Lazily build one Ajv instance holding the two vendored schemas. */
+async function ajv() {
+    ajvPromise ??= (async () => {
+        const instance = new Ajv2020Class({ strict: false });
+        for (const name of ['plugin.schema.json', 'mcp.schema.json']) {
+            const schemaText = await readFile(join(SCHEMAS_DIR, name), 'utf8');
+            instance.addSchema(JSON.parse(schemaText));
+        }
+        return instance;
+    })();
+    return ajvPromise;
+}
+/** Validate one JSON document against a vendored schema; errors joined for surfacing. */
+export async function validateAgainstSchema(schemaId, document) {
+    const instance = await ajv();
+    const validate = instance.getSchema(schemaId);
+    if (validate === undefined)
+        return [`no bundled validator for ${schemaId}`];
+    validate(document);
+    return (validate.errors ?? []).map((error) => `${error.instancePath === '' ? 'root' : error.instancePath} ${error.message ?? 'invalid'}`);
+}
+/** Whether a `$schema` value selects the local v1.0.0 ruleset. */
+export function isRecognizedSchema(value) {
+    return value === PLUGIN_SCHEMA_ID || value === MCP_SCHEMA_ID;
+}
+/**
+ * Spec §4 containment: a plugin-relative path must begin with `./` and, after
+ * resolution against the plugin root, stay inside the filesystem-resolved
+ * plugin root. Symlinks resolving outside the root are rejected.
+ * @returns `undefined` when contained, or the rejection reason.
+ */
+export async function pathContainmentError(pluginRoot, value) {
+    const raw = value.replace(/^\$\{PLUGIN_ROOT\}(\/|$)/, './');
+    if (!raw.startsWith('./'))
+        return `path "${value}" must begin with "./" (or ${'${PLUGIN_ROOT}'})`;
+    const candidate = resolve(pluginRoot, raw.slice(2));
+    let rootResolved;
+    try {
+        rootResolved = await realpath(pluginRoot);
+    }
+    catch {
+        rootResolved = resolve(pluginRoot);
+    }
+    const rootPrefix = rootResolved.endsWith(sep) ? rootResolved : `${rootResolved}${sep}`;
+    let candidateResolved;
+    try {
+        candidateResolved = await realpath(candidate);
+    }
+    catch {
+        candidateResolved = candidate;
+    }
+    if (candidateResolved !== rootResolved && !candidateResolved.startsWith(rootPrefix)) {
+        return `path "${value}" resolves outside the plugin root`;
+    }
+    return undefined;
+}
+/** Validate a plugin manifest per the vendored schema plus `$schema` recognition. */
+export async function validatePluginManifest(raw) {
+    const errors = [];
+    if (typeof raw !== 'object' || raw === null)
+        return ['manifest is not a JSON object'];
+    const record = raw;
+    if (!isRecognizedSchema(record['$schema'])) {
+        errors.push(`unrecognized $schema ${JSON.stringify(record['$schema'])}; this manager supports agent-plugins 1.0.0 only`);
+    }
+    errors.push(...await validateAgainstSchema(PLUGIN_SCHEMA_ID, raw));
+    return errors;
+}
+/**
+ * Parse and validate an `mcp.json` document: schema first, then §4 path
+ * containment for `command` and `cwd` of every stdio server.
+ * @returns the validated config plus per-problem strings; a failed `$schema`
+ *   or schema body drops the whole file, while per-server path problems
+ *   invalidate only their server.
+ */
+const KNOWN_MCP_TRANSPORTS = new Set(['stdio', 'streamable-http', 'sse']);
+export async function validateMcpJson(pluginRoot, raw, options) {
+    if (typeof raw !== 'object' || raw === null)
+        return { errors: ['mcp.json is not a JSON object'] };
+    const record = raw;
+    const errors = [];
+    const strict = options?.strict !== false;
+    if (strict) {
+        if (!isRecognizedSchema(record['$schema'])) {
+            return { errors: [`unrecognized mcp.json $schema ${JSON.stringify(record['$schema'])}; this manager supports agent-plugins 1.0.0 only`] };
+        }
+        const schemaErrors = await validateAgainstSchema(MCP_SCHEMA_ID, raw);
+        if (schemaErrors.length > 0)
+            return { errors: schemaErrors };
+    }
+    // Lenient native-client files may omit the `mcpServers` wrapper and put the
+    // server map at the top level (Claude Code `.mcp.json` shorthand).
+    let servers = record['mcpServers'];
+    if (typeof servers !== 'object' || servers === null) {
+        if (strict || record['$schema'] !== undefined || !Object.values(record).every(value => typeof value === 'object' && value !== null)) {
+            return { errors: ['mcp.json is missing mcpServers'] };
+        }
+        servers = record;
+    }
+    const valid = {};
+    for (const [name, value] of Object.entries(servers)) {
+        if (typeof value !== 'object' || value === null) {
+            errors.push(`server "${name}": not an object`);
+            continue;
+        }
+        const server = value;
+        // Claude Code dialects: `http`/`streamable-http` are the same remote
+        // transport, and `local` or a missing `type` (with `command`) mean stdio.
+        let type = typeof server.type === 'string' ? server.type : server.command !== undefined ? 'stdio' : undefined;
+        if (type === 'local')
+            type = 'stdio';
+        if (type === 'http')
+            type = 'streamable-http';
+        if (type === undefined || !KNOWN_MCP_TRANSPORTS.has(type)) {
+            errors.push(`server "${name}": unsupported transport ${JSON.stringify(server.type)} (supported: stdio, streamable-http, sse)`);
+            continue;
+        }
+        if (type !== 'stdio') {
+            valid[name] = { ...server, type };
+            continue;
+        }
+        const stdioServer = server;
+        const problems = [];
+        if (typeof stdioServer.command !== 'string') {
+            errors.push(`server "${name}": stdio servers require a command`);
+            continue;
+        }
+        if (stdioServer.command.includes('/')) {
+            if (!stdioServer.command.startsWith('./')) {
+                problems.push(`command "${stdioServer.command}" must be a bare executable name or a plugin-relative path beginning with "./"`);
+            }
+            else {
+                const reason = await pathContainmentError(pluginRoot, stdioServer.command);
+                if (reason !== undefined)
+                    problems.push(reason);
+            }
+        }
+        if (stdioServer.cwd !== undefined && !stdioServer.cwd.startsWith('${PLUGIN_DATA}')) {
+            // `.` is the Codex dialect spelling for the plugin root.
+            const cwd = stdioServer.cwd === '.' ? './' : stdioServer.cwd;
+            const reason = await pathContainmentError(pluginRoot, cwd);
+            if (reason !== undefined)
+                problems.push(reason);
+        }
+        if (problems.length > 0) {
+            errors.push(...problems.map(problem => `server "${name}": ${problem}`));
+        }
+        else {
+            valid[name] = { ...server, type: 'stdio' };
+        }
+    }
+    return { config: { schema: typeof record['$schema'] === 'string' ? record['$schema'] : 'native-client', servers: valid }, errors };
+}
+/** Expand `${PLUGIN_ROOT}`, `${PLUGIN_DATA}`, and `${NAME}` (process env) in one string.
+ *  Claude Code aliases `${CLAUDE_PLUGIN_ROOT}` / `${CLAUDE_PLUGIN_DATA}` and
+ *  `${NAME:-default}` fallbacks are honored for unset/empty env vars. */
+export function expandPlaceholders(value, pluginRoot, pluginData, env = process.env) {
+    return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (match, name, fallback) => {
+        if (name === 'PLUGIN_ROOT' || name === 'CLAUDE_PLUGIN_ROOT')
+            return pluginRoot;
+        if (name === 'PLUGIN_DATA' || name === 'CLAUDE_PLUGIN_DATA')
+            return pluginData;
+        return env[name] || fallback || '';
+    });
+}
+/** Resolve an expanded plugin-relative cwd to an absolute path. */
+export function resolveCwd(value, pluginRoot, pluginData) {
+    if (value.startsWith('${PLUGIN_DATA}'))
+        return resolve(pluginData, value.slice('${PLUGIN_DATA}'.length).replace(/^\/+/, ''));
+    if (value.startsWith('${PLUGIN_ROOT}'))
+        return resolve(pluginRoot, value.slice('${PLUGIN_ROOT}'.length).replace(/^\/+/, ''));
+    return resolve(pluginRoot, value.replace(/^\.\//, ''));
+}
+/** Whether one absolute path equals or lies under another absolute path. */
+export function isWithin(root, candidate) {
+    const relativePath = relative(root, candidate);
+    return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
+}

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "dsh-agent-plugins-market",
+  "description": "Bring the Claude Code / Codex / Cursor plugin-marketplace ecosystem into DeepSeek Harness (DSH): install & inject agent plugins — skills, MCP servers, hooks, slash commands — from git marketplace repos (agent-plugins.org v1.0.0, .claude-plugin, .codex-plugin, .cursor-plugin, .kimi-plugin), with a Web GUI market page.",
+  "version": "0.4.3",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": "./client/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "client",
+    "schemas",
+    "cordis.patch.yml",
+    "LICENSE",
+    "README.md",
+    "README.zh.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "build": "tsc -p tsconfig.json && pnpm run build:client",
+    "build:client": "tsdown && node scripts/normalize-client-banner.mjs",
+    "test": "vitest run",
+    "prepack": "pnpm run build"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-theme"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sivan757/dsh-agent-plugins-market.git"
+  },
+  "keywords": [
+    "deepseek",
+    "deepseek-harness",
+    "harness",
+    "dsh",
+    "dsh-plugin",
+    "agent-plugins",
+    "agent-plugin",
+    "plugin-marketplace",
+    "marketplace",
+    "claude-code",
+    "claude",
+    "codex",
+    "cursor",
+    "skills",
+    "mcp",
+    "mcp-servers",
+    "hooks",
+    "suite",
+    "ai-agents"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-hooks-claude-code": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-mcp-client": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-mcp-client": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-hooks-claude-code": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-hooks-claude-code": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-mcp-client": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
+    "@tsdown/css": "^0.22.14",
+    "@types/node": "^22.15.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "^19.2.4",
+    "jsdom": "^30.0.1",
+    "react": "^18.3.1",
+    "react-dom": "~18.3.1",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "homepage": "https://www.npmjs.com/package/dsh-agent-plugins-market"
+}

package/schemas/1.0.0/mcp.schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "title": "Agent Plugins MCP Configuration",
+  "description": "Machine-readable schema for mcp.json in Agent Plugins 1.0.0. The Agent Plugins specification defines additional semantic and operational requirements.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "const": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+      "description": "Canonical identifier of the MCP configuration schema for the Agent Plugins version targeted by this document."
+    },
+    "mcpServers": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/server"
+      }
+    }
+  },
+  "required": ["$schema", "mcpServers"],
+  "additionalProperties": false,
+  "$defs": {
+    "server": {
+      "title": "MCP server",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/stdioServer"
+        },
+        {
+          "$ref": "#/$defs/streamableHttpServer"
+        },
+        {
+          "$ref": "#/$defs/sseServer"
+        }
+      ]
+    },
+    "stdioServer": {
+      "title": "stdio MCP server",
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "stdio"
+        },
+        "command": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Executable token. Resolution rules are defined by the Agent Plugins specification."
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "env": {
+          "type": "object",
+          "propertyNames": {
+            "not": {
+              "enum": ["PLUGIN_ROOT", "PLUGIN_DATA"]
+            }
+          },
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "cwd": {
+          "type": "string",
+          "pattern": "^(?:\\./|\\$\\{PLUGIN_ROOT\\}(?:/|$)|\\$\\{PLUGIN_DATA\\}(?:/|$))",
+          "description": "Plugin-relative, PLUGIN_ROOT-rooted, or PLUGIN_DATA-rooted working directory. Filesystem containment is validated separately."
+        }
+      },
+      "required": ["type", "command"],
+      "additionalProperties": false
+    },
+    "streamableHttpServer": {
+      "title": "Streamable HTTP MCP server",
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "streamable-http"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1,
+          "description": "MCP endpoint URL. URL semantics are defined by the Agent Plugins specification."
+        },
+        "headers": {
+          "$ref": "#/$defs/headers"
+        }
+      },
+      "required": ["type", "url"],
+      "additionalProperties": false
+    },
+    "sseServer": {
+      "title": "Legacy HTTP+SSE MCP server",
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "sse"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1,
+          "description": "MCP endpoint URL. URL semantics are defined by the Agent Plugins specification."
+        },
+        "headers": {
+          "$ref": "#/$defs/headers"
+        }
+      },
+      "required": ["type", "url"],
+      "additionalProperties": false
+    },
+    "headers": {
+      "title": "HTTP headers",
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    }
+  }
+}

package/schemas/1.0.0/plugin.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "title": "Agent Plugins Manifest",
+  "description": "Machine-readable schema for plugin.json in Agent Plugins 1.0.0. The Agent Plugins specification defines additional semantic and operational requirements.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "const": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+      "description": "Canonical identifier of the plugin manifest schema for the Agent Plugins version targeted by this document."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^(?!.*(?:--|\\.\\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$",
+      "description": "Human-readable plugin name."
+    },
+    "version": {
+      "type": "string"
+    },
+    "description": {
+      "type": "string"
+    },
+    "author": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "email": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "homepage": {
+      "type": "string"
+    },
+    "repository": {
+      "type": "string"
+    },
+    "license": {
+      "type": "string"
+    },
+    "keywords": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Client-specific manifest data keyed by reverse-domain extension namespace. Agent Plugins assigns no semantics to namespace object contents.",
+      "additionalProperties": {
+        "type": "object"
+      }
+    }
+  },
+  "required": ["$schema", "name"],
+  "additionalProperties": false
+}

package/schemas/README.md

@@ -0,0 +1,14 @@
+# Vendored Agent Plugins JSON Schemas
+
+These files are pinned copies of the official Agent Plugins 1.0.0 schemas:
+
+- source: https://github.com/agentplugins/agent-plugins-spec (schemas/1.0.0/)
+- spec status: version 1.0.0, working draft
+- license: the Agent Plugins specification repository's license
+
+They are bundled into the published package because the specification requires
+clients to validate plugin packages without retrieving schemas at load time
+(§7.2.1: "Clients MUST NOT retrieve a schema while loading a plugin").
+
+Update procedure: replace both files from the upstream repository at the pinned
+spec version and bump the spec-version references in `src/validate.ts`.