@agentplugins/adapter-claude 0.1.0

package/README.md

@@ -0,0 +1,55 @@
+# @agentplugins/adapter-claude
+
+> AgentPlugins platform adapter for [Claude Code](https://code.claude.com/docs/en/plugins-reference).
+
+Compiles a universal `PluginManifest` into Claude Code's native plugin layout: `plugin.json` manifest, `hooks.json` hook wiring, inline handler scripts, `skills/`, and MCP server configuration.
+
+## Installation
+
+```bash
+npm install @agentplugins/adapter-claude
+```
+
+This package is typically installed transitively via [`@agentplugins/cli`](https://www.npmjs.com/package/@agentplugins/cli). Install it directly only if you're building a custom build pipeline.
+
+## Usage
+
+```typescript
+import { createClaudeAdapter } from '@agentplugins/adapter-claude';
+
+const adapter = createClaudeAdapter();
+const output = await adapter.compile(manifest);
+// → output.files: FileOutput[] of plugin.json, hooks/handlers, skills/, MCP config
+```
+
+You usually don't call the adapter directly — let `@agentplugins/cli` route to it via the registry:
+
+```bash
+npx agentplugins build --target claude
+```
+
+## Output shape
+
+A successful build writes to `dist/claude/`:
+
+```
+dist/claude/
+├── .claude-plugin/
+│   └── plugin.json
+├── hooks/
+│   └── hooks.json
+├── skills/
+│   └── <skill-name>/
+│       └── SKILL.md
+└── .mcp.json
+```
+
+Install with: `cp -r dist/claude ~/.claude/skills/<plugin-name>`
+
+## Supported hooks
+
+`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `SessionStart`, `SessionEnd`. See [HookContext in `@agentplugins/core`](https://www.npmjs.com/package/@agentplugins/core) for the universal hook names.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,509 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createAdapter: () => createAdapter,
+  createClaudeAdapter: () => createClaudeAdapter,
+  default: () => createClaudeAdapter
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@agentplugins/core");
+var CLAUDE_SUPPORTED_HOOKS = [
+  "sessionStart",
+  "sessionEnd",
+  "userPromptSubmit",
+  "userPromptExpansion",
+  "preToolUse",
+  "postToolUse",
+  "postToolUseFailure",
+  "permissionRequest",
+  "permissionDenied",
+  "subagentStart",
+  "subagentStop",
+  "preCompact",
+  "postCompact",
+  "stop",
+  "stopFailure",
+  "notification",
+  "fileChanged",
+  "cwdChanged",
+  "setup"
+];
+var CLAUDE_SUPPORTED_HANDLERS = [
+  "command",
+  "http",
+  "inline"
+  // auto-wrapped as command scripts
+];
+var HOOK_NAME_MAP = {
+  sessionStart: "SessionStart",
+  sessionEnd: "SessionEnd",
+  userPromptSubmit: "UserPromptSubmit",
+  userPromptExpansion: "UserPromptExpansion",
+  preToolUse: "PreToolUse",
+  postToolUse: "PostToolUse",
+  postToolUseFailure: "PostToolUseFailure",
+  permissionRequest: "PermissionRequest",
+  permissionDenied: "PermissionDenied",
+  subagentStart: "SubagentStart",
+  subagentStop: "SubagentStop",
+  preCompact: "PreCompact",
+  postCompact: "PostCompact",
+  stop: "Stop",
+  stopFailure: "StopFailure",
+  notification: "Notification",
+  fileChanged: "FileChanged",
+  cwdChanged: "CwdChanged",
+  setup: "Setup"
+};
+function createClaudeAdapter() {
+  return new ClaudePlatformAdapter();
+}
+function createAdapter() {
+  return createClaudeAdapter();
+}
+var ClaudePlatformAdapter = class {
+  name = "claude";
+  displayName = "Claude Code";
+  supportedHooks = CLAUDE_SUPPORTED_HOOKS;
+  supportedHandlers = CLAUDE_SUPPORTED_HANDLERS;
+  manifestPath = ".claude-plugin/plugin.json";
+  manifestFormat = "json";
+  // Inline handlers are wrapped as command scripts; tracks wrapper ID -> hook name
+  inlineWrappers = /* @__PURE__ */ new Map();
+  // ─── Validation ────────────────────────────────────────────────────────────
+  validate(plugin) {
+    const issues = [...(0, import_core.validateForPlatform)(plugin, "claude")];
+    if (plugin.hooks) {
+      for (const [name, def] of Object.entries(plugin.hooks)) {
+        const hookName = name;
+        if (!def) continue;
+        if (def.handler.type === "inline") {
+          const handler = def.handler;
+          if (typeof handler.handler !== "function") {
+            issues.push({
+              severity: import_core.Severity.ERROR,
+              field: `hooks.${hookName}.handler`,
+              message: "Inline handler must be a function"
+            });
+          } else {
+            issues.push({
+              severity: import_core.Severity.INFO,
+              field: `hooks.${hookName}.handler`,
+              message: "Inline handler will be auto-wrapped as a Claude command script",
+              suggestion: 'For better performance, use a "command" or "http" handler'
+            });
+          }
+        }
+        if (def.matcher && ["preToolUse", "postToolUse", "postToolUseFailure"].includes(hookName)) {
+          if (def.matcher.includes("*") && !def.matcher.match(/^\*?\w+\*?$/)) {
+            issues.push({
+              severity: import_core.Severity.WARNING,
+              field: `hooks.${hookName}.matcher`,
+              message: `Matcher pattern "${def.matcher}" may not be supported by Claude for tool hooks`,
+              suggestion: 'Use simple patterns like "toolName", "prefix*", or "*suffix"'
+            });
+          }
+        }
+      }
+    }
+    if (plugin.mcpServers) {
+      for (const [serverName, config] of Object.entries(plugin.mcpServers)) {
+        if (!config.command) {
+          issues.push({
+            severity: import_core.Severity.ERROR,
+            field: `mcpServers.${serverName}.command`,
+            message: `MCP server "${serverName}" requires a command`
+          });
+        }
+        if (config.transport && config.transport !== "stdio" && config.transport !== "http") {
+          issues.push({
+            severity: import_core.Severity.WARNING,
+            field: `mcpServers.${serverName}.transport`,
+            message: `Transport "${config.transport}" may not be supported by Claude MCP`,
+            suggestion: 'Use "stdio" (default) or "http"'
+          });
+        }
+      }
+    }
+    if (plugin.skills) {
+      for (let i = 0; i < plugin.skills.length; i++) {
+        const skill = plugin.skills[i];
+        if (skill.content && skill.filePath) {
+          issues.push({
+            severity: import_core.Severity.WARNING,
+            field: `skills[${i}]`,
+            message: `Skill "${skill.name}" has both content and filePath \u2014 content takes precedence`
+          });
+        }
+      }
+    }
+    if (plugin.userConfig) {
+      const supportedTypes = ["string", "number", "boolean", "directory", "file"];
+      for (const [key, opt] of Object.entries(plugin.userConfig)) {
+        if (!supportedTypes.includes(opt.type)) {
+          issues.push({
+            severity: import_core.Severity.WARNING,
+            field: `userConfig.${key}.type`,
+            message: `User config type "${opt.type}" may not be fully supported by Claude`,
+            suggestion: `Supported types: ${supportedTypes.join(", ")}`
+          });
+        }
+      }
+    }
+    return issues;
+  }
+  // ─── Compilation ───────────────────────────────────────────────────────────
+  compile(plugin) {
+    this.inlineWrappers.clear();
+    const files = [];
+    const warnings = [];
+    const postInstall = [];
+    const claudeManifest = this.buildManifest(plugin);
+    const hooksConfig = this.buildHooksConfig(plugin);
+    if (hooksConfig.length > 0) {
+      files.push({
+        path: "hooks/hooks.json",
+        content: JSON.stringify(hooksConfig, null, 2)
+      });
+    }
+    const inlineHandlers = this.extractInlineHandlers(plugin);
+    if (inlineHandlers.size > 0) {
+      const handlersModule = (0, import_core.generateHandlersModule)(inlineHandlers);
+      files.push({
+        path: "hooks/__agentplugins_handlers__.js",
+        content: handlersModule
+      });
+      for (const [wrapperId, { hookName }] of this.inlineWrappers.entries()) {
+        const wrapperScript = (0, import_core.generateHookWrapper)("./__agentplugins_handlers__.js", {
+          platform: "claude",
+          hookName,
+          wrapperId
+        });
+        files.push({
+          path: `hooks/${wrapperId}.js`,
+          content: wrapperScript
+        });
+      }
+      warnings.push(
+        `${inlineHandlers.size} inline handler(s) wrapped as command scripts. These require Node.js at runtime.`
+      );
+    }
+    if (plugin.skills && plugin.skills.length > 0) {
+      for (const skill of plugin.skills) {
+        const skillContent = this.buildSkillFile(skill);
+        const skillPath = `skills/${skill.name}/SKILL.md`;
+        files.push({
+          path: skillPath,
+          content: skillContent
+        });
+      }
+    }
+    if (plugin.mcpServers && Object.keys(plugin.mcpServers).length > 0) {
+      const mcpConfig = this.buildMCPConfig(plugin);
+      files.push({
+        path: ".mcp.json",
+        content: JSON.stringify(mcpConfig, null, 2)
+      });
+    }
+    const envScript = this.buildEnvScript(plugin);
+    if (envScript) {
+      files.push({
+        path: "hooks/__env__.sh",
+        content: envScript
+      });
+    }
+    postInstall.push(
+      `Copy the generated files to your Claude Code project root:`,
+      `  cp -r .claude-plugin hooks/ skills/ .mcp.json <your-project>/`,
+      ``,
+      `Environment variables available at runtime:`,
+      `  \${CLAUDE_PLUGIN_ROOT} \u2014 path to the plugin directory`,
+      `  \${CLAUDE_PLUGIN_DATA}  \u2014 path to plugin data storage`,
+      ``,
+      `Install location: ~/.claude/plugins/ or project-local .claude-plugin/`
+    );
+    if (inlineHandlers.size > 0) {
+      postInstall.push(
+        ``,
+        `NOTE: ${inlineHandlers.size} inline handler(s) require Node.js to execute.`,
+        `      Wrapper scripts are in hooks/*.js`
+      );
+    }
+    return {
+      files,
+      manifest: claudeManifest,
+      warnings,
+      issues: [],
+      postInstall: postInstall.length > 0 ? postInstall : void 0
+    };
+  }
+  // ─── Internal Helpers ──────────────────────────────────────────────────────
+  /**
+   * Build the Claude plugin.json manifest from a universal plugin manifest.
+   */
+  buildManifest(plugin) {
+    const manifest = {
+      name: plugin.name,
+      version: plugin.version,
+      description: plugin.description,
+      displayName: plugin.displayName,
+      author: plugin.author,
+      homepage: plugin.homepage,
+      repository: plugin.repository,
+      license: plugin.license,
+      keywords: plugin.keywords,
+      defaultEnabled: plugin.defaultEnabled ?? true,
+      root: "${CLAUDE_PLUGIN_ROOT}",
+      data: "${CLAUDE_PLUGIN_DATA}"
+    };
+    if (plugin.userConfig) {
+      manifest.userConfig = Object.fromEntries(
+        Object.entries(plugin.userConfig).map(([key, opt]) => [
+          key,
+          {
+            type: opt.type,
+            title: opt.title,
+            description: opt.description,
+            sensitive: opt.sensitive,
+            required: opt.required,
+            default: opt.default,
+            multiple: opt.multiple
+          }
+        ])
+      );
+    }
+    if (plugin.dependencies) {
+      manifest.dependencies = plugin.dependencies;
+    }
+    if (plugin.themes) {
+      manifest.themes = plugin.themes;
+    }
+    if (plugin.monitors) {
+      manifest.monitors = plugin.monitors;
+    }
+    if (plugin.lspServers) {
+      manifest.lspServers = plugin.lspServers;
+    }
+    return manifest;
+  }
+  /**
+   * Build the hooks.json configuration from universal hooks.
+   */
+  buildHooksConfig(plugin) {
+    if (!plugin.hooks) return [];
+    const entries = [];
+    for (const [name, def] of Object.entries(plugin.hooks)) {
+      const hookName = name;
+      if (!def) continue;
+      if (!this.supportedHooks.includes(hookName)) continue;
+      const claudeEvent = HOOK_NAME_MAP[hookName];
+      const handlerConfig = this.buildHandlerConfig(def, hookName);
+      if (handlerConfig) {
+        const entry = {
+          event: claudeEvent,
+          handler: handlerConfig
+        };
+        if (def.matcher) {
+          entry.matcher = def.matcher;
+        } else if (hookName === "preToolUse" || hookName === "postToolUse" || hookName === "postToolUseFailure") {
+          entry.matcher = "*";
+        }
+        entries.push(entry);
+      }
+    }
+    return entries;
+  }
+  /**
+   * Build a single handler configuration for hooks.json.
+   */
+  buildHandlerConfig(def, hookName) {
+    const handler = def.handler;
+    switch (handler.type) {
+      case "command": {
+        return {
+          type: "command",
+          command: handler.command,
+          shell: handler.shell,
+          statusMessage: handler.statusMessage
+        };
+      }
+      case "http": {
+        return {
+          type: "http",
+          url: handler.url,
+          headers: handler.headers
+        };
+      }
+      case "inline": {
+        const wrapperId = `__inline_${hookName}_${this.hashId(hookName)}`;
+        this.inlineWrappers.set(wrapperId, { hookName });
+        return {
+          type: "command",
+          command: `node "\${CLAUDE_PLUGIN_ROOT}/hooks/${wrapperId}.js"`,
+          shell: "bash",
+          statusMessage: `Running ${hookName} hook...`
+        };
+      }
+      default: {
+        const unknownHandler = handler;
+        if (unknownHandler.type === "mcp_tool") {
+          return {
+            type: "mcp_tool",
+            mcpTool: unknownHandler.mcpTool || unknownHandler.tool,
+            mcpServer: unknownHandler.mcpServer || unknownHandler.server
+          };
+        }
+        if (unknownHandler.type === "prompt") {
+          return {
+            type: "prompt",
+            prompt: unknownHandler.prompt
+          };
+        }
+        if (unknownHandler.type === "agent") {
+          return {
+            type: "agent",
+            agent: unknownHandler.agent
+          };
+        }
+        return null;
+      }
+    }
+  }
+  /**
+   * Build a SKILL.md file with YAML frontmatter from a universal skill definition.
+   */
+  buildSkillFile(skill) {
+    const frontmatter = {
+      name: skill.name,
+      description: skill.description
+    };
+    if (skill.filePath && !skill.content) {
+      frontmatter.source = skill.filePath;
+    }
+    const yamlLines = Object.entries(frontmatter).map(([key, value]) => {
+      if (typeof value === "string") {
+        if (value.includes(":") || value.includes("#") || value.includes('"')) {
+          return `${key}: "${value.replace(/"/g, '\\"')}"`;
+        }
+        return `${key}: ${value}`;
+      }
+      return `${key}: ${value}`;
+    }).join("\n");
+    const frontmatterBlock = `---
+${yamlLines}
+---
+`;
+    if (skill.content) {
+      if (skill.content.trimStart().startsWith("---")) {
+        return skill.content;
+      }
+      return frontmatterBlock + "\n" + skill.content;
+    }
+    if (skill.filePath) {
+      return frontmatterBlock + `
+# ${skill.name}
+
+See [${skill.filePath}](${skill.filePath}) for the full skill documentation.
+`;
+    }
+    return frontmatterBlock + `
+# ${skill.name}
+
+${skill.description}
+`;
+  }
+  /**
+   * Build the .mcp.json configuration from universal MCP server definitions.
+   */
+  buildMCPConfig(plugin) {
+    if (!plugin.mcpServers) return {};
+    const servers = {};
+    for (const [serverName, config] of Object.entries(plugin.mcpServers)) {
+      servers[serverName] = {
+        command: config.command,
+        args: config.args ?? [],
+        env: config.env ?? {},
+        // Claude uses 'stdio' by default
+        transport: config.transport ?? "stdio"
+      };
+    }
+    return { servers };
+  }
+  /**
+   * Extract inline handlers that need wrapping, returning a map suitable
+   * for generateHandlersModule().
+   */
+  extractInlineHandlers(plugin) {
+    const handlers = /* @__PURE__ */ new Map();
+    if (!plugin.hooks) return handlers;
+    for (const [name, def] of Object.entries(plugin.hooks)) {
+      const hookName = name;
+      if (!def || def.handler.type !== "inline") continue;
+      const inlineHandler = def.handler;
+      if (typeof inlineHandler.handler === "function") {
+        const wrapperId = `__inline_${hookName}_${this.hashId(hookName)}`;
+        handlers.set(wrapperId, inlineHandler.handler);
+      }
+    }
+    return handlers;
+  }
+  /**
+   * Build an environment setup script that exports CLAUDE_PLUGIN_ROOT and
+   * CLAUDE_PLUGIN_DATA for use by hook scripts.
+   */
+  buildEnvScript(plugin) {
+    if (!plugin.hooks) return null;
+    const hasCommandHandlers = Object.values(plugin.hooks).some(
+      (def) => def?.handler.type === "command" || def?.handler.type === "inline"
+    );
+    if (!hasCommandHandlers) return null;
+    return `#!/usr/bin/env bash
+# AgentPlugins Auto-Generated Environment Setup for Claude Code
+# Plugin: ${plugin.name}
+# DO NOT EDIT \u2014 This file is regenerated on each build.
+
+# Resolve plugin root relative to this script
+export CLAUDE_PLUGIN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+export CLAUDE_PLUGIN_DATA="\${CLAUDE_PLUGIN_ROOT}/.data"
+
+# Ensure data directory exists
+mkdir -p "\${CLAUDE_PLUGIN_DATA}"
+`;
+  }
+  /**
+   * Generate a short hash for a hook name to use in wrapper script filenames.
+   */
+  hashId(input) {
+    let hash = 0;
+    for (let i = 0; i < input.length; i++) {
+      const char = input.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash |= 0;
+    }
+    return Math.abs(hash).toString(36).slice(0, 6);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createAdapter,
+  createClaudeAdapter
+});

package/dist/index.d.cts

@@ -0,0 +1,120 @@
+import { PlatformAdapter } from '@agentplugins/core';
+
+/**
+ * AgentPlugins Claude Code Adapter
+ *
+ * Compiles universal AgentPlugins plugins into Claude Code's native plugin format.
+ *
+ * Claude Code uses:
+ *   - `.claude-plugin/plugin.json` — manifest
+ *   - `hooks/hooks.json` — hook configuration with matchers
+ *   - `skills/<name>/SKILL.md` — skill documentation (YAML frontmatter + markdown)
+ *   - `.mcp.json` — MCP server configurations
+ *   - `${CLAUDE_PLUGIN_ROOT}` and `${CLAUDE_PLUGIN_DATA}` — env var placeholders
+ *
+ * Handler mapping:
+ *   - command     → native command handler
+ *   - http        → native HTTP handler
+ *   - mcp_tool    → Claude's MCP tool handler (emitted in hooks.json)
+ *   - prompt      → Claude's prompt handler (emitted in hooks.json)
+ *   - agent       → Claude's agent handler (emitted in hooks.json)
+ *   - inline      → auto-wrapped as Node.js command script
+ *
+ * All 19 universal hooks are supported by Claude Code.
+ */
+
+/** Claude-specific handler types beyond the universal ones. */
+type ClaudeHandlerType = 'command' | 'http' | 'mcp_tool' | 'prompt' | 'agent';
+/** Claude plugin manifest shape. */
+interface ClaudePluginManifest {
+    name: string;
+    version: string;
+    description: string;
+    displayName?: string;
+    author?: string | {
+        name: string;
+        email?: string;
+        url?: string;
+    };
+    homepage?: string;
+    repository?: string;
+    license?: string;
+    keywords?: string[];
+    defaultEnabled?: boolean;
+    /** Claude-specific: plugin root directory env var */
+    root?: string;
+    /** Claude-specific: plugin data directory env var */
+    data?: string;
+    /** User configuration schema */
+    userConfig?: Record<string, ClaudeUserConfigField>;
+    /** Dependencies on other plugins */
+    dependencies?: string[];
+    /** Theme configuration */
+    themes?: ClaudeThemeConfig[];
+    /** File monitors */
+    monitors?: ClaudeMonitorConfig[];
+    /** LSP server configuration */
+    lspServers?: ClaudeLSPServerConfig[];
+    /** Extra metadata allowed by Claude */
+    [key: string]: unknown;
+}
+/** Claude user config field definition. */
+interface ClaudeUserConfigField {
+    type: 'string' | 'number' | 'boolean' | 'directory' | 'file';
+    title: string;
+    description: string;
+    sensitive?: boolean;
+    required?: boolean;
+    default?: unknown;
+    multiple?: boolean;
+}
+/** Claude theme configuration. */
+interface ClaudeThemeConfig {
+    name: string;
+    path: string;
+}
+/** Claude file monitor configuration. */
+interface ClaudeMonitorConfig {
+    pattern: string;
+    event: string;
+}
+/** Claude LSP server configuration. */
+interface ClaudeLSPServerConfig {
+    name: string;
+    command: string;
+    args?: string[];
+}
+/** Hook entry in Claude's hooks.json. */
+interface ClaudeHookEntry {
+    event: string;
+    matcher?: string;
+    handler: ClaudeHandlerConfig;
+}
+/** Handler configuration in hooks.json. */
+interface ClaudeHandlerConfig {
+    type: ClaudeHandlerType;
+    command?: string;
+    shell?: string;
+    statusMessage?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    mcpTool?: string;
+    mcpServer?: string;
+    prompt?: string;
+    agent?: string;
+}
+/**
+ * Create a Claude Code platform adapter.
+ *
+ * Usage:
+ * ```ts
+ * import { createAdapter } from '@agentplugins/adapter-claude';
+ * const adapter = createAdapter();
+ * const output = adapter.compile(manifest);
+ * ```
+ */
+declare function createClaudeAdapter(): PlatformAdapter;
+/** @deprecated Use createClaudeAdapter instead */
+declare function createAdapter(): PlatformAdapter;
+
+export { type ClaudeHandlerConfig, type ClaudeHookEntry, type ClaudeLSPServerConfig, type ClaudeMonitorConfig, type ClaudePluginManifest, type ClaudeThemeConfig, type ClaudeUserConfigField, createAdapter, createClaudeAdapter, createClaudeAdapter as default };

package/dist/index.d.ts

@@ -0,0 +1,120 @@
+import { PlatformAdapter } from '@agentplugins/core';
+
+/**
+ * AgentPlugins Claude Code Adapter
+ *
+ * Compiles universal AgentPlugins plugins into Claude Code's native plugin format.
+ *
+ * Claude Code uses:
+ *   - `.claude-plugin/plugin.json` — manifest
+ *   - `hooks/hooks.json` — hook configuration with matchers
+ *   - `skills/<name>/SKILL.md` — skill documentation (YAML frontmatter + markdown)
+ *   - `.mcp.json` — MCP server configurations
+ *   - `${CLAUDE_PLUGIN_ROOT}` and `${CLAUDE_PLUGIN_DATA}` — env var placeholders
+ *
+ * Handler mapping:
+ *   - command     → native command handler
+ *   - http        → native HTTP handler
+ *   - mcp_tool    → Claude's MCP tool handler (emitted in hooks.json)
+ *   - prompt      → Claude's prompt handler (emitted in hooks.json)
+ *   - agent       → Claude's agent handler (emitted in hooks.json)
+ *   - inline      → auto-wrapped as Node.js command script
+ *
+ * All 19 universal hooks are supported by Claude Code.
+ */
+
+/** Claude-specific handler types beyond the universal ones. */
+type ClaudeHandlerType = 'command' | 'http' | 'mcp_tool' | 'prompt' | 'agent';
+/** Claude plugin manifest shape. */
+interface ClaudePluginManifest {
+    name: string;
+    version: string;
+    description: string;
+    displayName?: string;
+    author?: string | {
+        name: string;
+        email?: string;
+        url?: string;
+    };
+    homepage?: string;
+    repository?: string;
+    license?: string;
+    keywords?: string[];
+    defaultEnabled?: boolean;
+    /** Claude-specific: plugin root directory env var */
+    root?: string;
+    /** Claude-specific: plugin data directory env var */
+    data?: string;
+    /** User configuration schema */
+    userConfig?: Record<string, ClaudeUserConfigField>;
+    /** Dependencies on other plugins */
+    dependencies?: string[];
+    /** Theme configuration */
+    themes?: ClaudeThemeConfig[];
+    /** File monitors */
+    monitors?: ClaudeMonitorConfig[];
+    /** LSP server configuration */
+    lspServers?: ClaudeLSPServerConfig[];
+    /** Extra metadata allowed by Claude */
+    [key: string]: unknown;
+}
+/** Claude user config field definition. */
+interface ClaudeUserConfigField {
+    type: 'string' | 'number' | 'boolean' | 'directory' | 'file';
+    title: string;
+    description: string;
+    sensitive?: boolean;
+    required?: boolean;
+    default?: unknown;
+    multiple?: boolean;
+}
+/** Claude theme configuration. */
+interface ClaudeThemeConfig {
+    name: string;
+    path: string;
+}
+/** Claude file monitor configuration. */
+interface ClaudeMonitorConfig {
+    pattern: string;
+    event: string;
+}
+/** Claude LSP server configuration. */
+interface ClaudeLSPServerConfig {
+    name: string;
+    command: string;
+    args?: string[];
+}
+/** Hook entry in Claude's hooks.json. */
+interface ClaudeHookEntry {
+    event: string;
+    matcher?: string;
+    handler: ClaudeHandlerConfig;
+}
+/** Handler configuration in hooks.json. */
+interface ClaudeHandlerConfig {
+    type: ClaudeHandlerType;
+    command?: string;
+    shell?: string;
+    statusMessage?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    mcpTool?: string;
+    mcpServer?: string;
+    prompt?: string;
+    agent?: string;
+}
+/**
+ * Create a Claude Code platform adapter.
+ *
+ * Usage:
+ * ```ts
+ * import { createAdapter } from '@agentplugins/adapter-claude';
+ * const adapter = createAdapter();
+ * const output = adapter.compile(manifest);
+ * ```
+ */
+declare function createClaudeAdapter(): PlatformAdapter;
+/** @deprecated Use createClaudeAdapter instead */
+declare function createAdapter(): PlatformAdapter;
+
+export { type ClaudeHandlerConfig, type ClaudeHookEntry, type ClaudeLSPServerConfig, type ClaudeMonitorConfig, type ClaudePluginManifest, type ClaudeThemeConfig, type ClaudeUserConfigField, createAdapter, createClaudeAdapter, createClaudeAdapter as default };

package/dist/index.js

@@ -0,0 +1,488 @@
+// src/index.ts
+import {
+  generateHookWrapper,
+  generateHandlersModule,
+  validateForPlatform,
+  Severity
+} from "@agentplugins/core";
+var CLAUDE_SUPPORTED_HOOKS = [
+  "sessionStart",
+  "sessionEnd",
+  "userPromptSubmit",
+  "userPromptExpansion",
+  "preToolUse",
+  "postToolUse",
+  "postToolUseFailure",
+  "permissionRequest",
+  "permissionDenied",
+  "subagentStart",
+  "subagentStop",
+  "preCompact",
+  "postCompact",
+  "stop",
+  "stopFailure",
+  "notification",
+  "fileChanged",
+  "cwdChanged",
+  "setup"
+];
+var CLAUDE_SUPPORTED_HANDLERS = [
+  "command",
+  "http",
+  "inline"
+  // auto-wrapped as command scripts
+];
+var HOOK_NAME_MAP = {
+  sessionStart: "SessionStart",
+  sessionEnd: "SessionEnd",
+  userPromptSubmit: "UserPromptSubmit",
+  userPromptExpansion: "UserPromptExpansion",
+  preToolUse: "PreToolUse",
+  postToolUse: "PostToolUse",
+  postToolUseFailure: "PostToolUseFailure",
+  permissionRequest: "PermissionRequest",
+  permissionDenied: "PermissionDenied",
+  subagentStart: "SubagentStart",
+  subagentStop: "SubagentStop",
+  preCompact: "PreCompact",
+  postCompact: "PostCompact",
+  stop: "Stop",
+  stopFailure: "StopFailure",
+  notification: "Notification",
+  fileChanged: "FileChanged",
+  cwdChanged: "CwdChanged",
+  setup: "Setup"
+};
+function createClaudeAdapter() {
+  return new ClaudePlatformAdapter();
+}
+function createAdapter() {
+  return createClaudeAdapter();
+}
+var ClaudePlatformAdapter = class {
+  name = "claude";
+  displayName = "Claude Code";
+  supportedHooks = CLAUDE_SUPPORTED_HOOKS;
+  supportedHandlers = CLAUDE_SUPPORTED_HANDLERS;
+  manifestPath = ".claude-plugin/plugin.json";
+  manifestFormat = "json";
+  // Inline handlers are wrapped as command scripts; tracks wrapper ID -> hook name
+  inlineWrappers = /* @__PURE__ */ new Map();
+  // ─── Validation ────────────────────────────────────────────────────────────
+  validate(plugin) {
+    const issues = [...validateForPlatform(plugin, "claude")];
+    if (plugin.hooks) {
+      for (const [name, def] of Object.entries(plugin.hooks)) {
+        const hookName = name;
+        if (!def) continue;
+        if (def.handler.type === "inline") {
+          const handler = def.handler;
+          if (typeof handler.handler !== "function") {
+            issues.push({
+              severity: Severity.ERROR,
+              field: `hooks.${hookName}.handler`,
+              message: "Inline handler must be a function"
+            });
+          } else {
+            issues.push({
+              severity: Severity.INFO,
+              field: `hooks.${hookName}.handler`,
+              message: "Inline handler will be auto-wrapped as a Claude command script",
+              suggestion: 'For better performance, use a "command" or "http" handler'
+            });
+          }
+        }
+        if (def.matcher && ["preToolUse", "postToolUse", "postToolUseFailure"].includes(hookName)) {
+          if (def.matcher.includes("*") && !def.matcher.match(/^\*?\w+\*?$/)) {
+            issues.push({
+              severity: Severity.WARNING,
+              field: `hooks.${hookName}.matcher`,
+              message: `Matcher pattern "${def.matcher}" may not be supported by Claude for tool hooks`,
+              suggestion: 'Use simple patterns like "toolName", "prefix*", or "*suffix"'
+            });
+          }
+        }
+      }
+    }
+    if (plugin.mcpServers) {
+      for (const [serverName, config] of Object.entries(plugin.mcpServers)) {
+        if (!config.command) {
+          issues.push({
+            severity: Severity.ERROR,
+            field: `mcpServers.${serverName}.command`,
+            message: `MCP server "${serverName}" requires a command`
+          });
+        }
+        if (config.transport && config.transport !== "stdio" && config.transport !== "http") {
+          issues.push({
+            severity: Severity.WARNING,
+            field: `mcpServers.${serverName}.transport`,
+            message: `Transport "${config.transport}" may not be supported by Claude MCP`,
+            suggestion: 'Use "stdio" (default) or "http"'
+          });
+        }
+      }
+    }
+    if (plugin.skills) {
+      for (let i = 0; i < plugin.skills.length; i++) {
+        const skill = plugin.skills[i];
+        if (skill.content && skill.filePath) {
+          issues.push({
+            severity: Severity.WARNING,
+            field: `skills[${i}]`,
+            message: `Skill "${skill.name}" has both content and filePath \u2014 content takes precedence`
+          });
+        }
+      }
+    }
+    if (plugin.userConfig) {
+      const supportedTypes = ["string", "number", "boolean", "directory", "file"];
+      for (const [key, opt] of Object.entries(plugin.userConfig)) {
+        if (!supportedTypes.includes(opt.type)) {
+          issues.push({
+            severity: Severity.WARNING,
+            field: `userConfig.${key}.type`,
+            message: `User config type "${opt.type}" may not be fully supported by Claude`,
+            suggestion: `Supported types: ${supportedTypes.join(", ")}`
+          });
+        }
+      }
+    }
+    return issues;
+  }
+  // ─── Compilation ───────────────────────────────────────────────────────────
+  compile(plugin) {
+    this.inlineWrappers.clear();
+    const files = [];
+    const warnings = [];
+    const postInstall = [];
+    const claudeManifest = this.buildManifest(plugin);
+    const hooksConfig = this.buildHooksConfig(plugin);
+    if (hooksConfig.length > 0) {
+      files.push({
+        path: "hooks/hooks.json",
+        content: JSON.stringify(hooksConfig, null, 2)
+      });
+    }
+    const inlineHandlers = this.extractInlineHandlers(plugin);
+    if (inlineHandlers.size > 0) {
+      const handlersModule = generateHandlersModule(inlineHandlers);
+      files.push({
+        path: "hooks/__agentplugins_handlers__.js",
+        content: handlersModule
+      });
+      for (const [wrapperId, { hookName }] of this.inlineWrappers.entries()) {
+        const wrapperScript = generateHookWrapper("./__agentplugins_handlers__.js", {
+          platform: "claude",
+          hookName,
+          wrapperId
+        });
+        files.push({
+          path: `hooks/${wrapperId}.js`,
+          content: wrapperScript
+        });
+      }
+      warnings.push(
+        `${inlineHandlers.size} inline handler(s) wrapped as command scripts. These require Node.js at runtime.`
+      );
+    }
+    if (plugin.skills && plugin.skills.length > 0) {
+      for (const skill of plugin.skills) {
+        const skillContent = this.buildSkillFile(skill);
+        const skillPath = `skills/${skill.name}/SKILL.md`;
+        files.push({
+          path: skillPath,
+          content: skillContent
+        });
+      }
+    }
+    if (plugin.mcpServers && Object.keys(plugin.mcpServers).length > 0) {
+      const mcpConfig = this.buildMCPConfig(plugin);
+      files.push({
+        path: ".mcp.json",
+        content: JSON.stringify(mcpConfig, null, 2)
+      });
+    }
+    const envScript = this.buildEnvScript(plugin);
+    if (envScript) {
+      files.push({
+        path: "hooks/__env__.sh",
+        content: envScript
+      });
+    }
+    postInstall.push(
+      `Copy the generated files to your Claude Code project root:`,
+      `  cp -r .claude-plugin hooks/ skills/ .mcp.json <your-project>/`,
+      ``,
+      `Environment variables available at runtime:`,
+      `  \${CLAUDE_PLUGIN_ROOT} \u2014 path to the plugin directory`,
+      `  \${CLAUDE_PLUGIN_DATA}  \u2014 path to plugin data storage`,
+      ``,
+      `Install location: ~/.claude/plugins/ or project-local .claude-plugin/`
+    );
+    if (inlineHandlers.size > 0) {
+      postInstall.push(
+        ``,
+        `NOTE: ${inlineHandlers.size} inline handler(s) require Node.js to execute.`,
+        `      Wrapper scripts are in hooks/*.js`
+      );
+    }
+    return {
+      files,
+      manifest: claudeManifest,
+      warnings,
+      issues: [],
+      postInstall: postInstall.length > 0 ? postInstall : void 0
+    };
+  }
+  // ─── Internal Helpers ──────────────────────────────────────────────────────
+  /**
+   * Build the Claude plugin.json manifest from a universal plugin manifest.
+   */
+  buildManifest(plugin) {
+    const manifest = {
+      name: plugin.name,
+      version: plugin.version,
+      description: plugin.description,
+      displayName: plugin.displayName,
+      author: plugin.author,
+      homepage: plugin.homepage,
+      repository: plugin.repository,
+      license: plugin.license,
+      keywords: plugin.keywords,
+      defaultEnabled: plugin.defaultEnabled ?? true,
+      root: "${CLAUDE_PLUGIN_ROOT}",
+      data: "${CLAUDE_PLUGIN_DATA}"
+    };
+    if (plugin.userConfig) {
+      manifest.userConfig = Object.fromEntries(
+        Object.entries(plugin.userConfig).map(([key, opt]) => [
+          key,
+          {
+            type: opt.type,
+            title: opt.title,
+            description: opt.description,
+            sensitive: opt.sensitive,
+            required: opt.required,
+            default: opt.default,
+            multiple: opt.multiple
+          }
+        ])
+      );
+    }
+    if (plugin.dependencies) {
+      manifest.dependencies = plugin.dependencies;
+    }
+    if (plugin.themes) {
+      manifest.themes = plugin.themes;
+    }
+    if (plugin.monitors) {
+      manifest.monitors = plugin.monitors;
+    }
+    if (plugin.lspServers) {
+      manifest.lspServers = plugin.lspServers;
+    }
+    return manifest;
+  }
+  /**
+   * Build the hooks.json configuration from universal hooks.
+   */
+  buildHooksConfig(plugin) {
+    if (!plugin.hooks) return [];
+    const entries = [];
+    for (const [name, def] of Object.entries(plugin.hooks)) {
+      const hookName = name;
+      if (!def) continue;
+      if (!this.supportedHooks.includes(hookName)) continue;
+      const claudeEvent = HOOK_NAME_MAP[hookName];
+      const handlerConfig = this.buildHandlerConfig(def, hookName);
+      if (handlerConfig) {
+        const entry = {
+          event: claudeEvent,
+          handler: handlerConfig
+        };
+        if (def.matcher) {
+          entry.matcher = def.matcher;
+        } else if (hookName === "preToolUse" || hookName === "postToolUse" || hookName === "postToolUseFailure") {
+          entry.matcher = "*";
+        }
+        entries.push(entry);
+      }
+    }
+    return entries;
+  }
+  /**
+   * Build a single handler configuration for hooks.json.
+   */
+  buildHandlerConfig(def, hookName) {
+    const handler = def.handler;
+    switch (handler.type) {
+      case "command": {
+        return {
+          type: "command",
+          command: handler.command,
+          shell: handler.shell,
+          statusMessage: handler.statusMessage
+        };
+      }
+      case "http": {
+        return {
+          type: "http",
+          url: handler.url,
+          headers: handler.headers
+        };
+      }
+      case "inline": {
+        const wrapperId = `__inline_${hookName}_${this.hashId(hookName)}`;
+        this.inlineWrappers.set(wrapperId, { hookName });
+        return {
+          type: "command",
+          command: `node "\${CLAUDE_PLUGIN_ROOT}/hooks/${wrapperId}.js"`,
+          shell: "bash",
+          statusMessage: `Running ${hookName} hook...`
+        };
+      }
+      default: {
+        const unknownHandler = handler;
+        if (unknownHandler.type === "mcp_tool") {
+          return {
+            type: "mcp_tool",
+            mcpTool: unknownHandler.mcpTool || unknownHandler.tool,
+            mcpServer: unknownHandler.mcpServer || unknownHandler.server
+          };
+        }
+        if (unknownHandler.type === "prompt") {
+          return {
+            type: "prompt",
+            prompt: unknownHandler.prompt
+          };
+        }
+        if (unknownHandler.type === "agent") {
+          return {
+            type: "agent",
+            agent: unknownHandler.agent
+          };
+        }
+        return null;
+      }
+    }
+  }
+  /**
+   * Build a SKILL.md file with YAML frontmatter from a universal skill definition.
+   */
+  buildSkillFile(skill) {
+    const frontmatter = {
+      name: skill.name,
+      description: skill.description
+    };
+    if (skill.filePath && !skill.content) {
+      frontmatter.source = skill.filePath;
+    }
+    const yamlLines = Object.entries(frontmatter).map(([key, value]) => {
+      if (typeof value === "string") {
+        if (value.includes(":") || value.includes("#") || value.includes('"')) {
+          return `${key}: "${value.replace(/"/g, '\\"')}"`;
+        }
+        return `${key}: ${value}`;
+      }
+      return `${key}: ${value}`;
+    }).join("\n");
+    const frontmatterBlock = `---
+${yamlLines}
+---
+`;
+    if (skill.content) {
+      if (skill.content.trimStart().startsWith("---")) {
+        return skill.content;
+      }
+      return frontmatterBlock + "\n" + skill.content;
+    }
+    if (skill.filePath) {
+      return frontmatterBlock + `
+# ${skill.name}
+
+See [${skill.filePath}](${skill.filePath}) for the full skill documentation.
+`;
+    }
+    return frontmatterBlock + `
+# ${skill.name}
+
+${skill.description}
+`;
+  }
+  /**
+   * Build the .mcp.json configuration from universal MCP server definitions.
+   */
+  buildMCPConfig(plugin) {
+    if (!plugin.mcpServers) return {};
+    const servers = {};
+    for (const [serverName, config] of Object.entries(plugin.mcpServers)) {
+      servers[serverName] = {
+        command: config.command,
+        args: config.args ?? [],
+        env: config.env ?? {},
+        // Claude uses 'stdio' by default
+        transport: config.transport ?? "stdio"
+      };
+    }
+    return { servers };
+  }
+  /**
+   * Extract inline handlers that need wrapping, returning a map suitable
+   * for generateHandlersModule().
+   */
+  extractInlineHandlers(plugin) {
+    const handlers = /* @__PURE__ */ new Map();
+    if (!plugin.hooks) return handlers;
+    for (const [name, def] of Object.entries(plugin.hooks)) {
+      const hookName = name;
+      if (!def || def.handler.type !== "inline") continue;
+      const inlineHandler = def.handler;
+      if (typeof inlineHandler.handler === "function") {
+        const wrapperId = `__inline_${hookName}_${this.hashId(hookName)}`;
+        handlers.set(wrapperId, inlineHandler.handler);
+      }
+    }
+    return handlers;
+  }
+  /**
+   * Build an environment setup script that exports CLAUDE_PLUGIN_ROOT and
+   * CLAUDE_PLUGIN_DATA for use by hook scripts.
+   */
+  buildEnvScript(plugin) {
+    if (!plugin.hooks) return null;
+    const hasCommandHandlers = Object.values(plugin.hooks).some(
+      (def) => def?.handler.type === "command" || def?.handler.type === "inline"
+    );
+    if (!hasCommandHandlers) return null;
+    return `#!/usr/bin/env bash
+# AgentPlugins Auto-Generated Environment Setup for Claude Code
+# Plugin: ${plugin.name}
+# DO NOT EDIT \u2014 This file is regenerated on each build.
+
+# Resolve plugin root relative to this script
+export CLAUDE_PLUGIN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+export CLAUDE_PLUGIN_DATA="\${CLAUDE_PLUGIN_ROOT}/.data"
+
+# Ensure data directory exists
+mkdir -p "\${CLAUDE_PLUGIN_DATA}"
+`;
+  }
+  /**
+   * Generate a short hash for a hook name to use in wrapper script filenames.
+   */
+  hashId(input) {
+    let hash = 0;
+    for (let i = 0; i < input.length; i++) {
+      const char = input.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash |= 0;
+    }
+    return Math.abs(hash).toString(36).slice(0, 6);
+  }
+};
+export {
+  createAdapter,
+  createClaudeAdapter,
+  createClaudeAdapter as default
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@agentplugins/adapter-claude",
+  "version": "0.1.0",
+  "description": "AgentPlugins platform adapter for Claude Code",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@agentplugins/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}