@agentplugins/adapter-copilot 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @agentplugins/adapter-copilot
+
+> AgentPlugins platform adapter for [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing).
+
+Compiles a universal `PluginManifest` into the Copilot CLI plugin layout: `plugin.json` manifest, `hooks.json` hook wiring, and MCP server configuration. Inline handlers are wrapped as command scripts that the host invokes.
+
+## Installation
+
+```bash
+npm install @agentplugins/adapter-copilot
+```
+
+Typically installed transitively via [`@agentplugins/cli`](https://www.npmjs.com/package/@agentplugins/cli).
+
+## Usage
+
+```typescript
+import { createCopilotAdapter } from '@agentplugins/adapter-copilot';
+
+const adapter = createCopilotAdapter();
+const output = await adapter.compile(manifest);
+```
+
+Or via the CLI:
+
+```bash
+npx agentplugins build --target copilot
+```
+
+## Output shape
+
+A successful build writes to `dist/copilot/`:
+
+```
+dist/copilot/
+├── plugin.json
+├── hooks/
+│   └── hooks.json
+└── .mcp.json
+```
+
+Install with: `copilot plugin install ./dist/copilot`
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,238 @@
+import { PlatformAdapter, TargetPlatform, UniversalHookName, HandlerType, PluginManifest, ValidationIssue, AdapterOutput } from '@agentplugins/core';
+
+/**
+ * @agentplugins/adapter-copilot
+ *
+ * GitHub Copilot CLI platform adapter for the AgentPlugins plugin system.
+ *
+ * This adapter compiles AgentPlugins {@link PluginManifest} objects into the
+ * multi-file layout expected by the Copilot CLI runtime:
+ *
+ *   - plugin.json          – top-level manifest (strict validation, metadata)
+ *   - hooks.json           – hook bindings with optional matcher filters
+ *   - skills/<name>/SKILL.md – declarative skill documentation
+ *   - .mcp.json            – MCP server configuration (when applicable)
+ *
+ * ## Supported hooks (11 / 20 universal hooks)
+ * Copilot supports 13 binding points; we map 11 distinct universal hooks to
+ * them.  The remaining 9 universal hooks are explicitly unsupported.
+ *
+ * | Universal hook        | Copilot event         | Notes |
+ * |-----------------------|-----------------------|-------|
+ * | sessionStart          | sessionStart          |       |
+ * | sessionEnd            | sessionEnd            |       |
+ * | userPromptSubmit      | userPromptSubmitted   |       |
+ * | preToolUse            | preToolUse            | FAIL-CLOSED: errors/timeouts deny the tool call |
+ * | postToolUse           | postToolUse           |       |
+ * | postToolUseFailure    | postToolUseFailure    |       |
+ * | permissionRequest     | permissionRequest     |       |
+ * | subagentStart         | subagentStart         |       |
+ * | subagentStop          | agentStop             | Copilot has no "subagentStop" — agentStop is the closest semantic match |
+ * | preCompact            | preCompact            |       |
+ * | notification          | notification          | Fire-and-forget |
+ *
+ * ## Supported handlers
+ * | Handler type | Details |
+ * |--------------|---------|
+ * | command      | bash or powershell scripts executed in a subshell |
+ * | http         | POST requests sent to a configured endpoint |
+ * | prompt       | Inline prompt template; **only allowed for sessionStart** |
+ *
+ * ## Runtime constraints
+ * - **preToolUse fail-closed**: any error or timeout during a `preToolUse`
+ *   hook causes the tool invocation to be denied. This is a security feature.
+ * - **30 s hook timeout**: hooks that do not respond within 30 s are treated
+ *   as failed (for preToolUse this means the tool call is rejected).
+ * - **10 KB additionalContext cap**: the combined size of all
+ *   `additionalContext` objects passed to a hook must not exceed 10 KB.
+ */
+
+/** Shape of a single hook entry in Copilot's `hooks.json`. */
+interface CopilotHookEntry {
+    /** Copilot event name (e.g. "preToolUse"). */
+    event: string;
+    /** Path to the handler script/binary or HTTP URL. */
+    handler: string;
+    /** Handler type discriminator. */
+    type: "command" | "http" | "prompt";
+    /** Optional matcher filter (e.g. toolName for preToolUse). */
+    matcher?: {
+        /** Field to match on (e.g. "toolName"). */
+        field: string;
+        /** Regex or literal value to match (e.g. "Bash" or "Edit|Write"). */
+        value: string;
+    };
+    /** Whether Copilot should wait for a response (default true except notification). */
+    awaitResponse?: boolean;
+    /** Timeout in seconds (default 30, max 30). */
+    timeout?: number;
+    /** Whether an error denies the operation (true for preToolUse). */
+    failClosed?: boolean;
+}
+/** Shape of the top-level `plugin.json` manifest. */
+interface CopilotPluginManifest {
+    /** Schema version. */
+    schemaVersion: string;
+    /** Plugin identifier. */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** Plugin description. */
+    description?: string;
+    /** Semantic version. */
+    version: string;
+    /** Whether strict validation is enabled (default true). */
+    strict?: boolean;
+    /** Maximum additionalContext size in bytes. */
+    maxAdditionalContextBytes?: number;
+    /** Default hook timeout in seconds. */
+    hookTimeoutSeconds?: number;
+    /** Author / publisher information. */
+    author?: string;
+    /** Homepage URL. */
+    homepage?: string;
+    /** License identifier. */
+    license?: string;
+    /** Tags for discovery. */
+    tags?: string[];
+    /** Paths to hook definitions (relative to plugin.json). */
+    hooks?: string;
+    /** Paths to skill directories (relative to plugin.json). */
+    skills?: string[];
+    /** MCP server configuration file path. */
+    mcp?: string;
+}
+/** Shape of `.mcp.json` when the plugin exposes MCP servers. */
+interface CopilotMcpConfig {
+    /** Schema version for MCP config. */
+    schemaVersion: string;
+    /** List of MCP server connections. */
+    servers: CopilotMcpServer[];
+}
+/** A single MCP server entry. */
+interface CopilotMcpServer {
+    /** Server identifier. */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Transport type. */
+    transport: "stdio" | "sse" | "http";
+    /** Command to launch (for stdio). */
+    command?: string;
+    /** Arguments for the command (for stdio). */
+    args?: string[];
+    /** URL endpoint (for sse / http). */
+    url?: string;
+    /** Environment variables to set. */
+    env?: Record<string, string>;
+}
+/** A compiled skill descriptor in `skills/<name>/SKILL.md` format. */
+interface CopilotSkillDescriptor {
+    /** Skill name. */
+    name: string;
+    /** Skill description. */
+    description: string;
+    /** Input parameters the skill accepts. */
+    parameters?: Array<{
+        name: string;
+        type: "string" | "number" | "boolean" | "object" | "array";
+        description?: string;
+        required?: boolean;
+    }>;
+    /** Example usage prompts. */
+    examples?: string[];
+}
+/**
+ * GitHub Copilot CLI platform adapter.
+ *
+ * Converts AgentPlugins {@link PluginManifest} objects into the file layout
+ * expected by the Copilot CLI runtime:
+ *
+ * ```
+ * .plugin/
+ *   plugin.json        – manifest
+ *   hooks.json         – hook bindings
+ *   skills/
+ *     <skill>/
+ *       SKILL.md       – declarative skill docs
+ *   .mcp.json          – MCP configuration (optional)
+ * ```
+ *
+ * @implements {PlatformAdapter}
+ */
+declare class CopilotAdapter implements PlatformAdapter {
+    /** Platform identifier. */
+    readonly name: TargetPlatform;
+    /** Human-readable display name. */
+    readonly displayName: string;
+    /** Universal hooks supported by this adapter. */
+    readonly supportedHooks: readonly UniversalHookName[];
+    /** Handler types understood by Copilot CLI. */
+    readonly supportedHandlers: readonly HandlerType[];
+    /** Path to the generated manifest file. */
+    readonly manifestPath: string;
+    /** Manifest format (JSON). */
+    readonly manifestFormat: "json" | "toml";
+    /**
+     * 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: PluginManifest): ValidationIssue[];
+    /**
+     * 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: PluginManifest): AdapterOutput;
+    /**
+     * 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
+     */
+    private buildMcpConfig;
+}
+/**
+ * Singleton instance of the Copilot CLI adapter.
+ *
+ * Import this directly to validate and compile plugins for the
+ * GitHub Copilot CLI platform:
+ *
+ * ```ts
+ * import { copilotAdapter } from "@agentplugins/adapter-copilot";
+ *
+ * const issues = copilotAdapter.validate(myPlugin);
+ * if (issues.length === 0) {
+ *   const output = copilotAdapter.compile(myPlugin);
+ *   // output.files contains plugin.json, hooks.json, skills, etc.
+ * }
+ * ```
+ */
+declare const copilotAdapter: CopilotAdapter;
+/** Factory function for creating a new Copilot adapter instance. */
+declare function createCopilotAdapter(): PlatformAdapter;
+
+export { CopilotAdapter, type CopilotHookEntry, type CopilotMcpConfig, type CopilotMcpServer, type CopilotPluginManifest, type CopilotSkillDescriptor, copilotAdapter, createCopilotAdapter };

package/dist/index.d.ts

@@ -0,0 +1,238 @@
+import { PlatformAdapter, TargetPlatform, UniversalHookName, HandlerType, PluginManifest, ValidationIssue, AdapterOutput } from '@agentplugins/core';
+
+/**
+ * @agentplugins/adapter-copilot
+ *
+ * GitHub Copilot CLI platform adapter for the AgentPlugins plugin system.
+ *
+ * This adapter compiles AgentPlugins {@link PluginManifest} objects into the
+ * multi-file layout expected by the Copilot CLI runtime:
+ *
+ *   - plugin.json          – top-level manifest (strict validation, metadata)
+ *   - hooks.json           – hook bindings with optional matcher filters
+ *   - skills/<name>/SKILL.md – declarative skill documentation
+ *   - .mcp.json            – MCP server configuration (when applicable)
+ *
+ * ## Supported hooks (11 / 20 universal hooks)
+ * Copilot supports 13 binding points; we map 11 distinct universal hooks to
+ * them.  The remaining 9 universal hooks are explicitly unsupported.
+ *
+ * | Universal hook        | Copilot event         | Notes |
+ * |-----------------------|-----------------------|-------|
+ * | sessionStart          | sessionStart          |       |
+ * | sessionEnd            | sessionEnd            |       |
+ * | userPromptSubmit      | userPromptSubmitted   |       |
+ * | preToolUse            | preToolUse            | FAIL-CLOSED: errors/timeouts deny the tool call |
+ * | postToolUse           | postToolUse           |       |
+ * | postToolUseFailure    | postToolUseFailure    |       |
+ * | permissionRequest     | permissionRequest     |       |
+ * | subagentStart         | subagentStart         |       |
+ * | subagentStop          | agentStop             | Copilot has no "subagentStop" — agentStop is the closest semantic match |
+ * | preCompact            | preCompact            |       |
+ * | notification          | notification          | Fire-and-forget |
+ *
+ * ## Supported handlers
+ * | Handler type | Details |
+ * |--------------|---------|
+ * | command      | bash or powershell scripts executed in a subshell |
+ * | http         | POST requests sent to a configured endpoint |
+ * | prompt       | Inline prompt template; **only allowed for sessionStart** |
+ *
+ * ## Runtime constraints
+ * - **preToolUse fail-closed**: any error or timeout during a `preToolUse`
+ *   hook causes the tool invocation to be denied. This is a security feature.
+ * - **30 s hook timeout**: hooks that do not respond within 30 s are treated
+ *   as failed (for preToolUse this means the tool call is rejected).
+ * - **10 KB additionalContext cap**: the combined size of all
+ *   `additionalContext` objects passed to a hook must not exceed 10 KB.
+ */
+
+/** Shape of a single hook entry in Copilot's `hooks.json`. */
+interface CopilotHookEntry {
+    /** Copilot event name (e.g. "preToolUse"). */
+    event: string;
+    /** Path to the handler script/binary or HTTP URL. */
+    handler: string;
+    /** Handler type discriminator. */
+    type: "command" | "http" | "prompt";
+    /** Optional matcher filter (e.g. toolName for preToolUse). */
+    matcher?: {
+        /** Field to match on (e.g. "toolName"). */
+        field: string;
+        /** Regex or literal value to match (e.g. "Bash" or "Edit|Write"). */
+        value: string;
+    };
+    /** Whether Copilot should wait for a response (default true except notification). */
+    awaitResponse?: boolean;
+    /** Timeout in seconds (default 30, max 30). */
+    timeout?: number;
+    /** Whether an error denies the operation (true for preToolUse). */
+    failClosed?: boolean;
+}
+/** Shape of the top-level `plugin.json` manifest. */
+interface CopilotPluginManifest {
+    /** Schema version. */
+    schemaVersion: string;
+    /** Plugin identifier. */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** Plugin description. */
+    description?: string;
+    /** Semantic version. */
+    version: string;
+    /** Whether strict validation is enabled (default true). */
+    strict?: boolean;
+    /** Maximum additionalContext size in bytes. */
+    maxAdditionalContextBytes?: number;
+    /** Default hook timeout in seconds. */
+    hookTimeoutSeconds?: number;
+    /** Author / publisher information. */
+    author?: string;
+    /** Homepage URL. */
+    homepage?: string;
+    /** License identifier. */
+    license?: string;
+    /** Tags for discovery. */
+    tags?: string[];
+    /** Paths to hook definitions (relative to plugin.json). */
+    hooks?: string;
+    /** Paths to skill directories (relative to plugin.json). */
+    skills?: string[];
+    /** MCP server configuration file path. */
+    mcp?: string;
+}
+/** Shape of `.mcp.json` when the plugin exposes MCP servers. */
+interface CopilotMcpConfig {
+    /** Schema version for MCP config. */
+    schemaVersion: string;
+    /** List of MCP server connections. */
+    servers: CopilotMcpServer[];
+}
+/** A single MCP server entry. */
+interface CopilotMcpServer {
+    /** Server identifier. */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Transport type. */
+    transport: "stdio" | "sse" | "http";
+    /** Command to launch (for stdio). */
+    command?: string;
+    /** Arguments for the command (for stdio). */
+    args?: string[];
+    /** URL endpoint (for sse / http). */
+    url?: string;
+    /** Environment variables to set. */
+    env?: Record<string, string>;
+}
+/** A compiled skill descriptor in `skills/<name>/SKILL.md` format. */
+interface CopilotSkillDescriptor {
+    /** Skill name. */
+    name: string;
+    /** Skill description. */
+    description: string;
+    /** Input parameters the skill accepts. */
+    parameters?: Array<{
+        name: string;
+        type: "string" | "number" | "boolean" | "object" | "array";
+        description?: string;
+        required?: boolean;
+    }>;
+    /** Example usage prompts. */
+    examples?: string[];
+}
+/**
+ * GitHub Copilot CLI platform adapter.
+ *
+ * Converts AgentPlugins {@link PluginManifest} objects into the file layout
+ * expected by the Copilot CLI runtime:
+ *
+ * ```
+ * .plugin/
+ *   plugin.json        – manifest
+ *   hooks.json         – hook bindings
+ *   skills/
+ *     <skill>/
+ *       SKILL.md       – declarative skill docs
+ *   .mcp.json          – MCP configuration (optional)
+ * ```
+ *
+ * @implements {PlatformAdapter}
+ */
+declare class CopilotAdapter implements PlatformAdapter {
+    /** Platform identifier. */
+    readonly name: TargetPlatform;
+    /** Human-readable display name. */
+    readonly displayName: string;
+    /** Universal hooks supported by this adapter. */
+    readonly supportedHooks: readonly UniversalHookName[];
+    /** Handler types understood by Copilot CLI. */
+    readonly supportedHandlers: readonly HandlerType[];
+    /** Path to the generated manifest file. */
+    readonly manifestPath: string;
+    /** Manifest format (JSON). */
+    readonly manifestFormat: "json" | "toml";
+    /**
+     * 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: PluginManifest): ValidationIssue[];
+    /**
+     * 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: PluginManifest): AdapterOutput;
+    /**
+     * 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
+     */
+    private buildMcpConfig;
+}
+/**
+ * Singleton instance of the Copilot CLI adapter.
+ *
+ * Import this directly to validate and compile plugins for the
+ * GitHub Copilot CLI platform:
+ *
+ * ```ts
+ * import { copilotAdapter } from "@agentplugins/adapter-copilot";
+ *
+ * const issues = copilotAdapter.validate(myPlugin);
+ * if (issues.length === 0) {
+ *   const output = copilotAdapter.compile(myPlugin);
+ *   // output.files contains plugin.json, hooks.json, skills, etc.
+ * }
+ * ```
+ */
+declare const copilotAdapter: CopilotAdapter;
+/** Factory function for creating a new Copilot adapter instance. */
+declare function createCopilotAdapter(): PlatformAdapter;
+
+export { CopilotAdapter, type CopilotHookEntry, type CopilotMcpConfig, type CopilotMcpServer, type CopilotPluginManifest, type CopilotSkillDescriptor, copilotAdapter, createCopilotAdapter };