@agentplugins/adapter-copilot 0.1.0

package/dist/index.js

@@ -0,0 +1,618 @@
+"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, {
+  CopilotAdapter: () => CopilotAdapter,
+  copilotAdapter: () => copilotAdapter,
+  createCopilotAdapter: () => createCopilotAdapter
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@agentplugins/core");
+var PLATFORM_NAME = "copilot";
+var DISPLAY_NAME = "GitHub Copilot CLI";
+var MANIFEST_PATH = "plugin.json";
+var MANIFEST_FORMAT = "json";
+var SUPPORTED_HOOKS = [
+  "sessionStart",
+  "sessionEnd",
+  "userPromptSubmit",
+  "preToolUse",
+  "postToolUse",
+  "postToolUseFailure",
+  "permissionRequest",
+  "subagentStart",
+  "subagentStop",
+  "preCompact",
+  "notification"
+];
+var SUPPORTED_HANDLERS = ["command", "http", "prompt"];
+var HOOK_MAP = {
+  sessionStart: "sessionStart",
+  sessionEnd: "sessionEnd",
+  userPromptSubmit: "userPromptSubmitted",
+  preToolUse: "preToolUse",
+  postToolUse: "postToolUse",
+  postToolUseFailure: "postToolUseFailure",
+  permissionRequest: "permissionRequest",
+  subagentStart: "subagentStart",
+  subagentStop: "agentStop",
+  // Copilot has no subagentStop; agentStop is closest
+  preCompact: "preCompact",
+  notification: "notification",
+  // Explicitly unsupported hooks
+  userPromptExpansion: void 0,
+  permissionDenied: void 0,
+  postCompact: void 0,
+  stop: void 0,
+  stopFailure: void 0,
+  fileChanged: void 0,
+  cwdChanged: void 0,
+  setup: void 0
+};
+var FIRE_AND_FORGET_HOOKS = ["notification"];
+var FAIL_CLOSED_HOOKS = ["preToolUse"];
+var MAX_HOOK_TIMEOUT_SECONDS = 30;
+var MAX_ADDITIONAL_CONTEXT_BYTES = 10 * 1024;
+var PROMPT_ALLOWED_HOOK = "sessionStart";
+function byteSize(value) {
+  try {
+    return new globalThis.TextEncoder().encode(JSON.stringify(value)).length;
+  } catch {
+    return 0;
+  }
+}
+function issue(severity, message, field) {
+  return { severity, message, field };
+}
+function checkUnsupportedHook(hook, path) {
+  const mapped = HOOK_MAP[hook];
+  if (mapped === void 0) {
+    return issue(
+      import_core.Severity.ERROR,
+      `Hook "${hook}" is not supported by the Copilot CLI platform. Supported hooks: ${SUPPORTED_HOOKS.map((h) => `"${h}"`).join(", ")}.`,
+      path
+    );
+  }
+  return void 0;
+}
+function validateHandler(handler, hookName, path) {
+  const issues = [];
+  const handlerPath = `${path}.handler`;
+  if (!SUPPORTED_HANDLERS.includes(handler.type)) {
+    issues.push(
+      issue(
+        import_core.Severity.ERROR,
+        `Handler type "${handler.type}" is not supported by Copilot CLI. Supported types: ${SUPPORTED_HANDLERS.map((t) => `"${t}"`).join(", ")}.`,
+        handlerPath
+      )
+    );
+    return issues;
+  }
+  switch (handler.type) {
+    case "command": {
+      const cmd = handler.config;
+      if (!cmd.shell) {
+        issues.push(
+          issue(
+            import_core.Severity.ERROR,
+            `Command handler must specify "shell" (e.g. "bash" or "powershell").`,
+            `${handlerPath}.config.shell`
+          )
+        );
+      } else if (!["bash", "powershell"].includes(cmd.shell)) {
+        issues.push(
+          issue(
+            import_core.Severity.WARNING,
+            `Shell "${cmd.shell}" may not be supported by all Copilot CLI environments. Recommended: "bash" or "powershell".`,
+            `${handlerPath}.config.shell`
+          )
+        );
+      }
+      if (!cmd.script && !cmd.command) {
+        issues.push(
+          issue(
+            import_core.Severity.ERROR,
+            `Command handler must specify "script" or "command".`,
+            `${handlerPath}.config`
+          )
+        );
+      }
+      break;
+    }
+    case "http": {
+      const httpCfg = handler.config;
+      if (!httpCfg.url) {
+        issues.push(
+          issue(
+            import_core.Severity.ERROR,
+            `HTTP handler must specify "url".`,
+            `${handlerPath}.config.url`
+          )
+        );
+      }
+      if (httpCfg.method && httpCfg.method.toUpperCase() !== "POST") {
+        issues.push(
+          issue(
+            import_core.Severity.ERROR,
+            `Copilot CLI only supports POST for HTTP handlers. Found method: "${httpCfg.method}".`,
+            `${handlerPath}.config.method`
+          )
+        );
+      }
+      break;
+    }
+    case "prompt": {
+      if (hookName !== PROMPT_ALLOWED_HOOK) {
+        issues.push(
+          issue(
+            import_core.Severity.ERROR,
+            `Prompt handler type is only allowed for the "${PROMPT_ALLOWED_HOOK}" hook. Hook "${hookName}" cannot use a prompt handler.`,
+            handlerPath
+          )
+        );
+      }
+      const promptCfg = handler.config;
+      if (!promptCfg.template) {
+        issues.push(
+          issue(
+            import_core.Severity.ERROR,
+            `Prompt handler must specify a "template".`,
+            `${handlerPath}.config.template`
+          )
+        );
+      }
+      break;
+    }
+  }
+  return issues;
+}
+function validateHookConstraints(hook, hookName, path) {
+  const issues = [];
+  const copilotHook = hook;
+  if (copilotHook.additionalContext) {
+    const size = byteSize(copilotHook.additionalContext);
+    if (size > MAX_ADDITIONAL_CONTEXT_BYTES) {
+      issues.push(
+        issue(
+          import_core.Severity.ERROR,
+          `additionalContext exceeds ${MAX_ADDITIONAL_CONTEXT_BYTES} bytes (${size} bytes found). Reduce the size of data passed to hooks.`,
+          `${path}.additionalContext`
+        )
+      );
+    }
+  }
+  if (copilotHook.timeout !== void 0 && copilotHook.timeout > MAX_HOOK_TIMEOUT_SECONDS) {
+    issues.push(
+      issue(
+        import_core.Severity.ERROR,
+        `Hook timeout (${copilotHook.timeout}s) exceeds the Copilot CLI maximum of ${MAX_HOOK_TIMEOUT_SECONDS}s.`,
+        `${path}.timeout`
+      )
+    );
+  }
+  if (hookName === "preToolUse") {
+    const cfg = hook.handler?.config;
+    if (!cfg?.matcher?.field || !cfg?.matcher?.value) {
+      issues.push(
+        issue(
+          import_core.Severity.WARNING,
+          `preToolUse hooks should specify a matcher (e.g. toolName: "Bash") to avoid intercepting every tool call. Without a matcher, the hook runs for ALL tools and errors will deny them (fail-closed behavior).`,
+          `${path}.handler.config.matcher`
+        )
+      );
+    }
+  }
+  return issues;
+}
+function compileSkill(skill) {
+  const copilotSkill = skill;
+  const descriptor = {
+    name: skill.name,
+    description: skill.description,
+    parameters: copilotSkill.parameters?.map((p) => ({
+      name: p.name,
+      type: p.type,
+      description: p.description,
+      required: p.required
+    })),
+    examples: copilotSkill.examples
+  };
+  const skillDir = `skills/${skill.name}`;
+  let md = `# ${skill.name}
+
+`;
+  md += `${skill.description}
+
+`;
+  if (descriptor.parameters && descriptor.parameters.length > 0) {
+    md += `## Parameters
+
+`;
+    md += `| Name | Type | Required | Description |
+`;
+    md += `|------|------|----------|-------------|
+`;
+    for (const p of descriptor.parameters) {
+      md += `| ${p.name} | ${p.type} | ${p.required ? "Yes" : "No"} | ${p.description ?? ""} |
+`;
+    }
+    md += `
+`;
+  }
+  if (descriptor.examples && descriptor.examples.length > 0) {
+    md += `## Examples
+
+`;
+    for (const ex of descriptor.examples) {
+      md += `\`\`\`
+${ex}
+\`\`\`
+
+`;
+    }
+  }
+  md += `## Metadata
+
+`;
+  md += `\`\`\`json
+${JSON.stringify(descriptor, null, 2)}
+\`\`\`
+`;
+  return { descriptor, skillDir, skillMdContent: md };
+}
+function compileHookEntry(hookName, hook) {
+  const handler = hook.handler;
+  const copilotEvent = HOOK_MAP[hookName];
+  const entry = {
+    event: copilotEvent,
+    type: handler.type,
+    handler: ""
+  };
+  switch (handler.type) {
+    case "command": {
+      const cfg = handler.config;
+      entry.handler = cfg.script ?? cfg.command ?? "";
+      break;
+    }
+    case "http": {
+      const cfg = handler.config;
+      entry.handler = cfg.url;
+      break;
+    }
+    case "prompt": {
+      const cfg = handler.config;
+      entry.handler = cfg.template;
+      break;
+    }
+  }
+  const matcher = handler.config?.matcher;
+  if (matcher?.field && matcher?.value) {
+    entry.matcher = {
+      field: matcher.field,
+      value: matcher.value
+    };
+  }
+  if (FIRE_AND_FORGET_HOOKS.includes(copilotEvent)) {
+    entry.awaitResponse = false;
+  }
+  const copilotHook = hook;
+  const timeout = copilotHook.timeout ?? MAX_HOOK_TIMEOUT_SECONDS;
+  entry.timeout = Math.min(timeout, MAX_HOOK_TIMEOUT_SECONDS);
+  if (FAIL_CLOSED_HOOKS.includes(copilotEvent)) {
+    entry.failClosed = true;
+  }
+  return entry;
+}
+var CopilotAdapter = class {
+  /** Platform identifier. */
+  name = PLATFORM_NAME;
+  /** Human-readable display name. */
+  displayName = DISPLAY_NAME;
+  /** Universal hooks supported by this adapter. */
+  supportedHooks = SUPPORTED_HOOKS;
+  /** Handler types understood by Copilot CLI. */
+  supportedHandlers = SUPPORTED_HANDLERS;
+  /** Path to the generated manifest file. */
+  manifestPath = MANIFEST_PATH;
+  /** Manifest format (JSON). */
+  manifestFormat = MANIFEST_FORMAT;
+  /**
+   * Validate a {@link PluginManifest} for Copilot CLI compatibility.
+   *
+   * Checks performed:
+   * 1. Only supported hooks are referenced.
+   * 2. Handler types are within the supported set.
+   * 3. Command handlers specify shell (bash/powershell) and script/command.
+   * 4. HTTP handlers use POST (the only method Copilot sends).
+   * 5. Prompt handlers are only used on `sessionStart`.
+   * 6. additionalContext does not exceed 10 KB.
+   * 7. Hook timeouts do not exceed 30 seconds.
+   * 8. preToolUse hooks are encouraged to specify a matcher.
+   * 9. All referenced skills have required fields (name, description).
+   *
+   * @param plugin – the plugin manifest to validate
+   * @returns array of validation issues (empty if fully valid)
+   */
+  validate(plugin) {
+    const issues = [];
+    if (plugin.hooks) {
+      for (const [hookName, hookDef] of Object.entries(plugin.hooks)) {
+        const hookPath = `hooks.${hookName}`;
+        const uHook = hookName;
+        const unsupported = checkUnsupportedHook(uHook, hookPath);
+        if (unsupported) {
+          issues.push(unsupported);
+          continue;
+        }
+        if (hookDef.handler) {
+          issues.push(
+            ...validateHandler(
+              hookDef.handler,
+              uHook,
+              hookPath
+            )
+          );
+        } else {
+          issues.push(
+            issue(
+              import_core.Severity.ERROR,
+              `Hook "${hookName}" is missing a handler definition.`,
+              hookPath
+            )
+          );
+        }
+        issues.push(...validateHookConstraints(hookDef, uHook, hookPath));
+      }
+    }
+    if (plugin.skills) {
+      for (let i = 0; i < plugin.skills.length; i++) {
+        const skill = plugin.skills[i];
+        const skillPath = `skills[${i}]`;
+        if (!skill.name || skill.name.trim() === "") {
+          issues.push(
+            issue(
+              import_core.Severity.ERROR,
+              `Skill at index ${i} is missing a "name".`,
+              `${skillPath}.name`
+            )
+          );
+        }
+        if (!skill.description || skill.description.trim() === "") {
+          issues.push(
+            issue(
+              import_core.Severity.ERROR,
+              `Skill "${skill.name ?? `#${i}`}" is missing a "description".`,
+              `${skillPath}.description`
+            )
+          );
+        }
+        const copilotSkill = skill;
+        if (copilotSkill.parameters) {
+          const validTypes = ["string", "number", "boolean", "object", "array"];
+          for (let j = 0; j < copilotSkill.parameters.length; j++) {
+            const p = copilotSkill.parameters[j];
+            if (!validTypes.includes(p.type)) {
+              issues.push(
+                issue(
+                  import_core.Severity.WARNING,
+                  `Parameter "${p.name}" has type "${p.type}" which may not be recognised by Copilot CLI. Valid types: ${validTypes.join(", ")}.`,
+                  `${skillPath}.parameters[${j}].type`
+                )
+              );
+            }
+          }
+        }
+      }
+    }
+    if (plugin.hooks?.preToolUse) {
+      const preToolHandler = plugin.hooks.preToolUse.handler;
+      const matcher = preToolHandler?.config?.matcher;
+      if (!matcher) {
+        issues.push(
+          issue(
+            import_core.Severity.WARNING,
+            `Plugin defines a "preToolUse" hook without a matcher. This will intercept ALL tool calls and any error will deny them (fail-closed). Consider adding a matcher like { field: "toolName", value: "Bash" }.`,
+            `hooks.preToolUse.handler.config.matcher`
+          )
+        );
+      }
+    }
+    return issues;
+  }
+  /**
+   * Compile a {@link PluginManifest} into the Copilot CLI file layout.
+   *
+   * Produces:
+   * - `plugin.json` – top-level manifest with metadata and file references
+   * - `hooks.json`  – hook bindings mapped to Copilot event names
+   * - `skills/<name>/SKILL.md` – one file per skill
+   * - `.mcp.json`   – MCP server configuration (if MCP servers are defined)
+   *
+   * @param plugin – the validated plugin manifest
+   * @returns {@link AdapterOutput} containing all generated files
+   */
+  compile(plugin) {
+    const files = [];
+    const warnings = [];
+    const hookEntries = [];
+    if (plugin.hooks) {
+      for (const [hookName, hookDef] of Object.entries(plugin.hooks)) {
+        const uHook = hookName;
+        if (!SUPPORTED_HOOKS.includes(uHook)) {
+          warnings.push(
+            `Skipping unsupported hook "${hookName}" during compilation.`
+          );
+          continue;
+        }
+        const handler = hookDef.handler;
+        if (handler.type === "prompt") {
+          const entry = compileHookEntry(uHook, hookDef);
+          hookEntries.push(entry);
+        } else {
+          const entry = compileHookEntry(uHook, hookDef);
+          if (handler.type === "command") {
+            const cfg = handler.config;
+            const scriptName = `hook-${hookName}.${cfg.shell === "powershell" ? "ps1" : "sh"}`;
+            const scriptContent = generateWrapperScript(cfg);
+            files.push({
+              path: scriptName,
+              content: scriptContent
+            });
+            entry.handler = `./${scriptName}`;
+          }
+          hookEntries.push(entry);
+        }
+      }
+    }
+    if (hookEntries.length > 0) {
+      files.push({
+        path: "hooks.json",
+        content: JSON.stringify(hookEntries, null, 2)
+      });
+    }
+    const skillDirs = [];
+    if (plugin.skills && plugin.skills.length > 0) {
+      for (const skill of plugin.skills) {
+        const { skillDir, skillMdContent } = compileSkill(skill);
+        skillDirs.push(skillDir);
+        files.push({
+          path: `${skillDir}/SKILL.md`,
+          content: skillMdContent
+        });
+      }
+    }
+    const mcpConfig = this.buildMcpConfig(plugin);
+    if (mcpConfig) {
+      files.push({
+        path: ".mcp.json",
+        content: JSON.stringify(mcpConfig, null, 2)
+      });
+    }
+    const copilotPlugin = plugin;
+    const copilotManifest = {
+      schemaVersion: "1.0",
+      id: copilotPlugin.id ?? copilotPlugin.name,
+      name: copilotPlugin.name,
+      description: copilotPlugin.description,
+      version: copilotPlugin.version,
+      strict: copilotPlugin.strict ?? true,
+      maxAdditionalContextBytes: MAX_ADDITIONAL_CONTEXT_BYTES,
+      hookTimeoutSeconds: MAX_HOOK_TIMEOUT_SECONDS,
+      author: typeof copilotPlugin.author === "string" ? copilotPlugin.author : copilotPlugin.author?.name,
+      homepage: copilotPlugin.homepage,
+      license: copilotPlugin.license,
+      tags: copilotPlugin.tags ?? copilotPlugin.keywords ?? void 0,
+      ...hookEntries.length > 0 && { hooks: "hooks.json" },
+      ...skillDirs.length > 0 && { skills: skillDirs },
+      ...mcpConfig && { mcp: ".mcp.json" }
+    };
+    files.unshift({
+      path: MANIFEST_PATH,
+      content: JSON.stringify(copilotManifest, null, 2)
+    });
+    return {
+      files,
+      manifest: copilotManifest,
+      warnings: warnings.length > 0 ? warnings : [],
+      issues: []
+    };
+  }
+  /**
+   * Build an MCP server configuration object from the plugin manifest.
+   *
+   * If the plugin defines MCP servers (in `plugin.mcpServers`), they are
+   * converted into Copilot's `.mcp.json` format.
+   *
+   * @param plugin – the plugin manifest
+   * @returns MCP config object, or `null` if no MCP servers are defined
+   */
+  buildMcpConfig(plugin) {
+    const servers = plugin.mcpServers;
+    if (!servers || servers.length === 0) {
+      return null;
+    }
+    return {
+      schemaVersion: "1.0",
+      servers: servers.map((s) => ({
+        id: s.id,
+        name: s.name,
+        transport: s.transport,
+        ...s.command && { command: s.command },
+        ...s.args && { args: s.args },
+        ...s.url && { url: s.url },
+        ...s.env && { env: s.env }
+      }))
+    };
+  }
+};
+function generateWrapperScript(cfg) {
+  const scriptBody = cfg.script ?? cfg.command ?? "";
+  if (cfg.shell === "powershell") {
+    return `
+# Auto-generated Copilot CLI hook wrapper
+param(
+    [Parameter(ValueFromPipeline = $true)]
+    [string]$Payload
+)
+
+# Read payload from stdin if not provided as argument
+if (-not $Payload) {
+    $Payload = $input | Out-String
+}
+
+# Parse JSON payload
+$HookData = $Payload | ConvertFrom-Json -ErrorAction SilentlyContinue
+
+# TODO: export relevant fields as environment variables if needed
+# $env:COPILOT_TOOL_NAME = $HookData.toolName
+
+# Execute user script
+${scriptBody}
+`.trim();
+  }
+  return `#!/usr/bin/env bash
+# Auto-generated Copilot CLI hook wrapper
+
+set -euo pipefail
+
+# Read JSON payload from stdin
+PAYLOAD="$(cat)"
+
+# Parse payload with jq if available; otherwise pass through raw
+if command -v jq &> /dev/null; then
+    TOOL_NAME="$(echo "$PAYLOAD" | jq -r '.toolName // empty')"
+    export COPILOT_TOOL_NAME="\${TOOL_NAME:-}"
+fi
+
+# Execute user script
+${scriptBody}
+`.trim();
+}
+var copilotAdapter = new CopilotAdapter();
+function createCopilotAdapter() {
+  return new CopilotAdapter();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CopilotAdapter,
+  copilotAdapter,
+  createCopilotAdapter
+});