@openacp/cli 2026.331.1 → 2026.331.3

package/dist/plugin-create-HFKS23JY.js

@@ -1,968 +0,0 @@
-import {
-  getCurrentVersion
-} from "./chunk-S64CB6J3.js";
-
-// src/cli/commands/plugin-create.ts
-import * as p from "@clack/prompts";
-import fs from "fs";
-import path from "path";
-
-// src/cli/plugin-template/package-json.ts
-function generatePackageJson(params) {
-  const packageJson = {
-    name: params.pluginName,
-    version: "0.1.0",
-    description: params.description || "",
-    type: "module",
-    main: "dist/index.js",
-    types: "dist/index.d.ts",
-    scripts: {
-      build: "tsc",
-      dev: "tsc --watch",
-      test: "vitest",
-      prepublishOnly: "npm run build"
-    },
-    author: params.author || "",
-    license: params.license,
-    keywords: ["openacp", "openacp-plugin"],
-    engines: {
-      openacp: `>=${params.cliVersion}`
-    },
-    peerDependencies: {
-      "@openacp/cli": `>=${params.cliVersion}`
-    },
-    devDependencies: {
-      "@openacp/plugin-sdk": params.cliVersion,
-      typescript: "^5.4.0",
-      vitest: "^3.0.0"
-    }
-  };
-  return JSON.stringify(packageJson, null, 2) + "\n";
-}
-
-// src/cli/plugin-template/tsconfig.ts
-function generateTsconfig() {
-  const tsconfig = {
-    compilerOptions: {
-      target: "ES2022",
-      module: "NodeNext",
-      moduleResolution: "NodeNext",
-      declaration: true,
-      outDir: "dist",
-      rootDir: "src",
-      strict: true,
-      esModuleInterop: true,
-      skipLibCheck: true,
-      forceConsistentCasingInFileNames: true
-    },
-    include: ["src"],
-    exclude: ["node_modules", "dist", "src/**/__tests__"]
-  };
-  return JSON.stringify(tsconfig, null, 2) + "\n";
-}
-
-// src/cli/plugin-template/dotfiles.ts
-function generateGitignore() {
-  return ["node_modules/", "dist/", "*.tsbuildinfo", ".DS_Store", ""].join("\n");
-}
-function generateNpmignore() {
-  return ["src/", "tsconfig.json", ".editorconfig", ".gitignore", "*.test.ts", "__tests__/", ""].join("\n");
-}
-function generateEditorconfig() {
-  return [
-    "root = true",
-    "",
-    "[*]",
-    "indent_style = space",
-    "indent_size = 2",
-    "end_of_line = lf",
-    "charset = utf-8",
-    "trim_trailing_whitespace = true",
-    "insert_final_newline = true",
-    ""
-  ].join("\n");
-}
-
-// src/cli/plugin-template/readme.ts
-function generateReadme(params) {
-  return [
-    `# ${params.pluginName}`,
-    "",
-    params.description || "An OpenACP plugin.",
-    "",
-    "## Installation",
-    "",
-    "```bash",
-    `openacp plugin add ${params.pluginName}`,
-    "```",
-    "",
-    "## Development",
-    "",
-    "```bash",
-    "npm install",
-    "npm run build",
-    "npm test",
-    "",
-    "# Live development with hot-reload:",
-    `openacp dev .`,
-    "```",
-    "",
-    "## License",
-    "",
-    params.license,
-    ""
-  ].join("\n");
-}
-
-// src/cli/plugin-template/plugin-source.ts
-function generatePluginSource(params) {
-  const dirName = params.pluginName.replace(/^@[^/]+\//, "");
-  const escapedDescription = (params.description || "").replace(/'/g, "\\'");
-  return `import type { OpenACPPlugin, PluginContext, InstallContext, MigrateContext } from '@openacp/plugin-sdk'
-
-const plugin: OpenACPPlugin = {
-  name: '${params.pluginName}',
-  version: '0.1.0',
-  description: '${escapedDescription}',
-
-  // Declare which permissions your plugin needs.
-  // Available: events:read, events:emit, services:register, services:use,
-  //            middleware:register, commands:register, storage:read, storage:write, kernel:access
-  permissions: ['events:read', 'services:register'],
-
-  // Dependencies on other plugins (loaded before this one).
-  // pluginDependencies: { '@openacp/security': '>=1.0.0' },
-
-  // Optional dependencies (used if available, gracefully degrade if not).
-  // optionalPluginDependencies: { '@openacp/usage': '>=1.0.0' },
-
-  /**
-   * Called during server startup in dependency order.
-   * Register services, middleware, commands, and event listeners here.
-   */
-  async setup(ctx: PluginContext): Promise<void> {
-    ctx.log.info('Plugin setup started')
-
-    // Example: register a service
-    // ctx.registerService('my-service', myServiceImpl)
-
-    // Example: listen to events
-    // ctx.on('session:created', (event) => { ... })
-
-    // Example: register a slash command
-    // ctx.registerCommand({
-    //   name: 'mycommand',
-    //   description: 'Does something useful',
-    //   category: 'plugin',
-    //   async handler(args) {
-    //     return { type: 'text', text: 'Hello from ${params.pluginName}!' }
-    //   },
-    // })
-
-    ctx.log.info('Plugin setup complete')
-  },
-
-  /**
-   * Called during server shutdown in reverse dependency order.
-   * Clean up resources, close connections, stop timers here.
-   * Has a 10-second timeout.
-   */
-  async teardown(): Promise<void> {
-    // Clean up resources here
-  },
-
-  /**
-   * Called when user runs \`openacp plugin add ${params.pluginName}\`.
-   * Use ctx.terminal for interactive prompts to gather configuration.
-   */
-  async install(ctx: InstallContext): Promise<void> {
-    ctx.terminal.log.info('Installing ${params.pluginName}...')
-
-    // Example: prompt for configuration
-    // const apiKey = await ctx.terminal.text({
-    //   message: 'Enter your API key',
-    //   validate: (v) => v.length === 0 ? 'Required' : undefined,
-    // })
-    // await ctx.settings.set('apiKey', apiKey)
-
-    ctx.terminal.log.success('Installation complete!')
-  },
-
-  /**
-   * Called when user runs \`openacp plugin configure ${params.pluginName}\`.
-   * Re-run configuration prompts to update settings.
-   */
-  async configure(ctx: InstallContext): Promise<void> {
-    ctx.terminal.log.info('Configuring ${params.pluginName}...')
-
-    // Re-run configuration prompts, pre-filling with current values
-    // const current = await ctx.settings.getAll()
-    // ...
-
-    ctx.terminal.log.success('Configuration updated!')
-  },
-
-  /**
-   * Called during boot when the plugin version has changed.
-   * Migrate settings from the old format to the new format.
-   */
-  async migrate(ctx: MigrateContext, oldSettings: unknown, oldVersion: string): Promise<unknown> {
-    ctx.log.info(\`Migrating from v\${oldVersion}\`)
-    // Return the migrated settings object
-    return oldSettings
-  },
-
-  /**
-   * Called when user runs \`openacp plugin remove ${params.pluginName}\`.
-   * Clean up any external resources. If opts.purge is true, delete all data.
-   */
-  async uninstall(ctx: InstallContext, opts: { purge: boolean }): Promise<void> {
-    ctx.terminal.log.info('Uninstalling ${params.pluginName}...')
-    if (opts.purge) {
-      await ctx.settings.clear()
-    }
-    ctx.terminal.log.success('Uninstalled!')
-  },
-}
-
-export default plugin
-`;
-}
-
-// src/cli/plugin-template/plugin-test.ts
-function generatePluginTest(params) {
-  return `import { describe, it, expect } from 'vitest'
-import { createTestContext, createTestInstallContext } from '@openacp/plugin-sdk/testing'
-import plugin from '../index.js'
-
-describe('${params.pluginName}', () => {
-  it('has correct metadata', () => {
-    expect(plugin.name).toBe('${params.pluginName}')
-    expect(plugin.version).toBeDefined()
-    expect(plugin.setup).toBeInstanceOf(Function)
-  })
-
-  it('sets up without errors', async () => {
-    const ctx = createTestContext({
-      pluginName: '${params.pluginName}',
-      pluginConfig: { enabled: true },
-      permissions: plugin.permissions,
-    })
-    await expect(plugin.setup(ctx)).resolves.not.toThrow()
-  })
-
-  it('tears down without errors', async () => {
-    if (plugin.teardown) {
-      await expect(plugin.teardown()).resolves.not.toThrow()
-    }
-  })
-
-  it('installs without errors', async () => {
-    if (plugin.install) {
-      const ctx = createTestInstallContext({
-        pluginName: '${params.pluginName}',
-        terminalResponses: { password: [''], confirm: [true], select: ['apiKey'] },
-      })
-      await expect(plugin.install(ctx)).resolves.not.toThrow()
-    }
-  })
-})
-`;
-}
-
-// src/cli/plugin-template/claude-md.ts
-function generateClaudeMd(params) {
-  return `# CLAUDE.md
-
-This file provides context for AI coding agents (Claude, Cursor, etc.) working on this plugin.
-
-## What is OpenACP?
-
-OpenACP is an open-source platform that bridges AI coding agents (Claude Code, Codex, etc.) to messaging platforms (Telegram, Discord, Slack) and custom UIs via the Agent Client Protocol (ACP). It features a microkernel plugin architecture where all features \u2014 adapters, services, commands \u2014 are plugins.
-
-- **Website & Docs**: https://openacp.gitbook.io/docs
-- **GitHub**: https://github.com/Open-ACP/OpenACP
-- **Plugin Registry**: https://github.com/Open-ACP/plugin-registry
-
-Key documentation pages:
-- [Getting Started](https://openacp.gitbook.io/docs/getting-started) \u2014 What is OpenACP, quickstart
-- [Plugin Development](https://openacp.gitbook.io/docs/extending/building-plugins) \u2014 How to build plugins
-- [Architecture](https://openacp.gitbook.io/docs/extending/architecture) \u2014 System design, plugin lifecycle
-- [Dev Mode](https://openacp.gitbook.io/docs/extending/dev-mode) \u2014 Hot-reload development workflow
-- [CLI Commands](https://openacp.gitbook.io/docs/api-reference/cli-commands) \u2014 Full CLI reference
-- [Platform Setup](https://openacp.gitbook.io/docs/platform-setup) \u2014 Telegram, Discord, Slack guides
-- [Configuration](https://openacp.gitbook.io/docs/self-hosting/configuration) \u2014 Config and settings reference
-
-## Project Overview
-
-This is an OpenACP plugin. Plugins extend OpenACP with new adapters, services, commands, and middleware.
-
-- **Package**: ${params.pluginName}
-- **SDK**: \`@openacp/plugin-sdk\` (types, base classes, testing utilities)
-- **Entry point**: \`src/index.ts\` (default export of \`OpenACPPlugin\` object)
-
-## Build & Run
-
-\`\`\`bash
-npm install           # Install dependencies
-npm run build         # Compile TypeScript (tsc)
-npm run dev           # Watch mode (tsc --watch)
-npm test              # Run tests (vitest)
-\`\`\`
-
-### Development with hot-reload
-
-\`\`\`bash
-openacp dev .         # Compiles, watches, and reloads plugin on changes
-\`\`\`
-
-## File Structure
-
-\`\`\`
-src/
-  index.ts              \u2014 Plugin entry point (exports OpenACPPlugin)
-  __tests__/
-    index.test.ts       \u2014 Tests using @openacp/plugin-sdk/testing
-package.json            \u2014 engines.openacp declares minimum CLI version
-tsconfig.json           \u2014 ES2022, NodeNext, strict mode
-CLAUDE.md               \u2014 This file (AI agent context)
-PLUGIN_GUIDE.md         \u2014 Human-readable developer guide
-\`\`\`
-
-## Architecture: How OpenACP Plugins Work
-
-### Plugin Lifecycle
-
-\`\`\`
-install \u2500\u2500> [reboot] \u2500\u2500> migrate? \u2500\u2500> setup \u2500\u2500> [running] \u2500\u2500> teardown \u2500\u2500> uninstall
-\`\`\`
-
-| Hook | Trigger | Interactive? | Has Services? |
-|------|---------|-------------|---------------|
-| \`install(ctx)\` | \`openacp plugin add <name>\` | Yes | No |
-| \`migrate(ctx, oldSettings, oldVersion)\` | Boot \u2014 stored version differs from plugin version | No | No |
-| \`configure(ctx)\` | \`openacp plugin configure <name>\` | Yes | No |
-| \`setup(ctx)\` | Every boot, after migrate | No | Yes |
-| \`teardown()\` | Shutdown (10s timeout) | No | Yes |
-| \`uninstall(ctx, opts)\` | \`openacp plugin remove <name>\` | Yes | No |
-
-### OpenACPPlugin Interface
-
-\`\`\`typescript
-interface OpenACPPlugin {
-  name: string                    // unique identifier, e.g. '@myorg/my-plugin'
-  version: string                 // semver
-  description?: string
-  permissions?: PluginPermission[]
-  pluginDependencies?: Record<string, string>          // name -> semver range
-  optionalPluginDependencies?: Record<string, string>  // used if available
-  overrides?: string              // replace a built-in plugin entirely
-  settingsSchema?: ZodSchema      // Zod validation for settings
-  essential?: boolean             // true = needs setup before system can run
-
-  setup(ctx: PluginContext): Promise<void>
-  teardown?(): Promise<void>
-  install?(ctx: InstallContext): Promise<void>
-  configure?(ctx: InstallContext): Promise<void>
-  migrate?(ctx: MigrateContext, oldSettings: unknown, oldVersion: string): Promise<unknown>
-  uninstall?(ctx: InstallContext, opts: { purge: boolean }): Promise<void>
-}
-\`\`\`
-
-### PluginContext API (available in setup)
-
-\`\`\`typescript
-interface PluginContext {
-  pluginName: string
-  pluginConfig: Record<string, unknown>   // from settings.json
-
-  // Events (requires 'events:read' / 'events:emit')
-  on(event: string, handler: (...args: unknown[]) => void): void
-  off(event: string, handler: (...args: unknown[]) => void): void
-  emit(event: string, payload: unknown): void
-
-  // Services (requires 'services:register' / 'services:use')
-  registerService<T>(name: string, implementation: T): void
-  getService<T>(name: string): T | undefined
-
-  // Middleware (requires 'middleware:register')
-  registerMiddleware<H extends MiddlewareHook>(hook: H, opts: MiddlewareOptions<MiddlewarePayloadMap[H]>): void
-
-  // Commands (requires 'commands:register')
-  registerCommand(def: CommandDef): void
-
-  // Storage (requires 'storage:read' / 'storage:write')
-  storage: PluginStorage  // get, set, delete, list, getDataDir
-
-  // Messaging (requires 'services:use')
-  sendMessage(sessionId: string, content: OutgoingMessage): Promise<void>
-
-  // Kernel access (requires 'kernel:access')
-  sessions: SessionManager
-  config: ConfigManager
-  eventBus: EventBus
-
-  // Always available
-  log: Logger  // trace, debug, info, warn, error, fatal, child
-}
-\`\`\`
-
-### CommandDef and CommandResponse
-
-\`\`\`typescript
-interface CommandDef {
-  name: string              // command name without slash
-  description: string       // shown in /help
-  usage?: string            // e.g. '<city>' or 'on|off'
-  category: 'system' | 'plugin'
-  handler(args: CommandArgs): Promise<CommandResponse | void>
-}
-
-interface CommandArgs {
-  raw: string               // text after command name
-  sessionId: string | null
-  channelId: string         // 'telegram', 'discord', 'slack'
-  userId: string
-  reply(content: string | CommandResponse): Promise<void>
-}
-
-type CommandResponse =
-  | { type: 'text'; text: string }
-  | { type: 'menu'; title: string; options: MenuOption[] }
-  | { type: 'list'; title: string; items: ListItem[] }
-  | { type: 'confirm'; question: string; onYes: string; onNo: string }
-  | { type: 'error'; message: string }
-  | { type: 'silent' }
-\`\`\`
-
-### Settings System
-
-- \`settingsSchema\`: Zod schema for validation
-- \`SettingsAPI\` (in InstallContext): get, set, getAll, setAll, delete, clear, has
-- Settings stored at \`~/.openacp/plugins/@scope/name/settings.json\`
-- \`PluginStorage\` (in PluginContext): key-value store at \`~/.openacp/plugins/data/@scope/name/kv.json\`
-- \`storage.getDataDir()\`: returns path for large files, databases, caches
-
-### InstallContext (for install/configure/uninstall)
-
-\`\`\`typescript
-interface InstallContext {
-  pluginName: string
-  terminal: TerminalIO        // text, select, confirm, password, multiselect, log, spinner, note
-  settings: SettingsAPI
-  legacyConfig?: Record<string, unknown>
-  dataDir: string
-  log: Logger
-}
-\`\`\`
-
-### Service Interfaces (available via ctx.getService)
-
-| Service name | Interface | Description |
-|---|---|---|
-| \`security\` | \`SecurityService\` | Access control, session limits, user roles |
-| \`file-service\` | \`FileServiceInterface\` | File saving, resolving, format conversion |
-| \`notifications\` | \`NotificationService\` | Send notifications to users |
-| \`usage\` | \`UsageService\` | Token/cost tracking and budget checking |
-| \`speech\` | \`SpeechServiceInterface\` | Text-to-speech and speech-to-text |
-| \`tunnel\` | \`TunnelServiceInterface\` | Port tunneling and public URL management |
-| \`context\` | \`ContextService\` | Context building for agent sessions |
-
-## Plugin Permissions
-
-Declare in \`permissions\` array. Only request what you need.
-
-| Permission | Allows |
-|---|---|
-| \`events:read\` | \`ctx.on()\` \u2014 subscribe to events |
-| \`events:emit\` | \`ctx.emit()\` \u2014 emit custom events (must prefix with plugin name) |
-| \`services:register\` | \`ctx.registerService()\` \u2014 provide services to other plugins |
-| \`services:use\` | \`ctx.getService()\`, \`ctx.sendMessage()\` \u2014 consume services |
-| \`middleware:register\` | \`ctx.registerMiddleware()\` \u2014 intercept and modify flows |
-| \`commands:register\` | \`ctx.registerCommand()\` \u2014 add chat commands |
-| \`storage:read\` | \`ctx.storage.get()\`, \`ctx.storage.list()\` |
-| \`storage:write\` | \`ctx.storage.set()\`, \`ctx.storage.delete()\` |
-| \`kernel:access\` | \`ctx.sessions\`, \`ctx.config\`, \`ctx.eventBus\`, \`ctx.core\` |
-
-Calling a method without the required permission throws \`PluginPermissionError\`.
-
-## Middleware Hooks (20 total)
-
-Register with \`ctx.registerMiddleware(hook, { priority?, handler })\`. Return \`null\` to block the flow, call \`next()\` to continue.
-
-### Message flow
-- \`message:incoming\` \u2014 incoming user message (channelId, threadId, userId, text, attachments)
-- \`message:outgoing\` \u2014 outgoing message to user (sessionId, message)
-
-### Agent flow
-- \`agent:beforePrompt\` \u2014 before prompt is sent to agent (sessionId, text, attachments)
-- \`agent:beforeEvent\` \u2014 before agent event is processed (sessionId, event)
-- \`agent:afterEvent\` \u2014 after agent event, before delivery (sessionId, event, outgoingMessage)
-
-### Turn lifecycle
-- \`turn:start\` \u2014 agent turn begins (sessionId, promptText, promptNumber)
-- \`turn:end\` \u2014 agent turn ends (sessionId, stopReason, durationMs)
-
-### File system
-- \`fs:beforeRead\` \u2014 before file read (sessionId, path, line, limit)
-- \`fs:beforeWrite\` \u2014 before file write (sessionId, path, content)
-
-### Terminal
-- \`terminal:beforeCreate\` \u2014 before terminal process spawned (sessionId, command, args, env, cwd)
-- \`terminal:afterExit\` \u2014 after terminal process exits (sessionId, terminalId, command, exitCode, durationMs)
-
-### Permission
-- \`permission:beforeRequest\` \u2014 before permission prompt (sessionId, request, autoResolve)
-- \`permission:afterResolve\` \u2014 after permission resolved (sessionId, requestId, decision, userId, durationMs)
-
-### Session
-- \`session:beforeCreate\` \u2014 before session creation (agentName, workingDir, userId, channelId, threadId)
-- \`session:afterDestroy\` \u2014 after session destroyed (sessionId, reason, durationMs, promptCount)
-
-### Control
-- \`mode:beforeChange\` \u2014 before mode change (sessionId, fromMode, toMode)
-- \`config:beforeChange\` \u2014 before config change (sessionId, configId, oldValue, newValue)
-- \`model:beforeChange\` \u2014 before model change (sessionId, fromModel, toModel)
-- \`agent:beforeCancel\` \u2014 before agent cancellation (sessionId, reason)
-- \`agent:beforeSwitch\` \u2014 **blocking** before agent switch (sessionId, fromAgent, toAgent). Return null/false to block.
-- \`agent:afterSwitch\` \u2014 **fire-and-forget** after agent switch (sessionId, fromAgent, toAgent, resumed). Observational only.
-
-## Plugin Events (subscribe with ctx.on)
-
-### System
-- \`kernel:booted\`, \`system:ready\`, \`system:shutdown\`, \`system:commands-ready\`
-
-### Plugin lifecycle
-- \`plugin:loaded\`, \`plugin:failed\`, \`plugin:disabled\`, \`plugin:unloaded\`
-
-### Session
-- \`session:created\`, \`session:ended\`, \`session:named\`, \`session:updated\`
-
-### Agent
-- \`agent:event\`, \`agent:prompt\`
-
-### Permission
-- \`permission:request\`, \`permission:resolved\`
-
-## Testing
-
-Use \`@openacp/plugin-sdk/testing\`:
-
-\`\`\`typescript
-import { createTestContext, createTestInstallContext, mockServices } from '@openacp/plugin-sdk/testing'
-\`\`\`
-
-### createTestContext(opts)
-
-Creates a test \`PluginContext\`. All state is in-memory.
-
-\`\`\`typescript
-const ctx = createTestContext({
-  pluginName: '${params.pluginName}',
-  pluginConfig: { enabled: true },
-  permissions: plugin.permissions,
-  services: { security: mockServices.security() },
-})
-await plugin.setup(ctx)
-expect(ctx.registeredCommands.has('mycommand')).toBe(true)
-const response = await ctx.executeCommand('mycommand', { raw: 'test' })
-\`\`\`
-
-Inspection properties: \`registeredServices\`, \`registeredCommands\`, \`registeredMiddleware\`, \`emittedEvents\`, \`sentMessages\`, \`executeCommand()\`.
-
-### createTestInstallContext(opts)
-
-Creates a test \`InstallContext\`. Terminal prompts auto-answered from \`terminalResponses\`.
-
-\`\`\`typescript
-const ctx = createTestInstallContext({
-  pluginName: '${params.pluginName}',
-  terminalResponses: { password: ['sk-test-key'], select: ['en'] },
-})
-await plugin.install!(ctx)
-expect(ctx.settingsData.get('apiKey')).toBe('sk-test-key')
-\`\`\`
-
-### mockServices
-
-Factory functions for mock service implementations:
-
-\`\`\`typescript
-mockServices.security(overrides?)    // checkAccess, checkSessionLimit, getUserRole
-mockServices.fileService(overrides?) // saveFile, resolveFile, readTextFileWithRange
-mockServices.notifications(overrides?) // notify, notifyAll
-mockServices.usage(overrides?)       // trackUsage, checkBudget, getSummary
-mockServices.speech(overrides?)      // textToSpeech, speechToText, register*
-mockServices.tunnel(overrides?)      // getPublicUrl, start, stop, getStore, fileUrl, diffUrl
-mockServices.context(overrides?)     // buildContext, registerProvider
-\`\`\`
-
-## Conventions
-
-- **ESM-only**: \`"type": "module"\` in package.json
-- **Import extensions**: All imports must use \`.js\` extension (e.g., \`import x from './util.js'\`)
-- **TypeScript strict mode**: \`strict: true\` in tsconfig.json
-- **Target**: ES2022, module NodeNext
-- **Test framework**: Vitest
-- **Test files**: \`src/**/__tests__/*.test.ts\`
-
-## How to Add a Command
-
-\`\`\`typescript
-// In setup():
-ctx.registerCommand({
-  name: 'mycommand',
-  description: 'Does something useful',
-  usage: '<arg>',
-  category: 'plugin',
-  async handler(args) {
-    const input = args.raw.trim()
-    if (!input) return { type: 'error', message: 'Usage: /mycommand <arg>' }
-    return { type: 'text', text: \\\`Result: \\\${input}\\\` }
-  },
-})
-\`\`\`
-
-Requires \`commands:register\` permission. Available as \`/mycommand\` (if no conflict) and \`/pluginscope:mycommand\` (always).
-
-## How to Add a Service
-
-\`\`\`typescript
-// In setup():
-const myService = new MyService()
-ctx.registerService('my-service', myService)
-\`\`\`
-
-Requires \`services:register\` permission. Other plugins consume with \`ctx.getService<MyService>('my-service')\`.
-
-## How to Add Middleware
-
-\`\`\`typescript
-// In setup():
-ctx.registerMiddleware('message:outgoing', {
-  priority: 50,  // lower = earlier execution
-  handler: async (payload, next) => {
-    payload.message.text = modifyText(payload.message.text)
-    return next()  // continue chain; return null to block
-  },
-})
-\`\`\`
-
-Requires \`middleware:register\` permission.
-
-## How Settings Work
-
-1. Define \`settingsSchema\` (Zod) on the plugin object
-2. In \`install()\`: use \`ctx.terminal\` for interactive prompts, save with \`ctx.settings.set()\`
-3. In \`configure()\`: re-run prompts with current values pre-filled
-4. In \`setup()\`: read settings from \`ctx.pluginConfig\`
-5. In \`migrate()\`: transform old settings to new format on version change
-
-## Version Compatibility
-
-The \`engines.openacp\` field in package.json declares the minimum CLI version. OpenACP checks this on install and warns if incompatible.
-`;
-}
-
-// src/cli/plugin-template/plugin-guide.ts
-function generatePluginGuide(params) {
-  return `# Plugin Developer Guide
-
-## Overview
-
-**${params.pluginName}** is an OpenACP plugin.
-
-> TODO: Describe what this plugin does.
-
-## Project Structure
-
-\`\`\`
-src/
-  index.ts              \u2014 Plugin entry point (exports OpenACPPlugin object)
-  __tests__/
-    index.test.ts       \u2014 Tests using Vitest + @openacp/plugin-sdk/testing
-package.json            \u2014 npm package config with engines.openacp constraint
-tsconfig.json           \u2014 TypeScript strict mode, ES2022, NodeNext
-CLAUDE.md               \u2014 Full technical reference for AI coding agents
-PLUGIN_GUIDE.md         \u2014 This file
-\`\`\`
-
-## Development Workflow
-
-1. **Edit** \`src/index.ts\` \u2014 implement your plugin logic
-2. **Dev mode**: \`openacp dev .\` \u2014 compiles, watches, and hot-reloads your plugin
-3. **Test**: \`npm test\` \u2014 runs Vitest with SDK testing utilities
-4. **Build**: \`npm run build\` \u2014 compiles TypeScript to \`dist/\`
-
-\`\`\`bash
-npm install
-openacp dev .     # start developing with hot-reload
-npm test          # run tests
-npm run build     # compile for publishing
-\`\`\`
-
-## Adding a Command
-
-Register commands in your \`setup()\` function. Requires \`commands:register\` permission.
-
-\`\`\`typescript
-async setup(ctx: PluginContext) {
-  ctx.registerCommand({
-    name: 'greet',
-    description: 'Send a greeting',
-    usage: '[name]',
-    category: 'plugin',
-    async handler(args) {
-      const name = args.raw.trim() || 'World'
-      return { type: 'text', text: \\\`Hello, \\\${name}!\\\` }
-    },
-  })
-}
-\`\`\`
-
-The command will be available as \`/greet\` in all messaging platforms.
-
-## Adding a Service
-
-Provide a service that other plugins can consume. Requires \`services:register\` permission.
-
-\`\`\`typescript
-async setup(ctx: PluginContext) {
-  const myService = {
-    doSomething(input: string): string {
-      return input.toUpperCase()
-    },
-  }
-  ctx.registerService('my-service', myService)
-}
-\`\`\`
-
-Other plugins access it with \`ctx.getService<MyServiceType>('my-service')\`.
-
-## Adding Middleware
-
-Intercept and modify message flows. Requires \`middleware:register\` permission.
-
-\`\`\`typescript
-async setup(ctx: PluginContext) {
-  ctx.registerMiddleware('message:outgoing', {
-    priority: 50,
-    handler: async (payload, next) => {
-      // Modify the message before delivery
-      payload.message.text += '\\n-- sent via ${params.pluginName}'
-      return next()  // continue the chain
-      // return null to block the message entirely
-    },
-  })
-}
-\`\`\`
-
-## Handling Settings
-
-### Install flow (first-time setup)
-
-\`\`\`typescript
-async install(ctx: InstallContext) {
-  const apiKey = await ctx.terminal.password({
-    message: 'Enter your API key:',
-    validate: (v) => v.length > 0 ? undefined : 'Required',
-  })
-  await ctx.settings.set('apiKey', apiKey)
-  ctx.terminal.log.success('Configured!')
-}
-\`\`\`
-
-### Configure flow (reconfiguration)
-
-\`\`\`typescript
-async configure(ctx: InstallContext) {
-  const current = await ctx.settings.getAll()
-  const apiKey = await ctx.terminal.password({
-    message: \\\`API key (current: \\\${current.apiKey ? '***' : 'not set'}):\\\`,
-  })
-  if (apiKey) await ctx.settings.set('apiKey', apiKey)
-  ctx.terminal.log.success('Updated!')
-}
-\`\`\`
-
-### Reading settings at runtime
-
-\`\`\`typescript
-async setup(ctx: PluginContext) {
-  const apiKey = ctx.pluginConfig.apiKey as string
-  if (!apiKey) {
-    ctx.log.warn('Not configured \u2014 run: openacp plugin configure ${params.pluginName}')
-    return
-  }
-  // Use apiKey...
-}
-\`\`\`
-
-## Testing
-
-Tests use Vitest and \`@openacp/plugin-sdk/testing\`.
-
-\`\`\`typescript
-import { describe, it, expect } from 'vitest'
-import { createTestContext, createTestInstallContext, mockServices } from '@openacp/plugin-sdk/testing'
-import plugin from '../index.js'
-
-describe('${params.pluginName}', () => {
-  it('registers commands on setup', async () => {
-    const ctx = createTestContext({ pluginName: '${params.pluginName}' })
-    await plugin.setup(ctx)
-    expect(ctx.registeredCommands.has('greet')).toBe(true)
-  })
-
-  it('command returns expected response', async () => {
-    const ctx = createTestContext({ pluginName: '${params.pluginName}' })
-    await plugin.setup(ctx)
-    const res = await ctx.executeCommand('greet', { raw: 'Alice' })
-    expect(res).toEqual({ type: 'text', text: 'Hello, Alice!' })
-  })
-
-  it('install saves settings', async () => {
-    const ctx = createTestInstallContext({
-      pluginName: '${params.pluginName}',
-      terminalResponses: { password: ['sk-test-key'] },
-    })
-    await plugin.install!(ctx)
-    expect(ctx.settingsData.get('apiKey')).toBe('sk-test-key')
-  })
-})
-\`\`\`
-
-### Available mock services
-
-\`\`\`typescript
-const ctx = createTestContext({
-  pluginName: '${params.pluginName}',
-  services: {
-    security: mockServices.security(),
-    usage: mockServices.usage({ async checkBudget() { return { ok: false, percent: 100 } } }),
-  },
-})
-\`\`\`
-
-## Publishing
-
-1. Update \`version\` in both \`package.json\` and \`src/index.ts\`
-2. Build and test:
-   \`\`\`bash
-   npm run build
-   npm test
-   \`\`\`
-3. Publish:
-   \`\`\`bash
-   npm publish --access public
-   \`\`\`
-4. Users install with:
-   \`\`\`bash
-   openacp plugin install ${params.pluginName}
-   \`\`\`
-5. Submit to the [OpenACP Plugin Registry](https://github.com/Open-ACP/plugin-registry) for discoverability.
-
-## Useful Links
-
-- [Architecture: Plugin System](https://docs.openacp.dev/architecture/plugin-system)
-- [Architecture: Writing Plugins](https://docs.openacp.dev/architecture/writing-plugins)
-- [Architecture: Command System](https://docs.openacp.dev/architecture/command-system)
-- [Plugin SDK Reference](https://docs.openacp.dev/extending/plugin-sdk-reference)
-- [Getting Started: Your First Plugin](https://docs.openacp.dev/extending/getting-started-plugin)
-- [Dev Mode](https://docs.openacp.dev/extending/dev-mode)
-- [Contributing](https://github.com/Open-ACP/OpenACP/blob/main/CONTRIBUTING.md)
-`;
-}
-
-// src/cli/commands/plugin-create.ts
-async function cmdPluginCreate() {
-  p.intro("Create a new OpenACP plugin");
-  const result = await p.group(
-    {
-      name: () => p.text({
-        message: "Plugin name (e.g., @myorg/adapter-matrix)",
-        placeholder: "@myorg/my-plugin",
-        validate: (value) => {
-          if (!value || !value.trim()) return "Plugin name is required";
-          if (!/^(@[a-z0-9-]+\/)?[a-z0-9-]+$/.test(value.trim())) {
-            return "Must be a valid npm package name (lowercase, hyphens, optional @scope/)";
-          }
-          return void 0;
-        }
-      }),
-      description: () => p.text({
-        message: "Description",
-        placeholder: "A short description of your plugin"
-      }),
-      author: () => p.text({
-        message: "Author",
-        placeholder: "Your Name <email@example.com>"
-      }),
-      license: () => p.select({
-        message: "License",
-        options: [
-          { value: "MIT", label: "MIT" },
-          { value: "Apache-2.0", label: "Apache 2.0" },
-          { value: "ISC", label: "ISC" },
-          { value: "UNLICENSED", label: "Unlicensed (private)" }
-        ]
-      })
-    },
-    {
-      onCancel: () => {
-        p.cancel("Plugin creation cancelled.");
-        process.exit(0);
-      }
-    }
-  );
-  const pluginName = result.name.trim();
-  const dirName = pluginName.replace(/^@[^/]+\//, "");
-  const targetDir = path.resolve(process.cwd(), dirName);
-  if (fs.existsSync(targetDir)) {
-    p.cancel(`Directory "${dirName}" already exists.`);
-    process.exit(1);
-  }
-  const spinner2 = p.spinner();
-  spinner2.start("Scaffolding plugin...");
-  fs.mkdirSync(path.join(targetDir, "src", "__tests__"), { recursive: true });
-  const params = {
-    pluginName,
-    description: result.description || "",
-    author: result.author || "",
-    license: result.license,
-    cliVersion: getCurrentVersion()
-  };
-  const files = [
-    { relativePath: "package.json", content: generatePackageJson(params) },
-    { relativePath: "tsconfig.json", content: generateTsconfig() },
-    { relativePath: ".gitignore", content: generateGitignore() },
-    { relativePath: ".npmignore", content: generateNpmignore() },
-    { relativePath: ".editorconfig", content: generateEditorconfig() },
-    { relativePath: "README.md", content: generateReadme(params) },
-    { relativePath: "CLAUDE.md", content: generateClaudeMd(params) },
-    { relativePath: "PLUGIN_GUIDE.md", content: generatePluginGuide(params) },
-    { relativePath: path.join("src", "index.ts"), content: generatePluginSource(params) },
-    { relativePath: path.join("src", "__tests__", "index.test.ts"), content: generatePluginTest(params) }
-  ];
-  for (const file of files) {
-    fs.writeFileSync(path.join(targetDir, file.relativePath), file.content);
-  }
-  spinner2.stop("Plugin scaffolded!");
-  p.note(
-    [
-      `cd ${dirName}`,
-      "npm install",
-      "npm run build",
-      "npm test",
-      "",
-      "# Start development with hot-reload:",
-      `openacp dev .`
-    ].join("\n"),
-    "Next steps"
-  );
-  p.outro(`Plugin ${pluginName} created in ./${dirName}`);
-}
-export {
-  cmdPluginCreate
-};
-//# sourceMappingURL=plugin-create-HFKS23JY.js.map