@agentplugins/adapter-copilot 0.1.0

package/dist/index.mjs

@@ -0,0 +1,593 @@
+// src/index.ts
+import {
+  Severity
+} from "@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(
+      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(
+        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(
+            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(
+            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(
+            Severity.ERROR,
+            `Command handler must specify "script" or "command".`,
+            `${handlerPath}.config`
+          )
+        );
+      }
+      break;
+    }
+    case "http": {
+      const httpCfg = handler.config;
+      if (!httpCfg.url) {
+        issues.push(
+          issue(
+            Severity.ERROR,
+            `HTTP handler must specify "url".`,
+            `${handlerPath}.config.url`
+          )
+        );
+      }
+      if (httpCfg.method && httpCfg.method.toUpperCase() !== "POST") {
+        issues.push(
+          issue(
+            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(
+            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(
+            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(
+          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(
+        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(
+          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(
+              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(
+              Severity.ERROR,
+              `Skill at index ${i} is missing a "name".`,
+              `${skillPath}.name`
+            )
+          );
+        }
+        if (!skill.description || skill.description.trim() === "") {
+          issues.push(
+            issue(
+              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(
+                  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(
+            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();
+}
+export {
+  CopilotAdapter,
+  copilotAdapter,
+  createCopilotAdapter
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@agentplugins/adapter-copilot",
+  "version": "0.1.0",
+  "description": "GitHub Copilot CLI platform adapter for AgentPlugins — compiles AgentPlugins plugins into Copilot-compatible manifests, hooks, skills, and MCP configuration",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/**/*.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@agentplugins/core": "workspace:*"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/espetro/agentplugins.git",
+    "directory": "packages/adapter-copilot"
+  },
+  "keywords": [
+    "agentplugins",
+    "github-copilot",
+    "copilot-cli",
+    "plugin-adapter",
+    "ai-agent",
+    "mcp"
+  ]
+}