@humain/terminal 0.1.1 → 0.2.1

package/dist/humain/mcp-adapter/vendor/agent-plugin-loader.ts

@@ -1,7 +1,9 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
 import { getAgentPath } from "./agent-dir.ts";
+import { markBuiltInAgentPlugin } from "./agent-plugin-provenance.ts";
 import type { McpConfig, ServerEntry } from "./types.ts";
+import { resolveRealContainedPath } from "./utils.ts";
 
 const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
 const MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
@@ -21,6 +23,8 @@ const PLUGIN_MANIFEST_FIELDS = new Set([
 const MCP_CONFIG_FIELDS = new Set(["$schema", "mcpServers"]);
 const STDIO_FIELDS = new Set(["type", "command", "args", "env", "cwd"]);
 const HTTP_FIELDS = new Set(["type", "url", "headers"]);
+const STRING_MANIFEST_FIELDS = ["version", "description", "homepage", "repository", "license"] as const;
+const AUTHOR_FIELDS = new Set(["name", "email", "url"]);
 
 interface AgentPluginManifest {
   name: string;
@@ -50,7 +54,7 @@ export function loadAgentPluginConfigs(paths: unknown, cwd = process.cwd()): Mcp
 
 export function getAgentPluginSummaries(paths: unknown, cwd = process.cwd()): AgentPluginSummary[] {
   return getPluginPaths(paths).map(path => {
-    const pluginRoot = resolvePluginPath(path, cwd);
+    const pluginRoot = resolvePluginRoot(path, cwd);
     const loaded = loadAgentPluginMcpConfig(path, cwd);
     const manifest = loaded ? readPluginManifest(pluginRoot, false) : null;
     return {
@@ -66,7 +70,7 @@ function getPluginPaths(paths: unknown): string[] {
 }
 
 function loadAgentPluginMcpConfig(path: string, cwd: string): McpConfig | null {
-  const pluginRoot = resolvePluginPath(path, cwd);
+  const pluginRoot = resolvePluginRoot(path, cwd);
   const manifest = readPluginManifest(pluginRoot, true);
   if (!manifest) return null;
 
@@ -76,10 +80,15 @@ function loadAgentPluginMcpConfig(path: string, cwd: string): McpConfig | null {
     console.warn(`Agent Plugin ${manifest.name} has invalid MCP config: mcp.json is not a regular file`);
     return { mcpServers: {} };
   }
+  const resolvedMcpPath = resolveRealContainedPath(pluginRoot, mcpPath);
+  if (!resolvedMcpPath) {
+    console.warn(`Agent Plugin ${manifest.name} has invalid MCP config: mcp.json must stay inside the plugin directory`);
+    return { mcpServers: {} };
+  }
 
   let raw: unknown;
   try {
-    raw = JSON.parse(readFileSync(mcpPath, "utf8"));
+    raw = JSON.parse(readFileSync(resolvedMcpPath, "utf8"));
   } catch (error) {
     console.warn(`Agent Plugin ${manifest.name} has invalid MCP config: failed to parse mcp.json`, error);
     return { mcpServers: {} };
@@ -98,10 +107,15 @@ function readPluginManifest(pluginRoot: string, report: boolean): AgentPluginMan
     if (report) console.warn(`Agent Plugin at ${pluginRoot} is invalid: plugin.json is not a regular file`);
     return null;
   }
+  const resolvedManifestPath = resolveRealContainedPath(pluginRoot, manifestPath);
+  if (!resolvedManifestPath) {
+    if (report) console.warn(`Agent Plugin at ${pluginRoot} is invalid: plugin.json must stay inside the plugin directory`);
+    return null;
+  }
 
   let raw: unknown;
   try {
-    raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+    raw = JSON.parse(readFileSync(resolvedManifestPath, "utf8"));
   } catch (error) {
     if (report) console.warn(`Agent Plugin at ${pluginRoot} is invalid: failed to parse plugin.json`, error);
     return null;
@@ -125,6 +139,20 @@ function readPluginManifest(pluginRoot: string, report: boolean): AgentPluginMan
     if (report) console.warn(`Agent Plugin at ${pluginRoot} is invalid: plugin.json name is invalid`);
     return null;
   }
+  for (const field of STRING_MANIFEST_FIELDS) {
+    if (manifest[field] !== undefined && typeof manifest[field] !== "string") {
+      if (report) console.warn(`Agent Plugin ${manifest.name} is invalid: plugin.json ${field} must be a string`);
+      return null;
+    }
+  }
+  if (manifest.keywords !== undefined && (!Array.isArray(manifest.keywords) || manifest.keywords.some(value => typeof value !== "string"))) {
+    if (report) console.warn(`Agent Plugin ${manifest.name} is invalid: plugin.json keywords must be an array of strings`);
+    return null;
+  }
+  if (manifest.author !== undefined && !isValidManifestAuthor(manifest.author)) {
+    if (report) console.warn(`Agent Plugin ${manifest.name} is invalid: plugin.json author is invalid`);
+    return null;
+  }
   if (manifest.extensions !== undefined && (!manifest.extensions || typeof manifest.extensions !== "object" || Array.isArray(manifest.extensions))) {
     if (report) console.warn(`Agent Plugin ${manifest.name} ignores non-object plugin.json extensions`);
   }
@@ -205,14 +233,14 @@ function translateStdioServer(
   const env = translateEnv(raw.env, manifest, serverName);
   if (env === null) return null;
 
-  const command = raw.command.startsWith("./") ? resolveContainedPath(pluginRoot, raw.command, pluginRoot) : raw.command;
-  if (command === null) return skipServer(manifest, serverName, "command must stay inside the plugin directory");
+  const command = raw.command.startsWith("./") ? resolveRealContainedPath(pluginRoot, resolve(pluginRoot, raw.command)) : raw.command;
+  if (command === null) return skipServer(manifest, serverName, "command must resolve to an accessible path inside the plugin directory");
 
   const pluginDataDir = getAgentPath("agent-plugin-data", manifest.name);
   const cwd = resolvePluginCwd(raw.cwd, pluginRoot, pluginDataDir);
-  if (cwd === null) return skipServer(manifest, serverName, "cwd must be plugin-relative, PLUGIN_ROOT-rooted, or PLUGIN_DATA-rooted");
+  if (cwd === null) return skipServer(manifest, serverName, "cwd must resolve from an allowed root and stay contained");
 
-  return {
+  return markBuiltInAgentPlugin({
     command,
     args: args.map(value => expandPluginPlaceholders(value, pluginRoot, pluginDataDir)),
     env: {
@@ -223,7 +251,7 @@ function translateStdioServer(
     cwd,
     pluginDataDir,
     literalEnv: true,
-  };
+  }, ["args", "env", "cwd"]);
 }
 
 function translateHttpServer(
@@ -240,11 +268,11 @@ function translateHttpServer(
   const headers = translateHeaders(raw.headers, manifest, serverName);
   if (headers === null) return null;
 
-  return {
+  return markBuiltInAgentPlugin({
     url: raw.url,
     httpTransport: type,
     ...(headers ? { headers } : {}),
-  };
+  }, headers ? ["headers"] : []);
 }
 
 function formatAgentPluginServerName(pluginName: string, serverName: string): string {
@@ -273,7 +301,7 @@ function translateEnv(value: unknown, manifest: AgentPluginManifest, serverName:
     console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: env must be an object of strings`);
     return null;
   }
-  const env: Record<string, string> = {};
+  const entries: Array<[string, string]> = [];
   for (const [key, entry] of Object.entries(value)) {
     if (key === "PLUGIN_ROOT" || key === "PLUGIN_DATA") {
       console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: env must not define ${key}`);
@@ -283,9 +311,9 @@ function translateEnv(value: unknown, manifest: AgentPluginManifest, serverName:
       console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: env values must be strings`);
       return null;
     }
-    env[key] = entry;
+    entries.push([key, entry]);
   }
-  return env;
+  return Object.fromEntries(entries);
 }
 
 function translateHeaders(value: unknown, manifest: AgentPluginManifest, serverName: string): Record<string, string> | undefined | null {
@@ -294,7 +322,7 @@ function translateHeaders(value: unknown, manifest: AgentPluginManifest, serverN
     console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: headers must be an object of strings`);
     return null;
   }
-  const headers: Record<string, string> = {};
+  const entries: Array<[string, string]> = [];
   const seen = new Set<string>();
   for (const [key, entry] of Object.entries(value)) {
     if (typeof entry !== "string") {
@@ -307,8 +335,9 @@ function translateHeaders(value: unknown, manifest: AgentPluginManifest, serverN
       return null;
     }
     seen.add(normalized);
-    headers[key] = entry;
+    entries.push([key, entry]);
   }
+  const headers = Object.fromEntries(entries);
   try {
     new Headers(headers);
   } catch {
@@ -324,6 +353,20 @@ function resolvePluginPath(path: string, cwd: string): string {
   return isAbsolute(path) ? resolve(path) : resolve(cwd, path);
 }
 
+function resolvePluginRoot(path: string, cwd: string): string {
+  const resolved = resolvePluginPath(path, cwd);
+  try {
+    return realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+function isValidManifestAuthor(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  return Object.entries(value).every(([key, entry]) => AUTHOR_FIELDS.has(key) && typeof entry === "string");
+}
+
 function isBareCommand(command: string): boolean {
   return !command.includes("/") && !command.includes("\\") && !command.includes("${PLUGIN_ROOT}") && !command.includes("${PLUGIN_DATA}");
 }
@@ -331,27 +374,23 @@ function isBareCommand(command: string): boolean {
 function resolvePluginCwd(value: unknown, pluginRoot: string, pluginDataDir: string): string | null {
   if (value === undefined) return pluginRoot;
   if (typeof value !== "string") return null;
-  if (value.startsWith("./")) return resolveContainedPath(pluginRoot, value, pluginRoot);
-  if (value === "${PLUGIN_ROOT}" || value.startsWith("${PLUGIN_ROOT}/")) {
-    return resolveContainedPath(pluginRoot, value.replace("${PLUGIN_ROOT}", "."), pluginRoot);
+  const expanded = expandPluginPlaceholders(value, pluginRoot, pluginDataDir);
+  if (value.startsWith("./") || value === "${PLUGIN_ROOT}" || value.startsWith("${PLUGIN_ROOT}/")) {
+    return resolveRealContainedPath(pluginRoot, resolve(pluginRoot, expanded));
   }
   if (value === "${PLUGIN_DATA}" || value.startsWith("${PLUGIN_DATA}/")) {
-    return resolveContainedPath(pluginDataDir, value.replace("${PLUGIN_DATA}", "."), pluginDataDir);
+    return resolvePluginDataCwd(pluginDataDir, expanded);
   }
   return null;
 }
 
-function resolveContainedPath(root: string, value: string, containmentRoot: string): string | null {
-  const resolved = resolve(root, value);
-  const rel = relative(containmentRoot, resolved);
-  if (rel === "" || (!rel.startsWith("..") && !rel.startsWith(sep) && !isAbsolute(rel))) return resolved;
-  return null;
+function resolvePluginDataCwd(pluginDataDir: string, expanded: string): string | null {
+  if (existsSync(pluginDataDir) && !resolveRealContainedPath(dirname(pluginDataDir), pluginDataDir)) return null;
+  return resolveRealContainedPath(pluginDataDir, resolve(pluginDataDir, expanded), true);
 }
 
 function expandPluginPlaceholders(value: string, pluginRoot: string, pluginDataDir: string): string {
-  return value
-    .replaceAll("${PLUGIN_ROOT}", pluginRoot)
-    .replaceAll("${PLUGIN_DATA}", pluginDataDir);
+  return value.replace(/\$\{PLUGIN_(ROOT|DATA)\}/g, (_, name: string) => name === "ROOT" ? pluginRoot : pluginDataDir);
 }
 
 function isValidAgentPluginUrl(value: string): boolean {

package/dist/humain/mcp-adapter/vendor/agent-plugin-provenance.ts

@@ -0,0 +1,36 @@
+import type { ServerEntry } from "./types.ts";
+
+const LITERAL_PLUGIN_FIELDS = ["args", "env", "cwd", "headers"] as const;
+type LiteralPluginField = typeof LITERAL_PLUGIN_FIELDS[number];
+const BUILT_IN_AGENT_PLUGIN = Symbol("built-in-agent-plugin");
+type BuiltInAgentPluginEntry = ServerEntry & { [BUILT_IN_AGENT_PLUGIN]?: ReadonlySet<LiteralPluginField> };
+
+/** @internal */
+export function markBuiltInAgentPlugin(definition: ServerEntry, fields: LiteralPluginField[]): ServerEntry {
+  (definition as BuiltInAgentPluginEntry)[BUILT_IN_AGENT_PLUGIN] = new Set(fields);
+  return definition;
+}
+
+/** @internal */
+export function isBuiltInAgentPlugin(definition: ServerEntry, field: LiteralPluginField): boolean {
+  return (definition as BuiltInAgentPluginEntry)[BUILT_IN_AGENT_PLUGIN]?.has(field) === true;
+}
+
+/** @internal */
+export function cloneBuiltInAgentPluginEntry(source: ServerEntry): ServerEntry | undefined {
+  const fields = LITERAL_PLUGIN_FIELDS.filter(field => Object.hasOwn(source, field) && isBuiltInAgentPlugin(source, field));
+  if (fields.length === 0) return undefined;
+  return markBuiltInAgentPlugin(structuredClone(source), fields);
+}
+
+/** @internal */
+export function mergeBuiltInAgentPluginEntries(base: ServerEntry, next: ServerEntry): ServerEntry {
+  const merged = { ...base, ...next };
+  delete (merged as BuiltInAgentPluginEntry)[BUILT_IN_AGENT_PLUGIN];
+  const fields = LITERAL_PLUGIN_FIELDS.filter(field => {
+    const owner = Object.hasOwn(next, field) ? next : base;
+    return Object.hasOwn(owner, field) && isBuiltInAgentPlugin(owner, field);
+  });
+  if (fields.length > 0) markBuiltInAgentPlugin(merged, fields);
+  return merged;
+}

package/dist/humain/mcp-adapter/vendor/claude-plugin-loader.ts

@@ -0,0 +1,365 @@
+import { closeSync, constants, existsSync, fstatSync, openSync, readFileSync, readdirSync, realpathSync, statSync, type Dirent, type Stats } from "node:fs";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+import { formatServerNamespace, type ClaudePluginConfig, type McpConfig, type ServerEntry } from "./types.ts";
+import { parseJsonWithComments } from "./utils.ts";
+
+interface ClaudePluginManifest {
+  name: string;
+}
+
+export interface ClaudePluginBundleResult {
+  mcpServers: Record<string, ServerEntry>;
+  skillPaths: string[];
+}
+
+export function loadClaudePluginBundles(
+  plugins: readonly ClaudePluginConfig[] | undefined,
+  cwd: string,
+  validateConfig: (raw: unknown) => McpConfig,
+  components: { mcp: boolean; skills: boolean },
+): ClaudePluginBundleResult {
+  const mcpServers: Record<string, ServerEntry> = {};
+  const skillPaths: string[] = [];
+  const seenRoots = new Set<string>();
+  const seenNames = new Map<string, string>();
+  const serverSources = new Map<string, string>();
+  const normalizedServerNames = new Map<string, string>();
+
+  for (const plugin of plugins ?? []) {
+    const configuredPath = resolvePluginPath(plugin.path, cwd);
+    const pluginRoot = resolvePluginRoot(configuredPath);
+    if (!pluginRoot) continue;
+    if (seenRoots.has(pluginRoot)) {
+      console.warn(`Claude plugin path is configured more than once: ${pluginRoot}`);
+      continue;
+    }
+    seenRoots.add(pluginRoot);
+
+    const manifest = readPluginManifest(pluginRoot);
+    if (manifest === false) continue;
+    const pluginName = manifest?.name ?? basename(pluginRoot);
+    const previousPluginRoot = seenNames.get(pluginName);
+    if (previousPluginRoot && previousPluginRoot !== pluginRoot) {
+      console.warn(`Claude plugin name conflict for "${pluginName}": ${previousPluginRoot} and ${pluginRoot}`);
+    } else {
+      seenNames.set(pluginName, pluginRoot);
+    }
+
+    if (components.mcp && plugin.mcp === true) {
+      const configPath = resolveContainedComponent(pluginRoot, ".mcp.json", "file", pluginName);
+      if (configPath) {
+        const config = readPluginMcpConfig(configPath, pluginName, pluginRoot, validateConfig);
+        for (const [serverName, server] of Object.entries(config.mcpServers)) {
+          const normalizedName = formatServerNamespace(serverName);
+          const previousName = normalizedServerNames.get(normalizedName);
+          const previousSource = previousName ? serverSources.get(previousName) : undefined;
+          if (previousName && previousSource) {
+            console.warn(`Claude plugin MCP server name conflict for "${serverName}": normalized name collides with "${previousName}" from ${previousSource}; the first plugin wins over ${configPath}`);
+            continue;
+          }
+          normalizedServerNames.set(normalizedName, serverName);
+          serverSources.set(serverName, configPath);
+          mcpServers[serverName] = server;
+        }
+      }
+    }
+
+    if (components.skills && plugin.skills === true) {
+      const skillsPath = resolveContainedComponent(pluginRoot, "skills", "directory", pluginName);
+      if (skillsPath) {
+        try {
+          for (const skillPath of discoverContainedSkillFiles(skillsPath, pluginName)) {
+            if (!skillPaths.includes(skillPath)) skillPaths.push(skillPath);
+          }
+        } catch (error) {
+          console.warn(`Claude plugin "${pluginName}" skills could not be read at ${skillsPath}: ${formatError(error)}`);
+        }
+      }
+    }
+  }
+
+  return { mcpServers, skillPaths };
+}
+
+function resolvePluginPath(path: string, cwd: string): string {
+  if (path === "~") return resolve(process.env.HOME ?? "", ".");
+  if (path.startsWith("~/")) return resolve(process.env.HOME ?? "", path.slice(2));
+  return isAbsolute(path) ? resolve(path) : resolve(cwd, path);
+}
+
+function resolvePluginRoot(path: string): string | null {
+  if (!existsSync(path)) {
+    console.warn(`Claude plugin path does not exist: ${path}`);
+    return null;
+  }
+  const stats = safeStat(path, "Claude plugin path");
+  if (!stats) return null;
+  if (!stats.isDirectory()) {
+    console.warn(`Claude plugin path is not a directory: ${path}`);
+    return null;
+  }
+  return safeRealpath(path, "Claude plugin path");
+}
+
+function readPluginManifest(pluginRoot: string): ClaudePluginManifest | null | false {
+  const configuredManifestPath = resolve(pluginRoot, ".claude-plugin", "plugin.json");
+  if (!existsSync(configuredManifestPath)) return null;
+  const stats = safeStat(configuredManifestPath, "Claude plugin manifest");
+  if (!stats) return null;
+  if (!stats.isFile()) {
+    console.warn(`Claude plugin manifest is not a regular file: ${configuredManifestPath}`);
+    return false;
+  }
+  const manifestPath = safeRealpath(configuredManifestPath, "Claude plugin manifest");
+  if (!manifestPath) return null;
+  if (!isContainedPath(pluginRoot, manifestPath)) {
+    console.warn(`Claude plugin manifest resolves outside the configured plugin directory: ${manifestPath}`);
+    return false;
+  }
+
+  const manifestText = safeReadFile(manifestPath, "Claude plugin manifest", pluginRoot);
+  if (manifestText === null) return null;
+
+  let raw: unknown;
+  try {
+    raw = parseJsonWithComments(manifestText);
+  } catch (error) {
+    console.warn(`Claude plugin manifest contains invalid JSON at ${manifestPath}: ${formatError(error)}`);
+    return false;
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    console.warn(`Claude plugin manifest must be a JSON object: ${manifestPath}`);
+    return false;
+  }
+
+  const manifest = raw as Record<string, unknown>;
+  if (typeof manifest.name !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(manifest.name)) {
+    console.warn(`Claude plugin manifest has an invalid name at ${manifestPath}: expected kebab-case`);
+    return false;
+  }
+  if (!hasValidManifestFieldTypes(manifest)) {
+    console.warn(`Claude plugin manifest has invalid field types at ${manifestPath}`);
+    return false;
+  }
+  return { name: manifest.name };
+}
+
+function hasValidManifestFieldTypes(manifest: Record<string, unknown>): boolean {
+  for (const field of ["$schema", "displayName", "version", "description", "homepage", "repository", "license"] as const) {
+    if (manifest[field] !== undefined && typeof manifest[field] !== "string") return false;
+  }
+  for (const field of ["commands", "agents", "skills", "hooks", "mcpServers", "lspServers", "outputStyles"] as const) {
+    const value = manifest[field];
+    if (value !== undefined && typeof value !== "string" && (!Array.isArray(value) || value.some(item => typeof item !== "string"))) return false;
+  }
+  if (manifest.defaultEnabled !== undefined && typeof manifest.defaultEnabled !== "boolean") return false;
+  if (manifest.keywords !== undefined && (!Array.isArray(manifest.keywords) || manifest.keywords.some(value => typeof value !== "string"))) return false;
+  if (manifest.author !== undefined) {
+    if (!manifest.author || typeof manifest.author !== "object" || Array.isArray(manifest.author)) return false;
+    const author = manifest.author as Record<string, unknown>;
+    if (typeof author.name !== "string") return false;
+    if (author.email !== undefined && typeof author.email !== "string") return false;
+    if (author.url !== undefined && typeof author.url !== "string") return false;
+  }
+  if (manifest.metadata !== undefined && (!manifest.metadata || typeof manifest.metadata !== "object" || Array.isArray(manifest.metadata))) return false;
+  return true;
+}
+
+function resolveContainedComponent(
+  pluginRoot: string,
+  component: string,
+  expected: "file" | "directory",
+  pluginName: string,
+): string | null {
+  const path = resolve(pluginRoot, component);
+  if (!existsSync(path)) {
+    console.warn(`Claude plugin "${pluginName}" is missing ${component}: ${path}`);
+    return null;
+  }
+  const stats = safeStat(path, `Claude plugin "${pluginName}" ${component}`);
+  if (!stats) return null;
+  if (expected === "file" ? !stats.isFile() : !stats.isDirectory()) {
+    console.warn(`Claude plugin "${pluginName}" ${component} is not a ${expected}: ${path}`);
+    return null;
+  }
+  const realPath = safeRealpath(path, `Claude plugin "${pluginName}" ${component}`);
+  if (!realPath) return null;
+  if (!isContainedPath(pluginRoot, realPath)) {
+    console.warn(`Claude plugin "${pluginName}" ${component} resolves outside the configured plugin directory: ${realPath}`);
+    return null;
+  }
+  return realPath;
+}
+
+function discoverContainedSkillFiles(skillsRoot: string, pluginName: string): string[] {
+  const skillFiles: string[] = [];
+  const visitedDirectories = new Set<string>();
+  const visit = (directory: string): void => {
+    const realDirectory = safeRealpath(directory, `Claude plugin "${pluginName}" skill directory`);
+    if (!realDirectory) return;
+    if (!isContainedPath(skillsRoot, realDirectory)) {
+      console.warn(`Claude plugin "${pluginName}" skill path resolves outside its skills directory: ${directory} -> ${realDirectory}`);
+      return;
+    }
+    if (visitedDirectories.has(realDirectory)) return;
+    visitedDirectories.add(realDirectory);
+    const entries = safeReadDir(realDirectory, `Claude plugin "${pluginName}" skill directory`);
+    if (!entries) return;
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      const path = resolve(realDirectory, entry.name);
+      if (entry.isSymbolicLink()) {
+        const target = safeRealpath(path, `Claude plugin "${pluginName}" skill path`);
+        if (!target) continue;
+        if (!isContainedPath(skillsRoot, target)) {
+          console.warn(`Claude plugin "${pluginName}" skill path resolves outside its skills directory: ${path} -> ${target}`);
+          continue;
+        }
+        const targetStats = safeStat(target, `Claude plugin "${pluginName}" skill path`);
+        if (!targetStats) continue;
+        if (targetStats.isDirectory()) visit(target);
+        else if (targetStats.isFile() && entry.name === "SKILL.md") skillFiles.push(target);
+      } else if (entry.isDirectory()) {
+        visit(path);
+      } else if (entry.isFile() && entry.name === "SKILL.md") {
+        const realPath = safeRealpath(path, `Claude plugin "${pluginName}" skill path`);
+        if (!realPath) continue;
+        if (!isContainedPath(skillsRoot, realPath)) {
+          console.warn(`Claude plugin "${pluginName}" skill path resolves outside its skills directory: ${path} -> ${realPath}`);
+          continue;
+        }
+        skillFiles.push(realPath);
+      }
+    }
+  };
+  visit(skillsRoot);
+  return skillFiles;
+}
+
+function readPluginMcpConfig(
+  configPath: string,
+  pluginName: string,
+  pluginRoot: string,
+  validateConfig: (raw: unknown) => McpConfig,
+): McpConfig {
+  let raw: unknown;
+  try {
+    const configText = safeReadFile(configPath, `Claude plugin "${pluginName}" MCP config`, pluginRoot);
+    if (configText === null) return { mcpServers: {} };
+    raw = parseJsonWithComments(configText);
+  } catch (error) {
+    console.warn(`Claude plugin "${pluginName}" has invalid MCP config at ${configPath}: ${formatError(error)}`);
+    return { mcpServers: {} };
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    console.warn(`Claude plugin "${pluginName}" MCP config must be a JSON object: ${configPath}`);
+    return { mcpServers: {} };
+  }
+
+  const servers = (raw as Record<string, unknown>).mcpServers;
+  if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
+    console.warn(`Claude plugin "${pluginName}" MCP config must contain an mcpServers object: ${configPath}`);
+    return { mcpServers: {} };
+  }
+
+  const config = validateConfig(raw);
+  const validated: Record<string, ServerEntry> = {};
+  for (const serverName of Object.keys(servers)) {
+    if (serverName.trim().length === 0) {
+      console.warn(`Claude plugin "${pluginName}" has an empty MCP server name at ${configPath}`);
+      continue;
+    }
+    const parsed = config.mcpServers[serverName];
+    if (!parsed || !hasValidServerTransport(parsed)) {
+      console.warn(`Claude plugin "${pluginName}" has invalid MCP server "${serverName}" at ${configPath}: expected exactly one non-empty command, url, or socket transport`);
+      continue;
+    }
+    validated[serverName] = replacePluginRoot(parsed, pluginRoot);
+  }
+  return { mcpServers: validated };
+}
+
+function hasValidServerTransport(entry: ServerEntry): boolean {
+  return [entry.command, entry.url, entry.socket].filter(value => typeof value === "string" && value.trim().length > 0).length === 1;
+}
+
+function replacePluginRoot(entry: ServerEntry, pluginRoot: string): ServerEntry {
+  const replace = (value: string): string => value.replaceAll("${CLAUDE_PLUGIN_ROOT}", pluginRoot);
+  const replaced = replaceStrings(entry, replace) as ServerEntry;
+  if (typeof replaced.command === "string") {
+    replaced.env = { ...replaced.env, CLAUDE_PLUGIN_ROOT: pluginRoot };
+  }
+  return replaced;
+}
+
+function replaceStrings(value: unknown, replace: (value: string) => string): unknown {
+  if (typeof value === "string") return replace(value);
+  if (Array.isArray(value)) return value.map(item => replaceStrings(item, replace));
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, replaceStrings(entry, replace)]));
+}
+
+function isContainedPath(root: string, path: string): boolean {
+  const rel = relative(root, path);
+  return rel === "" || (!rel.startsWith("..") && !rel.startsWith(sep) && !isAbsolute(rel));
+}
+
+function safeStat(path: string, description: string): Stats | null {
+  try {
+    return statSync(path);
+  } catch (error) {
+    console.warn(`${description} could not be read: ${path}: ${formatError(error)}`);
+    return null;
+  }
+}
+
+function safeRealpath(path: string, description: string): string | null {
+  try {
+    return realpathSync(path);
+  } catch (error) {
+    console.warn(`${description} could not be read: ${path}: ${formatError(error)}`);
+    return null;
+  }
+}
+
+function safeReadFile(path: string, description: string, containmentRoot: string): string | null {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const openedStats = fstatSync(fd);
+    if (!openedStats.isFile()) {
+      console.warn(`${description} is not a regular file: ${path}`);
+      return null;
+    }
+    const resolvedPath = safeRealpath(path, description);
+    if (!resolvedPath) return null;
+    if (!isContainedPath(containmentRoot, resolvedPath)) {
+      console.warn(`${description} resolves outside the configured plugin directory: ${resolvedPath}`);
+      return null;
+    }
+    const currentStats = safeStat(resolvedPath, description);
+    if (!currentStats) return null;
+    if (openedStats.dev !== currentStats.dev || openedStats.ino !== currentStats.ino) {
+      console.warn(`${description} changed while being read: ${path}`);
+      return null;
+    }
+    return readFileSync(fd, "utf8");
+  } catch (error) {
+    console.warn(`${description} could not be read: ${path}: ${formatError(error)}`);
+    return null;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function safeReadDir(path: string, description: string): Dirent[] | null {
+  try {
+    return readdirSync(path, { withFileTypes: true });
+  } catch (error) {
+    console.warn(`${description} could not be read: ${path}: ${formatError(error)}`);
+    return null;
+  }
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}