From a855a9584bd3b619ffaa13ddfe76cfb8505e2ade Mon Sep 17 00:00:00 2001 From: woai3c <411020382@qq.com> Date: Sun, 24 May 2026 18:30:25 +0800 Subject: [PATCH] feat(plugins): plugin / marketplace / hooks system + bilingual docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a complete plugin system to x-code-cli: skills, sub-agents, slash commands, MCP servers, and lifecycle hooks bundle into installable units, discovered via subscribed marketplaces (no self-hosted catalog), and powered by a 6-event hook system that lets plugins intercept or rewrite agent behaviour. **End-to-end verified against real Anthropic Claude Code marketplaces** — installs plugins from `anthropics/claude-code` and the 203-plugin `anthropics/claude-plugins-official` correctly. ## What's in Core: ~3000 lines - `packages/core/src/plugins/` — types, paths, manifest parsing (zod; auto-detects `.x-code-plugin/plugin.json` and `.claude-plugin/plugin.json`), installer (git / github / local + subdir), marketplace (subscribe + cache + reserved-name protection), enable-state (global + project scope), loader (auto-detects conventional `skills/` / `agents/` / `commands/` / `.mcp.json` / `hooks/hooks.json`), registry, integration, consent - `packages/core/src/hooks/` — types, schema, variable expansion (`${pluginDir}` / `${cwd}` / `${env:NAME}` / …), executor (shell spawn with stdin/stdout JSON protocol, timeout, AbortSignal), bus with decision aggregators - `packages/cli/src/plugin-cli.ts` — non-interactive `xc plugin ...` subcommands with readline consent prompt + `--yes` flag Integration - Skills / sub-agents / mcp loaders gain `extraDirs` / `extraServers` so plugin contributions fold into existing registries at startup - `agent/loop.ts` emits SessionStart, UserPromptSubmit (deny / inject context), TurnComplete - `agent/tool-execution.ts` emits PreToolUse (deny / modify args), PostToolUse (modify output) - CLI startup auto-subscribes `anthropic-marketplace` → `github:anthropics/claude-plugins-official` on first run - `/skill remove` redirects to `/plugin uninstall` for plugin-sourced skills; `pluginId` carried on SkillDefinition / SubAgentDefinition CLI surface - Slash: `/plugin {list,info,install,uninstall,enable,disable,search, update,refresh,doctor,marketplace}` with marketplace sub-tree - Non-interactive: `xc plugin ` mirrors the slash family - Startup flags: `--no-plugins`, `--no-hooks` ## Real-world compatibility (verified) The PR initially landed with two schema-design bugs that made it incompatible with every real-world Claude Code marketplace. Both were caught by actually fetching `anthropics/claude-code/.claude-plugin/ marketplace.json` and `anthropics/claude-plugins-official/.claude-plugin/ marketplace.json` and running them through the parser: 1. **Wire-format mismatch.** Real Claude Code marketplaces use `source` (not `kind`) as the discriminator with values `'git-subdir'` / `'url'` / `'github'` / `'local'`, plus a plain string shortcut for monorepo subdirs (`"./plugins/foo"`). The normaliser at `normalizeMarketplaceSource` now accepts every shape we observed and maps it to the internal `PluginSource` form so the installer stays on one shape. 2. **Conventional auto-detection.** Real plugin manifests typically only declare `name` / `version` / `description` / `author` and leave `skills` / `agents` / `commands` / `mcpServers` / `hooks` unset — the loader is expected to auto-detect the conventional directories. `resolveContributions` now probes `skills/`, `agents/`, `commands/`, `.mcp.json`, `hooks/hooks.json` when the manifest is silent. Additional fixes also driven by real-world data: - Marketplace fetch path: `.claude-plugin/marketplace.json` (was `marketplace.json` at root) - Default subscription: `anthropics/claude-plugins-official` (was a non-existent `anthropics/marketplace`) - Subdir installs (`git-subdir` source / monorepo plugins): the installer now shallow-clones the whole repo, copies the subdir into a fresh temp dir, discards the rest. Previously rejected outright. - `github` source object form accepts both `{owner, repo}` and the combined `{repo: "owner/repo"}` shape that `claude-plugins-official` uses - `commit` recognised as an alias for `ref` on github sources End-to-end test (`tmp/verify-real-install.mjs`, run manually, kept out of CI to avoid network dependency): - Installs `code-review` from `anthropics/claude-code` (monorepo subdir) - Loads via `loadAllPlugins` - Verifies `commandsDir` was auto-detected from `commands/` even though the manifest doesn't declare it - Installs `pr-review-toolkit` (larger, also subdir) - Both succeed cleanly Compatibility summary - Plugin manifest reads `.claude-plugin/plugin.json` in addition to the native path, so Claude Code / Codex plugins install unmodified - MCP server config schema unchanged — copy from `~/.claude/config.json` - Gemini extensions explicitly rejected with friendly error - Reserved marketplace names (`anthropic-marketplace`, `claude-plugins`, `x-code-official`) only accept their canonical GitHub orgs to prevent impersonation ## Docs (bilingual, `*.md` zh + `*.en.md` en) — ~2400 lines - `docs/skills.{md,en.md}` — SKILL.md format, `/skill` commands - `docs/sub-agents.{md,en.md}` — built-in + custom .md format - `docs/mcp.{md,en.md}` — mcpServers config, OAuth flow, /mcp commands - `docs/knowledge.{md,en.md}` — AGENTS.md 5-layer load + auto-memory - `docs/plugins.{md,en.md}` — install / manage / troubleshoot - `docs/marketplace.{md,en.md}` — schema, subscribe, self-host; source-shape table covers every Claude Code wire form - `docs/hooks.{md,en.md}` — 6 events, stdin/stdout protocol, examples - `docs/plugin-authoring.{md,en.md}` — manifest schema; explains the convention-based auto-detection so authors know they can omit declared paths for the standard layout README zh + en updated: feature list now mentions skills / MCP / plugins / hooks (all previously undocumented), new "Detailed Usage Docs" section links the 8 docs above. ## Tests - ~50 new tests for the plugin + hook subsystem, including a regression test that enumerates every Claude Code source wire form (`./plugins/foo`, `github:owner/repo`, `git-subdir`, `url`, `github` combined `repo: owner/repo`, etc.) - ~54 ceremony tests pruned across the whole suite - 575 tests pass, typecheck / lint / format clean ## Known limitations - `userConfig` field is parsed but **not actually prompted at install time yet** — the install consent shows the declared fields but doesn't ask for values - `/plugin refresh` prints "restart xc" — no in-process live reload - `/plugin enable|disable` writes global scope only (no `--scope` flag) - Multi-version coexistence / rollback not implemented - `commands/` plugin contribution is auto-detected and surfaced in `/plugin info`, but the CLI has no file-based slash command loader today — the directory is recognised, not yet wired - `sha` integrity-pin field on marketplace sources is parsed but not verified --- README.en.md | 40 +- README.md | 72 +- docs/hooks.en.md | 307 ++++++++ docs/hooks.md | 258 +++++++ docs/knowledge.en.md | 191 +++++ docs/knowledge.md | 166 +++++ docs/marketplace.en.md | 269 +++++++ docs/marketplace.md | 226 ++++++ docs/mcp.en.md | 265 +++++++ docs/mcp.md | 235 ++++++ docs/plugin-authoring.en.md | 229 ++++++ docs/plugin-authoring.md | 193 +++++ docs/plugins.en.md | 307 ++++++++ docs/plugins.md | 260 +++++++ docs/skills.en.md | 249 +++++++ docs/skills.md | 234 ++++++ docs/sub-agents.en.md | 179 +++++ docs/sub-agents.md | 155 ++++ packages/cli/src/index.ts | 117 ++- packages/cli/src/plugin-cli.ts | 667 ++++++++++++++++++ packages/cli/src/ui/components/App.tsx | 640 ++++++++++++++++- packages/core/src/agent/compression.ts | 71 ++ packages/core/src/agent/loop.ts | 106 ++- packages/core/src/agent/memory-extractor.ts | 10 +- packages/core/src/agent/sub-agents/index.ts | 3 +- packages/core/src/agent/sub-agents/loader.ts | 42 +- .../core/src/agent/sub-agents/registry.ts | 55 +- packages/core/src/agent/sub-agents/runner.ts | 67 ++ packages/core/src/agent/sub-agents/types.ts | 5 +- packages/core/src/agent/tool-execution.ts | 74 +- packages/core/src/commands/index.ts | 6 + packages/core/src/commands/loader.ts | 104 +++ packages/core/src/commands/registry.ts | 117 +++ packages/core/src/commands/types.ts | 47 ++ packages/core/src/hooks/bus.ts | 192 +++++ packages/core/src/hooks/config-schema.ts | 84 +++ packages/core/src/hooks/executor.ts | 198 ++++++ packages/core/src/hooks/index.ts | 19 + packages/core/src/hooks/registry.ts | 65 ++ packages/core/src/hooks/types.ts | 179 +++++ packages/core/src/hooks/variables.ts | 90 +++ packages/core/src/index.ts | 100 ++- packages/core/src/knowledge/auto-memory.ts | 16 +- packages/core/src/knowledge/loader.ts | 8 +- packages/core/src/mcp/loader.ts | 27 +- packages/core/src/plugins/consent.ts | 124 ++++ packages/core/src/plugins/enable-state.ts | 188 +++++ packages/core/src/plugins/installer.ts | 431 +++++++++++ packages/core/src/plugins/integration.ts | 251 +++++++ packages/core/src/plugins/loader.ts | 307 ++++++++ packages/core/src/plugins/manifest.ts | 174 +++++ packages/core/src/plugins/marketplace.ts | 557 +++++++++++++++ packages/core/src/plugins/paths.ts | 96 +++ packages/core/src/plugins/refresh.ts | 120 ++++ packages/core/src/plugins/registry.ts | 111 +++ packages/core/src/plugins/types.ts | 234 ++++++ packages/core/src/plugins/user-config.ts | 110 +++ packages/core/src/skills/loader.ts | 55 +- packages/core/src/skills/registry.ts | 19 +- packages/core/src/skills/settings.ts | 14 +- packages/core/src/types/index.ts | 34 +- packages/core/src/utils.ts | 46 +- packages/core/tests/api-errors.test.ts | 6 - packages/core/tests/cache-control.test.ts | 21 - packages/core/tests/commands.test.ts | 148 ++++ packages/core/tests/context-window.test.ts | 4 - packages/core/tests/diff.test.ts | 5 - packages/core/tests/file-ingest.test.ts | 12 - packages/core/tests/glob-tool.test.ts | 15 - packages/core/tests/hooks.test.ts | 360 ++++++++++ packages/core/tests/knowledge.test.ts | 8 - packages/core/tests/lru-cache.test.ts | 24 - packages/core/tests/mcp-config-schema.test.ts | 5 - packages/core/tests/media-type.test.ts | 5 - packages/core/tests/message-helpers.test.ts | 15 - packages/core/tests/messages.test.ts | 6 - packages/core/tests/permissions.test.ts | 4 - packages/core/tests/plugins-consent.test.ts | 158 +++++ .../core/tests/plugins-install-load.test.ts | 454 ++++++++++++ .../core/tests/plugins-integration.test.ts | 218 ++++++ packages/core/tests/plugins-manifest.test.ts | 125 ++++ .../core/tests/plugins-marketplace.test.ts | 238 +++++++ packages/core/tests/shell-error.test.ts | 14 - packages/core/tests/skills.test.ts | 66 +- packages/core/tests/tool-registry.test.ts | 5 - .../core/tests/tool-result-sanitize.test.ts | 8 - packages/core/tests/truncate.test.ts | 4 - packages/core/tests/vision-fallback.test.ts | 9 - 88 files changed, 11427 insertions(+), 325 deletions(-) create mode 100644 docs/hooks.en.md create mode 100644 docs/hooks.md create mode 100644 docs/knowledge.en.md create mode 100644 docs/knowledge.md create mode 100644 docs/marketplace.en.md create mode 100644 docs/marketplace.md create mode 100644 docs/mcp.en.md create mode 100644 docs/mcp.md create mode 100644 docs/plugin-authoring.en.md create mode 100644 docs/plugin-authoring.md create mode 100644 docs/plugins.en.md create mode 100644 docs/plugins.md create mode 100644 docs/skills.en.md create mode 100644 docs/skills.md create mode 100644 docs/sub-agents.en.md create mode 100644 docs/sub-agents.md create mode 100644 packages/cli/src/plugin-cli.ts create mode 100644 packages/core/src/commands/index.ts create mode 100644 packages/core/src/commands/loader.ts create mode 100644 packages/core/src/commands/registry.ts create mode 100644 packages/core/src/commands/types.ts create mode 100644 packages/core/src/hooks/bus.ts create mode 100644 packages/core/src/hooks/config-schema.ts create mode 100644 packages/core/src/hooks/executor.ts create mode 100644 packages/core/src/hooks/index.ts create mode 100644 packages/core/src/hooks/registry.ts create mode 100644 packages/core/src/hooks/types.ts create mode 100644 packages/core/src/hooks/variables.ts create mode 100644 packages/core/src/plugins/consent.ts create mode 100644 packages/core/src/plugins/enable-state.ts create mode 100644 packages/core/src/plugins/installer.ts create mode 100644 packages/core/src/plugins/integration.ts create mode 100644 packages/core/src/plugins/loader.ts create mode 100644 packages/core/src/plugins/manifest.ts create mode 100644 packages/core/src/plugins/marketplace.ts create mode 100644 packages/core/src/plugins/paths.ts create mode 100644 packages/core/src/plugins/refresh.ts create mode 100644 packages/core/src/plugins/registry.ts create mode 100644 packages/core/src/plugins/types.ts create mode 100644 packages/core/src/plugins/user-config.ts create mode 100644 packages/core/tests/commands.test.ts create mode 100644 packages/core/tests/hooks.test.ts create mode 100644 packages/core/tests/plugins-consent.test.ts create mode 100644 packages/core/tests/plugins-install-load.test.ts create mode 100644 packages/core/tests/plugins-integration.test.ts create mode 100644 packages/core/tests/plugins-manifest.test.ts create mode 100644 packages/core/tests/plugins-marketplace.test.ts diff --git a/README.en.md b/README.en.md index 7b408c1..568f61d 100644 --- a/README.en.md +++ b/README.en.md @@ -21,15 +21,19 @@ X-Code CLI supports the major LLM providers (Claude, GPT, DeepSeek, Gemini, Qwen - **Session resumption** — `--continue` resumes the most recent session; `--resume` opens a session picker or jumps directly by ID - **Knowledge system** — layered context loading (global AGENTS.md / global auto-memory / project AGENTS.md chain / project auto-memory / project-root `AGENTS.local.md`); subpackage AGENTS.md overrides the repo root. Each directory prefers `AGENTS.md` and falls back to `CLAUDE.md` when absent (Claude Code compat, read-only; `/init` only reads/writes `AGENTS.md`) - **Auto-memory** — after each turn, durable facts from the conversation (user preferences, corrections, project state, external pointers) are automatically saved and loaded as context next session; `/memory` to inspect entries, edit `auto.md` directly to modify +- **Skills** — describe reusable workflow templates as `SKILL.md` (e.g. code-review checklists, PR-review playbooks); trigger via `/` in the chat; `/skill` manages +- **MCP integration** — first-class Model Context Protocol support (stdio + HTTP with OAuth) via `/mcp`; server tools fold into the agent's tool set +- **Plugin system** — bundle skills / sub-agents / MCP servers / hooks into installable units, with subscribed marketplaces driving discovery. Manifest is byte-compatible with Claude Code's `.claude-plugin/plugin.json`, so its ecosystem installs directly. See [docs/plugins.md](./docs/plugins.md) +- **Hooks** — plugins can register ten lifecycle event callbacks (`SessionStart` / `UserPromptSubmit` / `PreToolUse` / `PostToolUse` / `PreCompact` / `PostCompact` / `SubagentStart` / `SubagentStop` / `TurnComplete` / `SessionEnd`) as shell commands that intercept or rewrite agent behaviour; supports `commandWindows` / `commandDarwin` / `commandLinux` per-platform overrides and a persistent `${pluginDataDir}` variable. See [docs/hooks.md](./docs/hooks.md) - **File attachments** — `@path` mentions or bare absolute paths in the prompt auto-ingest text / code / PDF / docx / xlsx / pptx / images - **Vision sub-agent** — text-only providers such as DeepSeek can borrow another configured vision model to generate image descriptions - **Theme switching** — `/theme` cycles through UI themes, controlling diff colors and syntax-highlight palette -- **Slash commands** — quick controls including `/help`, `/model`, `/thinking`, `/theme`, `/plan`, `/resume`, `/usage`, `/usage-history`, `/memory`, `/review`, and more +- **Slash commands** — quick controls including `/help`, `/model`, `/thinking`, `/theme`, `/plan`, `/resume`, `/usage`, `/usage-history`, `/memory`, `/review`, `/skill`, `/mcp`, `/plugin`, and more - **Unified thinking-mode toggle** — `/thinking on|off` consolidates each provider's bespoke thinking/reasoning parameters into a single switch - **Multiline input** — `Alt+Enter` (or `Option+Enter` on macOS) or a trailing `\` followed by Enter inserts a newline; plain Enter still submits - **Input history recall** — press `↑` / `↓` on an empty prompt to walk through previously submitted messages - **Cross-platform** — runs on Windows, macOS, and Linux -- **Non-interactive mode** — `--print` with pipes for scripts and CI +- **Non-interactive mode** — `--print` with pipes for scripts and CI; `xc plugin <...>` for non-interactive plugin management ## Install @@ -176,10 +180,22 @@ xc [options] [prompt] --continue, -c Resume the most recent session in this project (no picker) --resume, -r [id] Resume a session: no argument opens the picker; with an ID jumps directly --max-turns Cap on agent loop turns per submit (optional; default: unlimited) +--no-plugins Disable the plugin system entirely (only built-in contributions; useful for triage) +--no-hooks Plugins still load, but skip all hook execution --version, -v Show version --help, -h Show help ``` +### Non-interactive subcommands + +```text +xc plugin Manage plugins (list / install / uninstall / enable / disable / search / update / info / doctor / marketplace) +xc plugin install [--yes] Install a plugin; non-TTY defaults to deny, --yes skips confirmation +xc plugin marketplace Manage marketplace subscriptions (list / add / remove / refresh / info) +``` + +Full usage: [docs/plugins.md](./docs/plugins.md). + ## Slash Commands | Command | Description | @@ -197,6 +213,9 @@ xc [options] [prompt] | `/init` | Analyze the codebase and create or update `AGENTS.md` at the project root | | `/review [PR#]` | Review a GitHub PR (no argument lists open PRs); requires `gh` to be installed locally | | `/memory` | List auto-memory entries (project + global, grouped by category) | +| `/skill ` | Manage Skills (`list` / `install` / `refresh` / `enable` / `disable` / `remove`) | +| `/mcp ` | Manage MCP servers (`list` / `tools` / `add` / `remove` / `auth` / `refresh`, etc.) | +| `/plugin ` | Manage plugins and marketplaces — see [docs/plugins.md](./docs/plugins.md) | | `/exit` | Save the session and exit | ### Thinking-mode notes @@ -261,6 +280,23 @@ Per-provider support: - For complex UI reproduction or pixel-level layout review, the text description may omit fine details - For such scenarios, switch to a multimodal model (Claude, Gemini, GLM-4V, etc.) via `/model` and continue the conversation directly +## Detailed Usage Docs + +This README is the entry view. Each feature has a focused doc under [`docs/`](./docs/) (bilingual — Chinese as `*.md`, English as `*.en.md`): + +| Doc | What it covers | +| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| [`docs/skills.en.md`](./docs/skills.en.md) | Write reusable workflow templates, trigger with `/` | +| [`docs/sub-agents.en.md`](./docs/sub-agents.en.md) | Use built-in / custom sub-agents via the `task` tool | +| [`docs/mcp.en.md`](./docs/mcp.en.md) | Configure MCP servers (stdio / HTTP / OAuth) + `/mcp` commands | +| [`docs/knowledge.en.md`](./docs/knowledge.en.md) | Knowledge base (`AGENTS.md` / `CLAUDE.md` 5-layer load) and auto-memory | +| [`docs/plugins.en.md`](./docs/plugins.en.md) | Install / manage plugins, `/plugin` slash commands, `xc plugin` non-interactive form | +| [`docs/marketplace.en.md`](./docs/marketplace.en.md) | Subscribe to / self-host a plugin marketplace | +| [`docs/hooks.en.md`](./docs/hooks.en.md) | Plugins hook into 10 agent lifecycle events (decision protocol, cross-platform commands, worked examples) | +| [`docs/plugin-authoring.en.md`](./docs/plugin-authoring.en.md) | Write your own plugin (full manifest schema, layout conventions, iteration loop) | + +**Claude Code compatibility**: the plugin loader recognises both `.x-code-plugin/plugin.json` and `.claude-plugin/plugin.json`, so plugins authored for Claude Code / Codex install directly; the MCP config schema is identical to Claude Code's. First-run automatically subscribes to `anthropic-marketplace`. + ## Troubleshooting To capture a debug log, set `DEBUG_STDOUT=1` in the current session and launch. Shell syntax varies — pick the one that matches your shell: diff --git a/README.md b/README.md index 6e33a98..365cb1b 100644 --- a/README.md +++ b/README.md @@ -21,15 +21,19 @@ X-Code CLI 支持主流大模型（Claude、GPT、DeepSeek、Gemini、Qwen、Gro - **会话恢复**：`--continue` 恢复最近一次会话；`--resume` 打开历史会话选择器或按 ID 直达 - **知识库系统**：分层加载（全局 AGENTS.md / 全局自动记忆 / 项目 AGENTS.md chain / 项目自动记忆 / 项目根 `AGENTS.local.md`），项目子包可覆盖根级约定；每个目录优先读 `AGENTS.md`，缺失时回退到 `CLAUDE.md`（Claude Code 兼容,只读不写,`/init` 只读写 `AGENTS.md`） - **自动记忆**：每轮对话结束后自动从最近转录里筛选值得长期记住的事实(用户偏好、纠正反馈、项目状态、外部资源指针),下次会话作为上下文加载;`/memory` 查看当前条目,直接编辑 `auto.md` 修改 +- **Skills**：以 `SKILL.md` 描述可复用工作流模板（如代码审查清单、PR 评审范式），交互中通过 `/` 触发；`/skill` 管理 +- **MCP 集成**：支持 Model Context Protocol 服务器（stdio + HTTP，含 OAuth），由 `/mcp` 管理；服务器工具自动并入 agent 工具集 +- **插件系统**：将 skill / sub-agent / MCP 服务器 / hooks 打包成可分发单元，统一安装/启用/卸载；订阅 marketplace 一键发现插件；Manifest 与 Claude Code 字节级兼容，可直接安装其生态的插件。详见 [docs/plugins.md](./docs/plugins.md) +- **Hooks**：插件可注册 10 个生命周期事件回调（`SessionStart` / `UserPromptSubmit` / `PreToolUse` / `PostToolUse` / `PreCompact` / `PostCompact` / `SubagentStart` / `SubagentStop` / `TurnComplete` / `SessionEnd`），用 shell 命令拦截/改写 agent 行为；支持 `commandWindows` / `commandDarwin` / `commandLinux` 跨平台命令覆盖、`${pluginDataDir}` 持久数据目录。详见 [docs/hooks.md](./docs/hooks.md) - **文件附件**：在提示词中以 `@path` 或裸绝对路径引用文件，自动识别 text / code / PDF / docx / xlsx / pptx / 图片 - **视觉子 agent**：DeepSeek 等纯文本模型可借用其他多模态厂商生成图片描述 - **主题切换**：`/theme` 切换 UI 主题，控制 diff 配色和语法高亮风格 -- **斜杠命令**：`/help`、`/model`、`/thinking`、`/theme`、`/plan`、`/resume`、`/usage`、`/usage-history`、`/memory`、`/review` 等 +- **斜杠命令**：`/help`、`/model`、`/thinking`、`/theme`、`/plan`、`/resume`、`/usage`、`/usage-history`、`/memory`、`/review`、`/skill`、`/mcp`、`/plugin` 等 - **统一思考模式开关**：`/thinking on|off` 将不同厂商各异的 thinking/reasoning 参数统一为单一开关 - **多行输入**：`Alt+Enter`（macOS 为 `Option+Enter`）或行尾 `\` 后 Enter 插入换行；普通 Enter 直接发送 - **历史输入回溯**：输入框为空时按 `↑`/`↓` 召回已提交的提示词 - **跨平台**：支持 Windows、macOS、Linux -- **非交互模式**：`--print` 配合管道输入，可嵌入脚本与 CI +- **非交互模式**：`--print` 配合管道输入，可嵌入脚本与 CI；`xc plugin <...>` 非交互管理插件 ## 安装 @@ -176,28 +180,43 @@ xc [options] [prompt] --continue, -c 恢复当前项目最近一次会话（无选择器） --resume, -r [id] 恢复会话：无参数打开选择器，指定 ID 直达 --max-turns Agent 循环每次提交的轮次上限（可选，默认无上限） +--no-plugins 禁用插件系统（仅加载内置贡献，用于排障） +--no-hooks 插件正常加载，但跳过所有 hook 执行 --version, -v 显示版本号 --help, -h 显示帮助信息 ``` +### 非交互子命令 + +```text +xc plugin 管理插件（list / install / uninstall / enable / disable / search / update / info / doctor / marketplace） +xc plugin install [--yes] 安装插件；非 TTY 默认拒绝，--yes 跳过确认 +xc plugin marketplace 管理插件市场订阅（list / add / remove / refresh / info） +``` + +完整用法见 [docs/plugins.md](./docs/plugins.md)。 + ## 斜杠命令 -| 命令 | 说明 | -| --------------------- | ------------------------------------------------------------ | -| `/help` | 查看所有可用命令 | -| `/model [alias]` | 切换模型或查看可用模型列表 | -| `/thinking [on\|off]` | 启用 / 禁用思考模式（无参数时弹出选择器） | -| `/theme [name]` | 切换 UI 主题（无参数时弹出选择器），控制 diff 配色和语法高亮 | -| `/plan [on\|off]` | 启用 / 禁用 Plan 模式（无参数时切换当前状态） | -| `/usage` | 查看本次会话 Token 用量（含缓存命中率） | -| `/usage-history` | 列出当前项目历史会话，可交互选择查看详情 | -| `/clear` | 清空当前会话 | -| `/compact` | 手动压缩上下文 | -| `/resume` | 从当前项目的历史会话中选择一个恢复 | -| `/init` | 分析代码库后在项目根创建或更新 `AGENTS.md` | -| `/review [PR号]` | 评审 GitHub PR（无参数列出开放 PR；需本地装好 `gh`） | -| `/memory` | 查看当前自动记忆条目（project + global,按类目分组） | -| `/exit` | 保存会话并退出 | +| 命令 | 说明 | +| --------------------- | ------------------------------------------------------------------------------- | +| `/help` | 查看所有可用命令 | +| `/model [alias]` | 切换模型或查看可用模型列表 | +| `/thinking [on\|off]` | 启用 / 禁用思考模式（无参数时弹出选择器） | +| `/theme [name]` | 切换 UI 主题（无参数时弹出选择器），控制 diff 配色和语法高亮 | +| `/plan [on\|off]` | 启用 / 禁用 Plan 模式（无参数时切换当前状态） | +| `/usage` | 查看本次会话 Token 用量（含缓存命中率） | +| `/usage-history` | 列出当前项目历史会话，可交互选择查看详情 | +| `/clear` | 清空当前会话 | +| `/compact` | 手动压缩上下文 | +| `/resume` | 从当前项目的历史会话中选择一个恢复 | +| `/init` | 分析代码库后在项目根创建或更新 `AGENTS.md` | +| `/review [PR号]` | 评审 GitHub PR（无参数列出开放 PR；需本地装好 `gh`） | +| `/memory` | 查看当前自动记忆条目（project + global,按类目分组） | +| `/skill ` | 管理 Skills（`list` / `install` / `refresh` / `enable` / `disable` / `remove`） | +| `/mcp ` | 管理 MCP 服务器（`list` / `tools` / `add` / `remove` / `auth` / `refresh` 等） | +| `/plugin ` | 管理插件与 marketplace（详见 [docs/plugins.md](./docs/plugins.md)） | +| `/exit` | 保存会话并退出 | ### 思考模式说明 @@ -261,6 +280,23 @@ X-Code CLI 支持的 8 家厂商对思考 / 推理模式的默认行为存在差 - 复杂 UI 还原、像素级布局校验等场景下，文字描述可能丢失细节 - 此类场景建议通过 `/model` 切换至 Claude、Gemini、GLM-4V 等多模态模型直接处理 +## 详细使用文档 + +README 是入门视图，每个功能的完整用法在 [`docs/`](./docs/) 下（中英对照，中文为 `*.md`，英文为 `*.en.md`）： + +| 文档 | 你想做什么 | +| -------------------------------------------------------- | ------------------------------------------------------------------- | +| [`docs/skills.md`](./docs/skills.md) | 写复用工作流模板，`/` 触发 | +| [`docs/sub-agents.md`](./docs/sub-agents.md) | 用内置 / 自定义子 agent 委派子任务（`task` 工具） | +| [`docs/mcp.md`](./docs/mcp.md) | 配 MCP 服务器（stdio / HTTP / OAuth）+ `/mcp` 命令 | +| [`docs/knowledge.md`](./docs/knowledge.md) | 知识库（`AGENTS.md` / `CLAUDE.md` 5 层加载）与自动记忆 | +| [`docs/plugins.md`](./docs/plugins.md) | 安装/管理插件、`/plugin` 命令、`xc plugin` 子命令 | +| [`docs/marketplace.md`](./docs/marketplace.md) | 订阅 / 自建 plugin marketplace | +| [`docs/hooks.md`](./docs/hooks.md) | 插件挂 agent 生命周期 hook（10 个事件、决策协议、跨平台命令、示例） | +| [`docs/plugin-authoring.md`](./docs/plugin-authoring.md) | 自己写插件（完整 manifest schema、目录约定、迭代流程） | + +**Claude Code 兼容**：插件 manifest 同时识别 `.x-code-plugin/plugin.json` 与 `.claude-plugin/plugin.json`，Claude Code / Codex 生态的插件可直接安装；MCP 配置文件与 Claude Code 完全一致。首次启动自动订阅 `anthropic-marketplace`。 + ## 故障排查 如需调试或抓取运行日志，可在当前会话临时设置 `DEBUG_STDOUT=1` 环境变量启动。不同 shell 的语法不同，请按所用 shell 选择对应命令： diff --git a/docs/hooks.en.md b/docs/hooks.en.md new file mode 100644 index 0000000..68bf5dc --- /dev/null +++ b/docs/hooks.en.md @@ -0,0 +1,307 @@ +# Hooks + +A hook is a shell command a plugin registers against one of ten agent +lifecycle events. The CLI emits an event payload to the hook on +**stdin** as one JSON line; the hook may reply on **stdout** with a +one-line JSON `HookDecision` to influence what the agent does next. + +See also: [Authoring a plugin](plugin-authoring.md) · +[Plugins user guide](plugins.md) + +--- + +## Why shell, not an SDK + +Lowest barrier to entry. A bash one-liner or a tiny `node hook.js` +script gets you the same expressiveness as a programmatic API without +any code running inside our process. + +This also keeps the surface area small. The CLI doesn't ship a plugin +runtime — just spawns a child, pipes JSON, reads the answer. + +--- + +## The ten events + +| Event | Fires | Can decide | Typical use | +| ------------------ | ---------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------- | +| `SessionStart` | After CLI startup, before the first user prompt | no | warm up state, prep env | +| `UserPromptSubmit` | Just before the user's message hits the model | **allow / deny / inject context** | inject sprint info, redact secrets, gate by topic | +| `PreToolUse` | Before any tool is dispatched (writeFile, shell, MCP, sub-agent, …) | **allow / deny / modify args** | block dangerous paths, rewrite args, audit gate | +| `PostToolUse` | After a tool produces a result | **modify output** | rewrite tool result, append audit metadata | +| `PreCompact` | Before context compression runs (proactive threshold or reactive "too long") | no | checkpoint / persist state before messages trim | +| `PostCompact` | After compression finishes | no | notify, log what was reclaimed | +| `SubagentStart` | When the `task` tool spawns a sub-agent | no | audit which sub-agents fire, record start time | +| `SubagentStop` | When a sub-agent finishes (`completed` / `aborted` / `failed`) | no | measure sub-agent duration and token usage | +| `TurnComplete` | After each round of LLM streaming completes | no | notifications, metrics | +| `SessionEnd` | On CLI shutdown | no | flush logs, post a "session done" message | + +`SessionEnd` is fire-and-forget — the CLI exits without waiting for +hooks to complete. Don't put critical operations there; use +`TurnComplete` if you need guaranteed delivery. + +--- + +## Manifest declaration + +In your plugin's `plugin.json` (either inline or via a `hooks.json` +path): + +```jsonc +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "writeFile|edit", // regex against tool name + "command": "node ${pluginDir}/hooks/lint.js", + // Optional per-OS overrides. When set, the matching one replaces + // `command` on that platform. Unset platforms fall back to the + // base `command` — so a portable default plus a Windows-only + // override is a common pattern. + "commandWindows": "node \"${pluginDir}/hooks/lint.js\"", + "commandDarwin": "node ${pluginDir}/hooks/lint.js", // rarely needs to differ + "commandLinux": "node ${pluginDir}/hooks/lint.js", + "timeout": 5000, // ms (default 5000, cap 30000) + "description": "Lint before writing", + "failurePolicy": "allow", // or "block" (default "allow") + }, + ], + "UserPromptSubmit": [{ "command": "${pluginDir}/hooks/inject-context.sh" }], + }, +} +``` + +**Why ship all three platforms**: plugins end up installed on Windows / +Linux / macOS. A `bash foo.sh` default silently breaks for Windows +users. Make the base `command` a portable form (e.g. `node script.js`), +then add a platform-specific `commandWindows` / `commandDarwin` / +`commandLinux` only where one OS genuinely needs different syntax +(path quoting, PowerShell idiom, `.cmd` suffix). Don't ship plugins +that only work on your dev machine. + +Or pull it into a separate file: + +```jsonc +{ "hooks": "./hooks/hooks.json" } +``` + +with `./hooks/hooks.json` containing the same `{ PreToolUse: [...], ... }` +shape directly (no outer `hooks` wrapper). + +--- + +## Variable expansion in `command` + +| Variable | Expands to | +| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `${pluginDir}` | Plugin install dir (the versioned cache dir; wiped on reinstall / upgrade) | +| `${pluginDataDir}` | The plugin's **persistent data dir** (`~/.x-code/plugins/data//`). Survives uninstall+reinstall and version upgrades — use for indexes, caches, user prefs. | +| | Auto-`mkdir -p` on first substitution, so the hook can write there immediately. | +| `${cwd}` | Current working directory at event-emit time | +| `${homedir}` | `os.homedir()` | +| `${sep}` | OS path separator (`\` on Windows, `/` elsewhere) | +| `${env:NAME}` | `process.env.NAME` (empty string if unset) | + +Unknown variables are left **verbatim** in the command string — a typo +like `${plugindir}` shows up as a "file not found" shell error, not as +a silent empty substitution. That's deliberate so typos surface. + +**`${pluginDir}` vs `${pluginDataDir}`**: the former is where the +plugin's code lives (gone on uninstall / upgrade), the latter is where +its runtime data lives (preserved across versions). A "learned coding +style" cache should write to `${pluginDataDir}` so the user's history +isn't wiped on upgrade. + +--- + +## Stdin payload + +Every hook receives a single JSON line on stdin. Top-level shape: + +```jsonc +{ + "event": "PreToolUse", // event name + "session": { + // every event has this + "cwd": "/abs/path/to/project", + "modelId": "anthropic:claude-sonnet-4-6", + }, + "plugin": { + // identifies which plugin's + "id": "linear@anthropic-marketplace", // hook is running + "dir": "/abs/.x-code/plugins/cache/anthropic-marketplace/linear/1.2.0", + }, + + // Event-specific extras flattened in at top level: + "tool": { + // PreToolUse, PostToolUse + "name": "writeFile", + "args": { "path": "src/foo.ts", "content": "..." }, + "callId": "call_abc123", + + // PostToolUse only: + "output": "wrote 42 bytes", + "isError": false, + }, + "prompt": "Refactor X to do Y", // UserPromptSubmit only + "turn": 3, // TurnComplete only + "tokenUsage": { + // TurnComplete only, also SubagentStop + "inputTokens": 4321, + "outputTokens": 567, + "totalTokens": 4888, + }, + + // PreCompact / PostCompact + "trigger": "proactive", // or "reactive" (i.e. "prompt too long" recovery) + "messageCount": 87, // messages before (PreCompact) or after (PostCompact) + "tokenEstimate": 184_000, // PreCompact only + "summary": "...", // PostCompact only — empty string means light-compact path (no LLM summary) + + // SubagentStart / SubagentStop + "agent": { + "name": "code-reviewer", + "description": "review the diff", + "prompt": "", // SubagentStart only + }, + "durationMs": 12_345, // SubagentStop only + "outcome": "completed", // SubagentStop only: completed / aborted / failed +} +``` + +--- + +## Stdout decision + +A hook may reply with a single JSON line on stdout. Empty stdout = the +default `allow` (most fire-and-forget hooks output nothing). Anything +unparseable as JSON is treated as `allow` plus a debug-log breadcrumb. + +```jsonc +// Default — agent proceeds normally +{ "decision": "allow" } + +// Optional context to attach (UserPromptSubmit / PostToolUse) +{ "decision": "allow", "context": "Current sprint: Sprint 42" } + +// Stop the agent from doing the thing +{ "decision": "deny", "reason": "Editing prod config is forbidden" } + +// Rewrite the tool args (PreToolUse) or output (PostToolUse) +{ "decision": "modify", "args": { "path": "/safer/path" } } +{ "decision": "modify", "output": "[redacted]" } +{ "decision": "modify", "context": "Sprint 42 in progress" } +``` + +What gets applied: + +| Event | `deny` | `modify.args` | `modify.output` | `context` | +| ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------- | --------------------------------------- | ------------------------------- | +| `UserPromptSubmit` | blocks the prompt with a synthetic assistant message | — | — | prepended into the user message | +| `PreToolUse` | replaces the tool result with a "denied by hook" message | replaces the input args the tool actually receives | — | (ignored) | +| `PostToolUse` | (deny ignored — too late) | — | replaces the tool result the model sees | (ignored) | +| `SessionStart` / `PreCompact` / `PostCompact` / `SubagentStart` / `SubagentStop` / `TurnComplete` / `SessionEnd` | (no decisions — stdout ignored) | — | — | — | + +When multiple hooks match the same event: + +- **Decision events** run serially in registration order. A `deny` + short-circuits the remaining hooks. +- **Fire-and-forget events** run in parallel. +- `modify` decisions stack: later modifies override earlier ones. + +--- + +## Failure handling + +A hook that crashes, times out, or exits non-zero is treated as `allow` +by default and a warning lands in `~/.x-code/logs/debug.log` (set +`DEBUG_STDOUT=1` to enable that log). + +Set `"failurePolicy": "block"` on the entry to flip that for one hook — +non-zero exit then becomes a `deny`. Use this only for gating hooks +the user actively wants strict; the default-allow stance exists to +ensure a broken hook never wedges the agent. + +The 30-second timeout cap is a hard ceiling, not a default. Default is +5 seconds. Authors who need longer should split work into background +processes that the hook kicks off and returns immediately. + +--- + +## Abort behaviour + +Esc / Ctrl+C during a slow hook propagates via `AbortSignal` through +execa's `cancelSignal` and SIGKILLs the child process. Same machinery +the shell tool uses. Hooks don't need to do anything special — they +just get killed. + +--- + +## End-to-end example: lint before writes + +```js +// hooks/lint.js — fired on PreToolUse for writeFile|edit +const data = require('fs').readFileSync(0, 'utf-8') // read stdin +const event = JSON.parse(data) +const filePath = event.tool.args.path + +if (!filePath.endsWith('.ts')) { + console.log(JSON.stringify({ decision: 'allow' })) + process.exit(0) +} + +const { execSync } = require('child_process') +try { + execSync(`eslint --quiet "${filePath}"`, { stdio: 'pipe' }) + console.log(JSON.stringify({ decision: 'allow' })) +} catch (e) { + console.log( + JSON.stringify({ + decision: 'deny', + reason: `Lint failed:\n${e.stdout?.toString() || e.message}`, + }), + ) +} +``` + +Manifest: + +```jsonc +{ + "name": "ts-lint-gate", + "version": "0.1.0", + "hooks": { + "PreToolUse": [{ "matcher": "writeFile|edit", "command": "node ${pluginDir}/hooks/lint.js" }], + }, +} +``` + +The agent now sees a `deny` whenever it tries to write a TypeScript +file that fails lint — and the deny's `reason` shows up in the tool +result, so the model can see why and adjust. + +--- + +## Sub-agent behaviour + +Sub-agents inherit the parent's `HookBus`, so `PreToolUse` / +`PostToolUse` fire for tool calls inside a sub-agent run. This is +intentional — plugin authors wanting to audit ALL model behaviour can +do so. `SessionStart` / `SessionEnd` only fire for the outer session, +not per sub-agent. + +Beware recursion: if a hook itself invokes `xc` or another agent, its +own tool calls will also fire `PreToolUse`. Keep hook logic narrow, +and prefer the `matcher` regex to constrain which tools trigger them. + +--- + +## Suppressing hooks for a session + +```bash +xc --no-hooks # plugins still load, hooks just don't run +xc --no-plugins # nuclear option: no plugin loading at all +``` + +Useful for diagnosing whether a hook is the cause of a hang or +slowdown. diff --git a/docs/hooks.md b/docs/hooks.md new file mode 100644 index 0000000..cb0ec44 --- /dev/null +++ b/docs/hooks.md @@ -0,0 +1,258 @@ +# Hooks — 使用指南 + +Hook 是插件挂在 agent 生命周期事件上的 shell 命令。CLI 用 stdin 发 JSON 事件给你，你可以用 stdout 返回 JSON 决策来影响 agent 接下来怎么走。 + +英文版：[hooks.en.md](./hooks.en.md) · 相关：[plugins.md](./plugins.md) · [plugin-authoring.md](./plugin-authoring.md) + +--- + +## 为什么是 shell 而不是 SDK + +门槛最低。一段 bash 一行命令或者 `node hook.js` 短脚本就是完整的 hook，不需要在我们进程内跑插件代码——CLI 只负责拉子进程、传 JSON、读返回。 + +--- + +## 10 个事件 + +| Event | 触发时机 | 能决策 | 典型用途 | +| ------------------ | ---------------------------------------------------------------------------- | -------------------------------- | ----------------------------------------- | +| `SessionStart` | CLI 启动后，第一次用户提示前 | ❌ | 预热状态、设置环境 | +| `UserPromptSubmit` | 用户消息发给模型前 | ✅ allow / deny / inject context | 注入 sprint 信息、敏感词拦截、按主题分流 | +| `PreToolUse` | 任何工具派发前（writeFile、shell、MCP、sub-agent…） | ✅ allow / deny / modify args | 拦截危险路径、重写参数、审计 gate | +| `PostToolUse` | 工具产出结果后 | ✅ modify output | 改写工具返回值、追加审计元数据 | +| `PreCompact` | 上下文将要被压缩前（proactive 阈值触发，或 reactive "prompt too long" 触发） | ❌ | 在 messages 被裁剪前持久化、做 checkpoint | +| `PostCompact` | 压缩完成后 | ❌ | 通知、记录"刚刚压了多少" | +| `SubagentStart` | `task` 工具派生 sub-agent 跑前 | ❌ | 审计哪些 sub-agent 被调用、记开始时间 | +| `SubagentStop` | Sub-agent 结束（completed / aborted / failed 三种结局） | ❌ | 统计 sub-agent 耗时与 token 用量 | +| `TurnComplete` | 每轮 LLM 流式输出结束 | ❌ | 通知、统计 | +| `SessionEnd` | CLI 退出时 | ❌ | flush 日志、发"会话结束"提示 | + +`SessionEnd` 是 fire-and-forget——CLI 不等 hook 完成就退。重要操作放 `TurnComplete`。 + +--- + +## Manifest 里怎么声明 + +插件 `plugin.json` 里（inline 或者引到外部文件）： + +```jsonc +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "writeFile|edit", // tool 名的正则 + "command": "node ${pluginDir}/hooks/lint.js", + // 可选：平台特定覆盖。当前 OS 命中就替换上面的 command。 + // 未命中的平台落回 `command`，所以一个能在任何 POSIX 系统跑的 + // 默认 + 一个 Windows 专属备用是常见组合。 + "commandWindows": "node \"${pluginDir}/hooks/lint.js\"", + "commandDarwin": "node ${pluginDir}/hooks/lint.js", // 一般不需要单独写 + "commandLinux": "node ${pluginDir}/hooks/lint.js", + "timeout": 5000, // ms（默认 5000，上限 30000） + "description": "写文件前自动 lint", + "failurePolicy": "allow", // 或 "block"，默认 "allow" + }, + ], + "UserPromptSubmit": [{ "command": "${pluginDir}/hooks/inject-context.sh" }], + }, +} +``` + +**为什么三个平台都要写**：插件最终在 Windows / Linux / macOS 都会被装，作者写 `bash foo.sh` 这种 POSIX 命令默认在 Windows 上会失败。`command` 是基础——这里写一个语言无关、跨平台都能跑的命令（比如 `node script.js`）；当某一个平台真的需要不一样的写法（Windows 的路径引号、PowerShell 命令、`.cmd` 后缀等）时，再加对应的 `commandWindows` / `commandDarwin` / `commandLinux`。这样插件不会因为作者只在自己的开发机上测过就排除其他用户。 + +或者引到独立文件： + +```jsonc +{ "hooks": "./hooks/hooks.json" } +``` + +`./hooks/hooks.json` 直接是 `{ PreToolUse: [...], ... }`，不再有外层 `hooks` 包裹。 + +--- + +## `command` 里的变量替换 + +| 变量 | 展开成 | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `${pluginDir}` | 插件安装目录绝对路径（版本化 cache 目录，重装/升级时会被擦掉） | +| `${pluginDataDir}` | 插件**持久数据目录**（`~/.x-code/plugins/data//`），跨重装/升级保留——索引、缓存、用户偏好放这里。第一次替换时自动 `mkdir -p`，hook 直接写就行 | +| `${cwd}` | 事件发生时的当前工作目录 | +| `${homedir}` | `os.homedir()` | +| `${sep}` | OS 路径分隔符（Windows 是 `\`，其他是 `/`） | +| `${env:NAME}` | `process.env.NAME`（缺失返回空串） | + +**未知变量原样保留**——比如 `${plugindir}` 这种拼写错会以 "file not found" 在 shell 里报错，而不是被静默替换成空串。这是刻意设计，让 typo 现形。 + +**`${pluginDir}` vs `${pluginDataDir}`**：前者是插件代码所在地（卸载/升级时会丢），后者是插件运行期需要保留的数据所在地。比如一个 "学过的代码风格" 缓存应该写到 `${pluginDataDir}`，这样用户升级插件版本时之前的学习不会清零。 + +--- + +## Stdin payload + +每个 hook 从 stdin 收到一行 JSON。顶层结构： + +```jsonc +{ + "event": "PreToolUse", // 事件名 + "session": { + // 每个事件都有 + "cwd": "/abs/path/to/project", + "modelId": "anthropic:claude-sonnet-4-6", + }, + "plugin": { + // 标识哪个插件的 hook 正在跑 + "id": "linear@anthropic-marketplace", + "dir": "/abs/.x-code/plugins/cache/anthropic-marketplace/linear/1.2.0", + }, + + // 事件特有字段平铺在顶层： + "tool": { + // PreToolUse / PostToolUse + "name": "writeFile", + "args": { "path": "src/foo.ts", "content": "..." }, + "callId": "call_abc123", + + // PostToolUse 才有： + "output": "wrote 42 bytes", + "isError": false, + }, + "prompt": "Refactor X to do Y", // 仅 UserPromptSubmit + "turn": 3, // 仅 TurnComplete + "tokenUsage": { + // 仅 TurnComplete / SubagentStop + "inputTokens": 4321, + "outputTokens": 567, + "totalTokens": 4888, + }, + + // PreCompact / PostCompact + "trigger": "proactive", // 或 "reactive"（即"prompt too long"触发的) + "messageCount": 87, // 压缩前（PreCompact）或压缩后（PostCompact）的 messages 数量 + "tokenEstimate": 184_000, // 仅 PreCompact + "summary": "...", // 仅 PostCompact —— 空串表示走的是轻量压缩（没生成 LLM summary） + + // SubagentStart / SubagentStop + "agent": { + "name": "code-reviewer", + "description": "review the diff", + "prompt": "", // 仅 SubagentStart + }, + "durationMs": 12_345, // 仅 SubagentStop + "outcome": "completed", // 仅 SubagentStop：completed / aborted / failed +} +``` + +--- + +## Stdout 决策 + +Hook 用 stdout 回一行 JSON。stdout 为空 = 默认 `allow`（大部分 fire-and-forget hook 不输出）。无法解析为 JSON 的 stdout 也按 `allow` 处理，并在 debug log 留 breadcrumb。 + +```jsonc +// 默认：agent 正常走 +{ "decision": "allow" } + +// 附加 context（UserPromptSubmit / PostToolUse） +{ "decision": "allow", "context": "Current sprint: Sprint 42" } + +// 阻止 agent 做这件事 +{ "decision": "deny", "reason": "禁止编辑 prod 配置" } + +// 改写参数（PreToolUse）/ 改写输出（PostToolUse） +{ "decision": "modify", "args": { "path": "/safer/path" } } +{ "decision": "modify", "output": "[redacted]" } +{ "decision": "modify", "context": "Sprint 42 in progress" } +``` + +实际生效情况： + +| Event | `deny` | `modify.args` | `modify.output` | `context` | +| ---------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------ | --------------------------- | ---------------------- | +| `UserPromptSubmit` | 用合成的 assistant 消息回绝 | — | — | 前置注入到 user 消息里 | +| `PreToolUse` | 用 "denied by hook" 作为 tool 结果 | 替换 tool 实际收到的参数 | — | (忽略) | +| `PostToolUse` | (deny 忽略——已经太晚了) | — | 替换 model 看到的 tool 结果 | (忽略) | +| `SessionStart` / `PreCompact` / `PostCompact` / `SubagentStart` / `SubagentStop` / `TurnComplete` / `SessionEnd` | (无决策——stdout 被忽略) | — | — | — | + +多个 hook 命中同一事件： + +- **决策事件**按注册顺序串行；`deny` 短路剩下的 +- **fire-and-forget 事件**并行 +- `modify` 决策叠加：后面的覆盖前面的 + +--- + +## 失败处理 + +Hook 崩溃、超时或非零退出，默认按 `allow` 处理，warning 写到 `~/.x-code/logs/debug.log`（要先 `DEBUG_STDOUT=1`）。 + +某个 hook 设 `"failurePolicy": "block"` 才会把非零退出当 `deny`。只给真的想做严格 gate 的 hook 用——默认 allow 是为了保证坏 hook 不会卡死 agent。 + +30s 是 timeout 的硬上限，不是默认值。默认 5s。需要长时间任务的话，hook 应该 spawn 后台进程然后立即返回。 + +--- + +## Abort 行为 + +用户 Esc / Ctrl+C 时，AbortSignal 通过 execa 的 `cancelSignal` 一路传到 hook 子进程，SIGKILL。Hook 不用做任何特殊处理——会被直接干掉。 + +--- + +## 端到端示例：写文件前自动 lint + +```js +// hooks/lint.js — PreToolUse 上挂 writeFile|edit +const data = require('fs').readFileSync(0, 'utf-8') // 读 stdin +const event = JSON.parse(data) +const filePath = event.tool.args.path + +if (!filePath.endsWith('.ts')) { + console.log(JSON.stringify({ decision: 'allow' })) + process.exit(0) +} + +const { execSync } = require('child_process') +try { + execSync(`eslint --quiet "${filePath}"`, { stdio: 'pipe' }) + console.log(JSON.stringify({ decision: 'allow' })) +} catch (e) { + console.log( + JSON.stringify({ + decision: 'deny', + reason: `Lint failed:\n${e.stdout?.toString() || e.message}`, + }), + ) +} +``` + +Manifest： + +```jsonc +{ + "name": "ts-lint-gate", + "version": "0.1.0", + "hooks": { + "PreToolUse": [{ "matcher": "writeFile|edit", "command": "node ${pluginDir}/hooks/lint.js" }], + }, +} +``` + +之后 agent 写 TypeScript 文件失败 lint 时会收到 `deny`，原因附带具体 lint 输出——model 看得到为什么并自己调整。 + +--- + +## Sub-agent 行为 + +Sub-agent 继承父 session 的 HookBus，所以 sub-agent 里的工具调用也会触发 `PreToolUse` / `PostToolUse`。这是刻意的——想审计模型所有行为的 plugin 必须这样才能看全。`SessionStart` / `SessionEnd` 只对外层 session 触发，sub-agent 没有。 + +**注意递归**：hook 自己又调 `xc` 或起 agent 时，那些工具调用也会触发 `PreToolUse`。hook 逻辑要紧凑，多用 `matcher` 正则约束触发的 tool。 + +--- + +## 临时关掉 hooks + +```bash +xc --no-hooks # 插件正常加载，hooks 不执行 +xc --no-plugins # 核弹：完全关插件 +``` + +用于排查"是不是 hook 让 CLI 卡住/变慢"。 diff --git a/docs/knowledge.en.md b/docs/knowledge.en.md new file mode 100644 index 0000000..8a9ce35 --- /dev/null +++ b/docs/knowledge.en.md @@ -0,0 +1,191 @@ +# Knowledge Base & Auto-memory — Usage Guide + +X-Code CLI loads "project background + your preferences + key facts from +last session" into the system prompt automatically at the start of each +session. You don't need to re-explain your project structure, naming +conventions, or last-meeting decisions every time. + +中文版：[knowledge.md](./knowledge.md) + +--- + +## 5-layer loading order + +At startup, the layers are concatenated in this order. **Later layers +win** on duplicate names or shadowing concepts: + +``` +1. ~/.x-code/AGENTS.md # global preferences (hand-written) +2. ~/.x-code/memory/auto.md # global auto-memory (AI-written) +3. /AGENTS.md chain # walked from cwd up to .git root, root → leaf +4. /.x-code/memory/auto.md # project auto-memory (AI-written) +5. /AGENTS.local.md # project personal prefs (hand-written, gitignored) +``` + +Step 3's "chain" means: when you're working in a monorepo subpackage, +that subpackage's `AGENTS.md` overrides the root `AGENTS.md` — leaf wins. + +> **Windows paths**: `~/.x-code` maps to `%USERPROFILE%\.x-code`. + +--- + +## AGENTS.md vs CLAUDE.md + +At each layer, the loader prefers `AGENTS.md` and falls back to +`CLAUDE.md` (Claude Code compat, read-only) when absent. + +**Practical effects**: + +- A project that already has `CLAUDE.md` works as-is — no rewrite needed +- `/init` only ever writes `AGENTS.md` (both for first-create and update; + never touches `CLAUDE.md`) +- Migrating from Claude Code: keep `CLAUDE.md` as-is; or move its content + to `AGENTS.md` and delete `CLAUDE.md` for a clean break + +--- + +## What goes in each file + +### `~/.x-code/AGENTS.md` — global preferences + +Cross-project facts and conventions. Example: + +```markdown +# My preferences + +- I use Vitest, not Jest +- TypeScript projects prefer strict mode (`strict: true`); no `any` +- Git commits follow Conventional Commits (`feat:` / `fix:` / `chore:` …) +- Code comments in English; user-facing docs in Chinese + +# My usual project shape + +- monorepo via pnpm workspace +- packages live under `packages//src/...` +``` + +### `/AGENTS.md` — project shared (committed) + +Project architecture / conventions, shared with the team. Example: + +```markdown +# x-foo project + +## Architecture + +- `packages/api/` Hono server, deploys to Cloudflare Workers +- `packages/web/` Next.js 14 app router, deploys to Vercel +- `packages/shared/` cross-end shared types + utils + +## Don't touch + +- `migrations/` is owned by the DBA team; PRs should not modify it +- `prisma/seed.ts` runs in staging only; production uses a dedicated script + +## Common commands + +- `pnpm dev` brings the whole monorepo up (db + api + web) +- `pnpm bench:api` runs the API bench suite +``` + +In a monorepo, drop a subpackage's own `AGENTS.md` to override root-level +conventions (leaf wins). + +### `/AGENTS.local.md` — project personal (gitignored) + +Your local preferences — never committed. Example: + +```markdown +# My local prefs + +- macOS, fish shell +- Only run tests under packages/api/ locally — CI does the full sweep +- `pnpm bench:api -- --reporter=tap` for tap output +``` + +--- + +## Auto-memory (`auto.md`) + +After each turn, the CLI scans the recent transcript and writes durable +facts to `auto.md`. These load as context next session. + +What gets captured: + +- **user**: stable facts about the user's role / skills / goals +- **feedback**: user corrections or confirmations ("don't mock the db", + "yes that style was right") +- **project**: ongoing work / decisions / non-obvious project state +- **reference**: pointers to external resources (Linear project, Grafana + dashboard, etc.) + +Two files: + +| Path | Scope | +| ------------------------------- | ------- | +| `~/.x-code/memory/auto.md` | Global | +| `/.x-code/memory/auto.md` | Project | + +Each memory is a standalone Markdown section with YAML frontmatter (type, +key, date, etc. as metadata). + +### Inspect + +```text +> /memory +(the agent renders the list, grouped by category, project + global combined) +``` + +### Edit by hand + +Just edit the file — memories are Markdown, what you see is what's stored. +`/memory` reads the same file you're editing. + +To make the agent **forget** something, delete the corresponding section. +To **add** a fact, hand-write a section (minimum form: `# title` + a body +paragraph). + +--- + +## `/init` — bootstrap an AGENTS.md for a project + +Want an `AGENTS.md` for a project that doesn't have one? + +```text +> /init +(the agent scans the repo + git log + README, writes an initial AGENTS.md to the project root) +``` + +If `AGENTS.md` already exists, `/init` **updates** it incrementally +rather than overwriting. + +Safe to run repeatedly — the agent diffs current state vs the existing +file and folds in what's missing. + +--- + +## Practical tips + +- **Write decisions, not facts** — the agent can grep "which ORM is + used", but it can't guess "why we didn't pick X". Lean toward "why" + over "what" +- **Keep AGENTS.md short** — it lands in every session's system prompt; + long = token cost. A 500-line AGENTS.md is worse than a 50-line one + with a `## Detailed architecture` line linking to `docs/architecture.md` +- **`.local.md` is for you only** — don't put team conventions there or + your colleagues can't reproduce your environment +- **Don't hand-edit `auto.md` for config** — it's AI-written to be AI-read; + hand edits work but get overwritten as new memories land. For stable + preferences, use `AGENTS.md` + +--- + +## Troubleshooting + +| Symptom | Fix | +| --------------------------------- | --------------------------------------------------------------------------------------------------- | +| Agent doesn't know my preferences | Restart `xc` — AGENTS.md is read at startup only | +| `/memory` is empty | Normal for fresh projects; populates after a few sessions | +| Auto-memory doesn't seem to land | Check `~/.x-code/memory/auto.md` exists; `DEBUG_STDOUT=1` then grep `memory.` | +| Migrating from Claude Code | Leave `CLAUDE.md` in place — the loader reads it as a fallback when `AGENTS.md` is missing | +| AGENTS.md slows startup | Split it — keep conventions in the main file, move detailed docs elsewhere with a "see docs/X" link | diff --git a/docs/knowledge.md b/docs/knowledge.md new file mode 100644 index 0000000..670c52a --- /dev/null +++ b/docs/knowledge.md @@ -0,0 +1,166 @@ +# 知识库与自动记忆 — 使用指南 + +X-Code CLI 在每个会话启动时把"项目背景 + 你的偏好 + 上次的关键事实"自动拼进 system prompt 让 agent 知道。你不需要每次重新解释项目结构、命名约定、上次决定。 + +英文版：[knowledge.en.md](./knowledge.en.md) + +--- + +## 5 层加载顺序 + +启动时按下面顺序拼接，**先写的优先级低，后写的覆盖前面同名/同类内容**： + +``` +1. ~/.x-code/AGENTS.md # 全局偏好（手写） +2. ~/.x-code/memory/auto.md # 全局自动记忆（AI 写） +3. /AGENTS.md chain # 从 cwd 走到 .git 根，root → leaf +4. /.x-code/memory/auto.md # 项目自动记忆（AI 写） +5. /AGENTS.local.md # 项目私人偏好（手写，gitignored） +``` + +第 3 步的 "chain" 意思是：如果你在 monorepo 的子包工作，子包的 AGENTS.md 会覆盖根的 AGENTS.md——leaf 优先。 + +> **Windows 路径**：`~/.x-code` 在 Windows 上是 `%USERPROFILE%\.x-code`。 + +--- + +## AGENTS.md vs CLAUDE.md + +每一层加载时，先找 `AGENTS.md`；找不到才回退 `CLAUDE.md`（Claude Code 兼容只读）。 + +**意味着：** + +- 你有现成 `CLAUDE.md` 项目可以直接用，不需要重写 +- `/init` 永远只写 `AGENTS.md`（既新建也是 update 到 `AGENTS.md`，不动 `CLAUDE.md`） +- 想从 Claude Code 迁过来，留 `CLAUDE.md` 即可；想完全自治，把内容搬到 `AGENTS.md` 并删 `CLAUDE.md` + +--- + +## 三类文件分别写什么 + +### `~/.x-code/AGENTS.md` — 全局偏好 + +写跨项目通用的事实和偏好。例： + +```markdown +# 我的偏好 + +- 我习惯用 Vitest，不用 Jest +- 写 TS 优先严格模式（`strict: true`），不要 any +- Git commit 信息走 Conventional Commits（`feat:` / `fix:` / `chore:` …） +- 代码注释优先英文，doc 写中文 + +# 我常用的项目结构 + +- monorepo 用 pnpm workspace +- 包路径约定 `packages//src/...` +``` + +### `/AGENTS.md` — 项目共享（committed） + +写本项目的架构 / 约定，团队成员一起用。例： + +```markdown +# x-foo project + +## 架构 + +- `packages/api/` Hono server，部署到 Cloudflare Workers +- `packages/web/` Next.js 14 app router，部署到 Vercel +- `packages/shared/` 跨端共享类型 + util + +## 不要碰 + +- `migrations/` 由 DBA 维护，PR 别动 +- `prisma/seed.ts` 只在 staging 跑，生产用专门脚本 + +## 常用命令 + +- `pnpm dev` 启动整个 monorepo（含 db、api、web） +- `pnpm bench:api` 跑 api 基准测试 +``` + +monorepo 子包想覆盖根级约定时，在子包根放自己的 `AGENTS.md`（leaf 优先）。 + +### `/AGENTS.local.md` — 项目私人（gitignored） + +放你个人的本地偏好——不会提交。例： + +```markdown +# 我的本地偏好 + +- 我在用 macOS，shell 是 fish +- 测试只跑 packages/api/，其他改 PR 时 CI 会跑 +- 用 `pnpm bench:api -- --reporter=tap` 看 tap 输出 +``` + +--- + +## 自动记忆（`auto.md`） + +每轮对话结束后，CLI 自动从最近 transcript 里筛选**值得长期记住**的事实，写到 `auto.md`。下次会话作为上下文加载。 + +筛选什么： + +- **user**：关于用户角色 / 技能 / 目标的稳定事实 +- **feedback**：用户的纠正或确认（"不要 mock 数据库"、"这种风格就对了"） +- **project**：项目里的进行中工作 / 决定 / 非显然状态 +- **reference**：指向外部资源（Linear 项目、Grafana dashboard 等） + +文件分两份： + +| 路径 | 范围 | +| ------------------------------- | ---- | +| `~/.x-code/memory/auto.md` | 全局 | +| `/.x-code/memory/auto.md` | 项目 | + +文件里每条记忆是一个独立的 markdown section + YAML frontmatter（type、key、date 等元信息）。 + +### 查看自动记忆 + +```text +> /memory +（agent 弹列表，按类目分组，project + global 都列） +``` + +### 手动改 + +直接编辑文件——记忆是 markdown，所见即所得。`/memory` 弹的就是该文件的内容。 + +要让 agent **忘掉**某事，删对应 section 即可。要**添加**事实，可以手写 section（最简形态：`# 标题` + 一段 body）。 + +--- + +## `/init` — 给项目生成 AGENTS.md + +新项目想要 `AGENTS.md`？ + +```text +> /init +（agent 扫码 + git log + README，写一份初始 AGENTS.md 到项目根） +``` + +已经有 `AGENTS.md` 时，`/init` 会**更新**而不是覆盖。 + +可以反复跑——agent 会比对现状和文件，增量补充。 + +--- + +## 实战提示 + +- **AGENTS.md 写决定不写事实**——agent 能 grep 出"用了哪个 ORM"，但不能猜"为什么不用 X"。多写"why" 少写"what" +- **AGENTS.md 越短越好**——会加进每轮 system prompt，长 = token 成本。500 行的 AGENTS.md 不如 50 行的 AGENTS.md + 一个 `## 详细架构` 部分链到 `docs/architecture.md` +- **`.local.md` 写仅你需要的**——不要把团队约定塞 local，否则别人 reproduce 不出来你的环境 +- **不要直接编辑 `auto.md` 当配置**——它是 AI 写给 AI 看的格式，手改可以但风格会被下次自动写入打乱。要稳定的偏好放 `AGENTS.md` + +--- + +## 故障排查 + +| 症状 | 处理 | +| ----------------------- | ---------------------------------------------------------------------------- | +| Agent 不知道我的偏好 | 重启 `xc`——AGENTS.md 是启动期读一次 | +| `/memory` 是空的 | 全新项目正常，多对话几次会自动生成 | +| 看不到自动记忆生效 | 检查 `~/.x-code/memory/auto.md` 是否存在；`DEBUG_STDOUT=1` 后 grep `memory.` | +| 想从 Claude Code 迁过来 | 留着现有 `CLAUDE.md`，CLI 会读它（缺 `AGENTS.md` 时回退） | +| AGENTS.md 太长拖慢启动 | 拆分——主文件留约定，详细文档放别处，AGENTS.md 里引一句"详见 docs/X" | diff --git a/docs/marketplace.en.md b/docs/marketplace.en.md new file mode 100644 index 0000000..b57f190 --- /dev/null +++ b/docs/marketplace.en.md @@ -0,0 +1,269 @@ +# Marketplaces + +A marketplace is an **index** of plugins — a JSON file (one URL) that +lists `{ name, source }` entries pointing at the actual plugin repos +or paths. Marketplaces don't host plugin code themselves; they're +catalogs. + +`x-code` doesn't run its own marketplace. It **subscribes** to other +people's marketplaces. The marketplace.json schema is byte-compatible +with Claude Code's, so subscribing to Anthropic's official marketplace +works out of the box. + +See also: [Plugins user guide](plugins.md) · +[Authoring a plugin](plugin-authoring.md) + +--- + +## What ships by default + +The first time `xc` starts up, it writes a single subscription: + +| Name | Source | Notes | +| ----------------------- | ------------------------------------------- | -------------------------------------------------------------------------- | +| `anthropic-marketplace` | `github:anthropics/claude-plugins-official` | Anthropic's official Claude Code marketplace (200+ plugins), reserved name | + +If you remove that subscription with `/plugin marketplace remove +anthropic-marketplace`, a later startup **will not re-add it +automatically** (see [§ Idempotency](#idempotency) below). + +--- + +## Subscribing to a marketplace + +```bash +# From a GitHub repo (canonical path .claude-plugin/marketplace.json) +xc plugin marketplace add community github:foo/x-code-marketplace + +# From an HTTPS URL that serves marketplace.json directly +xc plugin marketplace add internal https://intranet.example.com/plugins.json + +# Then pull its index +xc plugin marketplace refresh community +``` + +Listing subscriptions: + +```bash +xc plugin marketplace list +# → +# Subscribed marketplaces (2): +# anthropic-marketplace github:anthropics/claude-plugins-official [official] +# community github:foo/x-code-marketplace +``` + +Inspecting a subscribed marketplace's contents: + +```bash +xc plugin marketplace info community +xc plugin search linear +``` + +Removing: + +```bash +xc plugin marketplace remove community +``` + +--- + +## Reserved names + +A small set of marketplace names is reserved to prevent impersonation: + +| Name | Only acceptable from | +| ----------------------- | --------------------- | +| `anthropic-marketplace` | `github:anthropics/…` | +| `claude-plugins` | `github:anthropics/…` | +| `x-code-official` | `github:woai3c/…` | + +Trying to subscribe to a reserved name with a non-canonical source is +rejected at the API level: + +```bash +$ xc plugin marketplace add anthropic-marketplace github:bad/marketplace +Marketplace name "anthropic-marketplace" is reserved; only sources +under github:anthropics/* may use it. Got: github:bad/marketplace +``` + +This is a name-collision guard, not a security audit — you're free to +subscribe to any non-reserved name from any source. + +--- + +## marketplace.json schema + +`xc` uses the public Claude Code marketplace schema — a file you +publish for `xc` works for Claude Code unchanged. The canonical path +inside a repo is **`.claude-plugin/marketplace.json`**. + +Reference real-world examples: `anthropics/claude-code` and +`anthropics/claude-plugins-official`. + +```jsonc +{ + "$schema": "https://json.schemastore.org/claude-code-marketplace.json", + "name": "community", + "version": "1.0.0", + "description": "Community-curated plugins.", + "owner": { "name": "Foo Org", "url": "https://foo.example" }, + "plugins": [ + { + "name": "linear", + "description": "Linear issue integration", + "version": "1.2.0", + "author": { "name": "...", "email": "..." }, + "category": "productivity", + "source": "./plugins/linear", // string shortcut: subdir of this marketplace's own repo + }, + { + "name": "k8s", + "source": "github:foo/k8s-plugin", // string shortcut: github + }, + { + "name": "from-monorepo", + "source": { + // git-subdir: a subpath inside some other git repo + "source": "git-subdir", + "url": "https://github.com/42Crunch-AI/claude-plugins.git", + "path": "plugins/api-security", + "ref": "v1.5.5", + }, + }, + ], +} +``` + +### Accepted `source` shapes + +`xc` accepts every wire form Claude Code marketplaces use (sampled +from `anthropics/claude-code` and `anthropics/claude-plugins-official`): + +| Shape | Notes | +| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `"./plugins/foo"` / `"../shared/x"` | **String relative path** — subdir of the marketplace's own repo. Most common; suits monorepo hosting (Anthropic's own uses this) | +| `"github:owner/repo[#ref]"` | **String GitHub shortcut** | +| `"https://..."` / `"git@..."` | **String git URL** | +| `{ source: "git-subdir", url, path, ref?, sha? }` | **Object git-subdir** — subdir of a different git repo. `sha` currently ignored (reserved for integrity check) | +| `{ source: "url", url, sha? }` | **Object full git URL** | +| `{ source: "github", owner, repo, ref?, subdir? }` or `{ source: "github", repo: "owner/repo", commit? }` | **Object GitHub** — owner/repo can be separate or combined; `commit` is an alias for `ref` | +| `{ source: "git", url, ref?, subdir? }` | **Object git** | +| `{ source: "local", path }` | **Local path** — dev only, not portable | + +Constraints: + +- String relative paths (`"./plugins/foo"`) only make sense when the marketplace was fetched via git clone — marketplaces subscribed by a raw HTTPS JSON URL can't reference relative subdirs (no repo to subdir into) +- Integrity check (`sha`) not yet implemented +- Internally normalised to `{ kind: 'git'|'github'|'local', ..., subdir? }`; the wire format only surfaces in marketplace.json + +--- + +## Hosting your own marketplace + +Two simple shapes work: + +**1. A GitHub repo** with `.claude-plugin/marketplace.json`. + +Subscribers run: + +```bash +xc plugin marketplace add github:youruser/yourrepo +``` + +The CLI does a shallow clone, reads `marketplace.json`, caches it, +deletes the clone. Subsequent `xc plugin marketplace refresh ` +re-clones. + +**2. An HTTPS endpoint** that serves `marketplace.json` directly. + +Subscribers run: + +```bash +xc plugin marketplace add https://example.com/marketplace.json +``` + +The CLI fetches via `fetch()`. Useful for internal corporate +marketplaces — you can serve different indexes to different VPNs, +require TLS, etc. + +Both forms cache the parsed index under +`~/.x-code/plugins/marketplaces//marketplace.json` so offline +use works after the first refresh. + +--- + +## Caching + +After `xc plugin marketplace refresh `, the index lives at +`~/.x-code/plugins/marketplaces//marketplace.json`. The cache +file's mtime is used as a "freshness" marker — there's currently no +automatic TTL refresh, so users (or scripts) call `refresh` when they +want a fresh pull. + +A future improvement is opt-in background refresh; today it's manual. + +--- + +## Curating your own + +Three rough patterns we've seen work: + +1. **Pure curation** — your marketplace.json lists plugins from other + people's repos. Zero hosting overhead; you act as the trust + intermediary. Useful for internal corp marketplaces ("here are the + ones our security team vetted"). + +2. **Author + curate** — you publish plugins under your own GitHub + org and list them in your marketplace. Standard ecosystem owner + model. + +3. **Mirror** — your marketplace.json points at the same plugin repos + another marketplace lists. Useful for high-availability or for + stripping non-mandatory entries from a larger upstream list. + +In all three, the marketplace.json itself stays small — just an index. +The plugins themselves live wherever you point at. + +--- + +## Idempotency + +`ensureDefaultMarketplaces()` (the function that writes the default +`anthropic-marketplace` subscription on first run) checks +`known_marketplaces.json` and skips if any entry is present. **Once +the file exists, it's never overwritten** — so removing the default +subscription sticks across restarts. + +If you later want it back: `xc plugin marketplace add +anthropic-marketplace github:anthropics/claude-plugins-official`. + +--- + +## Compatibility with Claude Code + +Anthropic's official Claude Code marketplace publishes a +`marketplace.json` at the schema we describe above. `xc` reads it +without translation. The same goes for any third-party Claude Code +marketplace — subscribing to it from `xc` works as long as the +listed plugins use one of: + +- `.claude-plugin/plugin.json` +- `.x-code-plugin/plugin.json` +- `plugin.json` + +at their root. (`xc` probes those three paths in that priority order.) + +Plugins that use Claude Code-only manifest fields (`output-styles`, +`lspServers`) install fine; those specific fields are silently dropped. + +--- + +## Troubleshooting + +| Symptom | Try | +| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| `add` rejected with "reserved" | The name's in [§ Reserved names](#reserved-names) and your source doesn't match. Use a different name. | +| `refresh` fails with HTTP error | The source URL is wrong, or the git repo doesn't have `marketplace.json` at the root. | +| `info` says "no cached index" | Run `refresh` first. | +| `search` returns nothing for a known plugin | Run `refresh` — the index may be stale, or the plugin may live in a marketplace you haven't subscribed to. | +| Want to migrate from Claude Code's marketplace | It's already subscribed by default. Just `xc plugin install @anthropic-marketplace`. | diff --git a/docs/marketplace.md b/docs/marketplace.md new file mode 100644 index 0000000..afa1827 --- /dev/null +++ b/docs/marketplace.md @@ -0,0 +1,226 @@ +# Marketplace — 使用指南 + +Marketplace 是一个**插件索引**——一个 JSON 文件（一个 URL），列出 `{ name, source }` 条目指向插件实际所在的 git repo 或本地路径。Marketplace 不托管插件代码，它是目录。 + +x-code 不自己运营 marketplace。它只**订阅**别人的 marketplace。Marketplace.json schema 与 Claude Code 字节级兼容，所以订阅 Anthropic 官方 marketplace 开箱即用。 + +英文版：[marketplace.en.md](./marketplace.en.md) · 相关：[plugins.md](./plugins.md) · [plugin-authoring.md](./plugin-authoring.md) + +--- + +## 开箱默认有什么 + +x-code 首次启动会自动写一条订阅： + +| 名字 | 源 | 说明 | +| ----------------------- | ------------------------------------------- | ----------------------------------------------------------- | +| `anthropic-marketplace` | `github:anthropics/claude-plugins-official` | Anthropic 官方 Claude Code marketplace（200+ 插件），保留名 | + +如果你用 `/plugin marketplace remove anthropic-marketplace` 删掉了，后续启动**不会自动重加**（详见 [幂等性](#幂等性)）。 + +--- + +## 订阅一个 marketplace + +```bash +# 从 GitHub repo（约定路径 .claude-plugin/marketplace.json） +xc plugin marketplace add community github:foo/x-code-marketplace + +# 从直接服务 marketplace.json 的 HTTPS URL +xc plugin marketplace add internal https://intranet.example.com/plugins.json + +# 然后拉它的索引 +xc plugin marketplace refresh community +``` + +列出订阅： + +```bash +xc plugin marketplace list +# → +# Subscribed marketplaces (2): +# anthropic-marketplace github:anthropics/claude-plugins-official [official] +# community github:foo/x-code-marketplace +``` + +看某个订阅里有啥： + +```bash +xc plugin marketplace info community +xc plugin search linear +``` + +取消订阅： + +```bash +xc plugin marketplace remove community +``` + +--- + +## 保留名 + +少数 marketplace 名字保留用于防仿冒： + +| 名字 | 只接受来源 | +| ----------------------- | --------------------- | +| `anthropic-marketplace` | `github:anthropics/…` | +| `claude-plugins` | `github:anthropics/…` | +| `x-code-official` | `github:woai3c/…` | + +用保留名但源不对的订阅会被 API 直接拒： + +```bash +$ xc plugin marketplace add anthropic-marketplace github:bad/marketplace +Marketplace name "anthropic-marketplace" is reserved; only sources +under github:anthropics/* may use it. Got: github:bad/marketplace +``` + +这只是命名碰撞保护，不是安全审计——任何非保留名你都可以随便订阅任何源。 + +--- + +## marketplace.json schema + +x-code 用 Anthropic 公开的 Claude Code marketplace schema——你写的文件可以被 Claude Code 直接用。文件位置约定：repo 的 **`.claude-plugin/marketplace.json`**。 + +参考真实文件：`anthropics/claude-code` 与 `anthropics/claude-plugins-official`。 + +```jsonc +{ + "$schema": "https://json.schemastore.org/claude-code-marketplace.json", + "name": "community", + "version": "1.0.0", + "description": "Community-curated plugins.", + "owner": { "name": "Foo Org", "url": "https://foo.example" }, + "plugins": [ + { + "name": "linear", + "description": "Linear issue 集成", + "version": "1.2.0", + "author": { "name": "...", "email": "..." }, + "category": "productivity", + "source": "./plugins/linear", // 字符串相对路径，最常用 + }, + { + "name": "k8s", + "source": "github:foo/k8s-plugin", // 字符串 github 简写 + }, + { + "name": "from-monorepo", + "source": { + // git-subdir：其他 git repo 的子目录 + "source": "git-subdir", + "url": "https://github.com/42Crunch-AI/claude-plugins.git", + "path": "plugins/api-security", + "ref": "v1.5.5", + }, + }, + ], +} +``` + +### 源（source）允许的形式 + +x-code 接受 Anthropic Claude Code 的全部 wire 形式（见 anthropics/claude-code、anthropics/claude-plugins-official 真实 marketplace.json）： + +| 形式 | 说明 | +| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `"./plugins/foo"` 或 `"../shared/x"` | **字符串相对路径**——指代订阅此 marketplace 的 git repo 内的子目录。最常见，适合 monorepo 集中托管多个插件（Anthropic 自家用这个） | +| `"github:owner/repo[#ref]"` | **字符串 GitHub 简写** | +| `"https://..."` 或 `"git@..."` | **字符串 git URL** | +| `{ source: "git-subdir", url, path, ref?, sha? }` | **对象 git-subdir**——其他 git repo 的子目录。`sha` 当前被忽略（未来做完整性校验） | +| `{ source: "url", url, sha? }` | **对象 git URL** | +| `{ source: "github", owner, repo, ref?, subdir? }` 或 `{ source: "github", repo: "owner/repo", commit? }` | **对象 GitHub**——owner/repo 可分开也可合并；`commit` 等价于 `ref` | +| `{ source: "git", url, ref?, subdir? }` | **对象 git** | +| `{ source: "local", path }` | **本地路径**——开发用，不可移植 | + +约束： + +- 字符串相对路径只有当 marketplace 通过 git clone 拉取时才有意义——订阅 raw HTTPS JSON URL 的 marketplace 不能用相对路径 +- 完整性校验（`sha`）暂未实现 +- 内部统一归一化成 `{ kind: 'git'|'github'|'local', ..., subdir? }`；wire 格式只在 marketplace.json 这层暴露 + +--- + +## 自己 host 一份 marketplace + +两种简单形态： + +**1. 一个 GitHub repo**，路径约定 `.claude-plugin/marketplace.json`（与 Claude Code 一致）。 + +订阅者执行： + +```bash +xc plugin marketplace add github:youruser/yourrepo +``` + +CLI 浅克隆 → 优先读 `.claude-plugin/marketplace.json`、缺失时回退到 repo 根的 `marketplace.json` → 缓存、删克隆。之后 `xc plugin marketplace refresh ` 再克隆刷新。 + +**2. 一个 HTTPS 端点**直接服务 `marketplace.json`。 + +订阅者执行： + +```bash +xc plugin marketplace add https://example.com/marketplace.json +``` + +CLI 用 `fetch()` 拉取。适合企业内部 marketplace——可按 VPN 服务不同索引、强制 TLS 等。 + +两种形态都会把解析后的索引缓存到 `~/.x-code/plugins/marketplaces//marketplace.json`，首次 refresh 之后就能离线用了。 + +--- + +## 缓存 + +`xc plugin marketplace refresh ` 之后索引在 `~/.x-code/plugins/marketplaces//marketplace.json`。缓存文件的 mtime 作为"新鲜度"标记——目前**没有自动 TTL 刷新**，需要用户（或脚本）主动 `refresh` 拉新。 + +未来计划做可选的后台刷新；目前手动。 + +--- + +## 怎么策划自己的 marketplace + +看到三种可用模式： + +1. **纯策划**——你的 marketplace.json 列别人 repo 的插件。零托管成本；你是信任中介。适合企业内部 marketplace（"这些是我们安全团队审过的"）。 + +2. **创作 + 策划**——你在自己 GitHub org 下发布插件并在自己的 marketplace 列出。标准的生态主理模式。 + +3. **镜像**——你的 marketplace.json 指向另一个 marketplace 列的同一批 repo。适合做高可用，或者从一个大上游列表里筛掉非强制的条目。 + +三种模式 marketplace.json 本身都很小——就是个索引。插件本身在哪都行。 + +--- + +## 幂等性 + +`ensureDefaultMarketplaces()`（首次启动写 `anthropic-marketplace` 默认订阅的函数）会先检查 `known_marketplaces.json`，任何条目存在就跳过。**文件一旦存在就不会被覆盖**——所以删掉默认订阅在重启间保留。 + +之后想要回来：`xc plugin marketplace add anthropic-marketplace github:anthropics/claude-plugins-official`。 + +--- + +## 与 Claude Code 的兼容性 + +Anthropic 官方 Claude Code marketplace 发布的 `marketplace.json` 用的就是上面描述的 schema。x-code 直接读，不需要翻译。任何第三方 Claude Code marketplace 也一样——x-code 订阅后能正常工作，只要里面列的插件用： + +- `.claude-plugin/plugin.json` +- `.x-code-plugin/plugin.json` +- `plugin.json` + +之一作为 manifest（x-code 按这个优先级探测三个路径）。 + +只用 Claude Code 独有 manifest 字段（`output-styles`、`lspServers`）的插件能正常装，那两个字段会被静默忽略。 + +--- + +## 故障排查 + +| 症状 | 处理 | +| ----------------------------------- | ----------------------------------------------------------------------- | +| `add` 报 "reserved" | 名字是 [保留名](#保留名) 且源不匹配。换别的名字 | +| `refresh` 失败 HTTP error | URL 错了，或者 git repo 根目录没有 `marketplace.json` | +| `info` 报 "no cached index" | 先 `refresh` | +| `search` 找不到已知插件 | 跑 `refresh`——索引可能 stale，或者该插件根本不在你订阅的 marketplace 里 | +| 想从 Claude Code marketplace 迁过来 | 它默认就订阅了。`xc plugin install @anthropic-marketplace` 即可 | diff --git a/docs/mcp.en.md b/docs/mcp.en.md new file mode 100644 index 0000000..3deeb6d --- /dev/null +++ b/docs/mcp.en.md @@ -0,0 +1,265 @@ +# MCP (Model Context Protocol) — Usage Guide + +X-Code CLI ships with a built-in MCP client. Any MCP-protocol server you +configure becomes part of the agent's tool set — the agent calls its tools +the same way it calls the built-ins. + +Both **stdio** (local subprocess) and **streamable HTTP** (remote, OAuth- +capable) transports are supported. + +中文版：[mcp.md](./mcp.md) + +--- + +## TL;DR + +Add an `mcpServers` field to `~/.x-code/config.json` (create the file if +needed), then restart `xc`: + +```jsonc +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed-dir"], + }, + "github": { + "url": "https://api.githubcopilot.com/mcp/", + }, + }, +} +``` + +After startup, use `/mcp list` to see connection status and `/mcp tools` +to see the tools each server exposes. + +--- + +## Config file locations + +| Scope | Path | When to use | +| ------- | ---------------------------- | ----------------------------------------------------- | +| Global | `~/.x-code/config.json` | Personal-use servers (filesystem, github, etc.) | +| Project | `/.x-code/config.json` | Repo-specific servers (internal company server, etc.) | + +The two scopes merge: project entries override global entries with the +same name. **Project-level configs trigger a trust dialog the first time +they appear** (matching Claude Code's security model). Declining skips +project servers for that session. The trust decision persists at +`~/.x-code/trusted-projects.json`. + +> **Windows paths**: `~/.x-code` maps to `%USERPROFILE%\.x-code` on +> Windows. Not repeated below. + +--- + +## mcpServers schema + +### stdio (local subprocess) + +```jsonc +{ + "mcpServers": { + "filesystem": { + "command": "npx", // required + "args": ["-y", "@modelcontextprotocol/server-filesystem", "${env:WORK_DIR}"], + "env": { + // optional: extra env vars + "DEBUG": "1", + }, + "cwd": "/some/dir", // optional: child cwd + "timeout": 30000, // optional: first-connect timeout in ms (default 30000) + "enabled": true, // optional: false skips the server + }, + }, +} +``` + +### HTTP (remote, optional OAuth) + +```jsonc +{ + "mcpServers": { + "github": { + "url": "https://api.githubcopilot.com/mcp/", // required + "headers": { + // optional: static request headers + "X-Client": "x-code", + }, + "timeout": 30000, + "enabled": true, + }, + }, +} +``` + +**OAuth**: HTTP servers that require OAuth surface as `needs_auth` on +first connect. Run `/mcp auth ` to drive the full OAuth flow — a +browser opens the authorization URL, the callback writes the token to +`~/.x-code/mcp/tokens/.json`. Subsequent launches inject +`Authorization: Bearer ...` automatically. + +**Don't hard-code tokens into `headers`** — the OAuth flow handles them. + +### Variable expansion + +`${VAR}` and `${env:VAR}` inside any string field are expanded against +`process.env` at startup. Missing variables raise an error and mark the +server `failed` (the other servers still load). + +```jsonc +{ + "github": { + "url": "${env:GITHUB_MCP_URL}", + "headers": { "Authorization": "Bearer ${env:GITHUB_TOKEN}" }, + }, +} +``` + +> **Tip**: any field carrying a secret should use `${env:...}`. Keep the +> secret in your shell rc file rather than committing it to a +> source-controlled config.json. + +--- + +## `/mcp` commands + +| Command | Description | +| ---------------------- | ----------------------------------------------------------------------------------------- | +| `/mcp list` | List every configured server with its status (connected / disabled / needs_auth / failed) | +| `/mcp tools [server]` | List tools available; optional filter by server name | +| `/mcp add` | Interactive add of a stdio / HTTP server to global or project config | +| `/mcp add-json` | Add a server from raw JSON (handy for pasting docs examples) | +| `/mcp remove` | Remove a server from config | +| `/mcp auth ` | Drive the OAuth flow for an HTTP server | +| `/mcp logout ` | Clear the stored OAuth token for a server | +| `/mcp refresh` | Re-read config files and reconnect every server (no CLI restart needed) | + +Example `/mcp list` output: + +``` +MCP servers: + filesystem connected — 11 tools, 0 resources + github needs auth — run /mcp logout github and restart to retry + internal failed — connect ECONNREFUSED 127.0.0.1:8080 +``` + +--- + +## Tool naming + +MCP tool names take the form `__` (double underscore). For +example: + +- `filesystem__read_file` +- `github__create_issue` + +When two servers expose the same tool name, the second gets a hash +suffix (e.g. `read_file_a3f2`) to avoid collision; the loader logs which +server got renamed. + +--- + +## Worked examples + +### Example 1: official filesystem server + +```jsonc +{ + "mcpServers": { + "fs": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "D:/work"], + }, + }, +} +``` + +After startup the agent gains `fs__read_file`, `fs__write_file`, +`fs__list_directory`, and so on — all scoped to `D:/work`. + +### Example 2: a custom stdio server + +```jsonc +{ + "mcpServers": { + "company": { + "command": "node", + "args": ["D:/tools/company-mcp/index.js"], + "env": { + "API_KEY": "${env:COMPANY_API_KEY}", + "ENDPOINT": "https://internal.corp/api", + }, + "cwd": "D:/tools/company-mcp", + }, + }, +} +``` + +### Example 3: HTTP server + OAuth + +```jsonc +{ + "mcpServers": { + "linear": { + "url": "https://mcp.linear.app/sse", + }, + }, +} +``` + +First run: + +``` +$ xc +[mcp] linear: needs auth +> /mcp auth linear +Opening browser to authorize linear... +Listening on http://localhost:33421/oauth/callback +[browser opens, user authorizes] +[token saved to ~/.x-code/mcp/tokens/linear.json] +linear connected — 8 tools, 2 resources +``` + +Subsequent launches inject the Bearer token automatically — no re-auth +needed until the token expires. + +--- + +## Plugin-contributed mcpServers + +Plugins can declare `mcpServers` in their manifest (inline or as a file +path). They load identically to user-configured servers, with two +differences: + +- **Treated as already-trusted** — the project trust dialog doesn't + fire (the user already consented to the plugin at install time) +- **Merge order**: user → plugin → project. Project entries still win + on name collisions +- **Listed in `/mcp list`** alongside user servers + +See [plugins.md](./plugins.md) § Contributions for the full picture. + +--- + +## Troubleshooting + +| Symptom | Try | +| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `/mcp list` shows `failed` | Read the `stderrTail` field (end of `/mcp list` output); usually "command not found" or wrong cwd | +| `needs_auth` and `/mcp auth` does nothing | Confirm the HTTP server actually supports OAuth; some custom servers use static tokens — set `headers: {"Authorization": "Bearer ..."}` instead | +| Tool-name collisions | A hash suffix is appended automatically; or rename the server (the `mcpServers` key) | +| Restarting `xc` feels slow | `/mcp refresh` reconnects in place — no CLI restart | +| Project config not loading | Did you decline the trust dialog at startup? Remove the matching path from `~/.x-code/trusted-projects.json` and restart to re-decide | +| Want to temporarily skip a server | Set `enabled: false` on the entry — more visible than commenting out the whole block | + +With `DEBUG_STDOUT=1` set, MCP events land in `~/.x-code/logs/debug.log`. +Grep for `mcp.` to follow connects / calls / errors. + +--- + +## Compatibility with Claude Code MCP config + +X-Code CLI's `mcpServers` schema matches Claude Code's exactly — copy +the `mcpServers` block from your `~/.claude/config.json` straight into +`~/.x-code/config.json`. One config, two CLIs. diff --git a/docs/mcp.md b/docs/mcp.md new file mode 100644 index 0000000..5bc8666 --- /dev/null +++ b/docs/mcp.md @@ -0,0 +1,235 @@ +# MCP（Model Context Protocol）— 使用指南 + +X-Code CLI 内置 MCP 客户端，可以把任意符合 MCP 协议的服务器接入 agent——它们提供的工具会自动并入 agent 工具集，agent 可以像调用内置工具一样调用它们。 + +支持 **stdio**（本地子进程）和 **streamable HTTP**（远端，含 OAuth）两种传输。 + +英文版：[mcp.en.md](./mcp.en.md) + +--- + +## TL;DR + +在 `~/.x-code/config.json` 加 `mcpServers` 字段（文件不存在就新建），然后重启 `xc`： + +```jsonc +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed-dir"], + }, + "github": { + "url": "https://api.githubcopilot.com/mcp/", + }, + }, +} +``` + +启动后用 `/mcp list` 查看连接状态，`/mcp tools` 查看可用工具。 + +--- + +## 配置文件位置 + +| Scope | 路径 | 何时用 | +| ----- | ---------------------------- | ------------------------------------------ | +| 全局 | `~/.x-code/config.json` | 个人通用 MCP 服务（filesystem、github 等） | +| 项目 | `/.x-code/config.json` | 仅此项目的 MCP 服务（公司内部 server 等） | + +两个 scope 合并：项目级覆盖同名全局。**项目级配置首次出现时弹"是否信任"对话框**（同 Claude Code 的安全模型），用户拒绝则跳过项目级。信任决定持久化到 `~/.x-code/trusted-projects.json`。 + +> **Windows 路径**：`~/.x-code` 在 Windows 上是 `%USERPROFILE%\.x-code`，下文不再重复。 + +--- + +## mcpServers 配置 schema + +### stdio（本地子进程） + +```jsonc +{ + "mcpServers": { + "filesystem": { + "command": "npx", // 必需 + "args": ["-y", "@modelcontextprotocol/server-filesystem", "${env:WORK_DIR}"], + "env": { + // 可选：额外环境变量 + "DEBUG": "1", + }, + "cwd": "/some/dir", // 可选：子进程工作目录 + "timeout": 30000, // 可选：首次连接超时（ms，默认 30000） + "enabled": true, // 可选：false 跳过此服务器 + }, + }, +} +``` + +### HTTP（远端，含可选 OAuth） + +```jsonc +{ + "mcpServers": { + "github": { + "url": "https://api.githubcopilot.com/mcp/", // 必需 + "headers": { + // 可选：静态请求头 + "X-Client": "x-code", + }, + "timeout": 30000, + "enabled": true, + }, + }, +} +``` + +**OAuth**：HTTP server 若需 OAuth 认证，首次连接返回 `needs_auth` 状态。用 `/mcp auth ` 触发完整 OAuth 流程——浏览器打开授权 URL，回调后 token 持久化到 `~/.x-code/mcp/tokens/.json`。下次启动自动注入 `Authorization: Bearer ...` 头。 + +**不要把 token 手写到 `headers`** 里——OAuth 流程会自动处理。 + +### 环境变量展开 + +任何字段值里的 `${VAR}` 与 `${env:VAR}` 会被启动期展开成 `process.env.VAR`。变量不存在时报错并将该 server 标记为 `failed`（不影响其他 server）。 + +```jsonc +{ + "github": { + "url": "${env:GITHUB_MCP_URL}", + "headers": { "Authorization": "Bearer ${env:GITHUB_TOKEN}" }, + }, +} +``` + +> **提示**：含密钥的字段强烈推荐用 `${env:...}`，把密钥放进 shell 启动文件而非提交到 git 的 config.json。 + +--- + +## `/mcp` 命令族 + +| 命令 | 说明 | +| ---------------------- | ------------------------------------------------------------------------------ | +| `/mcp list` | 列出所有配置的 server + 当前状态（connected / disabled / needs_auth / failed） | +| `/mcp tools [server]` | 列出可用工具；可选按 server 名过滤 | +| `/mcp add` | 交互式添加一个 stdio / HTTP server 到全局或项目 config | +| `/mcp add-json` | 从一段裸 JSON 添加一个 server（适合粘贴文档示例） | +| `/mcp remove` | 从 config 移除 server | +| `/mcp auth ` | 触发 HTTP server 的 OAuth 流程 | +| `/mcp logout ` | 清除 server 的 OAuth token | +| `/mcp refresh` | 重读 config 文件并重连所有 server（无需重启 xc） | + +`/mcp list` 输出示例： + +``` +MCP servers: + filesystem connected — 11 tools, 0 resources + github needs auth — run /mcp logout github and restart to retry + internal failed — connect ECONNREFUSED 127.0.0.1:8080 +``` + +--- + +## 工具命名 + +MCP 工具名格式为 `__`（双下划线分隔）。例： + +- `filesystem__read_file` +- `github__create_issue` + +两个 server 都暴露同名工具时，第二个会自动追加哈希后缀避免冲突（如 `read_file_a3f2`），并写日志说明。 + +--- + +## 实战示例 + +### 示例 1：filesystem server（官方提供） + +```jsonc +{ + "mcpServers": { + "fs": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "D:/work"], + }, + }, +} +``` + +启动后 agent 多了 `fs__read_file`、`fs__write_file`、`fs__list_directory` 等工具，可以读写 `D:/work` 下的文件。 + +### 示例 2：自建 stdio server + +```jsonc +{ + "mcpServers": { + "company": { + "command": "node", + "args": ["D:/tools/company-mcp/index.js"], + "env": { + "API_KEY": "${env:COMPANY_API_KEY}", + "ENDPOINT": "https://internal.corp/api", + }, + "cwd": "D:/tools/company-mcp", + }, + }, +} +``` + +### 示例 3：HTTP server + OAuth + +```jsonc +{ + "mcpServers": { + "linear": { + "url": "https://mcp.linear.app/sse", + }, + }, +} +``` + +首次启动： + +``` +$ xc +[mcp] linear: needs auth +> /mcp auth linear +Opening browser to authorize linear... +Listening on http://localhost:33421/oauth/callback +[browser opens, user authorizes] +[token saved to ~/.x-code/mcp/tokens/linear.json] +linear connected — 8 tools, 2 resources +``` + +之后所有启动自动带 Bearer token，无需重新认证（token 过期前）。 + +--- + +## Plugin 提供的 mcpServers + +Plugin 可以在 manifest 里声明 `mcpServers`（inline 或 path 形式），加载方式与用户配置相同： + +- **算 already-trusted**：不弹项目信任对话框（用户已经在安装 plugin 时同意了） +- **合并顺序**：user → plugin → project，名字冲突时项目级覆盖 +- **`/mcp list` 会一并显示** + +详情见 [plugins.md](./plugins.md) §贡献内容。 + +--- + +## 故障排查 + +| 现象 | 处理 | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| `/mcp list` 显示 `failed` | 看 `stderrTail` 字段（`/mcp list` 输出末尾）；最常见是命令找不到或工作目录错误 | +| `needs_auth` 且 `/mcp auth` 没反应 | 确认你的 HTTP server 支持 OAuth；某些自定义 server 用静态 token，直接写 `headers: {"Authorization": "Bearer ..."}` | +| 工具名冲突 | 同名 server 会被加 hash 后缀；想换名直接改 `mcpServers` 的 key | +| 重启太慢 | `/mcp refresh` 增量重连，不需 CLI 重启 | +| 项目级 config 不生效 | 启动时拒绝过信任对话框？删 `~/.x-code/trusted-projects.json` 里对应路径重启再次确认 | +| 想临时跳过某个 server | `enabled: false` 字段，比注释掉整段更明显 | + +启用 `DEBUG_STDOUT=1` 后所有 MCP 事件写入 `~/.x-code/logs/debug.log`，grep `mcp.` 看连接 / 调用 / 错误。 + +--- + +## 与 Claude Code MCP 配置的兼容性 + +X-Code CLI 的 `mcpServers` schema 与 Claude Code 一致——你可以直接把 Claude Code 的 `~/.claude/config.json` 里的 `mcpServers` 段复制到 `~/.x-code/config.json`。一份配置两边都能跑。 diff --git a/docs/plugin-authoring.en.md b/docs/plugin-authoring.en.md new file mode 100644 index 0000000..2a83522 --- /dev/null +++ b/docs/plugin-authoring.en.md @@ -0,0 +1,229 @@ +# Authoring a Plugin + +A plugin is a directory with a manifest at the root. This page is the +schema reference plus the layout conventions x-code expects. + +See also: [Plugins user guide](plugins.md) · [Hooks](hooks.md) · +[Marketplace](marketplace.md) + +--- + +## Minimum viable plugin + +The smallest plugin that loads: + +``` +my-plugin/ +└── .x-code-plugin/ + └── plugin.json +``` + +```jsonc +{ + "name": "my-plugin", + "version": "0.1.0", +} +``` + +Install it (from inside `my-plugin`'s parent dir): + +```bash +xc plugin install ./my-plugin +``` + +You'll get a "no contributions" warning in `/plugin info` — that's fine. +Add contributions below to make it useful. + +--- + +## Manifest paths the loader probes + +In order: + +1. `.x-code-plugin/plugin.json` ← preferred for new plugins +2. `.claude-plugin/plugin.json` ← for Claude Code compatibility +3. `plugin.json` ← tolerated + +If only `gemini-extension.json` is present, install is rejected with a +pointer to this page. (See [plugins.md § Compatibility](plugins.md).) + +--- + +## Manifest reference + +Every field is optional except `name` and `version`. Unknown top-level +fields are silently dropped, so plugins authored for Claude Code with +fields like `output-styles` or `lspServers` install cleanly — the +unsupported parts just don't activate. + +```jsonc +{ + // Schema version. Always "1" today; future breaking changes will + // bump this. If absent, "1" is assumed. + "schemaVersion": "1", + + // ── Identity ──────────────────────────────────────────────────── + "name": "linear", // [a-z0-9][a-z0-9-]* — used as + // a filesystem-safe path component + // on every OS + "version": "1.2.0", // semver string; not enforced + + "description": "Linear issue integration", + "author": { + // OR just a string "Name" + "name": "Anthropic", + "email": "support@anthropic.com", + "url": "https://anthropic.com", + }, + "keywords": ["productivity", "issue-tracker"], + "homepage": "https://github.com/anthropics/linear-plugin", + "license": "MIT", + + // ── Contributions (paths are relative to plugin root) ────────── + // + // Each `` field below points at a directory or, where noted, + // either a file path or an inline object. All are optional. + + "skills": "./skills", // directory of /SKILL.md + "agents": "./agents", // directory of .md + "commands": "./commands", // declared but not yet wired + // (no file-based slash command + // loader yet) + + // mcpServers: either a path to a JSON file shaped + // `{ "mcpServers": { ... } }` (same as ~/.x-code/config.json), + // OR the raw record inline. Inline form shown: + "mcpServers": { + "linear": { + "command": "node", + "args": ["${pluginDir}/server.js"], + "env": { "LINEAR_API_KEY": "${env:LINEAR_API_KEY}" }, + }, + }, + + // hooks: either a path to a hooks.json, OR an inline object. See + // docs/hooks.en.md for the full event list and decision protocol. + // 10 events: SessionStart / UserPromptSubmit / PreToolUse / PostToolUse + // / PreCompact / PostCompact / SubagentStart / SubagentStop / + // TurnComplete / SessionEnd + "hooks": { + "PreToolUse": [ + { + "matcher": "writeFile|edit", + "command": "node ${pluginDir}/hooks/lint.js", + // Cross-platform overrides — set whichever OSes need different syntax + "commandWindows": "node \"${pluginDir}/hooks/lint.js\"", + "timeout": 5000, + }, + ], + }, + + // ── User-supplied config items (prompted at install time) ────── + "userConfig": [ + { + "key": "LINEAR_API_KEY", + "type": "string", + "sensitive": true, // future: stored via system keyring + // (today: stored in settings) + "prompt": "Enter your Linear API key", + "required": true, + }, + ], + + // ── Dependencies & engines ───────────────────────────────────── + "dependencies": ["base-skills@anthropic-marketplace"], + "engines": { "x-code": ">=0.5.0" }, +} +``` + +### Field-level notes + +- **`name`** — lowercase letters, digits, dashes. Must start with a + letter or digit. The same rule applies in Claude Code / Codex. +- **`skills`** / **`agents`** / **`commands`** — paths to the + respective directories. **Most Claude Code plugins omit these + fields**; the loader auto-detects `skills/` / `agents/` / `commands/` + subdirs by convention. Only set explicitly when using a non-standard + layout. `commands` is accepted but not wired at runtime today. +- **`mcpServers`** — path or inline object. When unset, the loader + auto-detects `.mcp.json` (Claude Code convention) or `mcp.json`. + Per-server schema matches `~/.x-code/config.json`; variables + (`${pluginDir}`, `${env:NAME}`, …) expand at server-launch time. +- **`hooks`** — path or inline object. When unset, the loader + auto-detects `hooks/hooks.json`. See [hooks.en.md](hooks.en.md) for + the event list and decision JSON. + +--- + +## Layout convention + +``` +my-plugin/ +├── .x-code-plugin/ +│ └── plugin.json +├── skills/ +│ └── search/ +│ ├── SKILL.md # YAML frontmatter + body +│ └── references/ # bundled files surfaced in skill activation +│ └── api.md +├── agents/ +│ └── triage.md # sub-agent definition +├── commands/ # (declared but not yet loaded) +│ └── linear.md +├── mcp.json # if you split mcpServers into a file +├── hooks/ +│ ├── hooks.json # if you split hooks into a file +│ ├── lint.js +│ └── audit.sh +├── README.md +└── LICENSE +``` + +You don't have to use this exact layout — the `skills` / `agents` / +`commands` / `mcpServers` / `hooks` manifest fields can each point +anywhere relative to the plugin root. Sticking close to the convention +makes plugins easier to read. + +--- + +## Iterating locally + +1. Write the manifest and any contributions. +2. `xc plugin install ./my-plugin` — copies into + `~/.x-code/plugins/cache/local///` and records the + install. +3. Restart `xc` to pick up your contributions. +4. Iterate. Re-running `xc plugin install ./my-plugin` over the same + plugin overwrites the cache (same-version reinstall is supported); + bump the manifest version to install as a separate version. + +For tighter loops, you can edit files directly inside the cache dir — +it survives restarts. Don't ship that as your dev workflow though: +re-running the install ensures your source dir is the source of truth. + +--- + +## Testing your plugin + +The repo's existing fixtures show the shape of a test plugin — +see `packages/core/tests/plugins-install-load.test.ts` for examples +that install a plugin from a temp dir and assert the loader picks up +its contributions. + +The integration boundary (plugin → existing loaders) is in +`packages/core/src/plugins/integration.ts`. If a plugin's MCP / hook +config has a parse error, it surfaces via `/plugin doctor` rather than +crashing the CLI — your tests should cover that path too. + +--- + +## Common pitfalls + +| Pitfall | Fix | +| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` rejected with regex error | Use lowercase letters, digits, dashes only. No underscores, no uppercase. | +| Hook never fires | Restart `xc` after install — hooks register at startup. Check `DEBUG_STDOUT=1` + `~/.x-code/logs/debug.log`. | +| `${pluginDir}` not expanded | Only expanded inside hook commands and slash command templates. For MCP server args / env, the MCP loader does its own `${VAR}` expansion (env vars only — see `packages/core/src/mcp/expand-env.ts`). | +| `${pluginDataDir}` write fails | Auto-created at `~/.x-code/plugins/data//`, preserved across versions. First substitution does `mkdir -p`; permission errors surface in the shell. **Don't** write persistent data to `${pluginDir}` — it gets wiped on every reinstall / upgrade. | +| Plugin loads but contributions don't appear | Run `/plugin info ` to confirm the manifest was parsed and the contribution paths exist on disk. | +| Want to release publicly | Publish to a marketplace.json that lists your plugin's git URL; tell users to `xc plugin marketplace add `. See [marketplace.md](marketplace.md). | diff --git a/docs/plugin-authoring.md b/docs/plugin-authoring.md new file mode 100644 index 0000000..f170f4c --- /dev/null +++ b/docs/plugin-authoring.md @@ -0,0 +1,193 @@ +# 写自己的插件 + +插件就是一个带 manifest 的目录。本文是 schema 与 layout 约定的参考——如果你只是想用别人的插件，看 [plugins.md](./plugins.md) 就够了。 + +英文版：[plugin-authoring.en.md](./plugin-authoring.en.md) + +--- + +## 最小可用插件 + +能加载的最简结构： + +``` +my-plugin/ +└── .x-code-plugin/ + └── plugin.json +``` + +```jsonc +{ + "name": "my-plugin", + "version": "0.1.0", +} +``` + +安装（在 `my-plugin` 父目录里执行）： + +```bash +xc plugin install ./my-plugin +``` + +`/plugin info` 会显示 "no contributions" warning——正常。下面加贡献让它真正有用。 + +--- + +## Manifest 路径探测顺序 + +1. `.x-code-plugin/plugin.json` ← 新插件首选 +2. `.claude-plugin/plugin.json` ← Claude Code 兼容 +3. `plugin.json` ← 也接受 + +只有 `gemini-extension.json` 存在时安装被拒（与 Gemini 不兼容，详见 [plugins.md § 兼容性](./plugins.md)）。 + +--- + +## Manifest 字段参考 + +只有 `name` 和 `version` 必需。未知顶层字段静默 drop——所以 Claude Code 插件带 `output-styles` 或 `lspServers` 也能正常安装，那些字段不激活而已。 + +```jsonc +{ + // schema 版本，今天恒为 "1"。未来 breaking change 会 bump 这个值。 + // 缺失则默认 "1"。 + "schemaVersion": "1", + + // ── 身份 ──────────────────────────────────────────────────── + "name": "linear", // [a-z0-9][a-z0-9-]* — 用作跨平台 + // 文件系统安全路径片段 + "version": "1.2.0", // semver 字符串，不强制 + + "description": "Linear issue 集成", + "author": { + // 也接受 "Name" 字符串形式 + "name": "Anthropic", + "email": "support@anthropic.com", + "url": "https://anthropic.com", + }, + "keywords": ["productivity", "issue-tracker"], + "homepage": "https://github.com/anthropics/linear-plugin", + "license": "MIT", + + // ── 贡献（路径相对插件根） ────────────────────────────────── + // + // 下面每个 字段指向一个目录，或者标注的情况下也接受文件路径 + // 或 inline 对象。全部可选。 + + "skills": "./skills", // /SKILL.md 子目录的目录 + "agents": "./agents", // .md 文件的目录 + "commands": "./commands", // 声明但暂未生效 + // （还没有基于文件的 slash 命令加载器） + + // mcpServers: 既可以是路径，指向形如 + // `{ "mcpServers": { ... } }` 的 JSON 文件（同 ~/.x-code/config.json）， + // 也可以直接 inline。以下是 inline 形式： + "mcpServers": { + "linear": { + "command": "node", + "args": ["${pluginDir}/server.js"], + "env": { "LINEAR_API_KEY": "${env:LINEAR_API_KEY}" }, + }, + }, + + // hooks: 路径指向 hooks.json，或者直接 inline。详见 docs/hooks.md + // 10 个事件：SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / + // PreCompact / PostCompact / SubagentStart / SubagentStop / TurnComplete / + // SessionEnd + "hooks": { + "PreToolUse": [ + { + "matcher": "writeFile|edit", + "command": "node ${pluginDir}/hooks/lint.js", + // 跨平台命令：Windows / macOS / Linux 任一需要特殊语法时单独覆盖 + "commandWindows": "node \"${pluginDir}/hooks/lint.js\"", + "timeout": 5000, + }, + ], + }, + + // ── 用户提供的配置项（安装时弹询问，未来版本） ───────────────── + "userConfig": [ + { + "key": "LINEAR_API_KEY", + "type": "string", + "sensitive": true, // 未来：走系统 keyring + // 当前：解析了但尚未实际询问 / 存储 + "prompt": "输入你的 Linear API key", + "required": true, + }, + ], + + // ── 依赖与运行时兼容性 ────────────────────────────────────── + "dependencies": ["base-skills@anthropic-marketplace"], + "engines": { "x-code": ">=0.5.0" }, +} +``` + +### 字段细节 + +- **`name`** — 小写字母、数字、短横线。必须字母或数字开头。Claude Code / Codex 同规则。 +- **`skills`** / **`agents`** / **`commands`** — 指向各自目录。**绝大多数 Claude Code 插件 manifest 不写这三个字段**——loader 会自动探测 `skills/` / `agents/` / `commands/` 子目录（约定优先）。只在你想用非常规路径时声明。`commands` 当前只是声明被接受，运行时还没有 slash 命令加载器。 +- **`mcpServers`** — 路径或 inline 对象。不声明时自动探测 `.mcp.json`（Claude Code 约定）或 `mcp.json`。每个 server 的 schema 同 `~/.x-code/config.json`，变量展开（`${pluginDir}`、`${env:NAME}` 等）在 server 启动时进行。 +- **`hooks`** — 路径或 inline 对象。不声明时自动探测 `hooks/hooks.json`。详见 [hooks.md](./hooks.md)。 + +--- + +## 典型目录布局 + +``` +my-plugin/ +├── .x-code-plugin/ +│ └── plugin.json +├── skills/ +│ └── search/ +│ ├── SKILL.md # YAML frontmatter + body +│ └── references/ # bundled 文件，激活时一并通知 agent +│ └── api.md +├── agents/ +│ └── triage.md # sub-agent 定义 +├── commands/ # 暂未加载 +│ └── linear.md +├── mcp.json # 如果把 mcpServers 拆到独立文件 +├── hooks/ +│ ├── hooks.json # 如果把 hooks 拆到独立文件 +│ ├── lint.js +│ └── audit.sh +├── README.md +└── LICENSE +``` + +不必严格按这个布局——`skills` / `agents` / `commands` / `mcpServers` / `hooks` 字段每个都可以指任意相对路径。跟着约定走只是让别人读起来更顺。 + +--- + +## 本地迭代流程 + +1. 写 manifest 和贡献内容 +2. `xc plugin install ./my-plugin`——拷贝到 `~/.x-code/plugins/cache/local///` 并登记 +3. 重启 `xc` 让贡献生效 +4. 改 + 再装。同版本重装会覆盖缓存（支持同版本重装）；要并存多个版本就 bump 一下 manifest version + +更紧的循环可以直接编辑 cache 目录里的文件——重启 xc 仍能看到改动。但不要把这个当开发流程：定期 reinstall 一下让你的源目录保持权威。 + +--- + +## 测试插件 + +仓库现有测试 fixture 展示了测试插件的形态——见 +`packages/core/tests/plugins-install-load.test.ts`，里面有从临时目录装插件并断言 loader 加载贡献的例子。 + +集成边界（plugin → existing loaders）在 `packages/core/src/plugins/integration.ts`。如果插件的 MCP / hook 配置有解析错误，它会进 `/plugin doctor` 而不是炸 CLI——你的测试也应该覆盖那条路径。 + +--- + +## 常见坑 + +| 坑 | 处理 | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `name` 报 regex 错 | 只能用小写字母、数字、短横线。不能有下划线和大写 | +| Hook 不触发 | 装完 `xc` 重启——hook 在启动时注册。看 `DEBUG_STDOUT=1` + `~/.x-code/logs/debug.log` | +| `${pluginDir}` 没展开 | 只在 hook command 和 slash command 模板里展开。MCP server 的 args / env 走 MCP 自己的 `${VAR}` 展开（仅 env 变量，见 `packages/core/src/mcp/expand-env.ts`） | +| `${pluginDataDir}` 写入失败 | 自动创建在 `~/.x-code/plugins/data//`，跨版本保留。第一次替换时 `mkdir -p`，权限错误会让 shell 报错。**别**把可持久化数据写到 `${pluginDir}` —— 它会在重装/升级时整个被擦掉 | +| 插件装上了贡献不出现 | `/plugin info ` 确认 manifest 解析成功，且贡献路径在磁盘上存在 | +| 想公开发布 | 发一个 marketplace.json 列你的插件 git URL，告诉用户 `xc plugin marketplace add `。见 [marketplace.md](./marketplace.md) | diff --git a/docs/plugins.en.md b/docs/plugins.en.md new file mode 100644 index 0000000..7c92873 --- /dev/null +++ b/docs/plugins.en.md @@ -0,0 +1,307 @@ +# Plugins — User Guide + +A **plugin** is an installable package that contributes one or more of: +skills, sub-agents, slash commands, MCP servers, or lifecycle hooks. +Plugins are how third-party authors extend `xc` without forking the CLI. + +See also: [Authoring a plugin](plugin-authoring.md) · +[Hooks reference](hooks.md) · [Marketplace reference](marketplace.md) + +--- + +## TL;DR + +```bash +# Install from a subscribed marketplace +xc plugin install linear@anthropic-marketplace + +# Install from a GitHub repo +xc plugin install github:owner/repo + +# Install from a local path (great for plugin development) +xc plugin install ./my-plugin + +# List what's installed +xc plugin list + +# Remove a plugin +xc plugin uninstall linear@anthropic-marketplace +``` + +After install or uninstall, **restart `xc`** for the contributions +(skills / agents / MCP / hooks) to take effect. + +--- + +## Two ways to drive it + +The same operations exist in both surfaces — pick whichever you're in: + +| Action | Slash command (interactive) | Non-interactive | +| ------------------- | ------------------------------ | ------------------------------------ | +| List plugins | `/plugin list` | `xc plugin list` | +| Show plugin details | `/plugin info ` | `xc plugin info ` | +| Install | `/plugin install ` | `xc plugin install [--yes] ` | +| Uninstall | `/plugin uninstall ` | `xc plugin uninstall ` | +| Enable / disable | `/plugin enable\|disable ` | `xc plugin enable\|disable ` | +| Search marketplaces | `/plugin search ` | `xc plugin search ` | +| Update | `/plugin update ` | `xc plugin update ` | +| Diagnose problems | `/plugin doctor` | `xc plugin doctor` | +| Manage marketplaces | `/plugin marketplace …` | `xc plugin marketplace …` | + +The non-interactive form is intended for scripts and CI. `xc plugin +install` runs a y/N consent prompt by default; pass `--yes` to skip it +when you're scripting trusted installs. + +--- + +## Install sources + +`xc plugin install` accepts four kinds of source: + +| Form | Example | Notes | +| ----------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `@` | `linear@anthropic-marketplace` | Looks up the entry in the cached marketplace index and installs from its declared source. Requires the marketplace to be subscribed (and refreshed). | +| `github:/[#ref]` | `github:foo/bar`, `github:foo/bar#v1.2.0` | Shallow `git clone` of the repo. Ref is optional and may be a branch or tag. | +| `https://…` or `git@…` | `https://gitlab.example/foo/bar.git` | Any git-clone-able URL. | +| Filesystem path | `./my-plugin`, `/abs/path/to/plugin` | Useful for plugin authors iterating locally. | + +The first three install under the `local` marketplace unless you used +the `@` form. The marketplace name shows up in +`/plugin list` so you can tell at a glance where each plugin came from. + +--- + +## Install-time consent + +`xc plugin install` shows a preview before committing the install: + +``` +About to install: linear@anthropic-marketplace v1.2.0 + Linear issue integration + + Source: github:anthropics/linear-plugin + Marketplace: anthropic-marketplace [reserved/official] [verified] + Author: Anthropic + License: MIT + + Will contribute: + - skills (added to /skill list) + - MCP servers (will be spawned as subprocesses): linear + - Lifecycle hooks (will run shell commands on: PostToolUse) + +Proceed with install? [y/N] +``` + +The two **red** items in the list — MCP servers and lifecycle hooks — +are the load-bearing trust decisions: both run code on your machine. +Inspect the source before answering `y` for anything from a marketplace +you don't trust. + +In non-TTY environments (CI, piped install scripts), the prompt +defaults to **no**. Pass `--yes` to opt out: + +```bash +xc plugin install --yes linear@anthropic-marketplace +``` + +The slash-command flow (`/plugin install`) does not currently show this +prompt — typing the command in the chat is treated as explicit intent. +We may add an inline confirmation modal later; track this as a known +limitation today. + +--- + +## Scopes + +A plugin's enable flag lives in one of two scopes — same convention as +skills (see `packages/core/src/skills/settings.ts`): + +| Scope | File | Notes | +| --------- | ----------------------------------- | ---------------------------------------- | +| `user` | `~/.x-code/settings.json` | Default for `xc plugin enable\|disable`. | +| `project` | `/.x-code/settings.local.json` | Per-user, gitignored. Overrides `user`. | + +The shape inside each file: + +```jsonc +{ + "enabledPlugins": { + "linear@anthropic-marketplace": true, + "k8s-debug@local": false, + }, +} +``` + +A plugin not listed in either scope defaults to **enabled**. Disable +explicitly when you want it off. `project` settings win over `user`. + +Pick the scope explicitly via `--scope`: + +```bash +# Disable a plugin in this project only, leaving other projects untouched +xc plugin disable linear@anthropic-marketplace --scope=project +# Enable globally (the default) +xc plugin enable linear@anthropic-marketplace --scope=user +``` + +The slash command form (`/plugin enable | disable`) accepts the same flag. + +--- + +## Filesystem layout + +Everything plugin-related lives under `~/.x-code/plugins/`: + +``` +~/.x-code/plugins/ +├── known_marketplaces.json # subscribed marketplaces +├── marketplaces/ +│ └── anthropic-marketplace/ +│ └── marketplace.json # cached marketplace index +├── cache/ +│ └── anthropic-marketplace/ +│ └── linear/ +│ └── 1.2.0/ # actual installed plugin +│ ├── .claude-plugin/plugin.json +│ ├── skills/ +│ ├── mcp.json +│ └── hooks/hooks.json +├── data/ +│ └── linear@anthropic-marketplace/ # persistent per-plugin data +│ # (survives uninstall+reinstall) +└── installed_plugins.json # bookkeeping +``` + +The `data/` directory is preserved on uninstall, so reinstalling +recovers any state a plugin chose to save there. + +--- + +## Disabling the plugin system entirely + +Two startup escape hatches: + +```bash +xc --no-plugins # skip plugin discovery entirely +xc --no-hooks # load plugins but skip hook execution +``` + +Use `--no-plugins` when you suspect a plugin is the cause of a +problem; `--no-hooks` keeps skills / agents / MCP from broken plugins +active but mutes lifecycle hooks for a session. + +--- + +## When changes take effect — `/plugin refresh` + +Plugin contributions (skills / sub-agents / commands / hooks) are folded +into their respective registries at CLI startup. After installing, +uninstalling, enabling, or disabling a plugin mid-session, run +**`/plugin refresh`** to reload everything live without restarting: + +```text +> /plugin refresh +Reloaded plugins — added: my-new-plugin@local; unchanged: linear@anthropic-marketplace. +Downstream: 3 skill change(s), 1 command change(s). +Note: plugin-contributed MCP servers are not restarted — run `/mcp refresh` if needed. +Note: next message rebuilds the system prompt, so prompt-cache will miss once. +``` + +What happens internally: + +1. Re-scan installed plugins, re-parse every manifest. +2. Rebuild PluginRegistry in place (object identity stays — every captured ref is still valid). +3. Fold new skills / sub-agents / commands / hooks into their registries. +4. Invalidate `systemPromptCache` so the next message rebuilds the prompt (one cache miss, expected). + +**MCP exception**: plugin-contributed MCP servers spawned a child process +at first launch — hot reload does not restart them. After installing or +removing a plugin with MCP, follow up with `/mcp refresh`. + +`/plugin list` and `/plugin info` always reflect the live state. + +--- + +## `userConfig`: prompt at install time + +A plugin's manifest can declare what user-supplied configuration it +needs (API keys, account ids, base URLs, …): + +```jsonc +{ + "userConfig": [ + { + "key": "LINEAR_API_KEY", + "type": "string", + "sensitive": true, + "prompt": "Enter your Linear API key", + "required": true, + }, + { "key": "BASE_URL", "type": "string", "default": "https://api.example.com" }, + ], +} +``` + +At install time (when **not** running with `--yes`) the CLI walks each +field and prompts for a value; `sensitive: true` fields are entered +with local echo suppressed (git-style password input). + +Values are stored in `~/.x-code/plugins/user-config.json` with file mode +`0600` (owner-read-write only). At hook execution and at plugin- +contributed MCP server launch, they are injected into the child process +`env` keyed by the manifest's `key`. So a hook script can just read +`process.env.LINEAR_API_KEY` — no glue. + +⚠️ v1 caveat: `sensitive: true` currently only controls **display +during input**, not the at-rest storage. Real OS keychain integration +(macOS Keychain / Windows Credential Manager / Linux libsecret) is a +followup. On Windows `0600` is effectively a no-op for ACL reasons — +plan storage accordingly. + +`--yes` installs skip the prompt; values stay unset. To pre-seed values +for CI, hand-write `~/.x-code/plugins/user-config.json` before the +install. + +--- + +## `--plugin-debug` for diagnostics + +To watch plugin loading, hook execution, and marketplace fetches live: + +```bash +xc --plugin-debug +# equivalent to +XC_PLUGIN_DEBUG=1 xc +``` + +This mirrors `plugins.*` / `plugin.*` / `hooks.*` / `marketplace.*` +debug breadcrumbs to stderr, without flipping `DEBUG_STDOUT=1` (which +would dump every debug tag, far noisier). + +--- + +## Troubleshooting + +| Symptom | First thing to try | +| --------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| Plugin doesn't appear after install | Restart `xc`. Contributions are bound at startup. | +| `/plugin doctor` shows load errors | Check the file path it reports — usually a manifest typo. | +| MCP server from a plugin won't connect | Run `/mcp list` — plugin-contributed servers appear there too. | +| Hook fires unexpectedly | Set `DEBUG_STDOUT=1`, restart, then `tail ~/.x-code/logs/debug.log` and grep `hooks.`. | +| Suspect a plugin is breaking everything | Launch with `xc --no-plugins`. If the problem disappears, isolate with `/plugin disable ` + restart. | +| Hook is slow / hangs | Launch with `xc --no-hooks`. Each hook also has a 5s default timeout. | + +--- + +## Compatibility with Claude Code / Codex plugins + +`xc` deliberately reads `.claude-plugin/plugin.json` in addition to its +native `.x-code-plugin/plugin.json` path. A plugin authored for Claude +Code will install in `xc` without modification — its skills, agents, +MCP servers, and hooks all wire up the same way. The two fields we +don't support (`output-styles`, `lspServers`) are silently ignored; +everything else loads. + +Gemini extensions (`gemini-extension.json`) are **not** supported. +Trying to install one prints a friendly error pointing at this doc. diff --git a/docs/plugins.md b/docs/plugins.md new file mode 100644 index 0000000..918f5d7 --- /dev/null +++ b/docs/plugins.md @@ -0,0 +1,260 @@ +# 插件 — 使用指南 + +**插件**是可分发的功能包：把 skills / sub-agents / MCP 服务器 / hooks 打包成一个安装单元，第三方可以编写并分发，用户一行命令安装。 + +英文版：[plugins.en.md](./plugins.en.md) · 相关：[hooks.md](./hooks.md) · [marketplace.md](./marketplace.md) · 自己写插件见 [plugin-authoring.md](./plugin-authoring.md) + +--- + +## TL;DR + +```bash +# 从订阅的 marketplace 安装 +xc plugin install linear@anthropic-marketplace + +# 从 GitHub 仓库安装 +xc plugin install github:owner/repo + +# 从本地路径安装（适合插件开发迭代） +xc plugin install ./my-plugin + +# 列出已安装 +xc plugin list + +# 卸载 +xc plugin uninstall linear@anthropic-marketplace +``` + +**安装/卸载后请重启 `xc`** 让贡献的 skill / agent / MCP / hooks 生效。 + +--- + +## 两种使用方式 + +| 操作 | 交互内 slash 命令 | 命令行 | +| ---------------- | ------------------------------ | ------------------------------------ | +| 列出插件 | `/plugin list` | `xc plugin list` | +| 看插件详情 | `/plugin info ` | `xc plugin info ` | +| 安装 | `/plugin install ` | `xc plugin install [--yes] ` | +| 卸载 | `/plugin uninstall ` | `xc plugin uninstall ` | +| 启用 / 禁用 | `/plugin enable\|disable ` | `xc plugin enable\|disable ` | +| 搜索 marketplace | `/plugin search ` | `xc plugin search ` | +| 升级 | `/plugin update ` | `xc plugin update ` | +| 诊断 | `/plugin doctor` | `xc plugin doctor` | +| 管理 marketplace | `/plugin marketplace …` | `xc plugin marketplace …` | + +`xc plugin` 命令行形式适合脚本和 CI。`xc plugin install` 默认走 y/N consent 提示——加 `--yes` 跳过。 + +--- + +## 安装源的四种写法 + +| 形式 | 示例 | 说明 | +| ----------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------ | +| `@` | `linear@anthropic-marketplace` | 在缓存的 marketplace 索引里查，按其声明的 source 下载。要求 marketplace 已订阅并已 refresh | +| `github:/[#ref]` | `github:foo/bar`、`github:foo/bar#v1.2.0` | 浅克隆 GitHub repo。ref 可选，分支或 tag | +| `https://…` 或 `git@…` | `https://gitlab.example/foo/bar.git` | 任意 git URL | +| 文件路径 | `./my-plugin`、`/abs/path/to/plugin` | 适合插件开发者本地迭代 | + +后三种安装的插件归到 `local` marketplace。`/plugin list` 会按 marketplace 标注来源。 + +--- + +## 安装时的 consent 提示 + +`xc plugin install` 在真正落盘前会显示预览： + +``` +About to install: linear@anthropic-marketplace v1.2.0 + Linear issue integration + + Source: github:anthropics/linear-plugin + Marketplace: anthropic-marketplace [reserved/official] [verified] + Author: Anthropic + License: MIT + + Will contribute: + - skills (added to /skill list) + - MCP servers (will be spawned as subprocesses): linear + - Lifecycle hooks (will run shell commands on: PostToolUse) + +Proceed with install? [y/N] +``` + +预览中**红色**的两项——MCP 服务器和 lifecycle hooks——是关键的信任决策：两者都会在你的机器上跑代码。来自不熟悉 marketplace 的插件，按 `y` 前先看一眼源码。 + +非 TTY 环境（CI、脚本管道）下默认拒绝；显式跳过： + +```bash +xc plugin install --yes linear@anthropic-marketplace +``` + +Slash 命令版 `/plugin install` 暂时不弹此提示——交互内打命令本身视为同意。未来可能改成内联确认，目前算已知限制。 + +--- + +## Scope（启用范围） + +启用状态可写到两个 scope（与 skills、mcp 同约定）： + +| Scope | 路径 | 说明 | +| --------- | ----------------------------------- | ---------------------------------------- | +| `user` | `~/.x-code/settings.json` | `xc plugin enable\|disable` 的默认 scope | +| `project` | `/.x-code/settings.local.json` | per-user 在该 repo 的覆盖，gitignored | + +显式选定 scope 用 `--scope`： + +```bash +# 仅在当前项目禁用某插件，不影响其他项目 +xc plugin disable linear@anthropic-marketplace --scope=project +# 全局启用（默认行为） +xc plugin enable linear@anthropic-marketplace --scope=user +``` + +`/plugin enable | disable` 在交互模式下接受同样的 flag。 + +文件格式： + +```jsonc +{ + "enabledPlugins": { + "linear@anthropic-marketplace": true, + "k8s-debug@local": false, + }, +} +``` + +未列出的插件默认**启用**，显式禁用才生效。`project` 设置赢过 `user`。 + +--- + +## 文件系统布局 + +所有插件相关的东西都在 `~/.x-code/plugins/` 下： + +``` +~/.x-code/plugins/ +├── known_marketplaces.json # 订阅的 marketplace 列表 +├── marketplaces/ +│ └── anthropic-marketplace/ +│ └── marketplace.json # 缓存的 marketplace 索引 +├── cache/ +│ └── anthropic-marketplace/ +│ └── linear/ +│ └── 1.2.0/ # 实际安装的插件内容 +│ ├── .claude-plugin/plugin.json +│ ├── skills/ +│ ├── mcp.json +│ └── hooks/hooks.json +├── data/ +│ └── linear@anthropic-marketplace/ # 插件持久化数据，卸载也保留 +└── installed_plugins.json # 安装登记 +``` + +`data/` 在卸载时不删，重装时插件能恢复之前的状态。 + +> **Windows 路径**：`~/.x-code` 在 Windows 上是 `%USERPROFILE%\.x-code`。 + +--- + +## 关掉整个插件系统 + +两个启动开关： + +```bash +xc --no-plugins # 完全跳过插件发现 +xc --no-hooks # 插件正常加载，但 hooks 全部不执行 +``` + +`--no-plugins` 用于排查"是不是某个插件搞砸了"；`--no-hooks` 保留 skills / agents / MCP 但关掉所有 lifecycle 回调。 + +--- + +## 改动何时生效 + `/plugin refresh` + +插件的贡献（skill / sub-agent / 命令 / hooks）在 CLI 启动时合入对应的 registry。会话期间安装/卸载/启用/禁用之后，可以用 **`/plugin refresh`** 在当前会话即时重新加载所有插件，无需重启： + +```text +> /plugin refresh +Reloaded plugins — added: my-new-plugin@local; unchanged: linear@anthropic-marketplace, code-review@anthropic-marketplace. +Downstream: 3 skill change(s), 1 command change(s). +Note: plugin-contributed MCP servers are not restarted — run `/mcp refresh` if needed. +Note: next message rebuilds the system prompt, so prompt-cache will miss once. +``` + +刷新过程： + +1. 重扫已安装插件 + 解析 manifest +2. 重建 PluginRegistry（保留对象身份，所有 captured ref 仍然有效） +3. 把新的 skill / sub-agent / 命令 / hook 折回各自的 registry +4. 失效 `systemPromptCache` —— 下一条消息会重建系统 prompt（cache miss 一次，正常） + +**MCP 服务器例外**：plugin 贡献的 MCP server 在第一次启动时就 spawn 了子进程，hot reload 不会重启它们。装/卸有 MCP 的插件后**额外**跑一次 `/mcp refresh`。 + +`/plugin list` 与 `/plugin info` 始终展示当前真正在跑的状态。 + +--- + +## userConfig：装时问值 + +插件 manifest 可以声明它需要哪些用户提供的配置（API key、账号 ID、URL 等）： + +```jsonc +{ + "userConfig": [ + { + "key": "LINEAR_API_KEY", + "type": "string", + "sensitive": true, + "prompt": "Enter your Linear API key", + "required": true, + }, + { "key": "BASE_URL", "type": "string", "default": "https://api.example.com" }, + ], +} +``` + +装这个插件时（**非** `--yes` 模式），CLI 会按顺序逐项问值；`sensitive: true` 的字段输入时不回显（git 风格的密码输入）。 + +值存到 `~/.x-code/plugins/user-config.json`，文件权限 `0600`（仅本用户可读）。Hook 跑的时候、plugin-contributed MCP server 启动的时候，这些值会自动注入到子进程 `env`，key 名就是 manifest 里的 `key` 字段。所以 hook 脚本里直接 `process.env.LINEAR_API_KEY` 就能用，无需额外胶水。 + +⚠️ 当前 v1：`sensitive: true` 只控制**输入时的回显**，存储是 `0600` 文件不是系统 keychain。真正的 keychain 集成（macOS Keychain / Windows Credential Manager / Linux libsecret）规划在 followup。Windows 上 `0600` 实际是 no-op，注意场景。 + +`--yes` 安装跳过 prompt，user-config 留空。需要 CI 装的话，提前手写 `~/.x-code/plugins/user-config.json` 即可。 + +## `--plugin-debug` 排查 + +要看插件加载 / hook 执行 / marketplace fetch 的实时细节： + +```bash +xc --plugin-debug +# 等价于 +XC_PLUGIN_DEBUG=1 xc +``` + +把 `plugins.` / `plugin.` / `hooks.` / `marketplace.` 标签的 debug 行实时镜像到 stderr，不需要 `DEBUG_STDOUT=1`（那个会把所有 debug 都喷出来）。装/卸/启用插件后看不到预期效果时用这个。 + +## 故障排查 + +| 症状 | 先试 | +| ------------------------------- | ---------------------------------------------------------------------------- | +| 安装后插件不出现 | 重启 `xc`。贡献在启动时绑定 | +| `/plugin doctor` 报 load errors | 看它打印的路径——通常是 manifest 拼写错 | +| 插件的 MCP 服务连不上 | `/mcp list`——插件提供的 server 也会列在那里 | +| Hook 触发意外 | `DEBUG_STDOUT=1` 重启 → `tail ~/.x-code/logs/debug.log` 搜 `hooks.` | +| 怀疑某插件搞砸 | `xc --no-plugins` 启动；若问题消失就用 `/plugin disable ` + 重启逐个排查 | +| Hook 跑得慢 / 卡住 | `xc --no-hooks` 启动；每个 hook 默认 5s 超时 | + +--- + +## 与 Claude Code / Codex 插件的兼容性 + +x-code 故意同时识别 `.claude-plugin/plugin.json` 和原生的 `.x-code-plugin/plugin.json`。Claude Code 写的插件原样安装在 x-code 里——skills、agents、MCP servers、hooks 全部按一样的方式接入。两个 Claude Code 独有字段（`output-styles`、`lspServers`）会被静默忽略。 + +Gemini extension（`gemini-extension.json`）**不支持**——安装时会报错并指向本文档。 + +--- + +## 写自己的插件 + +见 [plugin-authoring.md](./plugin-authoring.md)，里面有完整 manifest schema、目录约定、本地迭代流程。 diff --git a/docs/skills.en.md b/docs/skills.en.md new file mode 100644 index 0000000..ce23e42 --- /dev/null +++ b/docs/skills.en.md @@ -0,0 +1,249 @@ +# Skills — Usage Guide + +**Skills** are reusable workflow prompt templates you write once and trigger +with `/` later. Common uses: code-review checklists, PR-review +playbooks, language- or framework-specific best-practice cheatsheets. + +中文版：[skills.md](./skills.md) + +--- + +## TL;DR + +```bash +# A global skill (available in every project) +mkdir -p ~/.x-code/skills/code-review +cat > ~/.x-code/skills/code-review/SKILL.md <<'EOF' +--- +name: code-review +description: Review a diff against the team checklist +--- +Review the diff I provide using these criteria: +1. Boundary conditions covered +2. Error handling complete +3. Tests updated to match +4. New dependencies introduced +EOF + +# Restart xc, or `/skill refresh` in the running session. +# Then in chat: +> /code-review @D:\project\diff.patch +``` + +--- + +## What a skill looks like on disk + +A skill is a directory with a `SKILL.md` at the top: + +``` +~/.x-code/skills// +├── SKILL.md # required: YAML frontmatter + Markdown body +├── references/ # optional bundled resources +├── scripts/ # optional helper scripts +└── ... # any other files +``` + +**SKILL.md content**: + +```markdown +--- +name: code-review +description: Review a diff against the team checklist (the agent reads this to decide whether to activate) +--- + +Review the diff I provide using these criteria: +... +``` + +The frontmatter accepts exactly two fields: + +- `name` (required) — should match the directory name; `/` triggers it +- `description` (required) — one-line summary; the agent reads it to decide + when to activate the skill on its own + +**Bundled files**: at activation time the CLI lists every non-hidden file in +the skill directory (capped at 50) and hands the list to the agent, which +can then read any of them by relative path: + +```markdown +Walk through the checklist in references/checklist.md and apply each item. +``` + +--- + +## Where skills live + +| Scope | Path | When | +| ------- | --------------------------------------- | ---------------------------------------- | +| Global | `~/.x-code/skills//SKILL.md` | Personal workflows that apply everywhere | +| Project | `/.x-code/skills//SKILL.md` | Workflows for one repo only | + +A project-level skill overrides a global skill of the same name. `.x-code/` +at the repo root is gitignored — to share skills with a team, publish them +as a plugin (see [plugins.en.md](./plugins.en.md)). + +> **Windows paths**: `~/.x-code` maps to `%USERPROFILE%\.x-code` on Windows. +> Not repeated below. + +--- + +## How activation works + +**Both activation paths inject the same `` payload**: + +### 1. The user types `/` + +```text +> /code-review +(agent receives the skill body and starts following it) + +> /code-review @src/utils.ts +(same, plus src/utils.ts is attached in the same turn) +``` + +### 2. The agent calls `activateSkill` on its own + +When a skill's `description` matches the current task, the agent may +activate it without prompting. That's why writing a precise description +matters: + +```markdown +--- +name: react-hooks +description: Check React Hook calls against the rules-of-hooks +--- +``` + +Too vague (e.g. "for React") triggers false activations; too narrow +(e.g. "check missing refs in useEffect dependency arrays") never auto- +activates. One clear sentence about _when_ to use it works best. + +--- + +## `/skill` commands + +| Command | Description | +| ----------------------------------------------- | ------------------------------------------------------------------------- | +| `/skill list` | List all loaded skills with on/off state and source (user / project) | +| `/skill install ` | Download a SKILL.md from a URL into user scope (plain HTTP fetch, no git) | +| `/skill refresh` | Re-scan skill directories + settings; takes effect immediately | +| `/skill enable [--scope=user\|project]` | Re-enable a disabled skill | +| `/skill disable [--scope=user\|project]` | Disable a skill (file kept; effective after restart) | +| `/skill remove ` | Delete the skill directory (rejected for plugin-sourced skills) | + +Disabled state is persisted to the matching scope's settings: + +- user → `disabledSkills` array in `~/.x-code/settings.json` +- project → `disabledSkills` array in `/.x-code/settings.local.json` + +The two lists are unioned — disabled in either scope means disabled. + +--- + +## Worked examples + +### Example 1: PR-review playbook (team checklist) + +`~/.x-code/skills/pr-review/SKILL.md`: + +```markdown +--- +name: pr-review +description: Walk a PR diff through the team review checklist and return GO/NOGO +--- + +For the PR diff I provide, check in order and produce a Markdown report: + +## Must-pass (any fail → NOGO) + +1. Tests included, covering the main path +2. No breaking changes to public surface (package exports / routes / DB schema) +3. Any new dependency present on the allowlist + +## Should-check (flag but don't block) + +4. Naming follows existing conventions +5. Docs / comments updated + +See references/api-allowlist.md for the allowed dependency list. + +End with: **GO** or **NOGO + blocking reason**. +``` + +`~/.x-code/skills/pr-review/references/api-allowlist.md`: + +```markdown +# Approved dependencies + +- axios +- zod +- date-fns + (anything else requires approval) +``` + +Usage: + +```text +> /pr-review here is the diff @D:\code\repo\diff.patch +``` + +### Example 2: Turn benchmark text into a chart + +`~/.x-code/skills/perf-chart/SKILL.md`: + +````markdown +--- +name: perf-chart +description: Render plain-text benchmark output as a mermaid xychart +--- + +I'll give you benchmark text (one operation per line). Please: + +1. Extract operation name / mean / stddev from each line +2. Emit a mermaid xychart-beta block +3. No prose — just the ```mermaid block + +Example input: +sort 1000 items: 12.3ms ± 1.1 +sort 10000 items: 134.5ms ± 4.2 + +Output: + +```mermaid +xychart-beta + title "Sort benchmark" + x-axis ["1k", "10k"] + y-axis "ms" + bar [12.3, 134.5] +``` +```` + +--- + +## Relationship to plugins + +Plugins can bundle skills: a plugin manifest declares `"skills": "./skills"` +and each subdir under that path becomes a skill. They load identically to +hand-authored global skills, but carry a `pluginId` tag. + +`/skill remove` won't delete a plugin-sourced skill — it redirects to +`/plugin uninstall` for the owning plugin. + +See [plugins.en.md](./plugins.en.md) and [plugin-authoring.en.md](./plugin-authoring.en.md). + +--- + +## Troubleshooting + +| Symptom | Fix | +| --------------------------------------------- | ---------------------------------------------------------------------- | +| Edited SKILL.md but nothing changed | `/skill refresh` or restart `xc` | +| `/` says skill not found | `/skill list` to confirm load; check frontmatter validity | +| Want to disable temporarily without removing | `/skill disable ` | +| Agent keeps activating it incorrectly | Tighten the `description` — avoid broad words like "code" or "project" | +| Bundled file list got truncated (>50 entries) | Split into multiple skills | + +``` + +``` diff --git a/docs/skills.md b/docs/skills.md new file mode 100644 index 0000000..a899e7e --- /dev/null +++ b/docs/skills.md @@ -0,0 +1,234 @@ +# Skills — 使用指南 + +**Skills** 是你写一次、之后用 `/` 一键触发的工作流提示词模板。常见用途：代码审查清单、PR 评审范式、特定语言/框架的最佳实践规范。 + +英文版：[skills.en.md](./skills.en.md) + +--- + +## TL;DR + +```bash +# 全局 skill（所有项目可用） +mkdir -p ~/.x-code/skills/code-review +cat > ~/.x-code/skills/code-review/SKILL.md <<'EOF' +--- +name: code-review +description: 按公司清单审查改动 +--- +请按下列要点审查我提供的 diff： +1. 边界条件是否覆盖 +2. 错误处理是否完整 +3. 单测是否同步更新 +4. 是否引入新的依赖 +EOF + +# 重启 xc 或在交互中 /skill refresh +# 然后在对话里： +> /code-review @D:\project\diff.patch +``` + +--- + +## Skill 文件长什么样 + +一个 skill 就是一个目录，里面有一个 `SKILL.md`： + +``` +~/.x-code/skills// +├── SKILL.md # 必需，YAML frontmatter + Markdown body +├── references/ # 可选，bundled 资源 +├── scripts/ # 可选，可执行脚本 +└── ... # 任意附加文件 +``` + +**SKILL.md 内容**： + +```markdown +--- +name: code-review +description: 按公司清单审查改动（被 agent 拿来判断是否激活时阅读） +--- + +请按下列要点审查我提供的 diff： +... +``` + +frontmatter 只接受两个字段： + +- `name`（必需）：与目录名一致；激活命令就是 `/` +- `description`（必需）：一句话描述，agent 会读它来决定是否在合适场景主动激活 + +**bundled 文件**：激活时，CLI 自动列出 `SKILL.md` 同级及子目录的所有文件（限 50 个）给 agent 看，agent 可以按相对路径读它们： + +```markdown +请按 references/checklist.md 中列的要点审查 +``` + +--- + +## Skills 存放位置 + +| Scope | 路径 | 何时用 | +| ----- | --------------------------------------- | -------------------- | +| 全局 | `~/.x-code/skills//SKILL.md` | 个人通用工作流 | +| 项目 | `/.x-code/skills//SKILL.md` | 仅此项目使用的工作流 | + +项目级同名 skill 会覆盖全局同名。`.x-code/` 在仓库根是 gitignored 的，团队共享 skill 需要换约定或者发布成 plugin（见 [plugins.md](./plugins.md)）。 + +> **Windows 路径**：`~/.x-code` 在 Windows 上是 `%USERPROFILE%\.x-code`，下文不再重复。 + +--- + +## 怎么触发 + +**两种方式都会注入完全相同的 `` 内容**： + +### 1. 用户主动 `/` 命令 + +```text +> /code-review +（agent 收到 skill body，开始按提示词工作） + +> /code-review @src/utils.ts +（同上，但额外把 src/utils.ts 一并发给 agent） +``` + +### 2. Agent 自主调用 `activateSkill` 工具 + +当 system prompt 里列出的 skill 描述与当前任务相关时，agent 可能主动激活——这是为什么 `description` 写得好很重要： + +```markdown +--- +name: react-hooks +description: 用于检查 React Hook 调用是否符合 rules-of-hooks +--- +``` + +写得不清楚（如"用于 React"）容易导致 agent 错误激活；写得太具体（如"用于检查 useEffect 依赖数组里有没有遗漏 ref"）则永远不会被自动激活。一句明确的"什么场景该用"是最佳形态。 + +--- + +## `/skill` 命令族 + +| 命令 | 说明 | +| ----------------------------------------------- | ------------------------------------------------------------- | +| `/skill list` | 列出所有已加载 skill，含 on/off 状态 + 来源（user / project） | +| `/skill install ` | 从 URL 下载一个 SKILL.md 装到全局（直接 HTTP fetch，无 git） | +| `/skill refresh` | 重扫 skill 目录 + 设置文件，立即生效 | +| `/skill enable [--scope=user\|project]` | 启用一个被禁用的 skill | +| `/skill disable [--scope=user\|project]` | 禁用一个 skill（保留文件，下次启动生效） | +| `/skill remove ` | 删除 skill 目录（仅对非 plugin 来源的 skill 生效） | + +启用状态写到对应 scope 的 settings： + +- user → `~/.x-code/settings.json` 的 `disabledSkills` 数组 +- project → `/.x-code/settings.local.json` 的 `disabledSkills` 数组 + +两个列表取并集——任一 scope 禁用则禁用。 + +--- + +## 实战示例 + +### 例 1：PR 评审范式（公司内部清单） + +`~/.x-code/skills/pr-review/SKILL.md`： + +```markdown +--- +name: pr-review +description: 按公司 PR 评审清单逐项检查并给出 GO/NOGO +--- + +针对我提供的 PR 改动，按下列顺序检查并输出 markdown 报告： + +## 必查项（任一不通过 → NOGO） + +1. 是否带单测，覆盖了主路径 +2. 是否破坏现有公开 API（package.json exports / 路由 / DB schema） +3. 是否引入新依赖；如有，新依赖是否在公司允许列表 + +## 建议项（标记但不阻断） + +4. 命名是否符合现有惯例 +5. 注释/文档是否同步 + +参考 references/api-allowlist.md 看允许的依赖清单。 + +最后给一个总评：**GO** 或 **NOGO + 阻塞原因**。 +``` + +`~/.x-code/skills/pr-review/references/api-allowlist.md`： + +```markdown +# 允许的依赖列表 + +- axios +- zod +- date-fns + （其他需走审批） +``` + +使用： + +```text +> /pr-review 这是改动 @D:\code\repo\diff.patch +``` + +### 例 2：把命令行输出转成图表 + +`~/.x-code/skills/perf-chart/SKILL.md`： + +````markdown +--- +name: perf-chart +description: 把基准测试的纯文本输出渲染成 mermaid 图 +--- + +我会给你一段基准测试输出（数字 + 操作名）。请： + +1. 抽取每行的"操作名 / 平均耗时 / 标准差" +2. 输出一个 mermaid xychart-beta 图 +3. 不要附加解释——只要 ```mermaid 代码块 + +例如输入： +sort 1000 items: 12.3ms ± 1.1 +sort 10000 items: 134.5ms ± 4.2 + +输出： + +```mermaid +xychart-beta + title "Sort benchmark" + x-axis ["1k", "10k"] + y-axis "ms" + bar [12.3, 134.5] +``` +```` + +--- + +## 与 plugin 的关系 + +Plugin 可以把 skills 打包发布：plugin 的 manifest 声明 `"skills": "./skills"`，里面的每个子目录就是一个 skill，加载方式与你手写的全局 skill 完全一致，只是会带上 `pluginId` 标记。 + +`/skill remove` 不能删 plugin skill——会提示你用 `/plugin uninstall` 卸载整个 plugin。 + +详情见 [plugins.md](./plugins.md) 与 [plugin-authoring.md](./plugin-authoring.md)。 + +--- + +## 常见问题 + +| 问题 | 处理 | +| -------------------------- | ------------------------------------------------------- | +| 改了 SKILL.md 不生效 | `/skill refresh` 或重启 `xc` | +| `/` 提示找不到 skill | `/skill list` 确认是否加载；frontmatter 是否合法 | +| 想临时禁用而不删除 | `/skill disable ` | +| Agent 总是错误自动激活 | 把 `description` 写得更具体——避开宽泛词如"代码"、"项目" | +| Bundled 文件太大（>50） | 列表会被截断；考虑拆成多个 skill | + +``` + +``` diff --git a/docs/sub-agents.en.md b/docs/sub-agents.en.md new file mode 100644 index 0000000..43a7968 --- /dev/null +++ b/docs/sub-agents.en.md @@ -0,0 +1,179 @@ +# Sub-agents (the `task` tool) — Usage Guide + +X-Code CLI supports sub-agent delegation through the `task` tool: the model +can hand an independent sub-task (research, code review, planning) to a +sub-agent with its own system prompt, isolated context window, and +optionally a different model. The sub-agent runs to completion and only +its final answer is folded back into the main agent — intermediate work +doesn't pollute the main conversation. + +中文版：[sub-agents.md](./sub-agents.md) + +--- + +## Built-in sub-agents + +Four ship in the box: + +| Name | Best for | Tool whitelist | +| ----------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| `explore` | Searching a large codebase for a symbol / keyword / call chain; read-only | `glob`, `grep`, `read_file`, `list_dir`, `web_fetch`, `web_search` | +| `general-purpose` | Catch-all research / multi-step tasks that don't fit elsewhere | default full tool set (minus `task`) | +| `plan` | Designing a plan; enters plan mode and writes a plan file | includes `enter_plan_mode` | +| `code-reviewer` | Reviewing diffs / PRs | read-leaning (grep / read_file / etc.) | + +The main agent invokes them via the `task` tool: + +```text +(the agent calls something like:) +task(subagent_type="explore", description="find all callers of formatDate", + prompt="Search the repo for callers of formatDate(). Return paths + line numbers.") +``` + +The sub-agent runs in isolated context (capped by `maxTurns`) and returns +only its final assistant text. Token usage is accumulated into the main +session. + +--- + +## Writing custom sub-agents + +Drop a `.md` file under either path: + +| Scope | Path | +| ------- | --------------------------------- | +| Global | `~/.x-code/agents/.md` | +| Project | `/.x-code/agents/.md` | + +Loaded at startup. Project-level wins over global of the same name; both +override built-ins. + +> **Windows paths**: `~/.x-code` maps to `%USERPROFILE%\.x-code`. + +### File format + +```markdown +--- +name: my-agent # required; the model invokes this name in task() +description: One sentence on when to use this agent. The model reads this to decide. # required +tools: [read_file, grep, glob] # optional: whitelist of allowed tools +disallowedTools: [shell] # optional: deny on top of the whitelist +model: anthropic:claude-haiku-4-5 # optional: override the parent model (use a cheaper one) +maxTurns: 15 # optional: hard turn cap (default 30) +shellRestrictions: [rm, mv] # optional: keyword blacklist for shell commands (only meaningful when shell is in tools) +--- + +Your system prompt goes here. Can be multi-paragraph — this is the +entire "instruction set" the sub-agent receives. + +If you want the sub-agent to know what tools it has, list them at the +end — but it's not required; the whitelist is enforced regardless. +``` + +No frontmatter field is checked at runtime besides `name` and +`description`. Everything else has sensible defaults. + +### Example: bench-runner + +`~/.x-code/agents/bench-runner.md`: + +```markdown +--- +name: bench-runner +description: Run the benchmark suite once in isolation and report numbers + any regression +tools: [shell, read_file] +model: anthropic:claude-haiku-4-5 +maxTurns: 8 +shellRestrictions: [rm, sudo, npm publish] +--- + +Your task is to run the project's bench suite and report results. + +1. Execute `pnpm bench` and collect the output +2. Read ./bench-baseline.json for baseline numbers +3. Compare: any operation slower than baseline by >10% counts as a regression +4. Format your output as plain text (no markdown): + + Bench results (vs baseline): + - sort 1k: 12.3ms (baseline 12.0ms, +2.5%, OK) + - sort 10k: 178.0ms (baseline 134.0ms, +32.8%, ⚠ regression) + + Verdict: 1 regression + +Don't try to fix any regression — just report. +``` + +When you ask the main agent "run bench and see if anything regressed", it +auto-dispatches via task: + +```text +> run bench and see if anything regressed +[agent calls task(subagent_type="bench-runner", ...)] +``` + +--- + +## Sub-agent constraints + +1. **No recursion**: a sub-agent cannot call the `task` tool. The + runtime rejects it. +2. **Shared AbortSignal**: Esc cancels the main agent and all running + sub-agents simultaneously. +3. **Plan mode inherited**: when the parent session is in plan mode, + the `general-purpose` sub-agent has write tools denied (the other + sub-agents may already be read-only via their whitelist). +4. **Isolated context**: a sub-agent doesn't see the parent's message + history — only its own system prompt + the `prompt` argument passed + to `task()`. +5. **Shared token usage**: sub-agent token use rolls up into the + parent's total. + +--- + +## Writing `tools` and `disallowedTools` + +- `tools: [...]` — whitelist. Only the listed tools are available. + **Omitting `tools` = full tool set** (minus `task`). +- `disallowedTools: [...]` — blacklist. Applied on top of the whitelist. + +A common read-only combo: + +```yaml +tools: [read_file, glob, grep, list_dir, web_fetch, web_search] +``` + +Shell access with dangerous-command guards: + +```yaml +tools: [read_file, shell, glob] +shellRestrictions: [rm, sudo, npm publish, git push] +``` + +--- + +## When to write a sub-agent — and when not to + +**Yes**: + +- Repetitive research / verification flows where you keep redoing the same prompt +- Offloading work to a cheaper model (haiku / glm-flash) +- Restricting tools to read-only / shell-only subsets +- Tasks with a fixed output format (bench reports, PR checklists) + +**No**: + +- One-off tasks (just say it in the main conversation) +- Tasks where the system prompt is nearly identical to general usage — + use a [skill](./skills.en.md) instead + +Rule of thumb: sub-agent ≈ "named callable sub-process"; skill ≈ +"embedded prompt template". + +--- + +## Relationship to plugins + +A plugin's manifest can declare `agents: "./agents"`; the `.md` files +under that path become available sub-agents. They load identically to +hand-authored global sub-agents, with a `pluginId` tag attached. See +[plugins.en.md](./plugins.en.md). diff --git a/docs/sub-agents.md b/docs/sub-agents.md new file mode 100644 index 0000000..5950ae3 --- /dev/null +++ b/docs/sub-agents.md @@ -0,0 +1,155 @@ +# 子 Agent（task 工具）— 使用指南 + +X-Code CLI 通过 `task` 工具支持子 agent 委派：模型可以把某个独立子任务（研究、code review、计划等）派给一个有自己 system prompt、独立上下文窗口、可选不同 model 的子 agent，运行完只把最终结论回填给主 agent。这样主对话不被中间过程污染。 + +英文版：[sub-agents.en.md](./sub-agents.en.md) + +--- + +## 内置子 agent + +CLI 自带 4 个： + +| 名字 | 适合 | 工具白名单 | +| ----------------- | --------------------------------------------------------- | ------------------------------------------------------------------ | +| `explore` | 在大代码库里搜索某个关键字 / 符号 / 调用链；只 read，不改 | `glob`、`grep`、`read_file`、`list_dir`、`web_fetch`、`web_search` | +| `general-purpose` | 不归类的杂项研究 / 多步骤任务 | 默认完整工具集（task 除外） | +| `plan` | 制定方案；进入 plan 模式 + 写 plan 文件 | 含 `enter_plan_mode` | +| `code-reviewer` | 审查改动 / PR / diff | 偏 read，含 grep / read_file 等 | + +主 agent 通过 `task` 工具调用它们： + +```text +（agent 自动调用，等价于：） +task(subagent_type="explore", description="find all callers of formatDate", + prompt="Search the repo for callers of formatDate(). Return paths + line numbers.") +``` + +子 agent 在隔离上下文里跑（最多 `maxTurns` 轮），结束后只返回最终的 assistant text。Token 用量记入主会话。 + +--- + +## 自定义子 agent + +把 `.md` 文件放到下面任一目录即可： + +| Scope | 路径 | +| ----- | --------------------------------- | +| 全局 | `~/.x-code/agents/.md` | +| 项目 | `/.x-code/agents/.md` | + +启动期自动扫描。项目级同名覆盖全局；同名再覆盖内置。 + +> **Windows 路径**：`~/.x-code` 在 Windows 上是 `%USERPROFILE%\.x-code`。 + +### 文件格式 + +```markdown +--- +name: my-agent # 必需，模型在 task() 里用这个名字调用 +description: 一句话说清何时该用，模型会读这个做决定。 # 必需 +tools: [read_file, grep, glob] # 可选，限定允许的工具白名单 +disallowedTools: [shell] # 可选，在白名单之上再禁 +model: anthropic:claude-haiku-4-5 # 可选，覆盖父 model（用更便宜的） +maxTurns: 15 # 可选，硬上限轮次，默认 30 +shellRestrictions: [rm, mv] # 可选，shell 命令关键字黑名单（只在 shell 在 tools 里时有意义） +--- + +你的 system prompt 写在这里。可以是多段——这是子 agent 收到的全部"指令"。 + +要让子 agent 知道它能用什么工具，可以在 prompt 末尾列出来，但不是必需的—— +工具白名单已经由 frontmatter 的 `tools` 决定。 +``` + +frontmatter 字段都不存在 `required` 的运行时检查（除了 name 和 description）——其余缺省值合理。 + +### 示例：bench-runner + +`~/.x-code/agents/bench-runner.md`： + +```markdown +--- +name: bench-runner +description: 在隔离环境跑一次基准测试，返回数字 + 是否回归 +tools: [shell, read_file] +model: anthropic:claude-haiku-4-5 +maxTurns: 8 +shellRestrictions: [rm, sudo, npm publish] +--- + +你的任务是跑当前项目的 bench 套件并报告结果。 + +1. 执行 `pnpm bench` 收集输出 +2. 读 ./bench-baseline.json 拿到基线数字 +3. 对比：每项操作和基线比慢超过 10% 算 regression +4. 输出格式（plain text，不要 markdown）： + + Bench results (vs baseline): + - sort 1k: 12.3ms (baseline 12.0ms, +2.5%, OK) + - sort 10k: 178.0ms (baseline 134.0ms, +32.8%, ⚠ regression) + + Verdict: 1 regression + +不要试图修复 regression——只报告。 +``` + +主 agent 在你提"跑下 bench 看有没有退步"时会自动派 task： + +```text +> 跑下 bench 看有没有退步 +[agent 调用 task(subagent_type="bench-runner", ...)] +``` + +--- + +## 子 agent 的约束 + +1. **禁递归**：子 agent 不能调 `task` 工具。运行时会拒绝。 +2. **共享 AbortSignal**：用户 Esc 会同时杀掉主 agent 和所有运行中的子 agent。 +3. **Plan 模式继承**：父 session 在 plan 模式下，`general-purpose` 子 agent 会被禁掉写工具（其他子 agent 的工具白名单可能本来就只读）。 +4. **独立上下文**：子 agent 看不到主 session 的 message history——它只看到自己的 system prompt + task 调用的 prompt 参数。 +5. **Token 共享**：所有子 agent 的 token 用量加进父 session 的总账。 + +--- + +## `tools` / `disallowedTools` 的写法 + +- `tools: [...]` — 白名单。只列出来的能用。**不写 `tools` = 默认完整工具集**（task 除外）。 +- `disallowedTools: [...]` — 黑名单。在白名单基础上再禁。 + +只读 agent 的常见组合： + +```yaml +tools: [read_file, glob, grep, list_dir, web_fetch, web_search] +``` + +需要 shell 但想拦截危险操作： + +```yaml +tools: [read_file, shell, glob] +shellRestrictions: [rm, sudo, npm publish, git push] +``` + +--- + +## 何时该写子 agent？什么时候不该？ + +**该写**： + +- 重复出现的研究 / 验证流程，主 agent 每次手写有差异 +- 要用便宜 model（haiku / glm-flash）跑能 offload 的工作 +- 想限制工具到只读 / 只 shell 等子集 +- 输出格式有固定模式（如 bench 报告、PR 审查清单） + +**不该写**： + +- 一次性任务（直接写在主对话里更快） +- 子 agent 系统 prompt 跟普通 system prompt 几乎一样的（用 [skill](./skills.md) 而非 sub-agent） + +经验：sub-agent ≈ "可被命名调用的子流程"；skill ≈ "嵌入提示词模板"。 + +--- + +## 与插件的关系 + +插件可以在 manifest 里声明 `agents: "./agents"`，子目录的 `.md` 文件就成为可用的子 agent，与你手写的全局子 agent 完全一致，只是带 `pluginId` 标记。详见 [plugins.md](./plugins.md)。 diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index 246f02d..78fb03e 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -10,24 +10,32 @@ import { McpPermissionStore, PROVIDER_DETECTION_ORDER, PROVIDER_KEY_URLS, + buildPluginIntegration, + createCommandRegistry, createModelRegistry, createOAuthProviderFactory, createSkillRegistry, createSubAgentRegistry, debugLog, + debugLogIntegrationDiagnostics, + emptyHookBus, + ensureDefaultMarketplaces, getAvailableProviders, getEnvVarName, getTokenStorage, listSessions, + loadAllPlugins, loadMcpFromDisk, loadSession, loadUserConfig, pickLatestSession, resolveModelId, + setPluginDebugMirror, } from '@x-code-cli/core' -import type { AgentOptions, LoadedSession, McpRegistry } from '@x-code-cli/core' +import type { AgentOptions, HookBus, LoadedSession, McpRegistry } from '@x-code-cli/core' import { getCleanupFn, getSessionExitInfo, startApp } from './app.js' +import { runPluginCli } from './plugin-cli.js' import { detectShell, formatPersistCommand } from './shell.js' import type { ShellType } from './shell.js' import { setSyntaxTheme } from './ui/syntax-highlight.js' @@ -93,6 +101,11 @@ let shutdownInProgress = false * their parent's stdin closed — usually fine, but explicit shutdown * is faster and less surprising. */ let mcpRegistryForShutdown: McpRegistry | null = null +/** Plugin hook bus captured at startup so gracefulShutdown can fire + * `SessionEnd` to plugin hooks before the process exits. Fire-and- + * forget — the 1s shutdown grace window is the only thing standing + * between a slow hook and an abrupt process kill. */ +let hookBusForShutdown: HookBus | null = null // Belt-and-suspenders terminal restore. Runs synchronously before exit so even // if Ink's unmount is partially broken (e.g. a useEffect cleanup threw, or the @@ -136,6 +149,14 @@ async function gracefulShutdown(exitCode: number): Promise { mcpRegistryForShutdown.shutdown().catch(() => undefined) } + // Plugin SessionEnd hooks. Fire-and-forget — we don't await because + // a slow hook would block the user's shell prompt from returning, + // and the exit-time grace is a small window anyway. Hooks needing + // guaranteed delivery should also subscribe to TurnComplete. + if (hookBusForShutdown?.has('SessionEnd')) { + hookBusForShutdown.emit({ name: 'SessionEnd', session: { cwd: process.cwd(), modelId: '' } }).catch(() => undefined) + } + resetTerminal() // Print AFTER resetTerminal so the line lands cleanly above the // shell prompt — colors are reset, raw mode is off, cursor is @@ -150,6 +171,16 @@ async function main() { checkNodeVersion() loadEnvFile() + // Non-interactive plugin management subcommand. Routed BEFORE yargs + // parses the rest of argv — otherwise `xc plugin install ./foo` + // would be treated as a prompt the agent should respond to. This + // runs without mounting Ink and exits when done. + const rawArgs = hideBin(process.argv) + if (rawArgs[0] === 'plugin') { + const exitCode = await runPluginCli(rawArgs.slice(1)) + process.exit(exitCode) + } + // Parse CLI arguments const argv = await yargs(hideBin(process.argv)) .scriptName('x-code') @@ -185,6 +216,36 @@ async function main() { // model to read-only exploration + a plan file until the user approves. describe: 'Start the session in plan mode (read-only exploration; user must approve before code edits)', }) + .option('plugins', { + type: 'boolean', + default: true, + // Declared as positive `--plugins` (default on) so yargs auto-derives + // the `--no-plugins` negation. The flag is an escape hatch for + // diagnosing whether a misbehaving plugin (broken skill, runaway + // hook, etc.) is the cause of a problem — `--no-plugins` skips + // loadAllPlugins entirely so only built-in contributions are active. + describe: 'Enable plugin discovery (default true). `--no-plugins` to disable for one session.', + }) + .option('hooks', { + type: 'boolean', + default: true, + // Same `--no-hooks` negation pattern as `--plugins`. Plugins still + // load (skills / agents / mcp contributions still register), only + // the hook subsystem is skipped — wires `emptyHookBus()` instead + // of the integration-built one. Use when a slow / runaway hook + // is suspected, without losing the rest of a plugin's content. + describe: 'Enable plugin hooks (default true). `--no-hooks` to skip hook execution for one session.', + }) + .option('plugin-debug', { + type: 'boolean', + default: false, + // Targeted debug output for plugin / hook / marketplace activity. + // Mirrors the matching debugLog() lines to stderr in addition to the + // log file, so you can see them live without tailing ~/.x-code/logs/. + // Equivalent to setting `XC_PLUGIN_DEBUG=1`. Doesn't change behaviour + // — only changes where the breadcrumbs go. + describe: 'Mirror plugin / hook / marketplace debug breadcrumbs to stderr (also XC_PLUGIN_DEBUG=1).', + }) .option('continue', { alias: 'c', type: 'boolean', @@ -292,8 +353,48 @@ async function main() { // Create registries and get model const providerRegistry = createModelRegistry() const model = providerRegistry.languageModel(modelId as `${string}:${string}`) - const subAgentRegistry = await createSubAgentRegistry() - const skillRegistry = await createSkillRegistry() + + // --plugin-debug / XC_PLUGIN_DEBUG=1: mirror plugin/hook/marketplace + // debugLog breadcrumbs to stderr so they're visible live without + // tailing ~/.x-code/logs/debug.log. Install BEFORE ensureDefaultMarketplaces + // so first-run subscribe messages show up too. Done as a global hook on + // debugLog rather than a new logger — keeps every existing call site + // automatic and avoids two parallel logging paths. + if (argv['plugin-debug'] || process.env.XC_PLUGIN_DEBUG === '1') { + setPluginDebugMirror(true) + } + + // First-run seed: writes the default `anthropic-marketplace` + // subscription to known_marketplaces.json if no subscription file + // exists yet. Idempotent — a user who explicitly removed the + // subscription won't get it back. Done before loadAllPlugins so the + // first run sees a populated marketplaces list. + if (argv.plugins !== false) { + await ensureDefaultMarketplaces().catch((err) => debugLog('plugins.ensure-defaults-failed', String(err))) + } + + // Plugins must load BEFORE skill / sub-agent / mcp registries so their + // contributions can be folded into each. `--no-plugins` short-circuits + // the entire chain. We surface non-fatal load errors to stderr in the + // same style as `[mcp] config error in ...` below — one broken plugin + // never blocks the others. Detailed diagnostics (collisions, unsupported + // commands, hook errors) go to debug.log via + // debugLogIntegrationDiagnostics for `/plugin doctor` to surface. + const pluginLoad = await loadAllPlugins({ cwd: process.cwd(), disabled: argv.plugins === false }) + for (const e of pluginLoad.registry.loadErrors()) { + console.error(chalk.yellow(`[plugin] ${e.id ?? e.path}: ${e.message}`)) + } + const pluginIntegration = await buildPluginIntegration(pluginLoad) + debugLogIntegrationDiagnostics(pluginIntegration) + if (pluginIntegration.mcpErrors.length > 0) { + for (const e of pluginIntegration.mcpErrors) { + console.error(chalk.yellow(`[plugin] ${e.pluginId}: ${e.message}`)) + } + } + + const subAgentRegistry = await createSubAgentRegistry({ extraDirs: pluginIntegration.agentsDirs }) + const skillRegistry = await createSkillRegistry({ extraDirs: pluginIntegration.skillsDirs }) + const commandRegistry = await createCommandRegistry({ extraDirs: pluginIntegration.commandsDirs }) // MCP: load servers, run trust dialog if project-level config is // unfamiliar. Done BEFORE Ink mounts so the readline-based trust @@ -304,6 +405,7 @@ async function main() { const mcpPermissionStore = new McpPermissionStore() const mcpLoadResult = await loadMcpFromDisk({ cwd: process.cwd(), + extraServers: pluginIntegration.mcpServers, askUser: (question, opts) => askInTerminal(question, opts), // The browser-open hook only fires during /mcp auth (passive boot // mode never invokes redirectToAuthorization — see @@ -319,6 +421,9 @@ async function main() { onExitRequested: () => process.exit(0), }) mcpRegistryForShutdown = mcpLoadResult.registry + // Don't fire SessionEnd hooks when --no-hooks is set — the user + // explicitly opted out of all hook execution this session. + hookBusForShutdown = argv.hooks === false ? null : pluginIntegration.hookBus if (mcpLoadResult.configErrors.length > 0) { for (const e of mcpLoadResult.configErrors) { @@ -353,6 +458,12 @@ async function main() { skillRegistry, mcpRegistry: mcpLoadResult.registry, mcpPermissionStore, + pluginRegistry: pluginLoad.registry, + commandRegistry, + // --no-hooks: swap in an empty bus so emit-sites are no-ops without + // touching the rest of plugin loading (skills / agents / mcp still + // register, just nothing listens on lifecycle events). + hookBus: argv.hooks === false ? emptyHookBus() : pluginIntegration.hookBus, } // Resume / continue. Three resume entry points: diff --git a/packages/cli/src/plugin-cli.ts b/packages/cli/src/plugin-cli.ts new file mode 100644 index 0000000..94db2b6 --- /dev/null +++ b/packages/cli/src/plugin-cli.ts @@ -0,0 +1,667 @@ +// @x-code-cli/cli — Non-interactive plugin subcommands +// +// `xc plugin ...` entry point — runs without mounting the +// Ink UI, prints to stdout/stderr, exits with a status code suitable +// for scripts. Mirrors the slash-command family in `App.tsx`'s +// `handlePlugin` so users can drive the same operations from either +// surface. +// +// Routed from `index.ts`'s main() before yargs sees the args — that +// way `xc plugin install ./foo` doesn't get treated as a prompt the +// agent should answer. +import { Chalk } from 'chalk' + +import { + addKnownMarketplace, + clearPluginEntry, + fetchMarketplace, + installPlugin, + listInstalledPlugins, + loadAllPlugins, + lookupPlugin, + readAllCachedMarketplaces, + readKnownMarketplaces, + removeKnownMarketplace, + setPluginEnabled, + uninstallPlugin, +} from '@x-code-cli/core' +import type { ConsentPreview, PluginScope, PluginSource } from '@x-code-cli/core' + +const chalk = new Chalk() + +export async function runPluginCli(args: string[]): Promise { + const sub = (args[0] ?? '').toLowerCase() + const rest = args.slice(1) + + try { + switch (sub) { + case '': + case 'list': + return await cliList(rest) + case 'info': + return await cliInfo(rest) + case 'install': + return await cliInstall(rest) + case 'uninstall': + return await cliUninstall(rest) + case 'enable': + return await cliToggle(rest, true) + case 'disable': + return await cliToggle(rest, false) + case 'search': + return await cliSearch(rest) + case 'update': + return await cliUpdate(rest) + case 'doctor': + return await cliDoctor() + case 'marketplace': + return await cliMarketplace(rest) + default: + printUsage() + return 1 + } + } catch (err) { + console.error(chalk.red(err instanceof Error ? err.message : String(err))) + return 1 + } +} + +function printUsage(): void { + console.error( + [ + 'Usage: xc plugin [args...]', + '', + 'Subcommands:', + ' list List installed plugins', + " info Show a plugin's manifest, contributions, hooks", + ' install Install from name@marketplace, github:owner/repo, git URL, or local path', + ' uninstall Remove a plugin (cache + settings; data dir preserved)', + ' enable Enable a plugin (global scope)', + ' disable Disable a plugin without uninstalling', + ' search Search subscribed marketplaces', + ' update Reinstall from recorded source', + ' doctor Show plugin load errors', + ' marketplace [args...]', + ' Manage marketplace subscriptions', + '', + 'Example:', + ' xc plugin marketplace add anthropic-marketplace github:anthropics/marketplace', + ' xc plugin marketplace refresh anthropic-marketplace', + ' xc plugin install linear@anthropic-marketplace', + ].join('\n'), + ) +} + +function formatSource(s: PluginSource | undefined): string { + if (!s) return '(unknown)' + if (s.kind === 'local') return `local: ${s.path}` + if (s.kind === 'git') return `git: ${s.url}${s.ref ? `#${s.ref}` : ''}` + return `github:${s.owner}/${s.repo}${s.ref ? `#${s.ref}` : ''}` +} + +// ── list / info ──────────────────────────────────────────────────────── + +async function cliList(args: string[] = []): Promise { + // Optional filters mirror the slash command: --enabled / --disabled. + // No flag = list every installed plugin (default). + let filter: 'all' | 'enabled' | 'disabled' = 'all' + for (const a of args) { + if (a === '--enabled') filter = 'enabled' + else if (a === '--disabled') filter = 'disabled' + } + + // For 'all' we can stay cheap and just read the bookkeeping file. For + // filtered views we need the enabled state, which only loadAllPlugins + // resolves (settings.json merge across scopes). + if (filter === 'all') { + const installed = await listInstalledPlugins() + if (installed.length === 0) { + console.log('No plugins installed.') + return 0 + } + console.log(`Installed plugins (${installed.length}):`) + const namePad = Math.max(...installed.map((p) => p.id.length), 8) + 2 + for (const p of installed) { + console.log(` ${p.id.padEnd(namePad)} v${p.version} ${formatSource(p.source)}`) + } + return 0 + } + + const load = await loadAllPlugins({ cwd: process.cwd() }) + const all = load.registry.listAll() + const filtered = filter === 'enabled' ? all.filter((p) => p.enabled) : all.filter((p) => !p.enabled) + if (all.length === 0) { + console.log('No plugins installed.') + return 0 + } + if (filtered.length === 0) { + console.log(`No ${filter} plugins.`) + return 0 + } + console.log(`Installed plugins (${filter}, ${filtered.length} of ${all.length}):`) + const namePad = Math.max(...filtered.map((p) => p.id.length), 8) + 2 + for (const p of filtered) { + const badge = p.enabled ? '[on] ' : '[off]' + console.log(` ${badge} ${p.id.padEnd(namePad)} v${p.manifest.version} ${formatSource(p.source)}`) + } + return 0 +} + +async function cliInfo(args: string[]): Promise { + const id = args[0] + if (!id) { + console.error('Usage: xc plugin info ') + return 1 + } + // Use loadAllPlugins to get the actual manifest + enable state, not + // just the bookkeeping record. + const load = await loadAllPlugins({ cwd: process.cwd() }) + const plugin = load.registry.getEntry(id) + if (!plugin) { + console.error(`No plugin '${id}' loaded.`) + return 1 + } + console.log(`${plugin.id} v${plugin.manifest.version}`) + if (plugin.manifest.description) console.log(plugin.manifest.description) + console.log() + console.log(`Enabled: ${plugin.enabled ? 'yes' : 'no'}`) + console.log(`Source: ${formatSource(plugin.source)}`) + console.log(`Marketplace: ${plugin.marketplace}`) + console.log(`Root dir: ${plugin.rootDir}`) + console.log(`Manifest: ${plugin.manifestPath} (${plugin.manifestFormat})`) + const c = load.contributions.get(plugin.id) + if (c) { + console.log() + console.log('Contributions:') + if (c.skillsDir) console.log(` skills: ${c.skillsDir}`) + if (c.agentsDir) console.log(` agents: ${c.agentsDir}`) + if (c.commandsDir) console.log(` commands: ${c.commandsDir}`) + if (c.mcpServers) console.log(` mcpServers: ${c.mcpServers.kind === 'inline' ? '(inline)' : c.mcpServers.path}`) + if (c.hooks) console.log(` hooks: ${c.hooks.kind === 'inline' ? '(inline)' : c.hooks.path}`) + } + return 0 +} + +// ── install / uninstall / update ─────────────────────────────────────── + +async function cliInstall(args: string[]): Promise { + // Strip --yes / -y from args before reading the source. Order- + // independent so users can write either `--yes ` or + // ` --yes`. + const skipConsent = args.includes('--yes') || args.includes('-y') + const sourceArgs = args.filter((a) => a !== '--yes' && a !== '-y') + const raw = sourceArgs.join(' ').trim() + if (!raw) { + console.error('Usage: xc plugin install [--yes] ') + console.error(' : name@marketplace | github:owner/repo | https://... | /path') + return 1 + } + + const parsed = await parseInstallSource(raw) + if (!parsed) return 1 + + console.log(`Installing from ${formatSource(parsed.source)} ...`) + try { + const result = await installPlugin({ + source: parsed.source, + marketplace: parsed.marketplace, + expectedName: parsed.expectedName, + consent: skipConsent ? undefined : promptConsent, + // userConfig prompt only runs when manifest declares fields AND + // not in `--yes` non-interactive mode (scripts can pre-seed + // values by editing ~/.x-code/plugins/user-config.json directly + // or by writing them via the future `xc plugin configure` cmd). + userConfigPrompt: skipConsent ? undefined : promptUserConfig, + }) + console.log(chalk.green(`Installed ${result.pluginId} v${result.manifest.version}`)) + console.log(`Cache: ${result.rootDir}`) + console.log("Restart xc to load this plugin's contributions.") + return 0 + } catch (err) { + console.error(chalk.red(`Install failed: ${err instanceof Error ? err.message : String(err)}`)) + return 1 + } +} + +/** Render the consent preview to stderr and read a y/n from stdin. + * Defaults to NO when run without a TTY (CI environments, piped + * install scripts) — those callers should pass `--yes` explicitly. */ +async function promptConsent(preview: ConsentPreview): Promise { + const lines: string[] = [] + lines.push('') + lines.push(chalk.bold.yellow(`About to install: ${preview.pluginId} v${preview.version}`)) + if (preview.description) lines.push(` ${preview.description}`) + lines.push('') + lines.push(` Source: ${formatSource(preview.source)}`) + lines.push( + ` Marketplace: ${preview.marketplace}${preview.fromReservedMarketplace ? ' [reserved/official]' : ''}${preview.verified ? ' [verified]' : ''}`, + ) + if (preview.author) lines.push(` Author: ${preview.author}`) + if (preview.license) lines.push(` License: ${preview.license}`) + if (preview.homepage) lines.push(` Homepage: ${preview.homepage}`) + lines.push('') + lines.push(' Will contribute:') + if (preview.hasSkillsDir) lines.push(' - skills (added to /skill list)') + if (preview.hasAgentsDir) lines.push(' - sub-agents (callable via the `task` tool)') + if (preview.hasCommandsDir) lines.push(' - slash commands (declared but not yet wired — no file-based loader)') + if (preview.inlineMcpServerNames.length > 0) { + lines.push( + ` - ${chalk.red('MCP servers')} (will be spawned as subprocesses): ${preview.inlineMcpServerNames.join(', ')}`, + ) + } else if (preview.hasPathMcpServers) { + lines.push(` - ${chalk.red('MCP servers')} (from external file — spawned as subprocesses)`) + } + if (preview.hookEvents.length > 0) { + lines.push(` - ${chalk.red('Lifecycle hooks')} (will run shell commands on: ${preview.hookEvents.join(', ')})`) + } else if (preview.hasPathHooks) { + lines.push(` - ${chalk.red('Lifecycle hooks')} (from external file — will run shell commands)`) + } + if ( + !preview.hasSkillsDir && + !preview.hasAgentsDir && + !preview.hasCommandsDir && + preview.inlineMcpServerNames.length === 0 && + !preview.hasPathMcpServers && + preview.hookEvents.length === 0 && + !preview.hasPathHooks + ) { + lines.push(' (no contributions declared)') + } + lines.push('') + + process.stderr.write(lines.join('\n')) + + // No TTY → default deny. Scripts should pass `--yes`. + if (!process.stdin.isTTY || !process.stdout.isTTY) { + process.stderr.write(chalk.yellow('No TTY — declining install. Use --yes to skip the prompt in scripts.\n')) + return false + } + + const readline = await import('node:readline/promises') + const rl = readline.createInterface({ input: process.stdin, output: process.stderr }) + try { + const answer = await rl.question('Proceed with install? [y/N] ') + return /^y(es)?$/i.test(answer.trim()) + } finally { + rl.close() + } +} + +/** Walk the manifest's userConfig list and prompt for each field. Mirrors + * the consent prompt's TTY-only stance: scripts piping into install + * should pre-seed values or use `--yes` (which skips this entirely). + * Sensitive fields are NOT echoed during typing — we toggle the tty + * to raw mode for the duration of the question, mirroring how `git` + * prompts for credentials. */ +async function promptUserConfig( + fields: Parameters[0]['userConfigPrompt']>>[0], +): Promise | null> { + // installer only calls us when fields.length > 0, but TypeScript can't + // see that from the call site — guard explicitly. + if (!fields) return {} + if (!process.stdin.isTTY || !process.stdout.isTTY) { + process.stderr.write( + chalk.yellow( + 'No TTY — skipping userConfig prompt. Pre-seed values in ~/.x-code/plugins/user-config.json or use --yes.\n', + ), + ) + return {} + } + process.stderr.write('\n' + chalk.bold('This plugin needs configuration:') + '\n') + + const collected: Record = {} + const readline = await import('node:readline/promises') + const rl = readline.createInterface({ input: process.stdin, output: process.stderr, terminal: true }) + try { + for (const f of fields) { + const label = f.prompt ?? f.description ?? f.key + const required = f.required ? ' (required)' : '' + const defaultNote = f.default !== undefined ? ` [default: ${f.default}]` : '' + const sensitive = f.sensitive === true + const promptText = ` ${chalk.cyan(f.key)}: ${label}${required}${defaultNote}\n > ` + + let answer: string + if (sensitive) { + // Suppress local echo for the duration of the read. Node's readline + // doesn't expose this directly, so we monkey-patch the output stream's + // write to drop everything except a one-off '*' per keystroke. Same + // technique inquirer uses for its `password` prompt. + const out = process.stderr + const originalWrite = out.write.bind(out) + process.stderr.write(promptText) + let muted = true + // eslint-disable-next-line @typescript-eslint/no-explicit-any + ;(out as { write: (...args: any[]) => boolean }).write = (chunk: string | Buffer) => { + if (!muted) return originalWrite(chunk) + const s = typeof chunk === 'string' ? chunk : chunk.toString() + if (s.includes('\n') || s.includes('\r')) return originalWrite(s) + return true + } + try { + answer = await rl.question('') + } finally { + muted = false + // eslint-disable-next-line @typescript-eslint/no-explicit-any + ;(out as { write: (...args: any[]) => boolean }).write = originalWrite + process.stderr.write('\n') + } + } else { + answer = await rl.question(promptText) + } + + const trimmed = answer.trim() + if (!trimmed) { + if (f.default !== undefined) { + collected[f.key] = f.default + } else if (f.required) { + process.stderr.write(chalk.red(` '${f.key}' is required.\n`)) + return null + } + continue + } + + if (f.type === 'number') { + const n = Number(trimmed) + if (!Number.isFinite(n)) { + process.stderr.write(chalk.red(` '${f.key}' must be a number.\n`)) + return null + } + collected[f.key] = n + } else if (f.type === 'boolean') { + collected[f.key] = /^(true|y|yes|1)$/i.test(trimmed) + } else { + collected[f.key] = trimmed + } + } + } finally { + rl.close() + } + return collected +} + +async function parseInstallSource( + raw: string, +): Promise<{ source: PluginSource; marketplace: string; expectedName?: string } | null> { + const isPath = raw.startsWith('./') || raw.startsWith('../') || raw.startsWith('/') || /^[a-zA-Z]:[/\\]/.test(raw) + const isGitUrl = /^https?:\/\//i.test(raw) || raw.startsWith('git@') + const isGhShort = raw.startsWith('github:') + const atIdx = raw.lastIndexOf('@') + const isMarketplaceRef = atIdx > 0 && !isPath && !isGitUrl && !isGhShort + + if (isMarketplaceRef) { + const name = raw.slice(0, atIdx) + const mpName = raw.slice(atIdx + 1) + const found = await lookupPlugin(`${name}@${mpName}`) + if (!found) { + console.error( + `Plugin '${name}' not found in marketplace '${mpName}'. ` + + `Run 'xc plugin marketplace refresh ${mpName}' or check the spelling.`, + ) + return null + } + return { source: found.entry.source, marketplace: mpName, expectedName: name } + } + if (isGhShort) { + const m = raw.match(/^github:([^/]+)\/(.+?)(?:#(.+))?$/i) + if (!m) { + console.error('Invalid github source. Expected github:owner/repo[#ref]') + return null + } + return { source: { kind: 'github', owner: m[1]!, repo: m[2]!, ref: m[3] }, marketplace: 'local' } + } + if (isGitUrl) { + return { source: { kind: 'git', url: raw }, marketplace: 'local' } + } + if (isPath) { + return { source: { kind: 'local', path: raw }, marketplace: 'local' } + } + console.error(`Unrecognised source: '${raw}'. Use name@marketplace, github:owner/repo, an https/git URL, or a path.`) + return null +} + +async function cliUninstall(args: string[]): Promise { + const id = args[0] + if (!id) { + console.error('Usage: xc plugin uninstall ') + return 1 + } + const result = await uninstallPlugin(id) + if (!result.removedRecord && result.removedVersions.length === 0) { + console.error(`No plugin '${id}' installed.`) + return 1 + } + for (const scope of ['user', 'project'] as PluginScope[]) { + await clearPluginEntry(id, scope).catch(() => undefined) + } + console.log( + chalk.green( + `Uninstalled ${id} (removed ${result.removedVersions.length} cached version${result.removedVersions.length === 1 ? '' : 's'})`, + ), + ) + console.log('Data dir preserved. Restart xc to drop contributions from active registries.') + return 0 +} + +async function cliToggle(args: string[], enable: boolean): Promise { + // Pull out the optional --scope flag before the positional id, matching + // the shape of /skill enable|disable. Default scope = 'user'. + let scope: PluginScope = 'user' + const positional: string[] = [] + for (const a of args) { + const m = a.match(/^(?:--scope|-s)(?:=(.+))?$/) + if (m) { + const v = m[1]?.toLowerCase() + if (v === 'user' || v === 'project') scope = v + continue + } + positional.push(a) + } + const id = positional[0] + if (!id) { + console.error(`Usage: xc plugin ${enable ? 'enable' : 'disable'} [--scope=user|project]`) + return 1 + } + const result = await setPluginEnabled(id, scope, enable) + const verb = enable ? 'enabled' : 'disabled' + if (result === 'noop') { + console.log(`Plugin '${id}' already ${verb} (${scope} scope).`) + } else { + console.log(chalk.green(`Plugin ${id} ${verb} in ${scope} scope.`)) + console.log('Restart xc to apply (contributions are bound at startup).') + } + return 0 +} + +async function cliUpdate(args: string[]): Promise { + const id = args[0] + if (!id) { + console.error('Usage: xc plugin update ') + return 1 + } + const records = await listInstalledPlugins() + const rec = records.find((r) => r.id === id) + if (!rec) { + console.error(`Plugin '${id}' not installed.`) + return 1 + } + console.log(`Reinstalling ${id} from ${formatSource(rec.source)} ...`) + try { + const result = await installPlugin({ + source: rec.source, + marketplace: rec.marketplace, + expectedName: rec.name, + }) + if (result.manifest.version === rec.version) { + console.log(`Reinstalled at the same version (${rec.version}).`) + } else { + console.log(chalk.green(`Updated ${rec.version} → ${result.manifest.version}`)) + } + return 0 + } catch (err) { + console.error(chalk.red(`Update failed: ${err instanceof Error ? err.message : String(err)}`)) + return 1 + } +} + +// ── search / doctor ──────────────────────────────────────────────────── + +async function cliSearch(args: string[]): Promise { + const kw = args.join(' ').trim().toLowerCase() + if (!kw) { + console.error('Usage: xc plugin search ') + return 1 + } + const marketplaces = await readAllCachedMarketplaces() + if (marketplaces.length === 0) { + console.error('No subscribed marketplaces. Add one with `xc plugin marketplace add`.') + return 1 + } + const matches: Array<{ marketplace: string; name: string; description?: string; verified?: boolean }> = [] + for (const m of marketplaces) { + for (const entry of m.plugins) { + const hay = [entry.name, entry.description ?? '', ...(entry.keywords ?? [])].join(' ').toLowerCase() + if (hay.includes(kw)) { + matches.push({ + marketplace: m.name, + name: entry.name, + description: entry.description, + verified: entry.verified, + }) + } + } + } + if (matches.length === 0) { + console.log(`No plugins matching '${kw}'.`) + return 0 + } + console.log(`Found ${matches.length} match${matches.length === 1 ? '' : 'es'}:`) + for (const m of matches) { + const tag = m.verified ? ' [verified]' : '' + console.log(` ${m.name}@${m.marketplace}${tag}`) + if (m.description) console.log(` ${m.description}`) + } + return 0 +} + +async function cliDoctor(): Promise { + const load = await loadAllPlugins({ cwd: process.cwd() }) + const all = load.registry.listAll() + const errors = load.registry.loadErrors() + console.log('Plugin doctor') + console.log() + console.log(` Total loaded: ${all.length}`) + console.log(` Enabled: ${all.filter((p) => p.enabled).length}`) + console.log(` Disabled: ${all.filter((p) => !p.enabled).length}`) + console.log(` Load errors: ${errors.length}`) + if (errors.length > 0) { + console.log() + console.log('Errors:') + for (const e of errors) { + console.log(` - ${e.id ?? '(unknown)'} at ${e.path}`) + console.log(` ${e.message}`) + } + } + console.log() + console.log('For deeper diagnostics, set DEBUG_STDOUT=1 and check ~/.x-code/logs/debug.log') + return errors.length > 0 ? 1 : 0 +} + +// ── marketplace ───────────────────────────────────────────────────────── + +async function cliMarketplace(args: string[]): Promise { + const sub = (args[0] ?? '').toLowerCase() + const rest = args.slice(1) + + if (sub === '' || sub === 'list') { + const km = await readKnownMarketplaces() + if (km.marketplaces.length === 0) { + console.log('No marketplaces subscribed.') + return 0 + } + console.log(`Subscribed marketplaces (${km.marketplaces.length}):`) + const namePad = Math.max(...km.marketplaces.map((m) => m.name.length), 8) + 2 + for (const m of km.marketplaces) { + const tag = m.reservedName ? ' [official]' : '' + console.log(` ${m.name.padEnd(namePad)} ${m.source}${tag}`) + } + return 0 + } + if (sub === 'add') { + const name = rest[0] + const source = rest.slice(1).join(' ') + if (!name || !source) { + console.error('Usage: xc plugin marketplace add ') + return 1 + } + try { + await addKnownMarketplace({ name, source }) + console.log(chalk.green(`Subscribed to ${name} (${source})`)) + console.log(`Run 'xc plugin marketplace refresh ${name}' to fetch its index.`) + return 0 + } catch (err) { + console.error(chalk.red(err instanceof Error ? err.message : String(err))) + return 1 + } + } + if (sub === 'remove') { + const name = rest[0] + if (!name) { + console.error('Usage: xc plugin marketplace remove ') + return 1 + } + const result = await removeKnownMarketplace(name) + if (result === 'noop') { + console.error(`No marketplace '${name}' subscribed.`) + return 1 + } + console.log(chalk.green(`Unsubscribed from ${name}.`)) + return 0 + } + if (sub === 'refresh') { + const km = await readKnownMarketplaces() + const wanted = rest[0] + const targets = wanted ? km.marketplaces.filter((m) => m.name === wanted) : km.marketplaces + if (targets.length === 0) { + console.error(wanted ? `No marketplace '${wanted}' subscribed.` : 'No marketplaces subscribed.') + return 1 + } + let hadError = false + for (const t of targets) { + try { + const m = await fetchMarketplace(t) + console.log(chalk.green(`✓ ${t.name} — ${m.plugins.length} plugin${m.plugins.length === 1 ? '' : 's'}`)) + } catch (err) { + hadError = true + console.error(chalk.red(`✗ ${t.name} — ${err instanceof Error ? err.message : String(err)}`)) + } + } + return hadError ? 1 : 0 + } + if (sub === 'info') { + const name = rest[0] + if (!name) { + console.error('Usage: xc plugin marketplace info ') + return 1 + } + const all = await readAllCachedMarketplaces() + const m = all.find((x) => x.name === name) + if (!m) { + console.error(`No cached index for '${name}'. Run 'xc plugin marketplace refresh ${name}' first.`) + return 1 + } + console.log(`${m.displayName ?? m.name} (${m.name})`) + if (m.description) console.log(m.description) + if (m.owner?.name) console.log(`Owner: ${m.owner.name}${m.owner.url ? ` (${m.owner.url})` : ''}`) + console.log() + console.log(`${m.plugins.length} plugin${m.plugins.length === 1 ? '' : 's'}:`) + for (const p of m.plugins) { + const ver = p.verified ? ' [verified]' : '' + const cat = p.category ? ` (${p.category})` : '' + console.log(` ${p.name}${ver}${cat}`) + if (p.description) console.log(` ${p.description}`) + } + return 0 + } + console.error('Usage: xc plugin marketplace [args...]') + return 1 +} diff --git a/packages/cli/src/ui/components/App.tsx b/packages/cli/src/ui/components/App.tsx index 956036a..c0651b1 100644 --- a/packages/cli/src/ui/components/App.tsx +++ b/packages/cli/src/ui/components/App.tsx @@ -10,32 +10,46 @@ import { GLOBAL_XCODE_DIR, MODEL_ALIASES, PROVIDER_MODELS, + addKnownMarketplace, + clearPluginEntry, createModelRegistry, detectScope, estimateTokenCount, + expandCommandBody, + fetchMarketplace, getAutoMemory, getAvailableProviders, getContextWindow, getMcpConfigPath, getScopedDisabledSkills, getTokenStorage, + installPlugin, + listInstalledPlugins, listSessions, loadMergedConfigsFromDisk, loadSession, loadUserConfig, + lookupPlugin, parseAdd, parseAddJson, parseRemove, pickLatestSession, + readAllCachedMarketplaces, + readKnownMarketplaces, readServerConfig, + refreshPluginContributions, reloadSkillRegistry, + removeKnownMarketplace, removeServerFromConfig, + resolveContributions, resolveModelId, saveUserConfig, serverExists, + setPluginEnabled, setSkillDisabled, skillSettingsPath, trustProject, + uninstallPlugin, wrapActivatedSkill, writeServerToConfig, } from '@x-code-cli/core' @@ -44,6 +58,8 @@ import type { KnowledgeFact, LanguageModel, LoadedSession, + PluginScope, + PluginSource, SkillDefinition, SkillSettingsScope, TokenUsage, @@ -140,6 +156,31 @@ export const SLASH_COMMANDS = [ { name: 'remove', description: 'Delete a skill directory from disk' }, ], }, + { + name: '/plugin', + description: 'Manage plugins (bundled skills / agents / mcp / hooks)', + // Subcommands mirror handlePlugin's switch. `marketplace` is itself a + // sub-group with its own subcommands (add / remove / list / refresh / info). + subcommands: [ + { name: 'list', description: 'List installed plugins (with enable state + source)' }, + { name: 'info', description: "Show a plugin's manifest, contributions, and hooks" }, + { + name: 'install', + description: 'Install a plugin from , git, github:owner/repo, or local path', + }, + { name: 'uninstall', description: 'Remove a plugin (cache + settings entry; data dir preserved)' }, + { + name: 'enable', + description: 'Enable a plugin (writes settings — restart for full effect; --scope=user|project)', + }, + { name: 'disable', description: 'Disable a plugin without uninstalling (--scope=user|project)' }, + { name: 'search', description: 'Search subscribed marketplaces by keyword' }, + { name: 'update', description: 'Reinstall a plugin from its recorded source' }, + { name: 'refresh', description: 'Live-reload plugins + skills/agents/commands/hooks (MCP needs /mcp refresh)' }, + { name: 'doctor', description: 'Show plugin load errors and integration warnings' }, + { name: 'marketplace', description: 'Manage marketplace subscriptions (add | remove | list | refresh | info)' }, + ], + }, { name: '/exit', description: 'Exit (flushes session)' }, ] as const @@ -693,13 +734,17 @@ export function App({ await handleMcp(text, arg) return + case 'plugin': + await handlePlugin(text, arg) + return + case 'exit': await cleanup() exit() return default: { - // Check if the command matches a loaded skill before giving up. + // Check if the command matches a loaded skill first. const skill = options.skillRegistry?.get(command) if (skill) { if (arg) { @@ -723,6 +768,18 @@ export function App({ } return } + + // Then check plugin-contributed slash commands. These map + // `commands/.md` files from any installed plugin to + // `/`. Body is sent as a model prompt with $ARGUMENTS + // / ${CLAUDE_PLUGIN_ROOT} substitution applied. + const cmd = options.commandRegistry?.get(command) + if (cmd) { + echoCommand(text) + const expanded = expandCommandBody(cmd, arg) + await submit(expanded, { silent: true }) + return + } addCommandMessage(text, `Unknown command: /${command}. Type /help for available commands.`) return } @@ -1141,7 +1198,7 @@ export function App({ } /** Format a memory fact list for display in scrollback. */ - function formatMemoryList(scope: 'project' | 'global', facts: KnowledgeFact[]): string { + function formatMemoryList(scope: 'project' | 'user', facts: KnowledgeFact[]): string { if (facts.length === 0) { return `**Auto memory (${scope})** — empty.` } @@ -1162,14 +1219,14 @@ export function App({ return lines.join('\n').trimEnd() } - /** /memory — show all auto-memory entries (project + global). The + /** /memory — show all auto-memory entries (project + user). The * extractor writes the underlying files in the background; users who * want to delete or edit entries open `auto.md` directly. */ function handleMemory() { const sections: string[] = [] sections.push(formatMemoryList('project', getAutoMemory('project').getAll())) sections.push('') - sections.push(formatMemoryList('global', getAutoMemory('global').getAll())) + sections.push(formatMemoryList('user', getAutoMemory('user').getAll())) addInfoMessage(sections.join('\n')) } @@ -1185,7 +1242,7 @@ export function App({ } /** Split a skill argument into `(name, scope)`, recognizing - * `--scope=global` / `--scope=project` / `-s=global` etc. Bare arg with + * `--scope=user` / `--scope=project` / `-s=user` etc. Bare arg with * no flag returns `scope: undefined` so the caller can default off the * skill's source. Unknown scope strings are ignored (scope stays * undefined) — keeps the parser permissive. */ @@ -1197,7 +1254,7 @@ export function App({ const m = tok.match(/^(?:--scope|-s)(?:=(.+))?$/) if (m) { const value = m[1]?.toLowerCase() - if (value === 'global' || value === 'project') scope = value + if (value === 'user' || value === 'project') scope = value continue } remaining.push(tok) @@ -1314,7 +1371,7 @@ export function App({ if (sub === 'disable' || sub === 'enable') { const name = subArg.trim() if (!name) { - addCommandMessage(text, `Usage: \`/skill ${sub} [--scope=global|project]\``) + addCommandMessage(text, `Usage: \`/skill ${sub} [--scope=user|project]\``) return } const { name: bareName, scope } = parseSkillScopeFlag(name) @@ -1351,11 +1408,11 @@ export function App({ return } // After re-enable, check whether the other scope is still hiding it - // — common pitfall when the user disables globally and then expects + // — common pitfall when the user disables at user scope and then expects // a project-level enable to revive it. let otherScopeNote = '' if (!disable) { - const other: SkillSettingsScope = effectiveScope === 'global' ? 'project' : 'global' + const other: SkillSettingsScope = effectiveScope === 'user' ? 'project' : 'user' try { const stillDisabled = (await getScopedDisabledSkills(other)).includes(bareName) if (stillDisabled) { @@ -1384,7 +1441,18 @@ export function App({ addCommandMessage(text, `No skill named \`${name}\` is loaded. Run \`/skill list\` to see available skills.`) return } - const baseDir = entry.source === 'global' ? GLOBAL_XCODE_DIR : path.join(process.cwd(), '.x-code') + // Plugin-contributed skills live under the plugin's cache dir, not + // under /skills/. `/skill remove` here would compute the + // wrong path and either no-op silently or remove an unrelated dir + // — redirect the user to `/plugin uninstall` instead. + if (entry.pluginId) { + addCommandMessage( + text, + `Skill **${name}** comes from plugin \`${entry.pluginId}\` — remove it with \`/plugin uninstall ${entry.pluginId}\` instead of \`/skill remove\`.`, + ) + return + } + const baseDir = entry.source === 'user' ? GLOBAL_XCODE_DIR : path.join(process.cwd(), '.x-code') const skillDir = path.join(baseDir, 'skills', name) try { await fs.rm(skillDir, { recursive: true, force: true }) @@ -1396,7 +1464,7 @@ export function App({ // at a removed skill would silently swallow a future re-install // with the same name (it'd come back disabled). try { - await setSkillDisabled(name, 'global', false) + await setSkillDisabled(name, 'user', false) await setSkillDisabled(name, 'project', false) } catch { // best-effort — main rm already succeeded @@ -1420,6 +1488,556 @@ export function App({ * `logout` is the only mutator that takes effect immediately: it * just deletes a token from disk; the actual reconnect happens at * next launch. */ + // ── /plugin handler family ──────────────────────────────────────────── + // + // Mirror /mcp / /skill in style: one top-level dispatcher (`handlePlugin`) + // that switches on the first token, plus a marketplace sub-dispatcher + // for the `marketplace` token's own sub-tree (add / remove / list / + // refresh / info). + // + // A note on `/plugin refresh`: in v1 the plugin contributions + // (skills / agents / mcp / hooks) are folded into their respective + // registries at startup. We have no in-process pathway today to + // re-fold them without rebuilding the agentOptions-level registries + // — so `/plugin install|enable|disable` print a "restart xc" hint. + // The metadata view (`/plugin list`, `/plugin info`) does reflect + // in-memory state from startup, which is the source of truth for + // "what's actually active right now". + + function formatPluginSource(s: PluginSource | undefined): string { + if (!s) return '(unknown)' + if (s.kind === 'local') return `local: ${s.path}` + if (s.kind === 'git') return `git: ${s.url}${s.ref ? `#${s.ref}` : ''}` + return `github:${s.owner}/${s.repo}${s.ref ? `#${s.ref}` : ''}` + } + + async function handlePlugin(text: string, arg: string) { + const trimmed = arg.trim() + const parts = trimmed.split(/\s+/) + const sub = (parts[0] ?? '').toLowerCase() + const rest = parts.slice(1).join(' ').trim() + + if (sub === 'marketplace') return handlePluginMarketplace(text, rest) + if (sub === '' || sub === 'list') return pluginList(text, arg) + if (sub === 'info') return pluginInfo(text, rest) + if (sub === 'install') return pluginInstall(text, rest) + if (sub === 'uninstall') return pluginUninstall(text, rest) + if (sub === 'enable') return pluginToggle(text, rest, true) + if (sub === 'disable') return pluginToggle(text, rest, false) + if (sub === 'search') return pluginSearch(text, rest) + if (sub === 'update') return pluginUpdate(text, rest) + if (sub === 'refresh') return void pluginRefresh(text) + if (sub === 'doctor') return pluginDoctor(text) + + addCommandMessage( + text, + 'Usage: `/plugin `', + ) + } + + function pluginList(text: string, raw: string) { + const reg = options.pluginRegistry + if (!reg) { + addCommandMessage(text, 'Plugin system is disabled for this session (`--no-plugins`).') + return + } + // Optional filters: --enabled (only on), --disabled (only off), no flag = all. + const tokens = raw.trim().split(/\s+/).filter(Boolean) + let filter: 'all' | 'enabled' | 'disabled' = 'all' + for (const t of tokens) { + // Skip the subcommand word itself ('list') if present + if (t === 'list') continue + if (t === '--enabled') filter = 'enabled' + else if (t === '--disabled') filter = 'disabled' + } + const all = reg.listAll() + if (all.length === 0) { + addCommandMessage(text, 'No plugins installed. Install one with `/plugin install `.') + return + } + const filtered = + filter === 'enabled' ? all.filter((p) => p.enabled) : filter === 'disabled' ? all.filter((p) => !p.enabled) : all + if (filtered.length === 0) { + addCommandMessage(text, `No ${filter} plugins.`) + return + } + const header = + filter === 'all' + ? `**Installed plugins** (${filtered.length}):` + : `**Installed plugins** (${filter}, ${filtered.length} of ${all.length}):` + const lines = [header, ''] + const namePad = Math.max(...filtered.map((p) => p.id.length), 8) + 2 + for (const p of filtered) { + const badge = p.enabled ? '[on] ' : '[off]' + const src = p.marketplace === 'local' ? '(local)' : `(${p.marketplace})` + lines.push(` ${badge} ${p.id.padEnd(namePad)} v${p.manifest.version} ${src}`) + } + const errors = reg.loadErrors() + if (errors.length > 0) { + lines.push('', `${errors.length} load error${errors.length === 1 ? '' : 's'} — run \`/plugin doctor\`.`) + } + addCommandMessage(text, lines.join('\n')) + } + + async function pluginInfo(text: string, raw: string) { + const id = raw.trim() + if (!id) { + addCommandMessage(text, 'Usage: `/plugin info ` (id = `name@marketplace`)') + return + } + const plugin = options.pluginRegistry?.getEntry(id) + if (!plugin) { + addCommandMessage(text, `No plugin \`${id}\` loaded. Check \`/plugin list\`.`) + return + } + const c = await resolveContributions(plugin) + const lines: string[] = [ + `**${plugin.id}** v${plugin.manifest.version}`, + plugin.manifest.description ?? '_(no description)_', + '', + `- Enabled: ${plugin.enabled ? 'yes' : 'no'}`, + `- Source: ${formatPluginSource(plugin.source)}`, + `- Marketplace: ${plugin.marketplace}`, + `- Root dir: ${plugin.rootDir}`, + `- Manifest: ${plugin.manifestPath} (${plugin.manifestFormat})`, + ] + if (plugin.manifest.author?.name) lines.push(`- Author: ${plugin.manifest.author.name}`) + if (plugin.manifest.homepage) lines.push(`- Homepage: ${plugin.manifest.homepage}`) + if (plugin.manifest.license) lines.push(`- License: ${plugin.manifest.license}`) + + lines.push('', '**Contributions:**') + let any = false + if (c.skillsDir) { + lines.push(`- skills: ${c.skillsDir}`) + any = true + } + if (c.agentsDir) { + lines.push(`- agents: ${c.agentsDir}`) + any = true + } + if (c.commandsDir) { + lines.push(`- commands: ${c.commandsDir}`) + any = true + } + if (c.mcpServers) { + lines.push(`- mcpServers: ${c.mcpServers.kind === 'inline' ? '(inline)' : c.mcpServers.path}`) + any = true + } + if (c.hooks) { + lines.push(`- hooks: ${c.hooks.kind === 'inline' ? '(inline)' : c.hooks.path}`) + any = true + } + if (!any) lines.push('- _(none)_') + + addCommandMessage(text, lines.join('\n')) + } + + async function pluginInstall(text: string, raw: string) { + if (!raw) { + addCommandMessage( + text, + 'Usage: `/plugin install `\n' + + ' Sources:\n' + + ' `@` — look up + install from subscribed marketplace\n' + + ' `github:owner/repo[#ref]` — install from a GitHub repo\n' + + ' `https://...` or `git@...` — install from any git URL\n' + + ' `/abs/path` or `./relative/path` — install from a local directory', + ) + return + } + + let source: PluginSource + let marketplace: string + let expectedName: string | undefined + + const isPath = raw.startsWith('./') || raw.startsWith('../') || raw.startsWith('/') || /^[a-zA-Z]:[/\\]/.test(raw) + const isGitUrl = /^https?:\/\//i.test(raw) || raw.startsWith('git@') + const isGhShort = raw.startsWith('github:') + const atIdx = raw.lastIndexOf('@') + const isMarketplaceRef = atIdx > 0 && !isPath && !isGitUrl && !isGhShort + + if (isMarketplaceRef) { + const name = raw.slice(0, atIdx) + const mpName = raw.slice(atIdx + 1) + const found = await lookupPlugin(`${name}@${mpName}`) + if (!found) { + addCommandMessage( + text, + `Plugin \`${name}\` not found in marketplace \`${mpName}\`. ` + + `Run \`/plugin marketplace refresh ${mpName}\` or check the spelling.`, + ) + return + } + source = found.entry.source + marketplace = mpName + expectedName = name + } else if (isGhShort) { + const m = raw.match(/^github:([^/]+)\/(.+?)(?:#(.+))?$/i) + if (!m) { + addCommandMessage(text, 'Invalid github source. Expected `github:owner/repo` or `github:owner/repo#ref`.') + return + } + source = { kind: 'github', owner: m[1]!, repo: m[2]!, ref: m[3] } + marketplace = 'local' + } else if (isGitUrl) { + source = { kind: 'git', url: raw } + marketplace = 'local' + } else if (isPath) { + source = { kind: 'local', path: raw } + marketplace = 'local' + } else { + addCommandMessage( + text, + `Unrecognised source: \`${raw}\`. Use \`name@marketplace\`, \`github:owner/repo\`, an https/git URL, or a path.`, + ) + return + } + + addCommandMessage(text, `Installing from ${formatPluginSource(source)} …`) + try { + const result = await installPlugin({ source, marketplace, expectedName }) + addCommandMessage( + text, + `Installed **${result.pluginId}** v${result.manifest.version}\n` + + `Cache: \`${result.rootDir}\`\n` + + `Restart xc to load this plugin's contributions (skills / agents / mcp / hooks).`, + ) + } catch (err) { + addCommandMessage(text, `Install failed: ${err instanceof Error ? err.message : String(err)}`) + } + } + + async function pluginUninstall(text: string, raw: string) { + const id = raw.trim() + if (!id) { + addCommandMessage(text, 'Usage: `/plugin uninstall ` (id = `name@marketplace`)') + return + } + try { + const result = await uninstallPlugin(id) + if (!result.removedRecord && result.removedVersions.length === 0) { + addCommandMessage(text, `No plugin \`${id}\` installed.`) + return + } + // Best-effort cleanup of settings entries in both scopes. + for (const scope of ['user', 'project'] as PluginScope[]) { + await clearPluginEntry(id, scope).catch(() => undefined) + } + const verCount = result.removedVersions.length + addCommandMessage( + text, + `Uninstalled **${id}** (removed ${verCount} cached version${verCount === 1 ? '' : 's'}).\n` + + `Plugin data dir preserved — reinstall will keep user state.\n` + + `Restart xc to drop this plugin's contributions from active registries.`, + ) + } catch (err) { + addCommandMessage(text, `Uninstall failed: ${err instanceof Error ? err.message : String(err)}`) + } + } + + /** Parse a `/plugin enable|disable` argument string, recognizing the + * shared `--scope=user|project` / `-s=user|project` flag (same parser + * shape as parseSkillScopeFlag). Default scope = 'user' so terse + * invocations stay terse. */ + function parsePluginScopeFlag(arg: string): { id: string; scope: PluginScope } { + const tokens = arg.split(/\s+/).filter(Boolean) + let scope: PluginScope = 'user' + const remaining: string[] = [] + for (const tok of tokens) { + const m = tok.match(/^(?:--scope|-s)(?:=(.+))?$/) + if (m) { + const value = m[1]?.toLowerCase() + if (value === 'user' || value === 'project') scope = value + continue + } + remaining.push(tok) + } + return { id: remaining.join(' '), scope } + } + + async function pluginToggle(text: string, raw: string, enable: boolean) { + const { id, scope } = parsePluginScopeFlag(raw) + if (!id) { + addCommandMessage(text, `Usage: \`/plugin ${enable ? 'enable' : 'disable'} [--scope=user|project]\``) + return + } + try { + const result = await setPluginEnabled(id, scope, enable) + const verb = enable ? 'enabled' : 'disabled' + if (result === 'noop') { + addCommandMessage(text, `Plugin \`${id}\` already ${verb} (${scope} scope).`) + } else { + addCommandMessage( + text, + `Plugin **${id}** ${verb} in ${scope} scope. Restart xc to apply (contributions are bound at startup).`, + ) + } + } catch (err) { + addCommandMessage(text, `Failed: ${err instanceof Error ? err.message : String(err)}`) + } + } + + async function pluginSearch(text: string, raw: string) { + const kw = raw.trim().toLowerCase() + if (!kw) { + addCommandMessage(text, 'Usage: `/plugin search `') + return + } + const marketplaces = await readAllCachedMarketplaces() + if (marketplaces.length === 0) { + addCommandMessage( + text, + 'No subscribed marketplaces. Add one with `/plugin marketplace add ` and `refresh` it.', + ) + return + } + const matches: Array<{ marketplace: string; name: string; description?: string; verified?: boolean }> = [] + for (const m of marketplaces) { + for (const entry of m.plugins) { + const hay = [entry.name, entry.description ?? '', ...(entry.keywords ?? [])].join(' ').toLowerCase() + if (hay.includes(kw)) { + matches.push({ + marketplace: m.name, + name: entry.name, + description: entry.description, + verified: entry.verified, + }) + } + } + } + if (matches.length === 0) { + addCommandMessage( + text, + `No plugins matching \`${kw}\` in ${marketplaces.length} subscribed marketplace${marketplaces.length === 1 ? '' : 's'}. ` + + `Run \`/plugin marketplace refresh\` to pull latest indexes.`, + ) + return + } + const lines = [`Found ${matches.length} match${matches.length === 1 ? '' : 'es'}:`] + for (const m of matches) { + const tag = m.verified ? ' [verified]' : '' + lines.push(` ${m.name}@${m.marketplace}${tag}`) + if (m.description) lines.push(` ${m.description}`) + } + lines.push('', 'Install with `/plugin install @`.') + addCommandMessage(text, lines.join('\n')) + } + + async function pluginUpdate(text: string, raw: string) { + const id = raw.trim() + if (!id) { + addCommandMessage(text, 'Usage: `/plugin update ` (whole-list update not yet implemented)') + return + } + const records = await listInstalledPlugins() + const rec = records.find((r) => r.id === id) + if (!rec) { + addCommandMessage(text, `Plugin \`${id}\` not installed.`) + return + } + addCommandMessage(text, `Reinstalling **${id}** from ${formatPluginSource(rec.source)} …`) + try { + const result = await installPlugin({ + source: rec.source, + marketplace: rec.marketplace, + expectedName: rec.name, + }) + const versionMsg = + result.manifest.version === rec.version + ? `Reinstalled at the same version (${rec.version}).` + : `Updated ${rec.version} → ${result.manifest.version}.` + addCommandMessage(text, `${versionMsg} Restart xc to load the new version.`) + } catch (err) { + addCommandMessage(text, `Update failed: ${err instanceof Error ? err.message : String(err)}`) + } + } + + async function pluginRefresh(text: string) { + if (!options.pluginRegistry) { + addCommandMessage(text, 'Plugin system is disabled for this session (`--no-plugins`).') + return + } + let summary + try { + summary = await refreshPluginContributions({ + pluginRegistry: options.pluginRegistry, + skillRegistry: options.skillRegistry, + subAgentRegistry: options.subAgentRegistry, + commandRegistry: options.commandRegistry, + hookBus: options.hookBus, + cwd: process.cwd(), + }) + } catch (err) { + addCommandMessage(text, `Failed to reload plugins: ${err instanceof Error ? err.message : String(err)}`) + return + } + // Invalidate the system prompt cache: plugin contributions feed into + // skills, agents, commands — all of which the prompt mentions. Same + // one-cache-miss trade /skill refresh + /mcp refresh make. + invalidateSystemPromptCache() + // Force the slash-command tab completion + /help list to re-memo off + // the new skill set. + setSkillRegistryVersion((v) => v + 1) + + const parts: string[] = [] + const p = summary.plugins + if (p.added.length) parts.push(`added: ${p.added.join(', ')}`) + if (p.removed.length) parts.push(`removed: ${p.removed.join(', ')}`) + if (p.changed.length) parts.push(`changed: ${p.changed.join(', ')}`) + if (parts.length === 0) parts.push(`no plugin changes (${p.unchanged.length} unchanged)`) + const lines = [`Reloaded plugins — ${parts.join('; ')}.`] + // Per-sub-registry deltas (only show ones that actually moved). + const subBits: string[] = [] + if (summary.skills && (summary.skills.added.length || summary.skills.removed.length)) + subBits.push(`${summary.skills.added.length + summary.skills.removed.length} skill change(s)`) + if (summary.subAgents && (summary.subAgents.added.length || summary.subAgents.removed.length)) + subBits.push(`${summary.subAgents.added.length + summary.subAgents.removed.length} sub-agent change(s)`) + if (summary.commands && (summary.commands.added.length || summary.commands.removed.length)) + subBits.push(`${summary.commands.added.length + summary.commands.removed.length} command change(s)`) + if (subBits.length) lines.push(`Downstream: ${subBits.join(', ')}.`) + // Plugin-contributed MCP servers aren't restarted here — that needs + // /mcp refresh. Mention it only when this refresh actually touched + // a plugin that contributes MCP so the user knows to follow up. + if (p.added.length || p.removed.length) { + lines.push('Note: plugin-contributed MCP servers are not restarted — run `/mcp refresh` if needed.') + } + lines.push('Note: next message rebuilds the system prompt, so prompt-cache will miss once.') + addCommandMessage(text, lines.join('\n')) + } + + function pluginDoctor(text: string) { + const reg = options.pluginRegistry + if (!reg) { + addCommandMessage(text, 'Plugin system is disabled for this session (`--no-plugins`).') + return + } + const errors = reg.loadErrors() + const all = reg.listAll() + const lines: string[] = ['**Plugin doctor**', ''] + lines.push(`- Total loaded: ${all.length}`) + lines.push(`- Enabled: ${all.filter((p) => p.enabled).length}`) + lines.push(`- Disabled: ${all.filter((p) => !p.enabled).length}`) + lines.push(`- Load errors: ${errors.length}`) + if (errors.length > 0) { + lines.push('', '**Errors:**') + for (const e of errors) { + lines.push(`- ${e.id ?? '(unknown)'} at \`${e.path}\``) + lines.push(` ${e.message}`) + } + } + lines.push( + '', + '_For deeper diagnostics (mcp collisions, hook errors, unsupported `commands` contributions), set `DEBUG_STDOUT=1` and check `~/.x-code/logs/debug.log`._', + ) + addCommandMessage(text, lines.join('\n')) + } + + async function handlePluginMarketplace(text: string, arg: string) { + const parts = arg.trim().split(/\s+/) + const sub = (parts[0] ?? '').toLowerCase() + const rest = parts.slice(1).join(' ').trim() + + if (sub === '' || sub === 'list') { + const km = await readKnownMarketplaces() + if (km.marketplaces.length === 0) { + addCommandMessage(text, 'No marketplaces subscribed. Add one with `/plugin marketplace add `.') + return + } + const lines = [`**Subscribed marketplaces** (${km.marketplaces.length}):`, ''] + const namePad = Math.max(...km.marketplaces.map((m) => m.name.length), 8) + 2 + for (const m of km.marketplaces) { + const tag = m.reservedName ? ' [official]' : '' + lines.push(` ${m.name.padEnd(namePad)} ${m.source}${tag}`) + } + addCommandMessage(text, lines.join('\n')) + return + } + + if (sub === 'add') { + const argParts = rest.split(/\s+/) + if (argParts.length < 2 || !argParts[0] || !argParts[1]) { + addCommandMessage( + text, + 'Usage: `/plugin marketplace add ` (source: `github:owner/repo` or an https URL to a marketplace.json)', + ) + return + } + const [name, ...sourceParts] = argParts + const source = sourceParts.join(' ') + try { + await addKnownMarketplace({ name, source }) + addCommandMessage( + text, + `Subscribed to **${name}** (\`${source}\`). Run \`/plugin marketplace refresh ${name}\` to fetch its index.`, + ) + } catch (err) { + addCommandMessage(text, `Failed: ${err instanceof Error ? err.message : String(err)}`) + } + return + } + + if (sub === 'remove') { + if (!rest) { + addCommandMessage(text, 'Usage: `/plugin marketplace remove `') + return + } + const result = await removeKnownMarketplace(rest) + if (result === 'noop') addCommandMessage(text, `No marketplace \`${rest}\` subscribed.`) + else addCommandMessage(text, `Unsubscribed from **${rest}**.`) + return + } + + if (sub === 'refresh') { + const km = await readKnownMarketplaces() + const targets = rest ? km.marketplaces.filter((m) => m.name === rest) : km.marketplaces + if (targets.length === 0) { + addCommandMessage(text, rest ? `No marketplace \`${rest}\` subscribed.` : 'No marketplaces subscribed.') + return + } + const lines: string[] = [`Refreshing ${targets.length} marketplace${targets.length === 1 ? '' : 's'} …`] + for (const t of targets) { + try { + const m = await fetchMarketplace(t) + lines.push(` ✓ ${t.name} — ${m.plugins.length} plugin${m.plugins.length === 1 ? '' : 's'}`) + } catch (err) { + lines.push(` ✗ ${t.name} — ${err instanceof Error ? err.message : String(err)}`) + } + } + addCommandMessage(text, lines.join('\n')) + return + } + + if (sub === 'info') { + if (!rest) { + addCommandMessage(text, 'Usage: `/plugin marketplace info `') + return + } + const all = await readAllCachedMarketplaces() + const m = all.find((x) => x.name === rest) + if (!m) { + addCommandMessage( + text, + `No cached index for marketplace \`${rest}\`. Run \`/plugin marketplace refresh ${rest}\` first.`, + ) + return + } + const lines: string[] = [`**${m.displayName ?? m.name}** (${m.name})`] + if (m.description) lines.push(m.description) + if (m.owner?.name) lines.push(`Owner: ${m.owner.name}${m.owner.url ? ` (${m.owner.url})` : ''}`) + lines.push('', `${m.plugins.length} plugin${m.plugins.length === 1 ? '' : 's'}:`) + for (const p of m.plugins) { + const ver = p.verified ? ' [verified]' : '' + const cat = p.category ? ` (${p.category})` : '' + lines.push(` ${p.name}${ver}${cat}`) + if (p.description) lines.push(` ${p.description}`) + } + addCommandMessage(text, lines.join('\n')) + return + } + + addCommandMessage(text, 'Usage: `/plugin marketplace `') + } + async function handleMcp(text: string, arg: string) { const argTrimmed = arg.trim() const sub = (argTrimmed.split(/\s+/)[0] ?? '').toLowerCase() diff --git a/packages/core/src/agent/compression.ts b/packages/core/src/agent/compression.ts index 408af6e..962d46a 100644 --- a/packages/core/src/agent/compression.ts +++ b/packages/core/src/agent/compression.ts @@ -13,13 +13,25 @@ import { generateText } from 'ai' import type { LanguageModel, ModelMessage } from 'ai' +import type { HookBus } from '../hooks/bus.js' import { generateSessionSummary } from '../knowledge/session.js' import type { AgentCallbacks } from '../types/index.js' +import { debugLog } from '../utils.js' import { estimateTokenCount } from './context-window.js' import { lightCompactMessages } from './light-compact.js' import type { LoopState } from './loop-state.js' import { markBoundaryAndReflush } from './session-store.js' +/** Optional hook surface threaded through both compression paths. Lets + * plugins observe (PreCompact) and react to (PostCompact) the act of + * trimming context — useful for checkpoint persistence or audit. */ +export interface CompactionHookContext { + hookBus?: HookBus + modelId: string + cwd: string + abortSignal?: AbortSignal +} + /** Number of recent messages to keep verbatim when compressing. */ export const KEEP_RECENT = 6 @@ -62,10 +74,23 @@ export async function checkAndCompressContext( model: LanguageModel, threshold: number, callbacks: AgentCallbacks, + hookCtx?: CompactionHookContext, ): Promise { const needsCompression = state.lastInputTokens > threshold || estimateTokenCount(state.messages) > threshold if (!needsCompression || state.messages.length <= KEEP_RECENT) return + // PreCompact — fires before either compaction path runs. We don't + // wait for hook decisions to influence behaviour (compaction is + // mandatory once we cross the threshold), so this is fire-and-forget. + const messageCountBefore = state.messages.length + const tokenEstimateBefore = estimateTokenCount(state.messages) + emitCompactionHook(hookCtx, { + name: 'PreCompact', + trigger: 'proactive', + messageCount: messageCountBefore, + tokenEstimate: tokenEstimateBefore, + }) + const light = lightCompactMessages(state.messages) if (light.dropped > 0) { state.messages = light.messages @@ -79,6 +104,12 @@ export async function checkAndCompressContext( // pre-boundary, but the loader cuts at the latest boundary). The // boundary carries no summary text since nothing was summarised. void markBoundaryAndReflush(state) + emitCompactionHook(hookCtx, { + name: 'PostCompact', + trigger: 'proactive', + messageCount: state.messages.length, + summary: '', + }) return } } @@ -101,6 +132,12 @@ export async function checkAndCompressContext( // the post-boundary jsonl content equals the new in-memory state. void markBoundaryAndReflush(state, summaryText) callbacks.onContextCompressed('Context compressed to fit context window.') + emitCompactionHook(hookCtx, { + name: 'PostCompact', + trigger: 'proactive', + messageCount: state.messages.length, + summary: summaryText, + }) } /** @@ -112,8 +149,15 @@ export async function handleContextTooLong( state: LoopState, model: LanguageModel, callbacks: AgentCallbacks, + hookCtx?: CompactionHookContext, ): Promise { if (state.messages.length <= KEEP_RECENT) return false + emitCompactionHook(hookCtx, { + name: 'PreCompact', + trigger: 'reactive', + messageCount: state.messages.length, + tokenEstimate: estimateTokenCount(state.messages), + }) state.messages = await compressMessages(state.messages, model) state.lastInputTokens = 0 // Same boundary discipline as the proactive path — reactive compact @@ -121,5 +165,32 @@ export async function handleContextTooLong( // compact-boundary marker to keep loader semantics consistent. void markBoundaryAndReflush(state) callbacks.onContextCompressed('Context too long — automatically compressed. Retrying...') + emitCompactionHook(hookCtx, { + name: 'PostCompact', + trigger: 'reactive', + messageCount: state.messages.length, + summary: '', + }) return true } + +/** Fire a PreCompact / PostCompact hook with the session context. Best + * effort — compaction has already happened (or is committed to happen), + * so hook failures and aborts must not bubble. */ +function emitCompactionHook( + ctx: CompactionHookContext | undefined, + partial: + | { name: 'PreCompact'; trigger: 'proactive' | 'reactive'; messageCount: number; tokenEstimate: number } + | { name: 'PostCompact'; trigger: 'proactive' | 'reactive'; messageCount: number; summary: string }, +): void { + if (!ctx?.hookBus?.has(partial.name)) return + void ctx.hookBus + .emit( + { + ...partial, + session: { cwd: ctx.cwd, modelId: ctx.modelId }, + }, + { signal: ctx.abortSignal }, + ) + .catch((err) => debugLog(`agent.hook-${partial.name.toLowerCase()}-error`, String(err))) +} diff --git a/packages/core/src/agent/loop.ts b/packages/core/src/agent/loop.ts index 960131d..edb2fdf 100644 --- a/packages/core/src/agent/loop.ts +++ b/packages/core/src/agent/loop.ts @@ -8,6 +8,8 @@ import path from 'node:path' import { streamText } from 'ai' import type { LanguageModel, UserContent } from 'ai' +import { aggregateUserPromptSubmit } from '../hooks/bus.js' +import type { HookEvent } from '../hooks/types.js' import { buildKnowledgeContext } from '../knowledge/loader.js' import { listMcpResources, readMcpResource } from '../mcp/resources.js' import { bridgeMcpTool, toSystemPromptEntries } from '../mcp/tool-bridge.js' @@ -34,6 +36,18 @@ import { buildSystemPrompt } from './system-prompt.js' import { processToolCalls } from './tool-execution.js' import { repairOrphanToolCalls, truncateToolResultsInMessages } from './tool-result-sanitize.js' +/** Prepend an injected context block to a UserContent payload. Used by + * the UserPromptSubmit hook decision: plugins can inject context (e.g. + * current sprint info) before the model sees the user's actual prompt. + * We prepend INTO the user message rather than insert a separate user + * message to avoid producing two consecutive user turns (some providers + * reject that — Claude refuses to alternate role==='user' twice). */ +function prependContext(userMessage: UserContent, context: string): UserContent { + const block = `\n${context}\n\n\n` + if (typeof userMessage === 'string') return block + userMessage + return [{ type: 'text', text: block }, ...userMessage] +} + /** Pull plain text out of a UserContent payload for slugification. * UserContent can be a string OR a multi-part array (text/image/file * parts after `buildUserContent` ingests `@path` references); we only @@ -356,7 +370,12 @@ async function runTurn( if (isAbortError(err, options.abortSignal)) return { kind: 'aborted' } if (isContextTooLongError(err)) { - const compressed = await handleContextTooLong(state, model, callbacks) + const compressed = await handleContextTooLong(state, model, callbacks, { + hookBus: options.hookBus, + modelId: options.modelId, + cwd: process.cwd(), + abortSignal: options.abortSignal, + }) // Compression makes its own LLM round-trip (2–5s) and doesn't accept // an abort signal. If the user Esc'd while it ran, the next runTurn // would issue another streamText only to have the SDK reject it @@ -392,7 +411,62 @@ export async function agentLoop( existingState?: LoopState, ): Promise { const state = existingState ?? createLoopState(options.permissionMode ?? 'default') - state.messages.push({ role: 'user', content: userMessage }) + + // ── Plugin hook: SessionStart ── + // First-invocation-of-the-session marker. Fire-and-forget, but awaited + // so hooks have a chance to inject session-scoped env / state before + // the user's prompt is processed. Skipped on subsequent calls within + // the same session (existingState !== undefined). + if (!existingState && options.hookBus?.has('SessionStart')) { + await options.hookBus + .emit( + { name: 'SessionStart', session: { cwd: process.cwd(), modelId: options.modelId } }, + { signal: options.abortSignal }, + ) + .catch((err) => { + if (options.abortSignal?.aborted) throw err + debugLog('agent.hook-session-start-error', String(err)) + }) + } + + // ── Plugin hook: UserPromptSubmit ── + // Runs BEFORE the message is pushed into state.messages so a `deny` + // decision keeps the transcript clean (no stranded prompt). A + // `modify` with `context` prepends the injected text into the user + // message itself rather than as a second user message — back-to-back + // user messages confuse some providers' tool-call sequencing. + let effectiveUserMessage = userMessage + if (options.hookBus?.has('UserPromptSubmit')) { + const promptText = userContentToText(userMessage) + try { + const decisions = await options.hookBus.emit( + { name: 'UserPromptSubmit', session: { cwd: process.cwd(), modelId: options.modelId }, prompt: promptText }, + { signal: options.abortSignal }, + ) + const effect = aggregateUserPromptSubmit(decisions) + if (effect.decision === 'deny') { + const reason = effect.reason ?? 'blocked by plugin hook' + const notice = `[Prompt blocked by plugin hook: ${reason}]` + callbacks.onTextDelta(notice) + // Push BOTH the user's original message and a synthetic assistant + // response — keeps state.messages valid as alternating user / + // assistant turns the next submit can build on. + state.messages.push({ role: 'user', content: userMessage }) + state.messages.push({ role: 'assistant', content: notice }) + return { state, turnCount: 0 } + } + if (effect.context) { + effectiveUserMessage = prependContext(userMessage, effect.context) + } + } catch (err) { + if (options.abortSignal?.aborted) { + return { state, turnCount: 0 } + } + debugLog('agent.hook-user-prompt-error', String(err)) + } + } + + state.messages.push({ role: 'user', content: effectiveUserMessage }) // Per-invocation turn counter. Scoped to this single `agentLoop` call // — re-entering the function (next user submit) starts at 0 again. @@ -496,7 +570,12 @@ export async function agentLoop( // pre-compaction tail is already on disk. void flushPendingMessages(state) - await checkAndCompressContext(state, model, compressionThreshold, callbacks) + await checkAndCompressContext(state, model, compressionThreshold, callbacks, { + hookBus: options.hookBus, + modelId: options.modelId, + cwd: process.cwd(), + abortSignal: options.abortSignal, + }) // Build the system prompt once per session and reuse it across turns. // Stable byte-level prefix is a prerequisite for OpenAI-compatible @@ -542,6 +621,27 @@ export async function agentLoop( const outcome = await runTurn(state, model, options, systemPrompt, callbacks, effectiveTools, turn) + // ── Plugin hook: TurnComplete ── + // Fires regardless of finish reason (including error / abort) so + // notification / audit hooks see every turn, not just clean stops. + // Parallel + best-effort: hook failures and aborts can't block the + // outcome dispatch below. + if (options.hookBus?.has('TurnComplete')) { + const event: HookEvent = { + name: 'TurnComplete', + session: { cwd: process.cwd(), modelId: options.modelId }, + turn, + tokenUsage: { + inputTokens: state.tokenUsage.inputTokens, + outputTokens: state.tokenUsage.outputTokens, + totalTokens: state.tokenUsage.totalTokens, + }, + } + void options.hookBus + .emit(event, { signal: options.abortSignal }) + .catch((err) => debugLog('agent.hook-turn-complete-error', String(err))) + } + if (outcome.kind === 'error') break if (outcome.kind === 'aborted') break if (outcome.kind === 'retry') { diff --git a/packages/core/src/agent/memory-extractor.ts b/packages/core/src/agent/memory-extractor.ts index 37b26b3..428c3a2 100644 --- a/packages/core/src/agent/memory-extractor.ts +++ b/packages/core/src/agent/memory-extractor.ts @@ -46,7 +46,7 @@ let inflight: Promise = Promise.resolve() const MemoryItemSchema = z.object({ category: z.enum(['user', 'feedback', 'project', 'reference']), - scope: z.enum(['project', 'global']), + scope: z.enum(['project', 'user']), key: z.string().min(1).describe('Short slug. Same key under same category overwrites the previous fact.'), fact: z.string().min(1).describe('The fact itself. Lead with the rule; for feedback include a one-line reason.'), }) @@ -64,10 +64,10 @@ const MemorySchema = z.object({ * only catches exact key collisions, not semantic overlap, so the * prevention has to happen in the extractor's prompt. */ function renderExistingMemory(): string { - const global = getAutoMemory('global').getPromptContent().trim() + const user = getAutoMemory('user').getPromptContent().trim() const project = getAutoMemory('project').getPromptContent().trim() const sections: string[] = [] - sections.push(`## Global (~/.x-code/memory/auto.md)\n${global || '(empty)'}`) + sections.push(`## User (~/.x-code/memory/auto.md)\n${user || '(empty)'}`) sections.push(`## Project (.x-code/memory/auto.md)\n${project || '(empty)'}`) return sections.join('\n\n') } @@ -132,7 +132,7 @@ The main agent has just finished replying to the user. Scan the recent transcrip **user** — durable facts about who the human is, changing how you'd talk to them next session. Trigger: role, expertise, working environment, language preferences, long-term constraints. Example: User says "I've been writing Go for ten years but this is my first time touching the React side." - → \`{ category: "user", scope: "global", key: "user-stack", fact: "Ten years of Go; first time touching React in this repo." }\` + → \`{ category: "user", scope: "user", key: "user-stack", fact: "Ten years of Go; first time touching React in this repo." }\` (Note: the fact is a direct paraphrase. Do NOT add "explain by analogy" or any other prescriptive action — that's inference, not what the user said.) **feedback** — corrections OR validated approaches. Both count. Lead with the rule, include a one-line reason. @@ -164,7 +164,7 @@ The main agent has just finished replying to the user. Scan the recent transcrip # Scope rule - Project-specific facts (this repo / team / release): \`scope: "project"\`. -- Cross-project facts about the user themselves (stack expertise, OS, name): \`scope: "global"\`. +- Cross-project facts about the user themselves (stack expertise, OS, name): \`scope: "user"\`. When in doubt, prefer empty array. The user can always type the durable fact again next session if it really matters.` diff --git a/packages/core/src/agent/sub-agents/index.ts b/packages/core/src/agent/sub-agents/index.ts index 0538bf9..b73d4bd 100644 --- a/packages/core/src/agent/sub-agents/index.ts +++ b/packages/core/src/agent/sub-agents/index.ts @@ -2,6 +2,7 @@ export type { SubAgentDefinition, SubAgentTrace, SubAgentEvent } from './types.js' export { builtInAgents } from './built-in.js' export { loadCustomAgents } from './loader.js' -export { SubAgentRegistry, createSubAgentRegistry, createBuiltInRegistry } from './registry.js' +export { SubAgentRegistry, createSubAgentRegistry, createBuiltInRegistry, reloadSubAgentRegistry } from './registry.js' +export type { SubAgentReloadSummary } from './registry.js' export { runSubAgent } from './runner.js' export type { RunSubAgentArgs, RunSubAgentResult } from './runner.js' diff --git a/packages/core/src/agent/sub-agents/loader.ts b/packages/core/src/agent/sub-agents/loader.ts index 105cd82..7fae932 100644 --- a/packages/core/src/agent/sub-agents/loader.ts +++ b/packages/core/src/agent/sub-agents/loader.ts @@ -81,7 +81,11 @@ function parseFrontmatter(raw: string): { data: Record; body: s return { data, body } } -async function loadAgentsFromDir(dir: string, source: SubAgentDefinition['source']): Promise { +async function loadAgentsFromDir( + dir: string, + source: SubAgentDefinition['source'], + pluginId?: string, +): Promise { const agents: SubAgentDefinition[] = [] let entries: string[] @@ -122,6 +126,7 @@ async function loadAgentsFromDir(dir: string, source: SubAgentDefinition['source maxTurns: fm.maxTurns ?? 30, shellRestrictions: fm.shellRestrictions, source, + ...(pluginId ? { pluginId } : {}), }) } catch (err) { console.error(`[sub-agents] Skipping ${filePath}: ${err instanceof Error ? err.message : String(err)}`) @@ -131,19 +136,40 @@ async function loadAgentsFromDir(dir: string, source: SubAgentDefinition['source return agents } -/** Load custom sub-agents from global + project directories. - * Environment variable `XC_AGENTS_DIR` overrides paths (testing only). */ -export async function loadCustomAgents(): Promise { +export interface LoadCustomAgentsOptions { + /** Extra sub-agent directories to scan, with the owning plugin id. + * See packages/core/src/plugins/integration.ts for how plugin + * contributions get turned into this shape. */ + extraDirs?: ReadonlyArray<{ dir: string; pluginId: string }> +} + +/** Load custom sub-agents from global + project directories, plus any + * extra dirs (plugin-contributed). Environment variable `XC_AGENTS_DIR` + * overrides the built-in paths for testing (extras are still honoured). */ +export async function loadCustomAgents(opts: LoadCustomAgentsOptions = {}): Promise { const override = process.env.XC_AGENTS_DIR if (override) { - return loadAgentsFromDir(override, 'project') + const overrideAgents = await loadAgentsFromDir(override, 'project') + return [...overrideAgents, ...(await loadAgentsFromExtras(opts.extraDirs))] } - const globalDir = path.join(GLOBAL_XCODE_DIR, 'agents') + const userDir = path.join(GLOBAL_XCODE_DIR, 'agents') const projectDir = path.join(process.cwd(), XCODE_DIR, 'agents') - const globalAgents = await loadAgentsFromDir(globalDir, 'global') + const userAgents = await loadAgentsFromDir(userDir, 'user') + const pluginAgents = await loadAgentsFromExtras(opts.extraDirs) const projectAgents = await loadAgentsFromDir(projectDir, 'project') - return [...globalAgents, ...projectAgents] + // user → plugin → project. SubAgentRegistry's Map.set overrides on + // duplicate names, so later entries win — same precedence as skills. + return [...userAgents, ...pluginAgents, ...projectAgents] +} + +async function loadAgentsFromExtras(extras: LoadCustomAgentsOptions['extraDirs']): Promise { + if (!extras || extras.length === 0) return [] + const out: SubAgentDefinition[] = [] + for (const { dir, pluginId } of extras) { + out.push(...(await loadAgentsFromDir(dir, 'user', pluginId))) + } + return out } diff --git a/packages/core/src/agent/sub-agents/registry.ts b/packages/core/src/agent/sub-agents/registry.ts index e2db524..dbad974 100644 --- a/packages/core/src/agent/sub-agents/registry.ts +++ b/packages/core/src/agent/sub-agents/registry.ts @@ -1,12 +1,22 @@ // @x-code-cli/core — Sub-agent registry // -// Constructed once at startup, immutable for the session lifetime. -// Built-in agents load synchronously; custom agents from disk are async. -// Same-name custom agents override built-ins (project > global > built-in). +// Constructed once at startup; can be hot-reloaded via reloadSubAgentRegistry +// when /plugin refresh fires. Built-in agents load synchronously; custom +// agents from disk are async. Same-name custom agents override built-ins +// (project > user > built-in). import { builtInAgents } from './built-in.js' -import { loadCustomAgents } from './loader.js' +import { type LoadCustomAgentsOptions, loadCustomAgents } from './loader.js' import type { SubAgentDefinition } from './types.js' +/** Diff summary returned by reload — drives the message surface for + * /plugin refresh. */ +export interface SubAgentReloadSummary { + added: string[] + removed: string[] + changed: string[] + unchanged: string[] +} + export class SubAgentRegistry { private agents: Map @@ -28,15 +38,48 @@ export class SubAgentRegistry { names(): string[] { return [...this.agents.keys()] } + + /** Replace the in-memory agent list with a fresh load. Used by + * /plugin refresh — keeps the same SubAgentRegistry object identity so + * every captured `options.subAgentRegistry` reference stays valid. */ + reload(agents: SubAgentDefinition[]): SubAgentReloadSummary { + const previous = this.agents + const next = new Map() + for (const a of agents) next.set(a.name, a) + const summary: SubAgentReloadSummary = { added: [], removed: [], changed: [], unchanged: [] } + for (const [name, agent] of next) { + const prev = previous.get(name) + if (!prev) summary.added.push(name) + else if (prev.prompt !== agent.prompt || prev.source !== agent.source || prev.pluginId !== agent.pluginId) + summary.changed.push(name) + else summary.unchanged.push(name) + } + for (const name of previous.keys()) { + if (!next.has(name)) summary.removed.push(name) + } + this.agents = next + return summary + } } /** Build the registry: built-in first, then custom (later entries override). */ -export async function createSubAgentRegistry(): Promise { - const custom = await loadCustomAgents() +export async function createSubAgentRegistry(opts: LoadCustomAgentsOptions = {}): Promise { + const custom = await loadCustomAgents(opts) // Load order: built-in → custom. Map insertion overwrites, so custom wins. return new SubAgentRegistry([...builtInAgents, ...custom]) } +/** Re-scan + rebuild the in-memory agent list in place. Same disk scan as + * startup; opts (notably extraDirs from plugins) carry over from the + * caller. Returns a diff summary for the /plugin refresh message. */ +export async function reloadSubAgentRegistry( + registry: SubAgentRegistry, + opts: LoadCustomAgentsOptions = {}, +): Promise { + const custom = await loadCustomAgents(opts) + return registry.reload([...builtInAgents, ...custom]) +} + /** Synchronous registry with only built-in agents (for testing or when * disk scan should be skipped). */ export function createBuiltInRegistry(): SubAgentRegistry { diff --git a/packages/core/src/agent/sub-agents/runner.ts b/packages/core/src/agent/sub-agents/runner.ts index 831e56e..ef9cc36 100644 --- a/packages/core/src/agent/sub-agents/runner.ts +++ b/packages/core/src/agent/sub-agents/runner.ts @@ -6,6 +6,8 @@ import type { LanguageModel } from 'ai' import { resolveModelId } from '../../config/index.js' +import type { HookBus } from '../../hooks/bus.js' +import type { HookEvent } from '../../hooks/types.js' import type { AgentCallbacks, AgentOptions, TokenUsage } from '../../types/index.js' import { debugLog } from '../../utils.js' import { createLoopState } from '../loop-state.js' @@ -15,6 +17,18 @@ import { buildSubAgentSystemPrompt } from '../system-prompt.js' import type { SubAgentRegistry } from './registry.js' import type { SubAgentDefinition } from './types.js' +/** Fire a SubagentStart / SubagentStop hook. Best effort — sub-agent + * invocation is mandatory once the parent decides to delegate, so hook + * failures and aborts must never bubble. */ +function emitSubAgentHook( + bus: HookBus | undefined, + event: HookEvent & { name: 'SubagentStart' | 'SubagentStop' }, + signal: AbortSignal | undefined, +): void { + if (!bus?.has(event.name)) return + void bus.emit(event, { signal }).catch((err) => debugLog(`agent.hook-${event.name.toLowerCase()}-error`, String(err))) +} + export interface RunSubAgentArgs { parentState: LoopState parentOptions: AgentOptions @@ -144,6 +158,18 @@ export async function runSubAgent(args: RunSubAgentArgs, parentModel: LanguageMo prompt, }) + // Plugin hook: SubagentStart — fires after the agent definition is + // resolved but before the nested agentLoop runs. Best-effort. + emitSubAgentHook( + parentOptions.hookBus, + { + name: 'SubagentStart', + session: { cwd: process.cwd(), modelId: parentOptions.modelId }, + agent: { name: agentName, description, prompt }, + }, + parentOptions.abortSignal, + ) + const subModel = resolveSubModel(agentDef, parentOptions, parentModel) const subModelId = agentDef.model ? (resolveModelId(agentDef.model) ?? parentOptions.modelId) : parentOptions.modelId @@ -241,6 +267,23 @@ export async function runSubAgent(args: RunSubAgentArgs, parentModel: LanguageMo aborted: false, }) + emitSubAgentHook( + parentOptions.hookBus, + { + name: 'SubagentStop', + session: { cwd: process.cwd(), modelId: parentOptions.modelId }, + agent: { name: agentName, description }, + durationMs, + outcome: 'completed', + tokenUsage: { + inputTokens: finalSubState.tokenUsage.inputTokens, + outputTokens: finalSubState.tokenUsage.outputTokens, + totalTokens: finalSubState.tokenUsage.totalTokens, + }, + }, + parentOptions.abortSignal, + ) + if (turnCount >= agentDef.maxTurns && !finalText) { return { resultText: `[Sub-agent reached max turns (${agentDef.maxTurns}) without finishing. Partial output: ${extractFinalText(finalSubState.messages) || 'none'}]`, @@ -287,6 +330,18 @@ export async function runSubAgent(args: RunSubAgentArgs, parentModel: LanguageMo aborted: true, }) + emitSubAgentHook( + parentOptions.hookBus, + { + name: 'SubagentStop', + session: { cwd: process.cwd(), modelId: parentOptions.modelId }, + agent: { name: agentName, description }, + durationMs, + outcome: 'aborted', + }, + parentOptions.abortSignal, + ) + return { resultText: text, tokenUsage: subState.tokenUsage, @@ -311,6 +366,18 @@ export async function runSubAgent(args: RunSubAgentArgs, parentModel: LanguageMo aborted: false, }) + emitSubAgentHook( + parentOptions.hookBus, + { + name: 'SubagentStop', + session: { cwd: process.cwd(), modelId: parentOptions.modelId }, + agent: { name: agentName, description }, + durationMs, + outcome: 'failed', + }, + parentOptions.abortSignal, + ) + return { resultText: `[Sub-agent failed: ${message}]`, tokenUsage: subState.tokenUsage, diff --git a/packages/core/src/agent/sub-agents/types.ts b/packages/core/src/agent/sub-agents/types.ts index c46570f..1af597a 100644 --- a/packages/core/src/agent/sub-agents/types.ts +++ b/packages/core/src/agent/sub-agents/types.ts @@ -17,7 +17,10 @@ export interface SubAgentDefinition { /** Shell commands to deny (keyword matching). Only relevant when shell is in tools */ shellRestrictions?: string[] /** Where this definition came from */ - source: 'built-in' | 'global' | 'project' + source: 'built-in' | 'user' | 'project' + /** When this sub-agent comes from a plugin contribution, the owning + * plugin's id (`name@marketplace`). */ + pluginId?: string } export interface SubAgentTrace { diff --git a/packages/core/src/agent/tool-execution.ts b/packages/core/src/agent/tool-execution.ts index 25bf8dc..e3064e6 100644 --- a/packages/core/src/agent/tool-execution.ts +++ b/packages/core/src/agent/tool-execution.ts @@ -4,6 +4,7 @@ import path from 'node:path' import type { ModelMessage } from 'ai' +import { aggregatePostToolUse, aggregatePreToolUse } from '../hooks/bus.js' import { classifyDecision } from '../mcp/permissions.js' import { checkPermission } from '../permissions/index.js' import { truncateToolResult } from '../tools/index.js' @@ -226,6 +227,34 @@ interface HandlerCtx { parentModel: LanguageModel } +/** Wrap pushToolResult with a PostToolUse hook emission. Only the two + * "real" success-result call sites use this — error / interrupt / + * permission-denial paths still call pushToolResult directly because + * emitting PostToolUse on a synthetic deny would be confusing for hook + * authors. Bypass handlers (askUser / task / MCP resources) also push + * directly today; lifting them to this helper is a follow-up. */ +async function pushSuccessfulToolResult(ctx: HandlerCtx, output: string, isError: boolean): Promise { + let effectiveOutput = output + if (ctx.options.hookBus?.has('PostToolUse')) { + try { + const decisions = await ctx.options.hookBus.emit( + { + name: 'PostToolUse', + session: { cwd: process.cwd(), modelId: ctx.options.modelId }, + tool: { name: ctx.toolName, args: ctx.input, callId: ctx.toolCallId, output, isError }, + }, + { signal: ctx.options.abortSignal }, + ) + const effect = aggregatePostToolUse(decisions) + if (effect.output !== undefined) effectiveOutput = effect.output + } catch (err) { + if (ctx.options.abortSignal?.aborted) return + debugLog('agent.hook-post-tool-error', String(err)) + } + } + pushToolResult(ctx.state, ctx.callbacks, ctx.toolCallId, ctx.toolName, effectiveOutput, isError) +} + type ToolHandler = (ctx: HandlerCtx) => Promise /** ── askUser ── @@ -487,6 +516,45 @@ async function handleToolCall( parentModel, } + // ── Plugin hook: PreToolUse ── + // Fires before bypass-handler routing and before MCP dispatch so the + // hook sees EVERY tool the model attempts (including askUser, task, + // and MCP tools). A deny becomes a synthetic tool_result the model + // sees, keeping state.messages valid. A modify can rewrite the input + // record (mutated in-place on ctx.input so downstream handlers and + // the loop guard see the post-modification args). + if (ctx.options.hookBus?.has('PreToolUse')) { + try { + const decisions = await ctx.options.hookBus.emit( + { + name: 'PreToolUse', + session: { cwd: process.cwd(), modelId: ctx.options.modelId }, + tool: { name: ctx.toolName, args: ctx.input, callId: ctx.toolCallId }, + }, + { signal: ctx.options.abortSignal }, + ) + const effect = aggregatePreToolUse(decisions) + if (effect.decision === 'deny') { + const reason = effect.reason ?? 'blocked by plugin hook' + pushToolResult( + state, + callbacks, + ctx.toolCallId, + ctx.toolName, + toolErrorString(`Tool denied by plugin hook: ${reason}`), + true, + ) + return + } + if (effect.args && typeof effect.args === 'object' && !Array.isArray(effect.args)) { + ctx.input = effect.args as Record + } + } catch (err) { + if (ctx.options.abortSignal?.aborted) return + debugLog('agent.hook-pre-tool-error', String(err)) + } + } + const bypassHandler = BYPASS_LOOP_GUARD_HANDLERS[ctx.toolName] if (bypassHandler) { await bypassHandler(ctx) @@ -512,7 +580,7 @@ async function handleToolCall( const result = await executeWriteOrShell(ctx) if (result == null) return - pushToolResult(state, callbacks, ctx.toolCallId, ctx.toolName, truncateToolResult(result.output), result.isError) + await pushSuccessfulToolResult(ctx, truncateToolResult(result.output), result.isError) } /** Dispatch an MCP tool call. Sits parallel to the writeFile/edit/shell @@ -596,8 +664,8 @@ async function handleMcpToolCall(ctx: HandlerCtx, deferred: ModelMessage[]): Pro // so Esc immediately cancels in-flight MCP calls. reportProgress(toolCallId, `Calling ${entry.serverName}/${entry.rawName}`) try { - const result = await registry.callTool(toolName, input, options.abortSignal) - pushToolResult(state, callbacks, toolCallId, toolName, truncateToolResult(result.text), result.isError) + const result = await registry.callTool(toolName, ctx.input, options.abortSignal) + await pushSuccessfulToolResult(ctx, truncateToolResult(result.text), result.isError) } catch (err) { if (isAbortError(err, options.abortSignal)) { pushToolResult(state, callbacks, toolCallId, toolName, '[Tool execution interrupted by user]', true) diff --git a/packages/core/src/commands/index.ts b/packages/core/src/commands/index.ts new file mode 100644 index 0000000..963fe1f --- /dev/null +++ b/packages/core/src/commands/index.ts @@ -0,0 +1,6 @@ +// @x-code-cli/core — Commands subsystem public surface +export type { CommandDefinition } from './types.js' +export { loadPluginCommands } from './loader.js' +export type { LoadCommandsOptions } from './loader.js' +export { CommandRegistry, createCommandRegistry, reloadCommandRegistry, expandCommandBody } from './registry.js' +export type { CommandReloadSummary } from './registry.js' diff --git a/packages/core/src/commands/loader.ts b/packages/core/src/commands/loader.ts new file mode 100644 index 0000000..dcc70c5 --- /dev/null +++ b/packages/core/src/commands/loader.ts @@ -0,0 +1,104 @@ +// @x-code-cli/core — File-based command loader +// +// Scans plugin-contributed `commands/` directories for `*.md` files and +// returns CommandDefinitions ready to register in CommandRegistry. +// Mirrors the sub-agents loader's structure — same minimal YAML +// frontmatter parser, same "one bad file logged + skipped, never +// crash the boot" error handling. +import fs from 'node:fs/promises' +import path from 'node:path' + +import type { CommandDefinition } from './types.js' + +/** Minimal YAML frontmatter parser. Same subset used by skills / + * sub-agents loaders — string scalars only, no dependency on + * gray-matter. Folds indented continuation lines into the previous + * line so the multi-line `allowed-tools` form that real Claude Code + * commands use parses without complaint (we ignore the value, but + * the parse mustn't choke). */ +function parseFrontmatter(raw: string): { data: Record; body: string } | null { + const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/) + if (!match) return null + + const yamlBlock = match[1]! + const body = match[2]! + const data: Record = {} + + const folded: string[] = [] + for (const line of yamlBlock.split(/\r?\n/)) { + if (/^\s/.test(line) && line.trim() && folded.length > 0) { + folded[folded.length - 1] += ' ' + line.trim() + } else { + folded.push(line) + } + } + + for (const line of folded) { + const trimmed = line.trim() + if (!trimmed || trimmed.startsWith('#')) continue + const colonIdx = trimmed.indexOf(':') + if (colonIdx < 1) continue + const key = trimmed.slice(0, colonIdx).trim() + let value: string = trimmed.slice(colonIdx + 1).trim() + if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) { + value = value.slice(1, -1) + } + data[key] = value + } + + return { data, body } +} + +async function loadCommandsFromDir(dir: string, pluginId: string, pluginRoot: string): Promise { + const out: CommandDefinition[] = [] + let entries: string[] + try { + entries = await fs.readdir(dir) + } catch { + return out + } + + for (const entry of entries) { + if (!entry.endsWith('.md')) continue + const filePath = path.join(dir, entry) + const name = entry.slice(0, -3) // strip .md + + try { + const raw = await fs.readFile(filePath, 'utf-8') + const parsed = parseFrontmatter(raw) + // Commands without frontmatter are still valid — the whole file + // becomes the body. Real Claude Code commands always have + // frontmatter, but be permissive. + const description = parsed?.data.description as string | undefined + const body = (parsed ? parsed.body : raw).trim() + + out.push({ + name, + description, + body, + source: 'plugin', + pluginId, + pluginRoot, + }) + } catch (err) { + console.error(`[commands] Skipping ${filePath}: ${err instanceof Error ? err.message : String(err)}`) + } + } + return out +} + +export interface LoadCommandsOptions { + /** Plugin-contributed command directories, each tagged with the + * owning plugin's id and root dir. Order determines registry + * insertion order (last-wins on name conflict). */ + extraDirs?: ReadonlyArray<{ dir: string; pluginId: string; pluginRoot: string }> +} + +export async function loadPluginCommands(opts: LoadCommandsOptions = {}): Promise { + const extras = opts.extraDirs ?? [] + const out: CommandDefinition[] = [] + for (const { dir, pluginId, pluginRoot } of extras) { + out.push(...(await loadCommandsFromDir(dir, pluginId, pluginRoot))) + } + return out +} diff --git a/packages/core/src/commands/registry.ts b/packages/core/src/commands/registry.ts new file mode 100644 index 0000000..2f6adc6 --- /dev/null +++ b/packages/core/src/commands/registry.ts @@ -0,0 +1,117 @@ +// @x-code-cli/core — Slash command registry +// +// Built once at CLI startup from plugin-contributed command files. +// Lookups happen from the App.tsx default slash-dispatcher when a typed +// `/` doesn't match any built-in command or skill. Same +// startup-frozen / byte-stability model as SkillRegistry. +import fs from 'node:fs' + +import { pluginDataDir } from '../plugins/paths.js' +import { type LoadCommandsOptions, loadPluginCommands } from './loader.js' +import type { CommandDefinition } from './types.js' + +/** Diff returned by reload — drives the /plugin refresh message. */ +export interface CommandReloadSummary { + added: string[] + removed: string[] + changed: string[] + unchanged: string[] +} + +export class CommandRegistry { + private byName: Map + + constructor(commands: ReadonlyArray = []) { + this.byName = new Map() + // Last-write wins on name collision (consistent with how + // SkillRegistry merges user → plugin → project). + for (const c of commands) this.byName.set(c.name, c) + } + + get(name: string): CommandDefinition | undefined { + return this.byName.get(name) + } + + list(): CommandDefinition[] { + return [...this.byName.values()] + } + + names(): string[] { + return [...this.byName.keys()] + } + + /** Replace the in-memory command set with a fresh load. Used by + * /plugin refresh — keeps registry identity stable so captured + * `options.commandRegistry` references stay valid. */ + reload(commands: ReadonlyArray): CommandReloadSummary { + const previous = this.byName + const next = new Map() + for (const c of commands) next.set(c.name, c) + const summary: CommandReloadSummary = { added: [], removed: [], changed: [], unchanged: [] } + for (const [name, cmd] of next) { + const prev = previous.get(name) + if (!prev) summary.added.push(name) + else if (prev.body !== cmd.body || prev.pluginId !== cmd.pluginId || prev.pluginRoot !== cmd.pluginRoot) + summary.changed.push(name) + else summary.unchanged.push(name) + } + for (const name of previous.keys()) { + if (!next.has(name)) summary.removed.push(name) + } + this.byName = next + return summary + } +} + +export async function createCommandRegistry(opts: LoadCommandsOptions = {}): Promise { + const commands = await loadPluginCommands(opts) + return new CommandRegistry(commands) +} + +/** Re-scan plugin command dirs and rebuild the registry in place. + * Caller is responsible for passing the latest plugin-derived extraDirs. */ +export async function reloadCommandRegistry( + registry: CommandRegistry, + opts: LoadCommandsOptions = {}, +): Promise { + const commands = await loadPluginCommands(opts) + return registry.reload(commands) +} + +/** Apply Claude Code-style placeholder substitutions to a command + * body before sending it as a model prompt. Recognised placeholders + * match real Claude Code plugin command files (verified against + * `anthropics/claude-code/plugins//commands/.md`): + * + * $ARGUMENTS / ${ARGUMENTS} — text the user typed after the + * command name (`/code-review 123` + * → `123`). Empty string when no + * argument was given. + * ${CLAUDE_PLUGIN_ROOT} — absolute path to the owning + * plugin's installed dir (versioned; + * wiped on reinstall). + * ${CLAUDE_PLUGIN_DATA} — persistent per-plugin data dir + * (`~/.x-code/plugins/data//`) + * that survives reinstalls and + * upgrades. Auto-created on first + * substitution. Left verbatim when + * the command has no plugin context. */ +export function expandCommandBody(cmd: CommandDefinition, args: string): string { + const root = cmd.pluginRoot ?? '' + let dataDir = '' + if (cmd.pluginId && cmd.body.includes('${CLAUDE_PLUGIN_DATA}')) { + dataDir = pluginDataDir(cmd.pluginId) + try { + fs.mkdirSync(dataDir, { recursive: true }) + } catch { + // mkdir failure leaves dataDir set to the path string anyway — + // the user's shell script will surface a sensible error if it + // actually tries to write there. + } + } + return cmd.body + .replaceAll('${CLAUDE_PLUGIN_ROOT}', root) + .replaceAll('${CLAUDE_PLUGIN_DATA}', dataDir) + .replaceAll('${ARGUMENTS}', args) + .replaceAll('$ARGUMENTS', args) +} diff --git a/packages/core/src/commands/types.ts b/packages/core/src/commands/types.ts new file mode 100644 index 0000000..f155ff0 --- /dev/null +++ b/packages/core/src/commands/types.ts @@ -0,0 +1,47 @@ +// @x-code-cli/core — File-based slash command types +// +// A "command" is a markdown file shipped by a plugin (or, in future, +// authored directly under ~/.x-code/commands/) that turns into a slash +// command at startup. Real Claude Code plugins ship them as +// `commands/.md` next to their plugin.json — `code-review.md` +// inside `code-review` plugin's `commands/` registers as `/code-review`. +// +// File format (matches Claude Code spec verified against +// anthropics/claude-code real plugin contents): +// +// --- +// description: Code review a pull request +// allowed-tools: Bash(gh pr view:*), … # ignored by us today +// --- +// +// +// +// Substitutions applied to the body before sending to the model: +// $ARGUMENTS — text typed after the command name +// ${ARGUMENTS} — same, brace form +// ${CLAUDE_PLUGIN_ROOT} — absolute path to the plugin root +// (so command bodies can reference +// bundled scripts via shell) + +export interface CommandDefinition { + /** Command invocation name without the leading slash. Derived from + * the filename (`code-review.md` → `code-review`). */ + name: string + /** Short one-line summary from the frontmatter `description` field — + * used by `/help` and `/plugin info` to label the command. */ + description?: string + /** The prompt template (everything after the frontmatter), trimmed. */ + body: string + /** Where this command came from. `'plugin'` is the only kind today + * since we don't (yet) scan `~/.x-code/commands/` for user-authored + * ones. Reserved for symmetry with SkillDefinition. */ + source: 'plugin' + /** When source === 'plugin', the owning plugin's id + * (`name@marketplace`). Used by `/plugin info` and to set + * `${CLAUDE_PLUGIN_ROOT}` correctly. */ + pluginId?: string + /** Absolute path to the plugin's root dir. Substituted in for + * `${CLAUDE_PLUGIN_ROOT}` in the body — so command bodies that + * reference bundled scripts can resolve them correctly. */ + pluginRoot?: string +} diff --git a/packages/core/src/hooks/bus.ts b/packages/core/src/hooks/bus.ts new file mode 100644 index 0000000..1830ea0 --- /dev/null +++ b/packages/core/src/hooks/bus.ts @@ -0,0 +1,192 @@ +// @x-code-cli/core — Hook event bus +// +// Thin orchestration layer over [[HookRegistry]]. The agent loop, +// tool-execution, compression, and sub-agent runner call `bus.emit(event)` +// at ten lifecycle points; the bus filters hooks by matcher (PreToolUse / +// PostToolUse only), runs them, and returns the aggregated decisions. +// +// Serial vs parallel: +// +// Decision events (UserPromptSubmit / PreToolUse / PostToolUse) run +// serially. A `deny` short-circuits the remaining hooks — the agent +// stops at the first stop. Order is registration order, so plugin +// authors get deterministic behaviour. +// +// Fire-and-forget events (SessionStart / PreCompact / PostCompact / +// SubagentStart / SubagentStop / TurnComplete / SessionEnd) run in +// parallel — they have no decisions and no ordering concerns. +// +// The bus catches per-hook errors and degrades to `allow` so one +// broken hook never blocks the loop. The executor already does the +// "non-zero exit / timeout → allow" handling — this layer adds the +// matcher-regex error guard. +import { debugLog } from '../utils.js' +import { type ExecuteHookOptions, executeHook } from './executor.js' +import { type HookRegistry, emptyHookRegistry } from './registry.js' +import type { HookDecision, HookEvent, RegisteredHook } from './types.js' + +export interface EmitOptions extends ExecuteHookOptions { + /** Force parallel execution. Default is serial for decision events + * and parallel for fire-and-forget. Caller almost never overrides. */ + parallel?: boolean +} + +export class HookBus { + // Mutable so /plugin refresh can swap in a fresh registry without + // forcing callers to re-capture the bus reference. New incoming + // event emissions then see the new hooks; any in-flight executeHook + // calls finish against the old registry (deliberate — finishing the + // hook is cheaper than coordinating shutdown). + constructor(private registry: HookRegistry) {} + + has(event: HookEvent['name']): boolean { + return this.registry.has(event) + } + + /** Replace the internal registry. Used by /plugin refresh after a + * rescan to pick up newly-installed / removed plugin hooks. */ + replaceRegistry(registry: HookRegistry): void { + this.registry = registry + } + + /** Emit an event. Returns the per-hook decisions in run order — empty + * when no hooks matched. Callers typically only inspect the result + * for the three DecisionEvents; for the others they just await + * completion for side effects. */ + async emit(event: HookEvent, opts: EmitOptions = {}): Promise { + const hooks = this.registry.get(event.name) + if (hooks.length === 0) return [] + + const applicable = hooks.filter((h) => matches(h, event)) + if (applicable.length === 0) return [] + + const isDecisionEvent = + event.name === 'UserPromptSubmit' || event.name === 'PreToolUse' || event.name === 'PostToolUse' + const parallel = opts.parallel ?? !isDecisionEvent + + if (parallel) { + // For fire-and-forget events we still await the results so the + // caller's await-for-completion semantics work; we just don't + // serialise execution. Individual hook failures don't fail the + // batch (executor returns `allow` on failure). + const settled = await Promise.allSettled(applicable.map((h) => executeHook(h, event, opts))) + const out: HookDecision[] = [] + for (const r of settled) { + if (r.status === 'fulfilled') out.push(r.value) + else { + if (opts.signal?.aborted) throw r.reason + debugLog('hooks.bus-error', `${event.name}: ${String(r.reason)}`) + out.push({ decision: 'allow' }) + } + } + return out + } + + // Serial: first `deny` halts the rest. modify decisions stack on + // the next hook's input via the caller (we just collect them). + const decisions: HookDecision[] = [] + for (const h of applicable) { + try { + const d = await executeHook(h, event, opts) + decisions.push(d) + if (d.decision === 'deny') break + } catch (err) { + if (opts.signal?.aborted) throw err + debugLog('hooks.bus-error', `${h.pluginId} ${event.name}: ${String(err)}`) + decisions.push({ decision: 'allow' }) + } + } + return decisions + } +} + +/** A bus with no registered hooks. The CLI passes this when plugins + * are disabled (`--no-plugins`) so the agent loop's emit-sites don't + * need null-checks. */ +export function emptyHookBus(): HookBus { + return new HookBus(emptyHookRegistry()) +} + +function matches(hook: RegisteredHook, event: HookEvent): boolean { + if (event.name !== 'PreToolUse' && event.name !== 'PostToolUse') return true + if (!hook.entry.matcher) return true + try { + return new RegExp(hook.entry.matcher).test(event.tool.name) + } catch (err) { + // Bad regex shouldn't silently disable the hook — degrade to + // "matches every tool" but log so support can spot the bad pattern. + debugLog('hooks.matcher-invalid', `${hook.pluginId}: ${String(err)}`) + return true + } +} + +// ── Decision aggregation helpers used by the agent loop emit-sites ── + +/** Collapse a list of PreToolUse decisions into a single effective + * outcome. Order matters: deny short-circuits earlier in `emit`, so + * if we see a `deny` here it's the final word. Modifications stack — + * the last `modify` with `args` wins (later plugins refine earlier + * plugins). */ +export interface PreToolEffect { + decision: 'allow' | 'deny' + reason?: string + /** Modified args, or undefined to use the original. */ + args?: unknown + /** Extra context to inject (rare for PreToolUse; supported for symmetry). */ + context?: string +} + +export function aggregatePreToolUse(decisions: ReadonlyArray): PreToolEffect { + let args: unknown + let context: string | undefined + for (const d of decisions) { + if (d.decision === 'deny') return { decision: 'deny', reason: d.reason } + if (d.decision === 'modify') { + if (d.args !== undefined) args = d.args + if (d.context) context = d.context + } else if (d.decision === 'allow' && d.context) { + context = d.context + } + } + return { decision: 'allow', args, context } +} + +export interface PostToolEffect { + /** Replacement output, or undefined to keep original. */ + output?: string + context?: string +} + +export function aggregatePostToolUse(decisions: ReadonlyArray): PostToolEffect { + let output: string | undefined + let context: string | undefined + for (const d of decisions) { + if (d.decision === 'modify') { + if (typeof d.output === 'string') output = d.output + if (d.context) context = d.context + } else if (d.decision === 'allow' && d.context) { + context = d.context + } + } + return { output, context } +} + +export interface UserPromptEffect { + decision: 'allow' | 'deny' + reason?: string + /** Concatenated context from every hook, ready to prepend to the user + * message. Empty string when no hook injected anything. */ + context: string +} + +export function aggregateUserPromptSubmit(decisions: ReadonlyArray): UserPromptEffect { + const contexts: string[] = [] + for (const d of decisions) { + if (d.decision === 'deny') return { decision: 'deny', reason: d.reason, context: '' } + // `context` is present on both 'allow' and 'modify' branches; the + // narrowing above eliminates 'deny', so this is safe. + if (d.decision === 'allow' && d.context) contexts.push(d.context) + else if (d.decision === 'modify' && d.context) contexts.push(d.context) + } + return { decision: 'allow', context: contexts.join('\n\n') } +} diff --git a/packages/core/src/hooks/config-schema.ts b/packages/core/src/hooks/config-schema.ts new file mode 100644 index 0000000..a36a95b --- /dev/null +++ b/packages/core/src/hooks/config-schema.ts @@ -0,0 +1,84 @@ +// @x-code-cli/core — hooks.json zod schema +// +// Validates a `HookConfig` whether it came from a hooks.json file on +// disk or an inline manifest object. Same schema both paths — keeps the +// failure mode identical so plugin authors don't get different errors +// depending on which form they used. +// +// Bad regex in `matcher` is NOT a schema error — it'd be inconvenient +// to require authors to author / test their regex against zod's strict +// mode. The bus catches RegExp construction errors at emit time and +// degrades to "matches every tool" (logged for support). +import { z } from 'zod' + +import type { HookConfig } from './types.js' + +const hookEntrySchema = z.object({ + matcher: z.string().optional(), + command: z.string().min(1), + // Platform-specific overrides. Optional; missing on a platform falls + // back to `command`. We deliberately don't enforce that at least one + // of them is set — the base command is always required. + commandWindows: z.string().min(1).optional(), + commandDarwin: z.string().min(1).optional(), + commandLinux: z.string().min(1).optional(), + timeout: z.number().int().positive().max(30_000).optional(), + description: z.string().optional(), + failurePolicy: z.enum(['allow', 'block']).optional(), +}) + +export const hookConfigSchema = z + .object({ + SessionStart: z.array(hookEntrySchema).optional(), + UserPromptSubmit: z.array(hookEntrySchema).optional(), + PreToolUse: z.array(hookEntrySchema).optional(), + PostToolUse: z.array(hookEntrySchema).optional(), + PreCompact: z.array(hookEntrySchema).optional(), + PostCompact: z.array(hookEntrySchema).optional(), + SubagentStart: z.array(hookEntrySchema).optional(), + SubagentStop: z.array(hookEntrySchema).optional(), + TurnComplete: z.array(hookEntrySchema).optional(), + SessionEnd: z.array(hookEntrySchema).optional(), + }) + // Unknown keys are tolerated for forward compat (future event names). + .passthrough() + +export class HookConfigParseError extends Error { + constructor( + message: string, + public readonly sourceLabel: string, + ) { + super(message) + this.name = 'HookConfigParseError' + } +} + +/** Validate an already-parsed-object form. Used for inline manifest + * configs and for the body of hooks.json after JSON.parse. */ +export function parseHookConfig(raw: unknown, sourceLabel: string): HookConfig { + const result = hookConfigSchema.safeParse(raw) + if (!result.success) { + const issues = result.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ') + throw new HookConfigParseError(`invalid hooks config — ${issues}`, sourceLabel) + } + // Strip unknown future keys at the type boundary — passthrough kept + // them on the runtime object, but our HookConfig type only knows the + // ten events. + const known: HookConfig = {} + for (const k of [ + 'SessionStart', + 'UserPromptSubmit', + 'PreToolUse', + 'PostToolUse', + 'PreCompact', + 'PostCompact', + 'SubagentStart', + 'SubagentStop', + 'TurnComplete', + 'SessionEnd', + ] as const) { + const arr = (result.data as Record)[k] + if (Array.isArray(arr)) known[k] = arr as HookConfig[typeof k] + } + return known +} diff --git a/packages/core/src/hooks/executor.ts b/packages/core/src/hooks/executor.ts new file mode 100644 index 0000000..3026dec --- /dev/null +++ b/packages/core/src/hooks/executor.ts @@ -0,0 +1,198 @@ +// @x-code-cli/core — Hook command executor +// +// Spawns a hook's shell command, writes the event JSON on stdin, reads +// the decision JSON from stdout. The whole protocol is line-oriented: +// one JSON object in, one JSON object out (or empty stdout = default +// allow). Anything else on stdout is ignored — common pattern for hooks +// that just want to log to stderr without influencing the agent. +// +// Failure handling is deliberately permissive (default `failurePolicy: +// 'allow'`): a broken hook must never wedge the agent loop. Non-zero +// exit, timeout, or crash all degrade to `allow` and log a debug +// breadcrumb. The `block` policy is opt-in and reserved for hooks the +// plugin author has explicitly designed as gating hooks. +// +// AbortSignal propagation: passed to execa's `cancelSignal` so the +// child process is SIGKILL'd when the user hits Esc mid-hook. Same +// machinery the shell tool uses. +import { execa } from 'execa' + +import { getPluginUserConfigEnv } from '../plugins/user-config.js' +import { debugLog } from '../utils.js' +import type { HookConfigEntry, HookDecision, HookEvent, RegisteredHook } from './types.js' +import { buildVariableContext, expandVariables } from './variables.js' + +/** Return the command appropriate for the current OS. Plugin authors + * set `command` as a portable default and may add `commandWindows` / + * `commandDarwin` / `commandLinux` to handle per-OS differences (e.g. + * shebang line, executable name, quoting). Unknown platforms (freebsd, + * sunos, aix) fall through to the base. */ +function pickPlatformCommand(entry: HookConfigEntry): string { + switch (process.platform) { + case 'win32': + return entry.commandWindows ?? entry.command + case 'darwin': + return entry.commandDarwin ?? entry.command + case 'linux': + return entry.commandLinux ?? entry.command + default: + return entry.command + } +} + +const DEFAULT_TIMEOUT_MS = 5_000 +const MAX_TIMEOUT_MS = 30_000 + +export interface ExecuteHookOptions { + /** Cancels the hook child process when fired. Agent loop's abort + * signal flows through here so Esc during a slow hook kills it + * promptly. */ + signal?: AbortSignal + /** Override the default 5s timeout. Per-hook `entry.timeout` still + * wins when both are set. Both are capped at 30s. */ + defaultTimeoutMs?: number +} + +/** Run one hook against one event. Returns the parsed decision (default + * allow on anything unexpected). Never throws unless the caller's + * AbortSignal fires — abort is the one error worth bubbling because + * the caller's loop is already shutting down. */ +export async function executeHook( + hook: RegisteredHook, + event: HookEvent, + opts: ExecuteHookOptions = {}, +): Promise { + const timeoutMs = Math.min(hook.entry.timeout ?? opts.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS) + + const vars = buildVariableContext({ + pluginDir: hook.pluginDir, + cwd: event.session.cwd, + pluginId: hook.pluginId, + }) + const expandedCommand = expandVariables(pickPlatformCommand(hook.entry), vars) + const stdinPayload = JSON.stringify(buildStdinPayload(hook, event)) + + // Merge the owning plugin's userConfig values into the hook's env. + // Hook scripts that need an API key declared in the manifest read it as + // `process.env[KEY]` without writing any glue — `${env:KEY}` substitution + // in the command string also resolves against this merged env. We fail + // silent if the read errors (no userConfig set yet ⇒ empty map). + let pluginEnv: Record = {} + try { + pluginEnv = await getPluginUserConfigEnv(hook.pluginId) + } catch (err) { + debugLog('hooks.user-config-read-failed', `${hook.pluginId}: ${String(err)}`) + } + + try { + const result = await execa(expandedCommand, [], { + shell: true, + input: stdinPayload, + timeout: timeoutMs, + cancelSignal: opts.signal, + stdio: 'pipe', + reject: false, // Non-zero exits handled below explicitly, not as throws. + cwd: event.session.cwd, + env: { ...process.env, ...pluginEnv }, + }) + + if (opts.signal?.aborted) { + // Aborted mid-execution. Caller's loop is winding down — surface + // by throwing so the bus stops cascading further hooks. + throw new Error('aborted') + } + + if (result.timedOut) { + debugLog('hooks.exec-timeout', `${hook.pluginId} ${event.name}: timed out after ${timeoutMs}ms`) + return failurePolicyDecision(hook, `hook timed out after ${timeoutMs}ms`) + } + if (typeof result.exitCode === 'number' && result.exitCode !== 0) { + const stderrTail = (result.stderr ?? '').toString().slice(0, 200) + debugLog('hooks.exec-nonzero', `${hook.pluginId} ${event.name}: exit ${result.exitCode} stderr=${stderrTail}`) + return failurePolicyDecision(hook, `hook exited ${result.exitCode}`) + } + + return parseDecision(result.stdout ?? '', hook, event) + } catch (err) { + if (opts.signal?.aborted) throw err + debugLog('hooks.exec-error', `${hook.pluginId} ${event.name}: ${String(err)}`) + return failurePolicyDecision(hook, `hook crashed: ${err instanceof Error ? err.message : String(err)}`) + } +} + +function failurePolicyDecision(hook: RegisteredHook, reason: string): HookDecision { + if (hook.entry.failurePolicy === 'block') return { decision: 'deny', reason } + return { decision: 'allow' } +} + +/** Build the JSON object sent to the hook over stdin. Event-specific + * fields are flattened in at the top level (matches Claude Code's + * hook protocol shape). */ +function buildStdinPayload(hook: RegisteredHook, event: HookEvent): Record { + const base: Record = { + event: event.name, + session: event.session, + plugin: { id: hook.pluginId, dir: hook.pluginDir }, + } + switch (event.name) { + case 'UserPromptSubmit': + base.prompt = event.prompt + break + case 'PreToolUse': + base.tool = event.tool + break + case 'PostToolUse': + base.tool = event.tool + break + case 'PreCompact': + base.trigger = event.trigger + base.messageCount = event.messageCount + base.tokenEstimate = event.tokenEstimate + break + case 'PostCompact': + base.trigger = event.trigger + base.messageCount = event.messageCount + base.summary = event.summary + break + case 'SubagentStart': + base.agent = event.agent + break + case 'SubagentStop': + base.agent = event.agent + base.durationMs = event.durationMs + base.outcome = event.outcome + if (event.tokenUsage) base.tokenUsage = event.tokenUsage + break + case 'TurnComplete': + base.turn = event.turn + if (event.tokenUsage) base.tokenUsage = event.tokenUsage + break + // SessionStart / SessionEnd have no extra fields beyond session/plugin. + } + return base +} + +function parseDecision(stdout: string, hook: RegisteredHook, event: HookEvent): HookDecision { + const trimmed = (stdout ?? '').toString().trim() + if (!trimmed) return { decision: 'allow' } + + try { + const parsed = JSON.parse(trimmed) as unknown + if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) { + const obj = parsed as Record + const d = obj.decision + if (d === 'allow' || d === 'deny' || d === 'modify') { + return obj as HookDecision + } + } + } catch { + // Not JSON — many hooks intend stdout for human eyes (logs). Treat + // as default allow but breadcrumb in case the user expected it to + // influence the agent. + debugLog( + 'hooks.decision-not-json', + `${hook.pluginId} ${event.name}: ignoring non-JSON stdout: ${trimmed.slice(0, 200)}`, + ) + } + return { decision: 'allow' } +} diff --git a/packages/core/src/hooks/index.ts b/packages/core/src/hooks/index.ts new file mode 100644 index 0000000..17a5916 --- /dev/null +++ b/packages/core/src/hooks/index.ts @@ -0,0 +1,19 @@ +// @x-code-cli/core — Hooks subsystem public surface +export type { + DecisionEvent, + HookConfig, + HookConfigEntry, + HookDecision, + HookEvent, + HookEventName, + RegisteredHook, + SessionContext, +} from './types.js' +export { hookConfigSchema, parseHookConfig, HookConfigParseError } from './config-schema.js' +export { buildVariableContext, expandVariables } from './variables.js' +export type { VariableContext } from './variables.js' +export { executeHook } from './executor.js' +export type { ExecuteHookOptions } from './executor.js' +export { HookRegistry, buildHookRegistry, emptyHookRegistry } from './registry.js' +export { HookBus, emptyHookBus, aggregatePreToolUse, aggregatePostToolUse, aggregateUserPromptSubmit } from './bus.js' +export type { EmitOptions, PreToolEffect, PostToolEffect, UserPromptEffect } from './bus.js' diff --git a/packages/core/src/hooks/registry.ts b/packages/core/src/hooks/registry.ts new file mode 100644 index 0000000..67dd0d6 --- /dev/null +++ b/packages/core/src/hooks/registry.ts @@ -0,0 +1,65 @@ +// @x-code-cli/core — Hook registry +// +// In-memory map from event name → ordered list of `RegisteredHook`s. +// Built once at CLI startup by [[buildHookRegistry]] and held by the +// HookBus for the session. Same byte-stability constraint as the rest +// of the plugin pipeline: hooks must not change between turns (a hook +// list change should go through `/plugin refresh` + systemPromptCache +// invalidation, even though hooks themselves don't appear in the +// prompt — keeping the rule uniform avoids special cases). +import type { HookConfig, HookEventName, RegisteredHook } from './types.js' + +export class HookRegistry { + private byEvent: Map + + constructor(hooks: ReadonlyArray = []) { + this.byEvent = new Map() + for (const h of hooks) { + const list = this.byEvent.get(h.event) ?? [] + list.push(h) + this.byEvent.set(h.event, list) + } + } + + /** Hooks bound to a given event, in registration order. */ + get(event: HookEventName): readonly RegisteredHook[] { + return this.byEvent.get(event) ?? [] + } + + /** Cheap check the bus uses to skip event-payload construction when + * no hook is listening — every emit-site is in a hot path. */ + has(event: HookEventName): boolean { + return (this.byEvent.get(event)?.length ?? 0) > 0 + } + + /** Every registered hook. Used by `/plugin doctor` to list what's + * active alongside which plugin contributed it. */ + list(): readonly RegisteredHook[] { + const all: RegisteredHook[] = [] + for (const arr of this.byEvent.values()) all.push(...arr) + return all + } +} + +/** Build a registry from per-plugin hook configs. Iteration order of + * the input array determines emit order — the caller (integration.ts) + * is responsible for handing us plugins in a stable order. */ +export function buildHookRegistry( + pluginHooks: ReadonlyArray<{ pluginId: string; pluginDir: string; config: HookConfig }>, +): HookRegistry { + const all: RegisteredHook[] = [] + for (const { pluginId, pluginDir, config } of pluginHooks) { + for (const eventName of Object.keys(config) as HookEventName[]) { + const entries = config[eventName] + if (!entries) continue + for (const entry of entries) { + all.push({ pluginId, pluginDir, event: eventName, entry }) + } + } + } + return new HookRegistry(all) +} + +export function emptyHookRegistry(): HookRegistry { + return new HookRegistry([]) +} diff --git a/packages/core/src/hooks/types.ts b/packages/core/src/hooks/types.ts new file mode 100644 index 0000000..e4ebbf1 --- /dev/null +++ b/packages/core/src/hooks/types.ts @@ -0,0 +1,179 @@ +// @x-code-cli/core — Hooks subsystem types +// +// A hook is a shell command a plugin registers against one of six agent +// lifecycle events. The CLI emits an event payload to the hook on stdin +// as one JSON line; the hook may reply on stdout with a one-line JSON +// `HookDecision` to influence what the agent does next (allow / deny / +// modify args / inject context). +// +// Why shell commands and not a programmatic SDK: lowest barrier to entry +// for plugin authors, matches the format users already see in Claude +// Code, and keeps the surface area small (no plugin code runs inside +// our process). See [[plugin-marketplace-design]] §8 for the full +// rationale. +// +// Why ten events: enough to cover the high-value lifecycle integrations +// (context injection, tool gating, sub-agent audit, compaction +// instrumentation, completion notifications) without exposing every +// internal seam we may want to refactor. Adding events later is cheap; +// removing them is a breaking change. PreCompact / PostCompact and +// SubagentStart / SubagentStop were added in round 2 to match the +// Claude/Codex shape — plugins that want to log every sub-agent +// invocation or persist state before compaction wipes it had no other +// hook to attach to. + +export type HookEventName = + | 'SessionStart' + | 'UserPromptSubmit' + | 'PreToolUse' + | 'PostToolUse' + | 'PreCompact' + | 'PostCompact' + | 'SubagentStart' + | 'SubagentStop' + | 'TurnComplete' + | 'SessionEnd' + +/** Subset of events that emit a decision the agent acts on. Other events + * are fire-and-forget — hooks may run side effects (logging, + * notifications) but the agent ignores their stdout. */ +export type DecisionEvent = 'UserPromptSubmit' | 'PreToolUse' | 'PostToolUse' + +/** One hook entry as it appears in hooks.json. */ +export interface HookConfigEntry { + /** Optional regex matching tool name. Only meaningful for PreToolUse / + * PostToolUse — ignored for other events. A missing matcher means + * "every tool". */ + matcher?: string + /** Shell command to run on the current platform when no platform-specific + * override below is set. Supports `${pluginDir}` / `${pluginDataDir}` / + * `${cwd}` / `${homedir}` / `${env:NAME}` / `${sep}` variable expansion + * (see [[variables]]). + * + * We require this even when the platform overrides are set so plugin + * authors can't accidentally ship a plugin that runs on *only* one OS + * — the base command is the safety net for any platform the author + * didn't explicitly think about. */ + command: string + /** Platform-specific override commands. When set, the matching one + * replaces `command` on that OS. Keys match `process.platform` + * values; unknown platforms (freebsd / sunos / aix) fall through to + * the base `command`. */ + commandWindows?: string + commandDarwin?: string + commandLinux?: string + /** Per-hook timeout in ms (default 5000, capped at 30000). */ + timeout?: number + description?: string + /** What to do when the hook exits non-zero or crashes: + * + * 'allow' (default) — log warning, treat as if the hook said allow + * 'block' — treat as deny (only meaningful for DecisionEvents) + * + * The default is permissive on purpose: a broken hook must not be + * able to wedge the agent loop indefinitely. */ + failurePolicy?: 'allow' | 'block' +} + +/** A whole hooks.json file. Each event name maps to an ordered array of + * entries — earlier entries run first, and for decision events a deny + * short-circuits the rest. */ +export type HookConfig = Partial> + +/** Session-level context attached to every event payload. */ +export interface SessionContext { + cwd: string + modelId: string + /** Optional — when the CLI assigns a session id we pass it through so + * hooks can correlate events. */ + sessionId?: string +} + +/** Discriminated union of every event payload shape. The `name` field + * doubles as the tag. The CLI builds these and hands them to + * [[HookBus.emit]] — the executor serialises them as JSON for stdin. */ +export type HookEvent = + | { name: 'SessionStart'; session: SessionContext } + | { name: 'UserPromptSubmit'; session: SessionContext; prompt: string } + | { + name: 'PreToolUse' + session: SessionContext + tool: { name: string; args: unknown; callId: string } + } + | { + name: 'PostToolUse' + session: SessionContext + tool: { name: string; args: unknown; callId: string; output: string; isError: boolean } + } + | { + name: 'PreCompact' + session: SessionContext + /** Why compaction is about to run — useful for hooks that want to + * decide whether to checkpoint state or skip. */ + trigger: 'proactive' | 'reactive' + /** Approximate message count and token count before compaction. */ + messageCount: number + tokenEstimate: number + } + | { + name: 'PostCompact' + session: SessionContext + trigger: 'proactive' | 'reactive' + /** Message count after compaction — the delta from PreCompact's + * messageCount tells the hook how much was reclaimed. */ + messageCount: number + /** Empty string when the path was a light-compact (no LLM summary + * was written). */ + summary: string + } + | { + name: 'SubagentStart' + session: SessionContext + agent: { + /** The sub-agent's registered name (e.g. `code-reviewer`). */ + name: string + /** The parent agent's one-line task description. */ + description: string + /** The full prompt the parent agent sent to the sub-agent. */ + prompt: string + } + } + | { + name: 'SubagentStop' + session: SessionContext + agent: { + name: string + description: string + } + /** Wall-clock duration of the sub-agent run. */ + durationMs: number + /** How the sub-agent finished. `aborted` includes Esc cancellation + * and reaching the per-agent maxTurns cap without finalising. */ + outcome: 'completed' | 'aborted' | 'failed' + tokenUsage?: { inputTokens: number; outputTokens: number; totalTokens: number } + } + | { + name: 'TurnComplete' + session: SessionContext + turn: number + tokenUsage?: { inputTokens: number; outputTokens: number; totalTokens: number } + } + | { name: 'SessionEnd'; session: SessionContext } + +/** What a hook can ask the agent to do via its stdout JSON. */ +export type HookDecision = + | { decision: 'allow'; context?: string } + | { decision: 'deny'; reason?: string } + | { decision: 'modify'; args?: unknown; output?: string; context?: string } + +/** A hook ready to execute — paired with its owning plugin's identity + * and rootDir so variable expansion can resolve `${pluginDir}`. Built + * by [[buildHookRegistry]] at startup, immutable for the session. */ +export interface RegisteredHook { + pluginId: string + /** Absolute path to the plugin's root dir — substituted into the + * hook command via `${pluginDir}`. */ + pluginDir: string + event: HookEventName + entry: HookConfigEntry +} diff --git a/packages/core/src/hooks/variables.ts b/packages/core/src/hooks/variables.ts new file mode 100644 index 0000000..94e0949 --- /dev/null +++ b/packages/core/src/hooks/variables.ts @@ -0,0 +1,90 @@ +// @x-code-cli/core — Hook command variable expansion +// +// Substitutes `${name}` and `${env:NAME}` patterns inside a hook command +// string. Unknown variables are left as the literal `${name}` so a typo +// surfaces in the resulting shell command's error message rather than +// silently expanding to an empty string (which would produce confusing +// "command not found" errors that don't point at the variable). +// +// Supported variables (cf. [[plugin-marketplace-design]] §8.4): +// +// ${pluginDir} absolute path to the owning plugin's installed dir +// (versioned cache dir; wiped on reinstall / upgrade) +// ${pluginDataDir} absolute path to the plugin's persistent data dir +// (~/.x-code/plugins/data//) — +// survives uninstall+reinstall and version upgrades. +// Created on demand by the caller before expansion; +// this module just substitutes the string. +// ${cwd} current working directory +// ${homedir} user home dir +// ${sep} OS-specific path separator (`\` Windows, `/` elsewhere) +// ${env:NAME} process env var `NAME` (empty string when unset) +import fs from 'node:fs' +import os from 'node:os' +import path from 'node:path' + +import { pluginDataDir as pluginDataDirPath } from '../plugins/paths.js' + +export interface VariableContext { + pluginDir: string + /** Persistent per-plugin data directory. Pre-created by + * [[buildVariableContext]] when a `pluginId` is supplied. */ + pluginDataDir?: string + cwd: string + homedir?: string + sep?: string +} + +/** Default variables derived from the current process + caller context. + * Pass `pluginId` to enable `${pluginDataDir}` — we'll resolve the + * per-plugin data dir path and `mkdir -p` it so the plugin can write + * there immediately. mkdirSync on an existing dir is a cheap no-op. */ +export function buildVariableContext(input: { pluginDir: string; cwd: string; pluginId?: string }): VariableContext { + let dataDir: string | undefined + if (input.pluginId) { + dataDir = pluginDataDirPath(input.pluginId) + try { + fs.mkdirSync(dataDir, { recursive: true }) + } catch { + // mkdir failure (permissions, disk full) leaves the dir missing — + // the plugin script will get a sane shell error when it tries to + // write there. Better than throwing here and wedging the hook. + } + } + return { + pluginDir: input.pluginDir, + pluginDataDir: dataDir, + cwd: input.cwd, + homedir: os.homedir(), + sep: path.sep, + } +} + +/** Expand `${pluginDir}` / `${pluginDataDir}` / `${cwd}` / `${homedir}` / + * `${sep}` / `${env:NAME}` references. Unknown patterns are left verbatim. */ +export function expandVariables(source: string, ctx: VariableContext): string { + return source.replace(/\$\{([^}]+)\}/g, (whole, expr: string) => { + const colonIdx = expr.indexOf(':') + if (colonIdx > 0) { + const ns = expr.slice(0, colonIdx) + const key = expr.slice(colonIdx + 1) + if (ns === 'env') return process.env[key] ?? '' + // Unknown namespace — leave verbatim + return whole + } + switch (expr) { + case 'pluginDir': + return ctx.pluginDir + case 'pluginDataDir': + return ctx.pluginDataDir ?? whole + case 'cwd': + return ctx.cwd + case 'homedir': + return ctx.homedir ?? '' + case 'sep': + return ctx.sep ?? path.sep + default: + return whole + } + }) +} diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 490d69d..243a5ea 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -64,7 +64,7 @@ export { loadPersistedRules, persistRule } from './permissions/index.js' export type { AllowRule } from './permissions/session-store.js' // Utils -export { GLOBAL_XCODE_DIR, XCODE_DIR, debugLog } from './utils.js' +export { GLOBAL_XCODE_DIR, XCODE_DIR, debugLog, setPluginDebugMirror } from './utils.js' export { LruCache } from './utils/lru-cache.js' export { mediaTypeFor } from './utils/media-type.js' export { extractText } from './utils/message-helpers.js' @@ -78,6 +78,104 @@ export { generateSessionSummary } from './knowledge/session.js' export { createSubAgentRegistry, createBuiltInRegistry, SubAgentRegistry } from './agent/sub-agents/index.js' export type { SubAgentDefinition, SubAgentEvent, SubAgentTrace } from './agent/sub-agents/index.js' +// File-based slash commands (plugin-contributed `commands/*.md`). +export { CommandRegistry, createCommandRegistry, loadPluginCommands, expandCommandBody } from './commands/index.js' +export type { CommandDefinition, LoadCommandsOptions } from './commands/index.js' + +// Hooks — agent lifecycle event subsystem driven by plugin contributions. +export { + HookBus, + emptyHookBus, + aggregatePreToolUse, + aggregatePostToolUse, + aggregateUserPromptSubmit, +} from './hooks/bus.js' +export type { EmitOptions as HookEmitOptions, PreToolEffect, PostToolEffect, UserPromptEffect } from './hooks/bus.js' +export { HookRegistry, buildHookRegistry, emptyHookRegistry } from './hooks/registry.js' +export { executeHook } from './hooks/executor.js' +export type { ExecuteHookOptions } from './hooks/executor.js' +export { hookConfigSchema, parseHookConfig, HookConfigParseError } from './hooks/config-schema.js' +export { buildVariableContext, expandVariables } from './hooks/variables.js' +export type { VariableContext } from './hooks/variables.js' +export type { + DecisionEvent, + HookConfig, + HookConfigEntry, + HookDecision, + HookEvent, + HookEventName, + RegisteredHook, + SessionContext as HookSessionContext, +} from './hooks/types.js' + +// Plugins — discovery, install, marketplace, registry. +export { loadAllPlugins, resolveContributions } from './plugins/loader.js' +export type { + LoadOptions as PluginLoadOptions, + LoadResult as PluginLoadResult, + ResolvedContributions, +} from './plugins/loader.js' +export { PluginRegistry, emptyPluginRegistry } from './plugins/registry.js' +export type { PluginReloadSummary } from './plugins/registry.js' +export { buildPluginIntegration, debugLogIntegrationDiagnostics } from './plugins/integration.js' +export type { PluginIntegrationOutput } from './plugins/integration.js' +export { refreshPluginContributions } from './plugins/refresh.js' +export type { PluginRefreshSummary, PluginRefreshTargets } from './plugins/refresh.js' +export { + installPlugin, + uninstallPlugin, + listInstalledPlugins, + findInstalledPlugin, + InstallError, +} from './plugins/installer.js' +export type { InstallRequest, InstallResult, UninstallResult } from './plugins/installer.js' +export { buildConsentPreview } from './plugins/consent.js' +export type { ConsentPreview, BuildPreviewInput } from './plugins/consent.js' +export { + getPluginUserConfig, + setPluginUserConfig, + clearPluginUserConfig, + getPluginUserConfigEnv, +} from './plugins/user-config.js' +export type { UserConfigValue, PluginUserConfig } from './plugins/user-config.js' +export { + parseMarketplace, + readKnownMarketplaces, + addKnownMarketplace, + removeKnownMarketplace, + ensureDefaultMarketplaces, + fetchMarketplace, + readAllCachedMarketplaces, + lookupPlugin, + resolveCloneUrl, + RESERVED_MARKETPLACE_NAMES, + MarketplaceParseError, +} from './plugins/marketplace.js' +export { + EnableState, + setPluginEnabled, + clearPluginEntry, + settingsPathForScope as pluginSettingsPathForScope, +} from './plugins/enable-state.js' +export type { ResolvedEnableState } from './plugins/enable-state.js' +export type { + LoadedPlugin, + PluginManifest, + PluginAuthor, + UserConfigItem, + PluginSource, + PluginScope, + ManifestFormat, + PluginLoadError, + Marketplace, + MarketplaceEntry, + KnownMarketplace, + KnownMarketplaces, + InstalledPluginRecord, + InstalledPlugins, +} from './plugins/types.js' +export { discoverManifest, parseManifest, ManifestParseError } from './plugins/manifest.js' + // Skills export { SkillRegistry, diff --git a/packages/core/src/knowledge/auto-memory.ts b/packages/core/src/knowledge/auto-memory.ts index eac9776..62c17c2 100644 --- a/packages/core/src/knowledge/auto-memory.ts +++ b/packages/core/src/knowledge/auto-memory.ts @@ -183,13 +183,13 @@ function parseMemoryFile(content: string): KnowledgeFact[] { // GLOBAL_XCODE_DIR. const projectMemories = new Map() -let globalMemory: AutoMemory | null = null +let userMemory: AutoMemory | null = null function projectMemoryPath(cwd: string): string { return path.join(cwd, XCODE_DIR, 'memory', 'auto.md') } -export function getAutoMemory(scope: 'project' | 'global'): AutoMemory { +export function getAutoMemory(scope: 'project' | 'user'): AutoMemory { if (scope === 'project') { const filePath = projectMemoryPath(process.cwd()) let mem = projectMemories.get(filePath) @@ -199,19 +199,19 @@ export function getAutoMemory(scope: 'project' | 'global'): AutoMemory { } return mem } - if (!globalMemory) { - globalMemory = new AutoMemory(path.join(GLOBAL_XCODE_DIR, 'memory', 'auto.md')) + if (!userMemory) { + userMemory = new AutoMemory(path.join(GLOBAL_XCODE_DIR, 'memory', 'auto.md')) } - return globalMemory + return userMemory } /** Initialize memories (load from disk + evict old entries) */ export async function initMemories(): Promise { const project = getAutoMemory('project') - const global = getAutoMemory('global') - await Promise.all([project.load(), global.load()]) + const user = getAutoMemory('user') + await Promise.all([project.load(), user.load()]) project.evict(90) - global.evict(90) + user.evict(90) } export { AutoMemory } diff --git a/packages/core/src/knowledge/loader.ts b/packages/core/src/knowledge/loader.ts index 44a4274..bc1d0a0 100644 --- a/packages/core/src/knowledge/loader.ts +++ b/packages/core/src/knowledge/loader.ts @@ -89,10 +89,10 @@ export async function buildKnowledgeContext(options?: { sessionContext?: string sections.push(`### Global Preferences (~/.x-code/${globalKnowledge.fileName})\n${globalKnowledge.content}`) } - const globalMemory = getAutoMemory('global') - const globalMemoryContent = globalMemory.getPromptContent() - if (globalMemoryContent) { - sections.push('### Global Auto Memory\n' + globalMemoryContent) + const userMemory = getAutoMemory('user') + const userMemoryContent = userMemory.getPromptContent() + if (userMemoryContent) { + sections.push('### Global Auto Memory\n' + userMemoryContent) } const cwd = process.cwd() diff --git a/packages/core/src/mcp/loader.ts b/packages/core/src/mcp/loader.ts index 11ead0c..63ec6e2 100644 --- a/packages/core/src/mcp/loader.ts +++ b/packages/core/src/mcp/loader.ts @@ -34,6 +34,12 @@ export interface LoadOptions { userServers: Record | undefined /** mcpServers from /.x-code/config.json. Requires consent. */ projectServers: Record | undefined + /** mcpServers contributed by enabled plugins. Trusted implicitly — + * the user already consented to the plugin at install time, so + * re-running the project-MCP trust dialog for plugin servers would + * be a duplicate prompt. Merged at the same precedence as + * `userServers` (project entries still override on name collision). */ + extraServers?: Record /** Absolute project path (cwd at CLI start). Used as the trust key. */ projectPath: string /** Renders the trust dialog. Same shape as `AgentCallbacks.onAskUser`. */ @@ -66,12 +72,17 @@ export async function loadMcpFromDisk(opts: { askUser: LoadOptions['askUser'] oauthProviderFor?: OAuthProviderFactory onExitRequested?: () => void + /** Plugin-contributed mcpServers — already-trusted, merged into the + * effective config alongside user-level servers. Built by + * packages/core/src/plugins/integration.ts. */ + extraServers?: Record }): Promise { const userServers = await readMcpServersFromFile(getUserConfigPath()) const projectServers = await readMcpServersFromFile(path.join(opts.cwd, XCODE_DIR, 'config.json')) return loadMcpServers({ userServers, projectServers, + extraServers: opts.extraServers, projectPath: opts.cwd, askUser: opts.askUser, oauthProviderFor: opts.oauthProviderFor, @@ -176,9 +187,19 @@ export async function loadMcpServers(options: LoadOptions): Promise } } - // Merge user + project. Project-level entries shadow user-level entries - // on name conflict (project wins by design — user explicitly trusted it). - const merged: Record = { ...userParsed.servers, ...projectServersToUse } + // Merge order: user → plugin → project. Plugin-contributed servers + // (`extraServers`) sit between user and project on purpose: + // - They're already-trusted (consent happened at plugin install) so + // they don't need to pass the trust dialog above, but + // - A name collision with a project-level entry still gives the + // project entry the win (project config is authored by the same + // person whose CLI is running and they may want to override a + // plugin's server choice). + const merged: Record = { + ...userParsed.servers, + ...(options.extraServers ?? {}), + ...projectServersToUse, + } // No servers configured anywhere → fast-path with an empty registry. // We still pass the oauthFactory so a later /mcp refresh (after the diff --git a/packages/core/src/plugins/consent.ts b/packages/core/src/plugins/consent.ts new file mode 100644 index 0000000..ebfe3a9 --- /dev/null +++ b/packages/core/src/plugins/consent.ts @@ -0,0 +1,124 @@ +// @x-code-cli/core — Install-time consent preview +// +// Before a plugin's contents are committed to the cache, the installer +// builds a `ConsentPreview` summarising what the plugin will contribute +// (hooks, MCP servers, scopes etc.) and hands it to the caller-supplied +// consent callback. If the callback returns false, the install aborts +// and the temp dir is cleaned up. +// +// The preview is built from the already-parsed manifest, so all the +// validation work has already happened — by the time we ask the user +// "do you accept?" we know the plugin parses cleanly and what it will +// touch on their system. +// +// What it intentionally does NOT include: +// +// - Skill / agent / command counts (they're hidden inside subdirs; +// scanning them just to build a preview would slow every install, +// and the preview is meant to be a glance, not an audit). +// - LICENSE file contents — surfaced as a name only; readers should +// follow the homepage / source URL to read the actual terms. +// +// What it DOES include — the things with real security blast radius: +// hooks (arbitrary shell), MCP servers (arbitrary subprocesses), and +// source (so the user knows whether it came from a trusted marketplace +// or a random GitHub repo). +import { parseHookConfig } from '../hooks/config-schema.js' +import type { HookEventName } from '../hooks/types.js' +import { parseServersBlock } from '../mcp/config-schema.js' +import type { PluginManifest, PluginSource } from './types.js' + +export interface ConsentPreview { + pluginId: string + version: string + description?: string + source: PluginSource + marketplace: string + /** True when the install came from a marketplace flagged `verified`. */ + verified: boolean + /** True when the marketplace's name is one of `RESERVED_MARKETPLACE_NAMES`. */ + fromReservedMarketplace: boolean + /** Hook event names the plugin registers. Empty means no hooks. */ + hookEvents: HookEventName[] + /** MCP server names contributed inline (path-form not previewed — + * requires reading another file before consent). */ + inlineMcpServerNames: string[] + hasSkillsDir: boolean + hasAgentsDir: boolean + hasCommandsDir: boolean + /** True when manifest declares `mcpServers` as a file path (not + * inline) — we don't have the names yet at consent time, but we can + * warn the user that the plugin DOES bring MCP servers. */ + hasPathMcpServers: boolean + /** Same as above for hooks declared via path rather than inline. */ + hasPathHooks: boolean + author?: string + license?: string + homepage?: string +} + +export interface BuildPreviewInput { + pluginId: string + manifest: PluginManifest + source: PluginSource + marketplace: string + verified?: boolean + fromReservedMarketplace?: boolean +} + +/** Build a `ConsentPreview` from a parsed manifest. The hook + mcp + * fields are inspected only for the inline shape; path-form + * contributions are surfaced as `has*` booleans so the consent UI can + * warn "this plugin contributes MCP servers" even when their names + * aren't yet known. */ +export function buildConsentPreview(input: BuildPreviewInput): ConsentPreview { + const m = input.manifest + + let hookEvents: HookEventName[] = [] + let hasPathHooks = false + if (m.hooks !== undefined) { + if (typeof m.hooks === 'string') { + hasPathHooks = true + } else { + try { + const cfg = parseHookConfig(m.hooks, input.pluginId) + hookEvents = Object.keys(cfg) as HookEventName[] + } catch { + // Don't fail consent on hook parse errors — the install path + // will surface them properly. Just leave hookEvents empty so + // the preview doesn't lie about what's registered. + } + } + } + + let inlineMcpServerNames: string[] = [] + let hasPathMcpServers = false + if (m.mcpServers !== undefined) { + if (typeof m.mcpServers === 'string') { + hasPathMcpServers = true + } else { + const { servers } = parseServersBlock(m.mcpServers) + inlineMcpServerNames = Object.keys(servers) + } + } + + return { + pluginId: input.pluginId, + version: m.version, + description: m.description, + source: input.source, + marketplace: input.marketplace, + verified: input.verified ?? false, + fromReservedMarketplace: input.fromReservedMarketplace ?? false, + hookEvents, + inlineMcpServerNames, + hasSkillsDir: !!m.skills, + hasAgentsDir: !!m.agents, + hasCommandsDir: !!m.commands, + hasPathMcpServers, + hasPathHooks, + author: m.author?.name, + license: m.license, + homepage: m.homepage, + } +} diff --git a/packages/core/src/plugins/enable-state.ts b/packages/core/src/plugins/enable-state.ts new file mode 100644 index 0000000..b05d544 --- /dev/null +++ b/packages/core/src/plugins/enable-state.ts @@ -0,0 +1,188 @@ +// @x-code-cli/core — Plugin enable/disable state +// +// Reads the per-scope `enabledPlugins` map from settings.json files and +// resolves the effective enabled state for each plugin id. +// +// Two-scope model, mirroring mcp + skill subsystems: +// +// user ~/.x-code/settings.json +// project /.x-code/settings.local.json (gitignored) +// +// `'project'` reading a `.local.json` file is a slight naming quirk we +// inherit from skills — it's a per-user override for one repo, not a +// team-shared file. A separate team-shared scope (committed) can be +// added later without touching the existing two. +// +// Map shape: `{ "name@marketplace": true | false }` — true = enabled, +// false = explicitly disabled, missing = use the project-wide default +// (currently `true`, i.e. default-enable). +// +// Precedence: project > user. An explicit value in a higher-priority +// scope wins; a missing entry falls through. +import fs from 'node:fs/promises' +import path from 'node:path' + +import { GLOBAL_XCODE_DIR, XCODE_DIR } from '../utils.js' +import type { PluginScope } from './types.js' + +/** Highest precedence first. The first scope with an explicit entry wins. */ +const SCOPE_PRECEDENCE: ReadonlyArray = ['project', 'user'] + +/** Default enabled state when no scope mentions the plugin. We default + * to ENABLED so newly-installed plugins work out-of-the-box; users who + * want opt-in behaviour can flip individual plugins off explicitly. */ +const DEFAULT_ENABLED = true + +interface PluginSettingsFile { + enabledPlugins?: Record +} + +export function settingsPathForScope(scope: PluginScope, cwd: string = process.cwd()): string { + if (scope === 'user') return path.join(GLOBAL_XCODE_DIR, 'settings.json') + return path.join(cwd, XCODE_DIR, 'settings.local.json') +} + +async function readSettings(scope: PluginScope, cwd: string): Promise { + const file = settingsPathForScope(scope, cwd) + try { + const raw = await fs.readFile(file, 'utf-8') + const parsed = JSON.parse(raw) as unknown + if (!parsed || typeof parsed !== 'object') return {} + const obj = parsed as Record + if (obj.enabledPlugins && typeof obj.enabledPlugins === 'object' && !Array.isArray(obj.enabledPlugins)) { + // Coerce values to boolean defensively — settings.json may have been + // hand-edited and the wrong type here shouldn't crash the loader. + const out: Record = {} + for (const [k, v] of Object.entries(obj.enabledPlugins)) { + if (typeof v === 'boolean') out[k] = v + } + return { enabledPlugins: out } + } + return {} + } catch (err) { + if ((err as NodeJS.ErrnoException).code === 'ENOENT') return {} + // Malformed JSON: ignore + return empty so a broken settings file never + // blocks startup. The user can fix the file and re-launch. + return {} + } +} + +/** Resolved per-plugin enable state, plus which scope decided it (for + * `/plugin doctor`). When `decidedBy` is `undefined`, no scope mentioned + * the plugin and the default applied. */ +export interface ResolvedEnableState { + enabled: boolean + decidedBy: PluginScope | undefined +} + +export class EnableState { + private constructor(private readonly perScope: Map>) {} + + /** Load both settings files and build a snapshot. The snapshot is + * intentionally immutable from this point — callers re-load via + * `EnableState.load()` after settings.json writes. `cwd` defaults to + * `process.cwd()` and controls where the `'project'` scope file is + * read from. */ + static async load(cwd: string = process.cwd()): Promise { + const map = new Map>() + for (const scope of SCOPE_PRECEDENCE) { + const s = await readSettings(scope, cwd) + map.set(scope, s.enabledPlugins ?? {}) + } + return new EnableState(map) + } + + /** Effective enabled state for one plugin id. */ + resolve(pluginId: string): ResolvedEnableState { + for (const scope of SCOPE_PRECEDENCE) { + const table = this.perScope.get(scope) ?? {} + if (pluginId in table) { + return { enabled: table[pluginId]!, decidedBy: scope } + } + } + return { enabled: DEFAULT_ENABLED, decidedBy: undefined } + } + + /** Raw map for one scope — used by `/plugin list` to show the per-scope + * flags alongside the effective state. */ + scopeEntries(scope: PluginScope): Record { + return { ...(this.perScope.get(scope) ?? {}) } + } +} + +// ── Mutating writes (used by /plugin enable|disable|install) ──────────── + +/** Write a single plugin's enable flag in the chosen scope. Read-modify- + * write so unrelated fields in settings.json (e.g. `disabledSkills` from + * the skill subsystem) aren't clobbered. Returns whether the file + * actually changed (so callers can render an accurate + * "already enabled" vs "enabled" message). */ +export async function setPluginEnabled( + pluginId: string, + scope: PluginScope, + enabled: boolean, + cwd: string = process.cwd(), +): Promise<'changed' | 'noop'> { + const file = settingsPathForScope(scope, cwd) + await fs.mkdir(path.dirname(file), { recursive: true }) + + let existing: Record = {} + try { + const raw = await fs.readFile(file, 'utf-8') + const parsed = JSON.parse(raw) as unknown + if (parsed && typeof parsed === 'object') existing = parsed as Record + } catch { + // first write — file may not exist yet + } + + const currentMap = + existing.enabledPlugins && typeof existing.enabledPlugins === 'object' && !Array.isArray(existing.enabledPlugins) + ? { ...(existing.enabledPlugins as Record) } + : {} + + if (currentMap[pluginId] === enabled) return 'noop' + currentMap[pluginId] = enabled + existing.enabledPlugins = currentMap + + await fs.writeFile(file, JSON.stringify(existing, null, 2) + '\n', 'utf-8') + return 'changed' +} + +/** Remove a plugin's entry from a scope's enabledPlugins (used by + * `/plugin uninstall` to keep settings.json tidy). */ +export async function clearPluginEntry( + pluginId: string, + scope: PluginScope, + cwd: string = process.cwd(), +): Promise<'changed' | 'noop'> { + const file = settingsPathForScope(scope, cwd) + let existing: Record = {} + try { + const raw = await fs.readFile(file, 'utf-8') + const parsed = JSON.parse(raw) as unknown + if (parsed && typeof parsed === 'object') existing = parsed as Record + } catch { + return 'noop' + } + + if ( + !existing.enabledPlugins || + typeof existing.enabledPlugins !== 'object' || + Array.isArray(existing.enabledPlugins) + ) { + return 'noop' + } + + const map = { ...(existing.enabledPlugins as Record) } + if (!(pluginId in map)) return 'noop' + delete map[pluginId] + + if (Object.keys(map).length === 0) { + delete existing.enabledPlugins + } else { + existing.enabledPlugins = map + } + + await fs.writeFile(file, JSON.stringify(existing, null, 2) + '\n', 'utf-8') + return 'changed' +} diff --git a/packages/core/src/plugins/installer.ts b/packages/core/src/plugins/installer.ts new file mode 100644 index 0000000..5e60445 --- /dev/null +++ b/packages/core/src/plugins/installer.ts @@ -0,0 +1,431 @@ +// @x-code-cli/core — Plugin installer +// +// Three supported source kinds: +// +// - 'local' filesystem directory → copied recursively into cache +// (skipping .git / node_modules / OS junk) +// - 'git' arbitrary git URL → shallow-cloned (depth 1, optional ref) +// - 'github' github:owner/repo → shallow-cloned via resolveCloneUrl +// Monorepo `subdir` supported: whole repo is shallow-cloned, +// the named subdir is copied into a fresh temp dir, the rest +// discarded. +// +// Install flow: +// 1. Fetch source into a temp dir +// 2. Discover + parse manifest (reject Gemini-only sources here) +// 3. Compute final cache path: cache//// +// 4. Wipe any existing install at that path (re-install / same-version upgrade) +// 5. Move temp → final (rename when possible, copy+rm fallback for EXDEV) +// 6. Append/update installed_plugins.json +// +// AbortSignal threads through git clone (via execa's `signal`) and the +// recursive copy (cooperative check between entries) so Esc during a long +// install cleanly cancels in-flight work. +// +// Cache layout is deliberately per-version so `/plugin update` can install +// a new version side-by-side and atomically switch (a later improvement); +// today we just overwrite same-version installs. +import { execa } from 'execa' + +import fs from 'node:fs/promises' +import os from 'node:os' +import path from 'node:path' + +import { debugLog } from '../utils.js' +import { type ConsentPreview, buildConsentPreview } from './consent.js' +import { ManifestParseError, discoverManifest, parseManifest } from './manifest.js' +import { RESERVED_MARKETPLACE_NAMES, readKnownMarketplaces, resolveCloneUrl } from './marketplace.js' +import { installedPluginsPath, pluginCacheDir, pluginCacheParent } from './paths.js' +import type { + InstalledPluginRecord, + InstalledPlugins, + ManifestFormat, + PluginManifest, + PluginScope, + PluginSource, +} from './types.js' +import { type UserConfigValue, setPluginUserConfig } from './user-config.js' + +export interface InstallRequest { + source: PluginSource + /** Marketplace this plugin belongs to. Use `"local"` for direct + * git/local installs that aren't associated with a subscribed + * marketplace — the resulting plugin id will be `@local`. */ + marketplace: string + /** Scope where the install is recorded (which settings.json's + * `enabledPlugins` map will mention it). Defaults to `'user'`. */ + scope?: PluginScope + /** If set, the installer aborts when the manifest's `name` field + * doesn't match — used by the marketplace install path to catch + * spoofed entries. */ + expectedName?: string + /** Whether the marketplace listing marked this plugin as verified. + * Surfaced to the consent callback so users know whether the listing + * came with curator endorsement. Pure metadata — we don't grant + * extra trust based on the flag. */ + verified?: boolean + /** Called after manifest parse but BEFORE the temp dir is moved to + * the cache. Return false to abort the install — the temp dir is + * cleaned up and the cache is untouched. Absent ⇒ install proceeds + * without prompting (used by tests + the `--yes` CLI flag). */ + consent?: (preview: ConsentPreview) => Promise | boolean + /** Called AFTER consent passes when the manifest declares `userConfig`. + * The caller (a CLI / TUI handler) collects values for each field — + * typically by prompting the user one field at a time, masking input + * for `sensitive: true` fields — and resolves to a `{ key: value }` + * map that gets persisted via user-config.ts. Returning `null` + * aborts the install (treat it like consent denial). Absent ⇒ we + * skip the prompt; non-sensitive fields fall back to manifest + * defaults, sensitive fields are simply unset (the plugin's hooks / + * MCP entries will see empty env vars, which is the same as today). */ + userConfigPrompt?: (fields: PluginManifest['userConfig']) => Promise | null> + signal?: AbortSignal +} + +export interface InstallResult { + pluginId: string + rootDir: string + manifest: PluginManifest + manifestFormat: ManifestFormat + record: InstalledPluginRecord +} + +export class InstallError extends Error { + constructor(message: string) { + super(message) + this.name = 'InstallError' + } +} + +export async function installPlugin(req: InstallRequest): Promise { + // ── Pre-flight policy checks (cheap, fail-fast) ── + // `strictKnownMarketplaces` and `blockedPlugins` come from + // ~/.x-code/plugins/known_marketplaces.json. When the admin + // (typically enterprise) has opted into strict mode, every install + // must come from a subscribed marketplace — direct git / github / + // local installs are denied. `blockedPlugins` is checked after the + // manifest is parsed (we need the canonical id). + const km = await readKnownMarketplaces() + if (km.strictKnownMarketplaces) { + const subscribed = km.marketplaces.some((m) => m.name === req.marketplace) + if (!subscribed) { + throw new InstallError( + `strict marketplace mode is enabled (known_marketplaces.json:strictKnownMarketplaces=true) — ` + + `plugins can only be installed from a subscribed marketplace, but "${req.marketplace}" is not one. ` + + `Either subscribe it first (\`xc plugin marketplace add\`) or turn strict mode off.`, + ) + } + } + + const tempDir = await fetchToTemp(req.source, req.signal) + + try { + const discovery = await discoverManifest(tempDir) + if (!discovery) { + throw new InstallError( + 'no plugin manifest found in source (looked for .x-code-plugin/plugin.json, .claude-plugin/plugin.json, plugin.json)', + ) + } + if (discovery.format === 'gemini') { + throw new InstallError( + 'this is a Gemini extension (gemini-extension.json) — x-code-cli does not support Gemini extensions; see docs/plugins.md', + ) + } + + let manifest: PluginManifest + try { + manifest = await parseManifest(discovery.manifestPath) + } catch (err) { + if (err instanceof ManifestParseError) throw new InstallError(err.message) + throw err + } + + if (req.expectedName && manifest.name !== req.expectedName) { + throw new InstallError(`manifest name "${manifest.name}" does not match expected "${req.expectedName}"`) + } + + // Now that we know the canonical plugin id, run the second + // policy check: blockedPlugins from known_marketplaces.json. This + // is an admin-style force-disable list — an install attempt for + // a blocked id is rejected regardless of marketplace / consent. + const earlyId = `${manifest.name}@${req.marketplace}` + if (km.blockedPlugins?.includes(earlyId)) { + throw new InstallError( + `plugin "${earlyId}" is on the blockedPlugins list in known_marketplaces.json — ` + + `remove it from that list (or use a different plugin) to install.`, + ) + } + + // ── Consent gate ── + // Built from the parsed manifest so the caller can render a + // preview of what the plugin will contribute (hooks, mcp, scopes) + // and ask the user explicitly. Skipping the prompt (callback + // absent) is intentional for non-interactive paths — the CLI + // implements `--yes` by simply not passing `consent`. + if (req.consent) { + const preview = buildConsentPreview({ + pluginId: `${manifest.name}@${req.marketplace}`, + manifest, + source: req.source, + marketplace: req.marketplace, + verified: req.verified, + fromReservedMarketplace: req.marketplace in RESERVED_MARKETPLACE_NAMES, + }) + const accepted = await req.consent(preview) + if (!accepted) { + throw new InstallError('install cancelled by user (consent declined)') + } + } + + // ── userConfig prompt (post-consent, pre-commit) ── + // Only fires when the manifest declares userConfig fields AND the + // caller wired a prompt callback. Non-interactive paths (--yes, CI) + // skip the prompt — fields stay unset and the plugin sees empty env + // vars at hook / mcp launch time, same as before this feature. + // Returning null from the prompt aborts the install (treated like + // consent denial); a non-null object is persisted via setPluginUserConfig. + if (manifest.userConfig && manifest.userConfig.length > 0 && req.userConfigPrompt) { + const collected = await req.userConfigPrompt(manifest.userConfig) + if (collected === null) { + throw new InstallError('install cancelled by user (userConfig prompt aborted)') + } + // Persist BEFORE moving the temp dir to cache so a crash between + // the two phases leaves the user with no broken plugin and no + // orphaned secret. The settings file is keyed by plugin id and + // overwrites cleanly on reinstall. + const pluginIdForConfig = `${manifest.name}@${req.marketplace}` + await setPluginUserConfig(pluginIdForConfig, collected) + } + + const finalDir = pluginCacheDir(req.marketplace, manifest.name, manifest.version) + + // Same-version reinstall: wipe existing install first. Skipping this + // would leave stale files mixed with new ones if the new version drops + // a file the old version had. + await fs.rm(finalDir, { recursive: true, force: true }) + await fs.mkdir(path.dirname(finalDir), { recursive: true }) + await moveOrCopy(tempDir, finalDir, req.signal) + + const pluginId = `${manifest.name}@${req.marketplace}` + const record: InstalledPluginRecord = { + id: pluginId, + name: manifest.name, + marketplace: req.marketplace, + version: manifest.version, + source: req.source, + installedAt: new Date().toISOString(), + installScope: req.scope ?? 'user', + } + await recordInstallation(record) + + return { pluginId, rootDir: finalDir, manifest, manifestFormat: discovery.format, record } + } catch (err) { + // Best-effort cleanup of the temp dir on any failure mid-install. The + // moveOrCopy success path renames the temp away, so this only fires + // when something went wrong before the move. + await fs.rm(tempDir, { recursive: true, force: true }).catch(() => { + /* nothing useful to do */ + }) + if (err instanceof InstallError || err instanceof ManifestParseError) throw err + throw new InstallError(err instanceof Error ? err.message : String(err)) + } +} + +// ── Source → temp dir ─────────────────────────────────────────────────── + +async function fetchToTemp(source: PluginSource, signal?: AbortSignal): Promise { + const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-plugin-install-')) + + if (source.kind === 'local') { + const resolved = path.resolve(source.path) + const stat = await fs.stat(resolved).catch(() => null) + if (!stat || !stat.isDirectory()) { + await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {}) + throw new InstallError(`local source is not a directory: ${resolved}`) + } + await copyDirFiltered(resolved, tempDir, signal) + return tempDir + } + + if (source.kind === 'git' || source.kind === 'github') { + const cloneUrl = source.kind === 'git' ? source.url : resolveCloneUrl(`github:${source.owner}/${source.repo}`) + const args = ['clone', '--depth', '1'] + if (source.ref) args.push('--branch', source.ref) + // For subdir installs we still shallow-clone the whole repo. Real + // sparse-checkout would be faster on huge monorepos but the + // `--depth 1 --filter=blob:none --sparse` sequence is fragile across + // git versions; a depth-1 clone of even a large monorepo is usually + // <100 MB. Revisit if it becomes a pain point. + args.push(cloneUrl, tempDir) + + try { + await execa('git', args, { signal, stdio: 'pipe' }) + } catch (err) { + await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {}) + throw new InstallError(`git clone failed: ${err instanceof Error ? err.message : String(err)}`) + } + // Drop the .git dir — we never need it after install and it would + // bloat the cache significantly for large-history repos. + await fs.rm(path.join(tempDir, '.git'), { recursive: true, force: true }).catch(() => {}) + + // Subdir handling: the plugin actually lives at /. + // Re-stage so the rest of the install flow (manifest discovery + + // moveOrCopy to cache) operates on just that subdir. Simplest + // approach: copy the subdir into a fresh temp dir, discard the + // original clone. + const subdir = source.subdir + if (subdir) { + const subdirPath = path.join(tempDir, subdir) + const stat = await fs.stat(subdirPath).catch(() => null) + if (!stat || !stat.isDirectory()) { + await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {}) + throw new InstallError(`subdir "${subdir}" not found in cloned repo ${cloneUrl}`) + } + const subdirTemp = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-plugin-subdir-')) + try { + await copyDirFiltered(subdirPath, subdirTemp, signal) + } catch (err) { + await fs.rm(subdirTemp, { recursive: true, force: true }).catch(() => {}) + await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {}) + throw new InstallError(`failed to extract subdir: ${err instanceof Error ? err.message : String(err)}`) + } + await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {}) + return subdirTemp + } + return tempDir + } + + await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {}) + throw new InstallError(`unknown source kind: ${(source as PluginSource).kind}`) +} + +/** Names we never copy through. `node_modules` is excluded because a + * bundled-deps plugin should reinstall on the user's machine; if a + * plugin genuinely needs node_modules we'll revisit. */ +const COPY_SKIP = new Set(['.git', 'node_modules', '.DS_Store', 'Thumbs.db']) + +async function copyDirFiltered(src: string, dst: string, signal?: AbortSignal): Promise { + await fs.mkdir(dst, { recursive: true }) + const entries = await fs.readdir(src, { withFileTypes: true }) + for (const entry of entries) { + signal?.throwIfAborted() + if (COPY_SKIP.has(entry.name)) continue + const s = path.join(src, entry.name) + const d = path.join(dst, entry.name) + if (entry.isDirectory()) { + await copyDirFiltered(s, d, signal) + } else if (entry.isFile()) { + await fs.copyFile(s, d) + } else if (entry.isSymbolicLink()) { + const target = await fs.readlink(s) + try { + await fs.symlink(target, d) + } catch { + // Windows without symlink privilege: fall back to copying the + // resolved file. Best effort — broken symlinks just get dropped. + await fs.copyFile(s, d).catch(() => {}) + } + } + } +} + +/** Move from temp → final dir. Rename is atomic + cheap when src and dst + * are on the same filesystem; otherwise (EXDEV on Windows mostly) we + * fall back to copy + rm. */ +async function moveOrCopy(src: string, dst: string, signal?: AbortSignal): Promise { + try { + await fs.rename(src, dst) + return + } catch (err) { + const code = (err as NodeJS.ErrnoException).code + if (code !== 'EXDEV' && code !== 'EPERM' && code !== 'ENOTEMPTY') { + // Surfacing the original error here would block install for transient + // weirdness; the copy fallback below succeeds in all the cases we've + // seen in the wild. Still log for postmortem. + debugLog('plugins.install-rename-fallback', String(err)) + } + } + await copyDirFiltered(src, dst, signal) + await fs.rm(src, { recursive: true, force: true }).catch(() => {}) +} + +// ── installed_plugins.json bookkeeping ────────────────────────────────── + +async function readInstalledPlugins(): Promise { + const file = installedPluginsPath() + try { + const raw = await fs.readFile(file, 'utf-8') + const parsed = JSON.parse(raw) as InstalledPlugins + if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.plugins)) { + return { schemaVersion: '1', plugins: [] } + } + return { schemaVersion: parsed.schemaVersion ?? '1', plugins: parsed.plugins } + } catch { + return { schemaVersion: '1', plugins: [] } + } +} + +async function writeInstalledPlugins(data: InstalledPlugins): Promise { + const file = installedPluginsPath() + await fs.mkdir(path.dirname(file), { recursive: true }) + await fs.writeFile(file, JSON.stringify(data, null, 2) + '\n', 'utf-8') +} + +async function recordInstallation(record: InstalledPluginRecord): Promise { + const data = await readInstalledPlugins() + const idx = data.plugins.findIndex((p) => p.id === record.id) + if (idx >= 0) data.plugins[idx] = record + else data.plugins.push(record) + await writeInstalledPlugins(data) +} + +export async function listInstalledPlugins(): Promise { + const data = await readInstalledPlugins() + return data.plugins +} + +export async function findInstalledPlugin(id: string): Promise { + const data = await readInstalledPlugins() + return data.plugins.find((p) => p.id === id) +} + +// ── Uninstall ────────────────────────────────────────────────────────── + +export interface UninstallResult { + /** Versions that were removed from cache. Empty if the plugin wasn't + * cached. */ + removedVersions: string[] + /** Whether the installed_plugins.json record was removed. */ + removedRecord: boolean +} + +/** Remove all cached versions of a plugin + drop its + * installed_plugins.json record. Leaves the data dir + * (`~/.x-code/plugins/data//`) intact so the user doesn't lose + * state if they reinstall later. */ +export async function uninstallPlugin(id: string): Promise { + const record = await findInstalledPlugin(id) + const result: UninstallResult = { removedVersions: [], removedRecord: false } + + if (record) { + const parent = pluginCacheParent(record.marketplace, record.name) + try { + const versions = await fs.readdir(parent) + result.removedVersions = versions + await fs.rm(parent, { recursive: true, force: true }) + } catch { + // No cache entries — the record might be stale. Removing the record + // below still happens. + } + } + + const data = await readInstalledPlugins() + const before = data.plugins.length + data.plugins = data.plugins.filter((p) => p.id !== id) + if (data.plugins.length !== before) { + await writeInstalledPlugins(data) + result.removedRecord = true + } + + return result +} diff --git a/packages/core/src/plugins/integration.ts b/packages/core/src/plugins/integration.ts new file mode 100644 index 0000000..2c29608 --- /dev/null +++ b/packages/core/src/plugins/integration.ts @@ -0,0 +1,251 @@ +// @x-code-cli/core — Plugin contributions → existing loaders integration +// +// Takes the output of [[loader]].loadAllPlugins and converts it into the +// shapes that the pre-existing skill / sub-agent / MCP loaders consume, +// so a CLI startup call sequence looks like: +// +// const pluginLoad = await loadAllPlugins({ cwd }) +// const integration = await buildPluginIntegration(pluginLoad) +// const skillRegistry = await createSkillRegistry({ extraDirs: integration.skillsDirs }) +// const agentRegistry = await createSubAgentRegistry({ extraDirs: integration.agentsDirs }) +// const mcpRegistry = await loadMcpFromDisk({ ..., extraServers: integration.mcpServers }) +// +// Three concerns this module owns and the others don't: +// +// 1. Resolving plugin `mcpServers` from the manifest (a path or an +// inline object) into a typed `Record`. +// The path form is a JSON file shaped `{ mcpServers: {...} }` +// (same as ~/.x-code/config.json). The inline form is the raw +// record itself. +// +// 2. Detecting name collisions across plugins. We deduplicate by +// server name — first plugin in iteration order wins, the second's +// entry is dropped with a warning. A future improvement: namespace +// server names with the plugin id. +// +// 3. Logging plugin contributions we don't (yet) support: `commands` +// (we lack a file-based slash command loader) and `hooks` (Task 9 +// will add the hook subsystem; until then, declared hooks are +// noted but not executed). +// +// Plugin order is deterministic — driven by the iteration order of +// `loadAllPlugins`'s `contributions` Map, which itself reflects the +// order of installed_plugins.json + project-local discovery. Stable +// across boots when the same plugins are installed. +import fs from 'node:fs/promises' + +import { HookBus } from '../hooks/bus.js' +import { HookConfigParseError, parseHookConfig } from '../hooks/config-schema.js' +import { HookRegistry, buildHookRegistry } from '../hooks/registry.js' +import type { HookConfig } from '../hooks/types.js' +import { parseServersBlock } from '../mcp/config-schema.js' +import { isStdioConfig } from '../mcp/types.js' +import type { McpServerConfig } from '../mcp/types.js' +import { debugLog } from '../utils.js' +import type { LoadResult, ResolvedContributions } from './loader.js' +import type { InlineMcpServers, LoadedPlugin } from './types.js' +import { getPluginUserConfigEnv } from './user-config.js' + +export interface PluginIntegrationOutput { + /** Extra skill directories the skill loader should scan, with the + * owning plugin id stamped on each. Only enabled plugins included. */ + skillsDirs: Array<{ dir: string; pluginId: string }> + /** Same as above for sub-agent .md files. */ + agentsDirs: Array<{ dir: string; pluginId: string }> + /** Same as above for slash command `*.md` files. Each entry carries + * the owning plugin's rootDir so the command body can substitute + * `${CLAUDE_PLUGIN_ROOT}` at activation time. */ + commandsDirs: Array<{ dir: string; pluginId: string; pluginRoot: string }> + /** Merged `mcpServers` block from every enabled plugin. Name + * collisions resolved first-wins; the losers are recorded in + * `mcpCollisions`. */ + mcpServers: Record + /** Hook registry built from every enabled plugin's `hooks` config. + * Empty when no plugin declared any hooks. Hand this to + * `new HookBus(...)` to wire the agent loop's emit-sites. */ + hookRegistry: HookRegistry + /** Ready-to-use bus over `hookRegistry`. Convenience for the CLI + * startup wiring — `AgentOptions.hookBus = integration.hookBus`. */ + hookBus: HookBus + /** Per-plugin summary of which event names had hooks — used by + * `/plugin doctor` and `/plugin info` UI. */ + pluginHooks: Array<{ pluginId: string; events: string[] }> + /** mcpServers entries dropped due to name collision with an earlier + * plugin. `{ name, droppedFrom, keptFrom }`. */ + mcpCollisions: Array<{ name: string; droppedFrom: string; keptFrom: string }> + /** mcpServers parse / read errors per plugin — these don't block + * startup, they surface in `/plugin doctor`. */ + mcpErrors: Array<{ pluginId: string; message: string }> + /** Hooks parse / read errors per plugin. */ + hookErrors: Array<{ pluginId: string; message: string }> +} + +export async function buildPluginIntegration(load: LoadResult): Promise { + // Hook registry is built last so we can collect the per-plugin configs + // along the way (we don't know all plugins' rootDirs in advance — they + // come from LoadedPlugin). + const hookInputs: Array<{ pluginId: string; pluginDir: string; config: HookConfig }> = [] + + const out: PluginIntegrationOutput = { + skillsDirs: [], + agentsDirs: [], + commandsDirs: [], + mcpServers: {}, + hookRegistry: new HookRegistry(), + hookBus: new HookBus(new HookRegistry()), + pluginHooks: [], + mcpCollisions: [], + mcpErrors: [], + hookErrors: [], + } + const mcpOwners = new Map() + + for (const plugin of load.registry.list()) { + const contrib = load.contributions.get(plugin.id) + if (!contrib) continue + + if (contrib.skillsDir) out.skillsDirs.push({ dir: contrib.skillsDir, pluginId: plugin.id }) + if (contrib.agentsDir) out.agentsDirs.push({ dir: contrib.agentsDir, pluginId: plugin.id }) + if (contrib.commandsDir) { + out.commandsDirs.push({ dir: contrib.commandsDir, pluginId: plugin.id, pluginRoot: plugin.rootDir }) + } + + if (contrib.hooks) { + const config = await resolvePluginHooks(plugin, contrib.hooks, out) + if (config) { + hookInputs.push({ pluginId: plugin.id, pluginDir: plugin.rootDir, config }) + out.pluginHooks.push({ pluginId: plugin.id, events: Object.keys(config) }) + } + } + + if (contrib.mcpServers) { + const servers = await resolvePluginMcpServers(plugin, contrib.mcpServers, out) + for (const [name, cfg] of Object.entries(servers)) { + const prevOwner = mcpOwners.get(name) + if (prevOwner !== undefined) { + out.mcpCollisions.push({ name, droppedFrom: plugin.id, keptFrom: prevOwner }) + continue + } + out.mcpServers[name] = cfg + mcpOwners.set(name, plugin.id) + } + } + } + + out.hookRegistry = buildHookRegistry(hookInputs) + out.hookBus = new HookBus(out.hookRegistry) + return out +} + +async function resolvePluginHooks( + plugin: LoadedPlugin, + contrib: NonNullable, + out: PluginIntegrationOutput, +): Promise { + let raw: unknown + if (contrib.kind === 'inline') { + raw = contrib.data + } else { + try { + const text = await fs.readFile(contrib.path, 'utf-8') + raw = JSON.parse(text) + } catch (err) { + out.hookErrors.push({ + pluginId: plugin.id, + message: `failed to read hooks file ${contrib.path}: ${err instanceof Error ? err.message : String(err)}`, + }) + return null + } + } + try { + return parseHookConfig(raw, plugin.id) + } catch (err) { + out.hookErrors.push({ + pluginId: plugin.id, + message: err instanceof HookConfigParseError ? err.message : String(err), + }) + return null + } +} + +async function resolvePluginMcpServers( + plugin: LoadedPlugin, + contrib: NonNullable, + out: PluginIntegrationOutput, +): Promise> { + let rawBlock: unknown + if (contrib.kind === 'inline') { + rawBlock = contrib.data as InlineMcpServers + } else { + try { + const raw = await fs.readFile(contrib.path, 'utf-8') + const parsed = JSON.parse(raw) as { mcpServers?: unknown } + if (parsed && typeof parsed === 'object' && parsed.mcpServers) { + rawBlock = parsed.mcpServers + } else { + rawBlock = {} + } + } catch (err) { + out.mcpErrors.push({ + pluginId: plugin.id, + message: `failed to read mcpServers file ${contrib.path}: ${err instanceof Error ? err.message : String(err)}`, + }) + return {} + } + } + + const { servers, errors } = parseServersBlock(rawBlock) + for (const e of errors) { + out.mcpErrors.push({ pluginId: plugin.id, message: `mcpServers.${e.name}: ${e.message}` }) + } + + // Merge the owning plugin's userConfig values into each server's env + // map. Authors who want an API key from a userConfig field declared + // in the manifest just reference it as a normal env var inside the + // mcpServers entry (or skip the explicit reference and rely on the + // child process's inherited env). Pre-existing server env entries win + // so an author can override a userConfig value per-server if needed. + try { + const pluginEnv = await getPluginUserConfigEnv(plugin.id) + if (Object.keys(pluginEnv).length > 0) { + for (const name of Object.keys(servers)) { + const cfg = servers[name]! + // Only stdio servers spawn a child process and accept env vars — + // HTTP servers are remote endpoints, env merging is meaningless. + if (isStdioConfig(cfg)) { + servers[name] = { ...cfg, env: { ...pluginEnv, ...(cfg.env ?? {}) } } + } + } + } + } catch (err) { + out.mcpErrors.push({ pluginId: plugin.id, message: `userConfig env merge: ${String(err)}` }) + } + + return servers +} + +/** Convenience: log non-fatal integration diagnostics to debug.log so + * `/plugin doctor` and ad-hoc support can find them. CLI startup calls + * this after `buildPluginIntegration` returns. */ +export function debugLogIntegrationDiagnostics(integration: PluginIntegrationOutput): void { + for (const c of integration.commandsDirs) { + debugLog('plugins.commands-loaded', `${c.pluginId} commands dir: ${c.dir}`) + } + for (const h of integration.pluginHooks) { + debugLog('plugins.hooks-registered', `${h.pluginId} hooks: [${h.events.join(', ')}]`) + } + for (const e of integration.hookErrors) { + debugLog('plugins.hook-error', `${e.pluginId}: ${e.message}`) + } + for (const c of integration.mcpCollisions) { + debugLog('plugins.mcp-collision', `mcpServer "${c.name}" from ${c.droppedFrom} dropped (kept ${c.keptFrom})`) + } + for (const e of integration.mcpErrors) { + debugLog('plugins.mcp-error', `${e.pluginId}: ${e.message}`) + } +} + +// Re-export commonly used pieces so a single import from this module is +// enough for typical CLI startup wiring. +export type { LoadResult, ResolvedContributions } from './loader.js' +export { loadAllPlugins } from './loader.js' diff --git a/packages/core/src/plugins/loader.ts b/packages/core/src/plugins/loader.ts new file mode 100644 index 0000000..0a808a8 --- /dev/null +++ b/packages/core/src/plugins/loader.ts @@ -0,0 +1,307 @@ +// @x-code-cli/core — Plugin startup loader +// +// One-shot orchestration called from the CLI entry. Two passes: +// +// Pass 1 — globally-installed plugins from installed_plugins.json. Each +// record points at a versioned cache dir; we load whichever +// version the record names. Orphan records (record present but +// cache dir missing) surface as PluginLoadError. +// +// Pass 2 — project-local plugins under /.x-code/plugins//. +// These aren't tracked in installed_plugins.json — they're +// committed to the repo as in-tree plugins. Marketplace name +// is always "local" for these. +// +// `installed_plugins.json` is the source of truth for global installs. +// Orphan cache dirs (no record) are silently ignored — they'll be cleaned +// up next time the user runs `/plugin uninstall`. +// +// One broken plugin (bad JSON, missing manifest, schema violation) never +// aborts the boot — errors collect into a `PluginLoadError[]` for +// `/plugin doctor` to surface. +// +// The returned `PluginRegistry` is meant to be frozen for the session +// (same byte-stability constraint as MCP / skills — see CLAUDE.md). The +// CLI calls `loadAllPlugins()` once at startup and stashes the result on +// `AgentOptions`. `/plugin refresh` swaps the in-memory state via +// `registry.reload(...)` and invalidates `systemPromptCache`. +import fs from 'node:fs/promises' +import path from 'node:path' + +import { EnableState } from './enable-state.js' +import { listInstalledPlugins } from './installer.js' +import { ManifestParseError, discoverManifest, parseManifest } from './manifest.js' +import { pluginCacheDir, projectPluginsDir } from './paths.js' +import { PluginRegistry } from './registry.js' +import type { + InlineHookConfig, + InlineMcpServers, + LoadedPlugin, + PluginLoadError, + PluginManifest, + PluginScope, + PluginSource, +} from './types.js' + +export interface LoadOptions { + /** Current working directory. Used to find project-local plugins. */ + cwd: string + /** Skip plugin loading entirely. Wired to the `--no-plugins` startup + * flag. Returns an empty registry. */ + disabled?: boolean +} + +export interface LoadResult { + registry: PluginRegistry + /** Per-plugin resolved contribution paths. Workflow B (skill / agent / + * mcp loader integration) reads from here to merge in plugin-provided + * content. Keyed by plugin id. */ + contributions: Map +} + +/** A plugin's manifest contributions, with relative paths resolved + * against `rootDir`. The `path` / `inline` discriminator on `mcpServers` + * and `hooks` reflects the manifest's union — authors can either point + * at a file or inline the config. */ +export interface ResolvedContributions { + /** Absolute path to the plugin's skills directory, if any. Each + * subdir under here is expected to follow the existing + * `/SKILL.md` layout (so the skill loader can scan it + * without changes). */ + skillsDir?: string + /** Absolute path to the plugin's sub-agent .md files dir. */ + agentsDir?: string + /** Absolute path to the plugin's slash-command .md files dir. */ + commandsDir?: string + /** mcpServers contribution — either a path to a JSON file shaped like + * `{ mcpServers: { ... } }` or the inline record (matches the + * ~/.x-code/config.json `mcpServers` shape). */ + mcpServers?: { kind: 'path'; path: string } | { kind: 'inline'; data: InlineMcpServers } + /** hooks contribution — path to hooks.json or inline object. Schema + * validation lives in packages/core/src/hooks (workflow C). */ + hooks?: { kind: 'path'; path: string } | { kind: 'inline'; data: InlineHookConfig } +} + +export async function loadAllPlugins(opts: LoadOptions): Promise { + if (opts.disabled) { + return { registry: new PluginRegistry([], []), contributions: new Map() } + } + + const enableState = await EnableState.load(opts.cwd) + const plugins: LoadedPlugin[] = [] + const errors: PluginLoadError[] = [] + const contributions = new Map() + + // ── Pass 1: global installs ──────────────────────────────────────────── + const installed = await listInstalledPlugins() + for (const record of installed) { + const rootDir = pluginCacheDir(record.marketplace, record.name, record.version) + await loadOnePlugin({ + rootDir, + fallbackId: record.id, + marketplace: record.marketplace, + scope: record.installScope, + source: record.source, + enableState, + plugins, + errors, + contributions, + }) + } + + // ── Pass 2: project-local plugins ────────────────────────────────────── + const projectRoot = projectPluginsDir(opts.cwd) + let projectEntries: import('node:fs').Dirent[] = [] + try { + projectEntries = await fs.readdir(projectRoot, { withFileTypes: true }) + } catch { + /* no project plugins dir — common case */ + } + for (const entry of projectEntries) { + if (!entry.isDirectory()) continue + const pluginRoot = path.join(projectRoot, entry.name) + await loadOnePlugin({ + rootDir: pluginRoot, + // Provisional id from dirname; overridden by manifest.name when we + // parse it. + fallbackId: `${entry.name}@local`, + marketplace: 'local', + scope: 'project', + source: undefined, + enableState, + plugins, + errors, + contributions, + }) + } + + return { registry: new PluginRegistry(plugins, errors), contributions } +} + +interface LoadOneArgs { + rootDir: string + fallbackId: string + marketplace: string + scope: PluginScope + source: PluginSource | undefined + enableState: EnableState + plugins: LoadedPlugin[] + errors: PluginLoadError[] + contributions: Map +} + +async function loadOnePlugin(args: LoadOneArgs): Promise { + try { + const discovery = await discoverManifest(args.rootDir) + if (!discovery) { + args.errors.push({ + id: args.fallbackId, + path: args.rootDir, + message: + 'no plugin manifest found (looked for .x-code-plugin/plugin.json, .claude-plugin/plugin.json, plugin.json)', + }) + return + } + if (discovery.format === 'gemini') { + args.errors.push({ + id: args.fallbackId, + path: args.rootDir, + message: 'Gemini extensions are not supported (gemini-extension.json detected); see docs/plugins.md', + }) + return + } + + let manifest: PluginManifest + try { + manifest = await parseManifest(discovery.manifestPath) + } catch (err) { + args.errors.push({ + id: args.fallbackId, + path: args.rootDir, + message: err instanceof ManifestParseError ? err.message : String(err), + }) + return + } + + // Canonical id always comes from the manifest, never from the cache + // dir name. For installed plugins this matches the recorded id; for + // project-local plugins it may differ from the dirname and the + // manifest wins. + const id = `${manifest.name}@${args.marketplace}` + const enableResolution = args.enableState.resolve(id) + + const plugin: LoadedPlugin = { + id, + manifest, + rootDir: args.rootDir, + manifestPath: discovery.manifestPath, + manifestFormat: discovery.format, + source: args.source, + marketplace: args.marketplace, + scope: args.scope, + enabled: enableResolution.enabled, + } + args.plugins.push(plugin) + args.contributions.set(id, await resolveContributions(plugin)) + } catch (err) { + args.errors.push({ + id: args.fallbackId, + path: args.rootDir, + message: err instanceof Error ? err.message : String(err), + }) + } +} + +/** Resolve a plugin's manifest contribution fields into absolute paths + * (or inline objects). Exported because individual callers occasionally + * need to recompute this (e.g. `/plugin info` for a single plugin). + * + * **Two discovery passes per contribution kind:** + * + * 1. **Manifest-declared** — if the manifest names a path (e.g. + * `"skills": "./my-skills"`), use that. + * 2. **Convention-based fallback** — if not declared, probe the + * conventional directory (`skills/`, `agents/`, `commands/`) and + * the conventional file (`hooks/hooks.json`, `.mcp.json`, + * `mcp.json`). This is how real Claude Code plugins work — their + * manifests typically only carry `name`/`version`/`description` and + * drop the contributions next to it. + * + * Async because the convention probe has to stat directories. */ +export async function resolveContributions(plugin: LoadedPlugin): Promise { + const m = plugin.manifest + const root = plugin.rootDir + const result: ResolvedContributions = {} + + // skills / agents / commands — directory contributions + if (m.skills) { + result.skillsDir = path.resolve(root, m.skills) + } else if (await isDir(path.join(root, 'skills'))) { + result.skillsDir = path.join(root, 'skills') + } + if (m.agents) { + result.agentsDir = path.resolve(root, m.agents) + } else if (await isDir(path.join(root, 'agents'))) { + result.agentsDir = path.join(root, 'agents') + } + if (m.commands) { + result.commandsDir = path.resolve(root, m.commands) + } else if (await isDir(path.join(root, 'commands'))) { + result.commandsDir = path.join(root, 'commands') + } + + // mcpServers — either declared (path / inline) or auto-discovered + // from a conventional file + if (m.mcpServers !== undefined) { + if (typeof m.mcpServers === 'string') { + result.mcpServers = { kind: 'path', path: path.resolve(root, m.mcpServers) } + } else { + result.mcpServers = { kind: 'inline', data: m.mcpServers } + } + } else { + // Claude Code convention: `.mcp.json` at plugin root. We also + // accept `mcp.json` (without dot) as a pragmatic fallback — + // some authors use the visible form. + for (const conv of ['.mcp.json', 'mcp.json']) { + const p = path.join(root, conv) + if (await isFile(p)) { + result.mcpServers = { kind: 'path', path: p } + break + } + } + } + + // hooks — same pattern, conventional file `hooks/hooks.json` + if (m.hooks !== undefined) { + if (typeof m.hooks === 'string') { + result.hooks = { kind: 'path', path: path.resolve(root, m.hooks) } + } else { + result.hooks = { kind: 'inline', data: m.hooks } + } + } else { + const conv = path.join(root, 'hooks', 'hooks.json') + if (await isFile(conv)) { + result.hooks = { kind: 'path', path: conv } + } + } + + return result +} + +async function isDir(p: string): Promise { + try { + const s = await fs.stat(p) + return s.isDirectory() + } catch { + return false + } +} + +async function isFile(p: string): Promise { + try { + const s = await fs.stat(p) + return s.isFile() + } catch { + return false + } +} diff --git a/packages/core/src/plugins/manifest.ts b/packages/core/src/plugins/manifest.ts new file mode 100644 index 0000000..c9c579e --- /dev/null +++ b/packages/core/src/plugins/manifest.ts @@ -0,0 +1,174 @@ +// @x-code-cli/core — Plugin manifest discovery + zod validation +// +// One job: given a plugin root directory on disk, find its manifest +// (probing the three accepted relative paths in priority order), parse + +// validate the JSON, and return a `PluginManifest`. The caller resolves +// contribution paths and figures out scope / enable state. +// +// Unknown top-level fields in the manifest are silently stripped (zod's +// default behaviour with `z.object`). This is intentional: it lets newer +// Claude Code manifests with fields we don't understand (e.g. +// `output-styles`, `lspServers`) still parse — we just don't act on them. +// `/plugin doctor` later surfaces them as "loaded but contributing X +// unsupported fields" so users know they're getting partial behaviour. +import fs from 'node:fs/promises' +import path from 'node:path' + +import { z } from 'zod' + +import { GEMINI_MANIFEST_REL, MANIFEST_CANDIDATES } from './paths.js' +import type { ManifestFormat, PluginManifest } from './types.js' + +// ── Zod schemas ───────────────────────────────────────────────────────── + +const authorSchema = z.union([ + z.string(), + z.object({ + name: z.string().optional(), + email: z.string().optional(), + url: z.string().optional(), + }), +]) + +const userConfigItemSchema = z.object({ + key: z.string().min(1), + type: z.enum(['string', 'number', 'boolean']), + sensitive: z.boolean().optional(), + prompt: z.string().optional(), + required: z.boolean().optional(), + default: z.union([z.string(), z.number(), z.boolean()]).optional(), + description: z.string().optional(), +}) + +/** Some contribution fields accept either a relative path (string) OR an + * inline object — Claude Code's `mcpServers` and `hooks` work this way. + * We don't validate the inline object's shape here; that's the job of + * the mcp / hooks subsystems, which already own their own schemas. */ +const pathOrInline = z.union([z.string().min(1), z.record(z.string(), z.unknown())]) + +/** Plugin name: lowercase letters, digits, dashes; must start with a + * letter or digit. Matches Claude Code / Codex / Gemini and keeps names + * safe to use as filesystem path components on Windows. */ +const NAME_RE = /^[a-z0-9][a-z0-9-]*$/ + +const manifestSchema = z.object({ + schemaVersion: z.string().optional(), + name: z + .string() + .min(1) + .regex(NAME_RE, 'name must be lowercase letters, digits, and dashes only (e.g. "linear-issues")'), + // version is optional in real Claude Code plugins (verified against + // anthropics/claude-plugins-official — many ship without one, + // including major third-party plugins like amplitude). We default + // to "0.0.0" so cache paths and the installed_plugins.json record + // still have a usable string. + version: z.string().min(1).optional(), + description: z.string().optional(), + author: authorSchema.optional(), + keywords: z.array(z.string()).optional(), + homepage: z.string().optional(), + license: z.string().optional(), + + skills: z.string().min(1).optional(), + agents: z.string().min(1).optional(), + commands: z.string().min(1).optional(), + mcpServers: pathOrInline.optional(), + hooks: pathOrInline.optional(), + + userConfig: z.array(userConfigItemSchema).optional(), + dependencies: z.array(z.string().min(1)).optional(), + engines: z.object({ 'x-code': z.string().optional() }).optional(), +}) + +// ── Discovery ─────────────────────────────────────────────────────────── + +export interface ManifestDiscovery { + /** Absolute path to the manifest file. */ + manifestPath: string + format: ManifestFormat +} + +/** Probe a plugin root for a manifest. Returns the highest-priority + * match. Returns `{ format: 'gemini', ... }` when ONLY a Gemini manifest + * exists — the installer uses this to produce a friendly "we don't + * support Gemini extensions" error rather than a confusing + * "no manifest found". */ +export async function discoverManifest(rootDir: string): Promise { + for (const candidate of MANIFEST_CANDIDATES) { + const full = path.join(rootDir, candidate.rel) + if (await fileExists(full)) { + return { manifestPath: full, format: candidate.format } + } + } + const gemini = path.join(rootDir, GEMINI_MANIFEST_REL) + if (await fileExists(gemini)) { + return { manifestPath: gemini, format: 'gemini' } + } + return null +} + +// ── Parsing ───────────────────────────────────────────────────────────── + +export class ManifestParseError extends Error { + constructor( + message: string, + public readonly manifestPath: string, + ) { + super(message) + this.name = 'ManifestParseError' + } +} + +/** Parse + validate a manifest JSON file. Fills in `schemaVersion: "1"` + * when absent (the implicit default — most existing Claude Code plugins + * don't set this field). Throws `ManifestParseError` with a path-tagged + * message on failure so the loader can collect it as a doctor entry + * without aborting the whole boot. */ +export async function parseManifest(manifestPath: string): Promise { + let raw: string + try { + raw = await fs.readFile(manifestPath, 'utf-8') + } catch (err) { + throw new ManifestParseError( + `failed to read manifest: ${err instanceof Error ? err.message : String(err)}`, + manifestPath, + ) + } + + let json: unknown + try { + json = JSON.parse(raw) + } catch (err) { + throw new ManifestParseError( + `manifest is not valid JSON: ${err instanceof Error ? err.message : String(err)}`, + manifestPath, + ) + } + + const result = manifestSchema.safeParse(json) + if (!result.success) { + const issues = result.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ') + throw new ManifestParseError(`invalid manifest — ${issues}`, manifestPath) + } + + const data = result.data + return { + ...data, + schemaVersion: data.schemaVersion ?? '1', + version: data.version ?? '0.0.0', + // Normalise the author union — internal callers only deal with the + // object form. String authors are turned into `{ name: }`. + author: typeof data.author === 'string' ? { name: data.author } : data.author, + } +} + +// ── Helpers ───────────────────────────────────────────────────────────── + +async function fileExists(p: string): Promise { + try { + await fs.access(p) + return true + } catch { + return false + } +} diff --git a/packages/core/src/plugins/marketplace.ts b/packages/core/src/plugins/marketplace.ts new file mode 100644 index 0000000..2c88738 --- /dev/null +++ b/packages/core/src/plugins/marketplace.ts @@ -0,0 +1,557 @@ +// @x-code-cli/core — Marketplace subscription + index parsing +// +// A marketplace is a curated catalog of plugins (its `marketplace.json` +// is a list of `{ name, source, ... }` entries). The CLI doesn't host +// its own marketplace — see [[plugin-marketplace-design]] §7.1 for the +// "subscribe to others" rationale. This module: +// +// 1. Reads + writes `known_marketplaces.json` (the user's subscription +// list) with reserved-name protection. +// 2. Fetches and caches marketplace indexes from either an HTTPS URL +// pointing to the raw marketplace.json or a git URL (we clone +// shallow and read `.claude-plugin/marketplace.json`, which is the +// path real Claude Code marketplaces publish at). +// 3. Parses marketplace.json into a typed `Marketplace`, normalising +// each plugin's `source` field from the on-disk wire form +// (string shortcut, `git-subdir`, `url`, …) into our internal +// `PluginSource` so the installer only deals with one shape. +// 4. Looks up `name@marketplace` plugin ids → install sources. +// +// Wire format vs internal `PluginSource`: the real Claude Code spec +// uses `source` as the discriminator with values `'git-subdir'`, +// `'url'`, etc., plus a plain string shortcut for monorepo subdirs +// (`"./plugins/foo"`). We map all of those to `PluginSource` so the +// rest of the system can stay on one shape. See +// [[normalizeMarketplaceSource]] for the conversion table. +// +// All disk + network I/O accepts an AbortSignal so Esc cancellations +// from the agent loop propagate cleanly. +import { execa } from 'execa' + +import fs from 'node:fs/promises' +import os from 'node:os' +import path from 'node:path' + +import { z } from 'zod' + +import { debugLog } from '../utils.js' +import { knownMarketplacesPath, marketplaceDir, marketplaceIndexPath } from './paths.js' +import type { KnownMarketplace, KnownMarketplaces, Marketplace, MarketplaceEntry, PluginSource } from './types.js' + +// ── Reserved marketplace names ────────────────────────────────────────── + +/** Names that may only be registered if their source matches the canonical + * upstream. Prevents a malicious actor from publishing + * `anthropic-marketplace` from their own repo and impersonating Anthropic. + * Maps to expected GitHub org. */ +export const RESERVED_MARKETPLACE_NAMES: Readonly> = { + 'anthropic-marketplace': 'anthropics', + 'claude-plugins': 'anthropics', + 'x-code-official': 'woai3c', +} + +// ── Source normalisation (wire format → internal PluginSource) ────────── + +/** Convert a marketplace `source` field (in its on-disk wire form) into + * our internal `PluginSource`. Supports every shape we've seen in real + * Claude Code marketplaces: + * + * | Wire form | Normalised PluginSource | + * |-------------------------------------------------------------|--------------------------------------------------| + * | `"./plugins/foo"` or `"../shared/x"` | `{kind:'git', url:, subdir:'plugins/foo'}` | + * | `"github:owner/repo[#ref]"` | `{kind:'github', owner, repo, ref?}` | + * | `"https://…"` or `"git@…"` | `{kind:'git', url}` | + * | `{source:'git-subdir', url, path, ref?, sha?}` | `{kind:'git', url, ref?, subdir:path}` | + * | `{source:'url', url, sha?}` | `{kind:'git', url}` | + * | `{source:'git', url, ref?, subdir?}` | `{kind:'git', url, ref?, subdir?}` | + * | `{source:'github', owner, repo, ref?, subdir?}` | `{kind:'github', owner, repo, ref?, subdir?}` | + * | `{source:'local', path}` | `{kind:'local', path}` | + * | `{kind:'git'\|'github'\|'local', …}` (our legacy form) | passes through | + * + * The relative-string form (`./plugins/foo`) needs the marketplace's + * own clone URL — that's the repo we'll subdir into. Passed in via + * `ctx.marketplaceCloneUrl`. Throws when the string is relative but + * no context was provided (HTTPS-fetched marketplaces can't host + * relative-path plugins for obvious reasons). + * + * The `sha` field from `git-subdir` / `url` is intentionally dropped + * today — we don't yet verify integrity. Reserved for a follow-up. */ +export function normalizeMarketplaceSource(raw: unknown, ctx: { marketplaceCloneUrl?: string } = {}): PluginSource { + if (typeof raw === 'string') { + if (raw.startsWith('./') || raw.startsWith('../')) { + const cloneUrl = ctx.marketplaceCloneUrl + if (!cloneUrl) { + throw new Error( + `relative source "${raw}" requires the marketplace's own clone URL, but the marketplace was fetched without one (typically because it was loaded from a raw HTTPS URL rather than a git repo)`, + ) + } + const subdir = raw.replace(/^\.\//, '') + return { kind: 'git', url: cloneUrl, subdir } + } + if (raw.startsWith('github:')) { + const m = raw.match(/^github:([^/]+)\/(.+?)(?:#(.+))?$/i) + if (!m) throw new Error(`invalid github source: ${raw}`) + return { kind: 'github', owner: m[1]!, repo: m[2]!, ref: m[3] } + } + if (/^https?:\/\//i.test(raw) || raw.startsWith('git@')) { + return { kind: 'git', url: raw } + } + throw new Error(`unrecognised source string: ${raw}`) + } + + if (raw && typeof raw === 'object') { + const o = raw as Record + const disc = (typeof o.source === 'string' ? o.source : (o.kind as string | undefined)) as string | undefined + + if (disc === 'git-subdir') { + if (typeof o.url !== 'string' || typeof o.path !== 'string') { + throw new Error('git-subdir source requires `url` and `path`') + } + return { + kind: 'git', + url: o.url, + subdir: o.path, + ref: typeof o.ref === 'string' ? o.ref : undefined, + } + } + if (disc === 'url') { + if (typeof o.url !== 'string') throw new Error('url source requires `url`') + return { kind: 'git', url: o.url } + } + if (disc === 'git') { + if (typeof o.url !== 'string') throw new Error('git source requires `url`') + return { + kind: 'git', + url: o.url, + ref: typeof o.ref === 'string' ? o.ref : undefined, + subdir: typeof o.subdir === 'string' ? o.subdir : undefined, + } + } + if (disc === 'github') { + // Two real-world shapes for github sources: + // { owner, repo, ref?, subdir? } — separate owner / repo + // { repo: "owner/repo" } — combined slash-form (seen in real + // claude-plugins-official entries) + let owner = typeof o.owner === 'string' ? o.owner : undefined + let repo = typeof o.repo === 'string' ? o.repo : undefined + if (!owner && repo && repo.includes('/')) { + const slash = repo.indexOf('/') + owner = repo.slice(0, slash) + repo = repo.slice(slash + 1) + } + if (!owner || !repo) { + throw new Error('github source requires `owner` + `repo` or `repo: "owner/repo"`') + } + const ref = typeof o.ref === 'string' ? o.ref : typeof o.commit === 'string' ? o.commit : undefined + return { + kind: 'github', + owner, + repo, + ref, + subdir: typeof o.subdir === 'string' ? o.subdir : undefined, + } + } + if (disc === 'local') { + if (typeof o.path !== 'string') throw new Error('local source requires `path`') + return { kind: 'local', path: o.path } + } + throw new Error( + `unknown source discriminator: ${disc ?? '(missing)'} — accepted: git-subdir, url, git, github, local`, + ) + } + + throw new Error('source must be a string or object') +} + +// ── Zod schemas for marketplace.json ──────────────────────────────────── + +// `source` is validated as "string OR object" at the zod layer; the real +// shape check happens inside `normalizeMarketplaceSource` because the +// union has too many discriminator forms (some use `source`, some use +// `kind`) for zod's discriminated union to handle cleanly. +const wireSourceSchema = z.union([z.string().min(1), z.record(z.string(), z.unknown())]) + +const wireEntrySchema = z.object({ + name: z.string().min(1), + description: z.string().optional(), + category: z.string().optional(), + verified: z.boolean().optional(), + source: wireSourceSchema, + version: z.string().optional(), + homepage: z.string().optional(), + keywords: z.array(z.string()).optional(), + // Real Claude Code plugin entries also carry top-level `author`. Not + // currently part of MarketplaceEntry but accept to avoid rejecting. + author: z.unknown().optional(), +}) + +const wireMarketplaceSchema = z.object({ + schemaVersion: z.string().optional(), + name: z.string().min(1), + displayName: z.string().optional(), + description: z.string().optional(), + owner: z + .object({ + name: z.string().optional(), + url: z.string().optional(), + email: z.string().optional(), + }) + .optional(), + plugins: z.array(wireEntrySchema), +}) + +export class MarketplaceParseError extends Error { + constructor( + message: string, + public readonly sourceLabel: string, + ) { + super(message) + this.name = 'MarketplaceParseError' + } +} + +export interface ParseMarketplaceContext { + /** The git clone URL of the marketplace's own repo, used to resolve + * relative-string sources like `"./plugins/foo"`. Absent when the + * marketplace was fetched from a raw HTTPS URL (those can't host + * relative plugins). */ + marketplaceCloneUrl?: string +} + +/** Parse + validate a marketplace.json string and normalise every + * plugin's `source` into our internal `PluginSource`. `sourceLabel` is + * included in error messages so the user knows which marketplace + * failed. */ +export function parseMarketplace(raw: string, sourceLabel: string, ctx: ParseMarketplaceContext = {}): Marketplace { + let json: unknown + try { + json = JSON.parse(raw) + } catch (err) { + throw new MarketplaceParseError(`not valid JSON: ${err instanceof Error ? err.message : String(err)}`, sourceLabel) + } + const result = wireMarketplaceSchema.safeParse(json) + if (!result.success) { + const issues = result.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ') + throw new MarketplaceParseError(`invalid marketplace.json — ${issues}`, sourceLabel) + } + + const normalised: MarketplaceEntry[] = [] + const sourceErrors: string[] = [] + for (let i = 0; i < result.data.plugins.length; i++) { + const entry = result.data.plugins[i]! + try { + const source = normalizeMarketplaceSource(entry.source, ctx) + normalised.push({ + name: entry.name, + description: entry.description, + category: entry.category, + verified: entry.verified, + version: entry.version, + homepage: entry.homepage, + keywords: entry.keywords, + source, + }) + } catch (err) { + // One bad plugin entry doesn't kill the marketplace — most users + // care about other plugins in the catalog. Collect and surface in + // a single error AFTER trying every entry. + sourceErrors.push(`plugins.${i} (${entry.name}): ${err instanceof Error ? err.message : String(err)}`) + } + } + if (normalised.length === 0 && sourceErrors.length > 0) { + throw new MarketplaceParseError(`no plugin entries parsed — ${sourceErrors.join('; ')}`, sourceLabel) + } + if (sourceErrors.length > 0) { + debugLog('plugins.marketplace-source-errors', `${sourceLabel}: ${sourceErrors.join(' | ')}`) + } + + return { + schemaVersion: result.data.schemaVersion ?? '1', + name: result.data.name, + displayName: result.data.displayName, + description: result.data.description, + owner: result.data.owner ? { name: result.data.owner.name, url: result.data.owner.url } : undefined, + plugins: normalised, + } +} + +// ── known_marketplaces.json: read / write ─────────────────────────────── + +/** Fresh empty state. Function (not const) so each call returns a fresh + * `marketplaces: []` — a shared constant would let one caller's mutation + * leak into the next caller's "empty" result. */ +function freshKnown(): KnownMarketplaces { + return { marketplaces: [] } +} + +export async function readKnownMarketplaces(): Promise { + const file = knownMarketplacesPath() + try { + const raw = await fs.readFile(file, 'utf-8') + const parsed = JSON.parse(raw) as unknown + if (!parsed || typeof parsed !== 'object') return freshKnown() + const obj = parsed as Record + const list = Array.isArray(obj.marketplaces) ? (obj.marketplaces as KnownMarketplace[]) : [] + return { + marketplaces: list.filter((m) => m && typeof m.name === 'string' && typeof m.source === 'string'), + strictKnownMarketplaces: + typeof obj.strictKnownMarketplaces === 'boolean' ? obj.strictKnownMarketplaces : undefined, + blockedPlugins: Array.isArray(obj.blockedPlugins) + ? (obj.blockedPlugins as unknown[]).filter((s): s is string => typeof s === 'string') + : undefined, + } + } catch (err) { + if ((err as NodeJS.ErrnoException).code === 'ENOENT') return freshKnown() + debugLog('plugins.known-marketplaces-read-failed', String(err)) + return freshKnown() + } +} + +async function writeKnownMarketplaces(km: KnownMarketplaces): Promise { + const file = knownMarketplacesPath() + await fs.mkdir(path.dirname(file), { recursive: true }) + // Read-modify-write so any unrelated future fields aren't clobbered. + let existing: Record = {} + try { + const raw = await fs.readFile(file, 'utf-8') + const parsed = JSON.parse(raw) as unknown + if (parsed && typeof parsed === 'object') existing = parsed as Record + } catch { + // first write + } + existing.marketplaces = km.marketplaces + if (km.strictKnownMarketplaces !== undefined) existing.strictKnownMarketplaces = km.strictKnownMarketplaces + if (km.blockedPlugins !== undefined) existing.blockedPlugins = km.blockedPlugins + await fs.writeFile(file, JSON.stringify(existing, null, 2) + '\n', 'utf-8') +} + +/** Ensure the default marketplace subscriptions exist. Called from CLI + * startup so a fresh install lands with Anthropic's official + * marketplace pre-subscribed and `/plugin search` returns hits without + * the user having to manually add anything. Idempotent — never + * overwrites an existing entry, so a user who removed the + * subscription stays unsubscribed. + * + * Target is `anthropics/claude-plugins-official` (203 plugins) rather + * than the smaller bundled marketplace in `anthropics/claude-code` + * itself — the dedicated repo is the canonical discovery surface. */ +export async function ensureDefaultMarketplaces(): Promise { + const km = await readKnownMarketplaces() + const haveAnthropic = km.marketplaces.some((m) => m.name === 'anthropic-marketplace') + if (haveAnthropic) return + + // Use addKnownMarketplace so the reserved-name check fires — it + // sets `reservedName: true` + `officialSource: 'anthropics'`. + try { + await addKnownMarketplace({ + name: 'anthropic-marketplace', + source: 'github:anthropics/claude-plugins-official', + }) + } catch (err) { + debugLog('plugins.default-marketplace-add-failed', String(err)) + } +} + +/** Register a new marketplace subscription. Rejects reserved names whose + * source doesn't match the canonical upstream — see + * RESERVED_MARKETPLACE_NAMES. Idempotent: re-adding the same name + * updates the source. */ +export async function addKnownMarketplace(entry: KnownMarketplace): Promise { + const reservedOrg = RESERVED_MARKETPLACE_NAMES[entry.name] + if (reservedOrg !== undefined) { + if (!sourceMatchesOrg(entry.source, reservedOrg)) { + throw new Error( + `Marketplace name "${entry.name}" is reserved; only sources under github:${reservedOrg}/* may use it. ` + + `Got: ${entry.source}`, + ) + } + entry.reservedName = true + entry.officialSource = reservedOrg + } + + const km = await readKnownMarketplaces() + const idx = km.marketplaces.findIndex((m) => m.name === entry.name) + if (idx >= 0) { + km.marketplaces[idx] = entry + } else { + km.marketplaces.push(entry) + } + await writeKnownMarketplaces(km) +} + +export async function removeKnownMarketplace(name: string): Promise<'removed' | 'noop'> { + const km = await readKnownMarketplaces() + const before = km.marketplaces.length + km.marketplaces = km.marketplaces.filter((m) => m.name !== name) + if (km.marketplaces.length === before) return 'noop' + await writeKnownMarketplaces(km) + return 'removed' +} + +function sourceMatchesOrg(source: string, expectedOrg: string): boolean { + // Accepts `github:org/repo[...]` and `https://github.com/org/repo[...]`. + const ghShort = source.match(/^github:([^/]+)\//i) + if (ghShort) return ghShort[1]!.toLowerCase() === expectedOrg.toLowerCase() + const ghHttps = source.match(/^https?:\/\/github\.com\/([^/]+)\//i) + if (ghHttps) return ghHttps[1]!.toLowerCase() === expectedOrg.toLowerCase() + return false +} + +// ── Fetch / refresh a marketplace index ───────────────────────────────── + +export interface FetchOptions { + signal?: AbortSignal + /** Skip network if a cached index exists and is younger than this. */ + maxAgeMs?: number +} + +/** Pull a fresh marketplace.json into the local cache and parse it. + * Supports two source shapes: + * + * - `https://...` or `http://...` — direct URL to marketplace.json + * - anything else (`github:owner/repo`, git URL) — shallow clone, + * then read `.claude-plugin/marketplace.json` (the canonical + * Claude Code path — see `anthropics/claude-code` and + * `anthropics/claude-plugins-official` for reference layouts) + * + * Writes the parsed file to ~/.x-code/plugins/marketplaces//marketplace.json + * before returning. */ +export async function fetchMarketplace(entry: KnownMarketplace, opts: FetchOptions = {}): Promise { + const cachedPath = marketplaceIndexPath(entry.name) + + if (opts.maxAgeMs !== undefined) { + const fresh = await isFreshEnough(cachedPath, opts.maxAgeMs) + if (fresh) { + const raw = await fs.readFile(cachedPath, 'utf-8') + return parseMarketplace(raw, entry.name, contextForKnownEntry(entry)) + } + } + + const isHttp = /^https?:\/\//i.test(entry.source) && /\.json($|\?)/i.test(entry.source) + const rawJson = isHttp + ? await fetchHttpJson(entry.source, opts.signal) + : await fetchViaShallowClone(entry.source, opts.signal) + + const marketplace = parseMarketplace(rawJson, entry.name, contextForKnownEntry(entry)) + + await fs.mkdir(marketplaceDir(entry.name), { recursive: true }) + await fs.writeFile(cachedPath, rawJson, 'utf-8') + + return marketplace +} + +/** Build the `ParseMarketplaceContext` from a known marketplace entry. + * For git-cloned marketplaces this provides the clone URL so plugin + * entries with relative-string sources like `"./plugins/foo"` resolve + * to that subdir of the marketplace's own repo. For raw-HTTPS + * marketplaces no clone URL exists; relative sources in such + * marketplaces fail to normalise (correctly — there's no repo to + * refer to). */ +function contextForKnownEntry(entry: KnownMarketplace): ParseMarketplaceContext { + const isRawHttps = /^https?:\/\//i.test(entry.source) && /\.json($|\?)/i.test(entry.source) + if (isRawHttps) return {} + return { marketplaceCloneUrl: resolveCloneUrl(entry.source) } +} + +async function isFreshEnough(filePath: string, maxAgeMs: number): Promise { + try { + const stat = await fs.stat(filePath) + return Date.now() - stat.mtimeMs <= maxAgeMs + } catch { + return false + } +} + +async function fetchHttpJson(url: string, signal?: AbortSignal): Promise { + const res = await fetch(url, { signal }) + if (!res.ok) { + throw new Error(`HTTP ${res.status} ${res.statusText} fetching ${url}`) + } + return res.text() +} + +/** Clone the repo at the given source into a temp dir (depth 1) and + * return the contents of the marketplace index. Probes the canonical + * `.claude-plugin/marketplace.json` first and falls back to a + * root-level `marketplace.json` for non-standard layouts. The clone + * is removed before returning regardless of success. */ +async function fetchViaShallowClone(source: string, signal?: AbortSignal): Promise { + const cloneUrl = resolveCloneUrl(source) + const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-marketplace-')) + try { + await execa('git', ['clone', '--depth', '1', cloneUrl, tempDir], { signal, stdio: 'pipe' }) + const candidates = [ + path.join(tempDir, '.claude-plugin', 'marketplace.json'), + path.join(tempDir, 'marketplace.json'), + ] + for (const candidate of candidates) { + try { + return await fs.readFile(candidate, 'utf-8') + } catch { + // try the next candidate + } + } + throw new Error( + `marketplace repo ${cloneUrl} has no .claude-plugin/marketplace.json (also tried root marketplace.json)`, + ) + } finally { + await fs.rm(tempDir, { recursive: true, force: true }).catch(() => { + /* best effort */ + }) + } +} + +/** Turn a source string into something `git clone` understands: + * `github:owner/repo` → `https://github.com/owner/repo.git`. Anything + * else is passed through (real git URLs, ssh:, etc.). */ +export function resolveCloneUrl(source: string): string { + const m = source.match(/^github:([^/]+)\/(.+?)(?:\.git)?$/i) + if (m) { + return `https://github.com/${m[1]}/${m[2]}.git` + } + return source +} + +// ── Lookup helpers ────────────────────────────────────────────────────── + +/** Read every cached marketplace index. Used by `/plugin search` and + * `/plugin install ` lookups. Marketplaces with broken + * cached indexes are skipped + logged; one bad marketplace doesn't break + * the others. */ +export async function readAllCachedMarketplaces(): Promise { + const km = await readKnownMarketplaces() + const out: Marketplace[] = [] + for (const entry of km.marketplaces) { + try { + const raw = await fs.readFile(marketplaceIndexPath(entry.name), 'utf-8') + out.push(parseMarketplace(raw, entry.name, contextForKnownEntry(entry))) + } catch (err) { + debugLog('plugins.marketplace-cache-read-failed', `${entry.name}: ${String(err)}`) + } + } + return out +} + +/** Find one plugin entry by `name@marketplace` id. Returns `undefined` + * when the marketplace isn't subscribed or the plugin isn't listed. */ +export async function lookupPlugin( + pluginId: string, +): Promise<{ marketplace: Marketplace; entry: MarketplaceEntry } | undefined> { + const at = pluginId.lastIndexOf('@') + if (at <= 0) return undefined + const pluginName = pluginId.slice(0, at) + const marketplaceName = pluginId.slice(at + 1) + + const km = await readKnownMarketplaces() + const known = km.marketplaces.find((m) => m.name === marketplaceName) + + try { + const raw = await fs.readFile(marketplaceIndexPath(marketplaceName), 'utf-8') + const m = parseMarketplace(raw, marketplaceName, known ? contextForKnownEntry(known) : {}) + const entry = m.plugins.find((p) => p.name === pluginName) + if (!entry) return undefined + return { marketplace: m, entry } + } catch { + return undefined + } +} diff --git a/packages/core/src/plugins/paths.ts b/packages/core/src/plugins/paths.ts new file mode 100644 index 0000000..db9a10d --- /dev/null +++ b/packages/core/src/plugins/paths.ts @@ -0,0 +1,96 @@ +// @x-code-cli/core — Plugin filesystem layout +// +// Centralised path helpers for the plugin subsystem. Every other plugin +// module asks here rather than re-deriving paths so that the +// `XC_PLUGINS_DIR` test override has a single chokepoint. +// +// Layout (under ~/.x-code/plugins/ by default): +// +// known_marketplaces.json — subscribed marketplaces registry +// marketplaces//marketplace.json +// — cached marketplace index +// cache//// +// — actual installed plugin contents +// data// — plugin's persistent data dir +// (survives upgrades; plugin-id is +// "name@marketplace" with path +// separators sanitised) +// installed_plugins.json — bookkeeping of installed plugins +import path from 'node:path' + +import { GLOBAL_XCODE_DIR, XCODE_DIR } from '../utils.js' + +const PLUGINS_DIR_NAME = 'plugins' + +/** Root of the plugin subsystem. Override via `XC_PLUGINS_DIR` (used by + * tests; works the same way as `XC_AGENTS_DIR` / `XC_SKILLS_DIR`). */ +export function pluginsRoot(): string { + const override = process.env.XC_PLUGINS_DIR + if (override) return override + return path.join(GLOBAL_XCODE_DIR, PLUGINS_DIR_NAME) +} + +/** ~/.x-code/plugins/known_marketplaces.json */ +export function knownMarketplacesPath(): string { + return path.join(pluginsRoot(), 'known_marketplaces.json') +} + +/** ~/.x-code/plugins/marketplaces// */ +export function marketplaceDir(name: string): string { + return path.join(pluginsRoot(), 'marketplaces', name) +} + +/** ~/.x-code/plugins/marketplaces//marketplace.json */ +export function marketplaceIndexPath(name: string): string { + return path.join(marketplaceDir(name), 'marketplace.json') +} + +/** ~/.x-code/plugins/cache/// — all versions live + * under this directory; the active version is whichever the installer + * recorded most recently in installed_plugins.json. */ +export function pluginCacheParent(marketplace: string, plugin: string): string { + return path.join(pluginsRoot(), 'cache', marketplace, plugin) +} + +/** ~/.x-code/plugins/cache//// */ +export function pluginCacheDir(marketplace: string, plugin: string, version: string): string { + return path.join(pluginCacheParent(marketplace, plugin), version) +} + +/** ~/.x-code/plugins/data// — persistent per-plugin + * data dir that survives upgrades. Plugin IDs ("name@marketplace") are + * sanitised so the `@` and any accidental path separators don't break + * on Windows. */ +export function pluginDataDir(pluginId: string): string { + const safe = pluginId.replace(/[/\\:]/g, '_') + return path.join(pluginsRoot(), 'data', safe) +} + +/** ~/.x-code/plugins/installed_plugins.json */ +export function installedPluginsPath(): string { + return path.join(pluginsRoot(), 'installed_plugins.json') +} + +/** /.x-code/plugins/ — rare; used when a project ships its own + * plugins committed to the repo (vs. installing from a marketplace). + * The loader scans this in addition to the global cache. */ +export function projectPluginsDir(cwd: string): string { + return path.join(cwd, XCODE_DIR, 'plugins') +} + +// ── Manifest discovery within a plugin root ───────────────────────────── + +/** Relative manifest paths the loader probes, in priority order. The first + * one found wins. We deliberately accept Claude Code's path so plugins + * authored for Claude Code install in x-code-cli without modification — + * see [[plugin-marketplace-design]] §3 (cross-product compatibility). */ +export const MANIFEST_CANDIDATES: ReadonlyArray<{ format: 'native' | 'claude' | 'bare'; rel: string }> = [ + { format: 'native', rel: '.x-code-plugin/plugin.json' }, + { format: 'claude', rel: '.claude-plugin/plugin.json' }, + { format: 'bare', rel: 'plugin.json' }, +] + +/** Gemini's manifest filename. Probed only to produce a helpful error + * message when a user tries to install a Gemini-only extension — + * installer rejects with a pointer to the design doc. */ +export const GEMINI_MANIFEST_REL = 'gemini-extension.json' diff --git a/packages/core/src/plugins/refresh.ts b/packages/core/src/plugins/refresh.ts new file mode 100644 index 0000000..40c206b --- /dev/null +++ b/packages/core/src/plugins/refresh.ts @@ -0,0 +1,120 @@ +// @x-code-cli/core — Plugin hot-reload orchestrator +// +// `/plugin refresh` enters here. The job is to re-scan installed plugins +// from disk and propagate the new state to every downstream registry +// without restarting xc. +// +// Why this is its own module and not a method on PluginRegistry: +// reloading the plugin registry itself is one line — the work is folding +// the new contributions into the FOUR sub-registries the rest of the +// agent loop captured at startup (skill / sub-agent / command / hook). +// Each captured reference must stay stable, so each registry exposes a +// reload-in-place method instead of returning a new instance. +// +// Not handled here: MCP servers. Plugin-contributed MCP servers spawn +// child processes at startup; restarting them mid-session needs the +// MCP-specific orchestration that already lives behind `/mcp refresh`. +// The user can run that separately if they need MCP changes to land. +import { reloadSubAgentRegistry } from '../agent/sub-agents/registry.js' +import type { SubAgentRegistry, SubAgentReloadSummary } from '../agent/sub-agents/registry.js' +import { reloadCommandRegistry } from '../commands/registry.js' +import type { CommandRegistry, CommandReloadSummary } from '../commands/registry.js' +import type { HookBus } from '../hooks/bus.js' +import type { HookRegistry } from '../hooks/registry.js' +import { reloadSkillRegistry } from '../skills/registry.js' +import type { SkillRegistry, SkillReloadSummary } from '../skills/registry.js' +import { buildPluginIntegration } from './integration.js' +import { loadAllPlugins } from './loader.js' +import type { PluginRegistry, PluginReloadSummary } from './registry.js' + +export interface PluginRefreshSummary { + /** Plugin-level diff — what plugins appeared / disappeared / changed. + * This is the headline the /plugin refresh message renders. */ + plugins: PluginReloadSummary + /** Per-sub-registry diffs — useful for /plugin doctor-style detail. + * Each is optional because a caller may not have wired every registry + * (e.g. tests skip them). */ + skills?: SkillReloadSummary + subAgents?: SubAgentReloadSummary + commands?: CommandReloadSummary + /** Number of hook entries registered after refresh — surfaced for + * user feedback. We don't compute a per-event diff because hooks + * don't have a stable identity (no name field); the count alone is + * enough to confirm "hooks reloaded". */ + hookCount: number +} + +export interface PluginRefreshTargets { + pluginRegistry: PluginRegistry + /** Sub-registries that should fold in the new plugin contributions. + * Pass whichever ones the caller has wired. */ + skillRegistry?: SkillRegistry + subAgentRegistry?: SubAgentRegistry + commandRegistry?: CommandRegistry + hookBus?: HookBus + /** cwd defaults to process.cwd(); overridable for tests. */ + cwd?: string +} + +/** Re-scan installed plugins and fold the new state into every wired + * registry. Caller is responsible for invalidating systemPromptCache + * afterwards (we'd need the cache reference here, which sits one layer + * up in the agent options). */ +export async function refreshPluginContributions(targets: PluginRefreshTargets): Promise { + const cwd = targets.cwd ?? process.cwd() + + // 1. Re-scan plugins from disk. loadAllPlugins builds its own internal + // registry — we pull the plugin list + load errors out of it and + // feed them into the caller's long-lived registry via reload(). + const load = await loadAllPlugins({ cwd }) + + // 2. Swap into the caller's plugin registry, capture the headline diff. + const pluginsSummary = targets.pluginRegistry.reload(load.registry.listAll(), [...load.registry.loadErrors()]) + + // 3. Recompute downstream integration (skills dirs, agents dirs, + // commands dirs, mcp servers, hook registry) from the new + // plugin set. + const integration = await buildPluginIntegration(load) + + // 4. Fold into each sub-registry the caller wired up. + const out: PluginRefreshSummary = { plugins: pluginsSummary, hookCount: 0 } + + if (targets.skillRegistry) { + out.skills = await reloadSkillRegistry(targets.skillRegistry, { extraDirs: integration.skillsDirs }) + } + if (targets.subAgentRegistry) { + out.subAgents = await reloadSubAgentRegistry(targets.subAgentRegistry, { extraDirs: integration.agentsDirs }) + } + if (targets.commandRegistry) { + out.commands = await reloadCommandRegistry(targets.commandRegistry, { extraDirs: integration.commandsDirs }) + } + if (targets.hookBus) { + targets.hookBus.replaceRegistry(integration.hookRegistry) + // Count by summing entry counts across the new registry's events. + // Used for the user message — exact diff isn't worth the complexity. + out.hookCount = countHooks(integration.hookRegistry) + } + + return out +} + +function countHooks(registry: HookRegistry): number { + // HookRegistry exposes get(eventName) → array; iterate the known event + // names. Names are duplicated from types.ts but importing them here + // would create a circular dependency, so we hardcode the small list. + const eventNames = [ + 'SessionStart', + 'UserPromptSubmit', + 'PreToolUse', + 'PostToolUse', + 'PreCompact', + 'PostCompact', + 'SubagentStart', + 'SubagentStop', + 'TurnComplete', + 'SessionEnd', + ] as const + let n = 0 + for (const e of eventNames) n += registry.get(e).length + return n +} diff --git a/packages/core/src/plugins/registry.ts b/packages/core/src/plugins/registry.ts new file mode 100644 index 0000000..268bad7 --- /dev/null +++ b/packages/core/src/plugins/registry.ts @@ -0,0 +1,111 @@ +// @x-code-cli/core — Plugin registry +// +// Built once at CLI startup by [[loader]].loadAllPlugins(), then frozen +// for the session. The registry holds every plugin that successfully +// loaded — enabled AND disabled — so `/plugin list` can show both, plus +// every load error so `/plugin doctor` can surface them. +// +// Hot-reload model mirrors SkillRegistry: `/plugin refresh` rebuilds the +// internal state in place (preserving the registry object identity so +// every captured `options.pluginRegistry` reference stays valid) and the +// CLI invalidates `systemPromptCache` afterwards — the byte-stability +// constraint described in CLAUDE.md still applies because plugins +// contribute skills / agents / commands into the system prompt. +import type { LoadedPlugin, PluginLoadError } from './types.js' + +/** Summary of what changed between two registry snapshots — used by + * `/plugin refresh` to render an "added / removed / changed" message + * the same way `/mcp refresh` and `/skill refresh` do. */ +export interface PluginReloadSummary { + added: string[] + removed: string[] + changed: string[] + unchanged: string[] +} + +export class PluginRegistry { + private byId: Map + private errors: PluginLoadError[] + + constructor(plugins: LoadedPlugin[], errors: PluginLoadError[] = []) { + this.byId = new Map() + for (const p of plugins) this.byId.set(p.id, p) + this.errors = [...errors] + } + + /** Enabled plugin by id. Disabled plugins are hidden from this lookup — + * use [[getEntry]] when you need to inspect the disabled flag (e.g. + * `/plugin list`). */ + get(id: string): LoadedPlugin | undefined { + const p = this.byId.get(id) + if (!p || !p.enabled) return undefined + return p + } + + /** Plugin by id including disabled ones. */ + getEntry(id: string): LoadedPlugin | undefined { + return this.byId.get(id) + } + + /** Enabled plugins only — what the agent loop sees. */ + list(): LoadedPlugin[] { + return [...this.byId.values()].filter((p) => p.enabled) + } + + /** Every loaded plugin, with the disabled ones. */ + listAll(): LoadedPlugin[] { + return [...this.byId.values()] + } + + /** Plugin ids only (enabled). */ + ids(): string[] { + return this.list().map((p) => p.id) + } + + /** Non-fatal errors collected during load. Surfaced by `/plugin doctor`. */ + loadErrors(): readonly PluginLoadError[] { + return this.errors + } + + /** Replace the in-memory plugin list with a fresh load. Used by + * `/plugin refresh` — keeps the same PluginRegistry object identity + * so every cached reference stays valid. Returns a diff summary so + * the caller can render an "added / removed / changed / unchanged" + * message. */ + reload(plugins: LoadedPlugin[], errors: PluginLoadError[] = []): PluginReloadSummary { + const previous = this.byId + const next = new Map() + for (const p of plugins) next.set(p.id, p) + + const summary: PluginReloadSummary = { added: [], removed: [], changed: [], unchanged: [] } + for (const [id, plugin] of next) { + const prev = previous.get(id) + if (!prev) { + summary.added.push(id) + } else if ( + prev.manifest.version !== plugin.manifest.version || + prev.rootDir !== plugin.rootDir || + prev.enabled !== plugin.enabled || + prev.scope !== plugin.scope + ) { + summary.changed.push(id) + } else { + summary.unchanged.push(id) + } + } + for (const id of previous.keys()) { + if (!next.has(id)) summary.removed.push(id) + } + + this.byId = next + this.errors = [...errors] + return summary + } +} + +/** Empty registry — used when plugin loading is disabled (e.g. + * `--no-plugins` startup flag) or no plugins are installed. Cheaper than + * null-checking the registry everywhere downstream. */ +export function emptyPluginRegistry(): PluginRegistry { + return new PluginRegistry([], []) +} diff --git a/packages/core/src/plugins/types.ts b/packages/core/src/plugins/types.ts new file mode 100644 index 0000000..f49de98 --- /dev/null +++ b/packages/core/src/plugins/types.ts @@ -0,0 +1,234 @@ +// @x-code-cli/core — Plugin system core types +// +// A plugin bundles skills / sub-agents / slash commands / MCP servers / +// hooks behind a single manifest and namespace. Plugins are discovered +// at CLI startup, frozen for the session (same byte-stability constraint +// as skills + sub-agents — see CLAUDE.md on systemPromptCache), and +// re-loaded only via `/plugin refresh` which explicitly invalidates the +// prompt cache. +// +// Manifest format is intentionally byte-compatible with Claude Code's +// `.claude-plugin/plugin.json` so the same plugin tarball can be installed +// in either CLI. The native `.x-code-plugin/plugin.json` path is also +// accepted (preferred for newly-authored x-code-only plugins) and a bare +// `plugin.json` in the root is tolerated. + +// ── Plugin source (where it came from) ─────────────────────────────────── + +/** Where a plugin was installed from — the internal canonical form used + * by the installer and recorded in `installed_plugins.json`. Marketplace + * entries arrive in a different on-disk wire format (string shortcut, + * `git-subdir`, `url`) and are normalised to this shape by + * [[normalizeMarketplaceSource]]. `subdir` is supported on both git and + * github so monorepo-published plugins (common in real Claude Code + * marketplaces like `anthropics/claude-plugins-official`) install + * correctly. */ +export type PluginSource = + | { kind: 'git'; url: string; ref?: string; subdir?: string } + | { kind: 'github'; owner: string; repo: string; ref?: string; subdir?: string } + | { kind: 'local'; path: string } + +/** Two-scope plugin enablement, mirroring the convention used by mcp and + * skill (see packages/core/src/skills/settings.ts): + * + * 'user' → ~/.x-code/settings.json + * 'project' → /.x-code/settings.local.json (gitignored) + * + * `'project'` reading a `.local.json` file is a slight naming quirk + * inherited from skills — it's a per-user override scoped to one repo, + * not a team-shared file. A separate team-shared scope (committed) can + * be layered on later without changing this union. */ +export type PluginScope = 'user' | 'project' + +// ── Manifest (the contract authors write) ─────────────────────────────── + +export interface PluginAuthor { + name?: string + email?: string + url?: string +} + +/** A single user-prompted config item (API key, base URL, etc.). When + * `sensitive: true`, the value lives in the system keyring rather than + * settings.json. Schema mirrors Claude Code's so the same plugin works + * in either CLI without authors writing a separate config block. */ +export interface UserConfigItem { + key: string + type: 'string' | 'number' | 'boolean' + sensitive?: boolean + prompt?: string + required?: boolean + default?: string | number | boolean + description?: string +} + +/** Inline hook configuration (the alternative to a hooks file path). + * Loose shape here — full validation lives in + * packages/core/src/hooks/config-schema.ts so that hooks-only changes + * don't reach into the plugin layer. */ +export type InlineHookConfig = Record + +/** Inline mcpServers record (the alternative to a path string). Matches + * the shape of `mcpServers` in ~/.x-code/config.json — validated by + * the existing mcp config-schema, not duplicated here. */ +export type InlineMcpServers = Record + +/** The plugin manifest as parsed from disk. All paths are STORED RAW — + * resolution against the plugin root happens in [[loader]]. Unknown + * fields in the source JSON are silently stripped (zod default) so that + * newer Claude Code manifests with fields we don't understand still + * load cleanly. */ +export interface PluginManifest { + /** Schema version. Defaults to "1" when missing. Bumped by us only on + * breaking changes to the manifest contract; older plugins still load + * as long as their fields validate. */ + schemaVersion: string + name: string + version: string + description?: string + author?: PluginAuthor + keywords?: string[] + homepage?: string + license?: string + + // ── Contributions (all optional, all relative to plugin root) ───────── + /** Path to a directory of skills, each in `/SKILL.md` form (same + * layout as `~/.x-code/skills/`). Or a single file path. */ + skills?: string + /** Path to a directory of sub-agent `.md` files (same layout as + * `~/.x-code/agents/`). */ + agents?: string + /** Path to a directory of slash command `.md` files. */ + commands?: string + /** Either a path to a JSON file with `{ mcpServers: { ... } }` OR an + * inline `mcpServers` record. Inline form matches the shape used in + * ~/.x-code/config.json. */ + mcpServers?: string | InlineMcpServers + /** Either a path to a hooks.json OR an inline hook config. */ + hooks?: string | InlineHookConfig + + // ── Author-visible config the user fills in at install time ─────────── + userConfig?: UserConfigItem[] + + // ── Plugin-to-plugin deps & runtime compat ──────────────────────────── + /** Dependencies as `name@marketplace` IDs. Bare `name` resolves against + * the same marketplace as the dependent plugin. */ + dependencies?: string[] + engines?: { 'x-code'?: string } +} + +// ── Loaded plugin (what the registry holds at runtime) ────────────────── + +/** Which manifest file we loaded. `'gemini'` is never reached — Gemini + * extensions are rejected at install time by design (see plugin-marketplace-design.md + * §3.4) and the value is only used in error reporting to say "this looks + * like a Gemini extension, we don't support those". */ +export type ManifestFormat = 'native' | 'claude' | 'bare' | 'gemini' + +export interface LoadedPlugin { + /** Composite id `name@marketplace`. `marketplace` is `"local"` for + * plugins installed from a local path (i.e. authored in-tree). */ + id: string + manifest: PluginManifest + /** Absolute path to the plugin's root directory. */ + rootDir: string + /** Absolute path to the manifest file we loaded. */ + manifestPath: string + manifestFormat: ManifestFormat + /** Where this plugin originally came from. `undefined` only for the + * rare case of a plugin manually dropped into cache without metadata. */ + source: PluginSource | undefined + /** Marketplace name this plugin belongs to. `"local"` for plugins + * installed from a local path / authored in-tree. */ + marketplace: string + scope: PluginScope + /** Effective enabled state after merging all three scopes. */ + enabled: boolean +} + +/** A non-fatal load error — collected by the loader and surfaced via + * `/plugin doctor`. One broken plugin must never crash the CLI. */ +export interface PluginLoadError { + /** `name@marketplace` if we got far enough to know it. */ + id?: string + /** Filesystem path that triggered the error, even if no manifest parsed. */ + path: string + message: string +} + +// ── Marketplace (the index / catalog format) ──────────────────────────── + +/** One plugin listing within a marketplace. `source` tells the installer + * where to fetch the plugin from. */ +export interface MarketplaceEntry { + name: string + description?: string + category?: string + /** Marketplace-curator's claim of vetted-ness. We surface this in the UI + * but never grant additional trust based on it — install consent still + * runs. */ + verified?: boolean + source: PluginSource + /** Pinned version, if any. Otherwise installer reads version from the + * fetched manifest. */ + version?: string + homepage?: string + keywords?: string[] +} + +export interface Marketplace { + schemaVersion: string + name: string + displayName?: string + description?: string + owner?: { name?: string; url?: string } + plugins: MarketplaceEntry[] +} + +/** One entry in `~/.x-code/plugins/known_marketplaces.json` — a + * marketplace the user has subscribed to. The `source` string can be a + * git URL (`github:owner/repo`, `https://...`) or a direct HTTPS URL + * to the marketplace.json. */ +export interface KnownMarketplace { + name: string + source: string + /** Set on built-in entries (e.g., the default `anthropic-marketplace`). + * Reserved names only accept their canonical source — see + * RESERVED_MARKETPLACE_NAMES in [[marketplace]]. */ + reservedName?: boolean + /** Expected GitHub org for reserved names. The installer rejects any + * attempt to register a reserved name pointing elsewhere. */ + officialSource?: string +} + +export interface KnownMarketplaces { + marketplaces: KnownMarketplace[] + /** When true, plugins can only be installed from a marketplace in the + * `marketplaces` list. Off by default; enterprise admins flip it on. */ + strictKnownMarketplaces?: boolean + /** Plugin IDs (`name@marketplace`) that are force-disabled regardless of + * user settings. Admin-style block list. */ + blockedPlugins?: string[] +} + +// ── Installed plugin registry (~/.x-code/plugins/installed_plugins.json) ─ + +/** One entry in the installed registry — the bookkeeping we keep about + * each cached install so updates / uninstalls / scope changes work + * without re-reading every manifest. */ +export interface InstalledPluginRecord { + id: string + name: string + marketplace: string + version: string + source: PluginSource + installedAt: string + /** Which scope's settings.json triggered the install (where to record + * the enable). User scope is the default. */ + installScope: PluginScope +} + +export interface InstalledPlugins { + schemaVersion: string + plugins: InstalledPluginRecord[] +} diff --git a/packages/core/src/plugins/user-config.ts b/packages/core/src/plugins/user-config.ts new file mode 100644 index 0000000..a150e02 --- /dev/null +++ b/packages/core/src/plugins/user-config.ts @@ -0,0 +1,110 @@ +// @x-code-cli/core — Plugin userConfig storage +// +// Each plugin can declare a `userConfig` block in its manifest — a list of +// fields the plugin needs from the user (API keys, account ids, working +// directories, etc). At install time the CLI prompts for each field's +// value; this module owns the on-disk persistence layer. +// +// Layout: +// +// ~/.x-code/plugins/user-config.json → { +// [pluginId]: { [key]: } +// } +// +// Storage format is a plain JSON map; the file is created with 0600 +// (owner-read-write only) so a process in another user's session can't +// read sensitive values. This is NOT a substitute for a real OS keychain +// (macOS Keychain / Windows Credential Manager / Linux libsecret) — it's +// a pragmatic v1 that avoids the native-build complexity. The +// `sensitive: true` field still drives mask-on-input at prompt time; only +// the at-rest storage shares one file. +// +// A future enhancement will move `sensitive` entries to a real keychain. +// The reader merges from both sources, so adding it later is a non- +// breaking change. +// +// Why not split sensitive vs non-sensitive into separate files: it would +// just multiply file IO without raising the security bar (both files live +// in the same dir with the same perms). Real protection requires a real +// keychain; until then, one file is honest about what we're doing. +import fs from 'node:fs/promises' +import path from 'node:path' + +import { debugLog } from '../utils.js' +import { pluginsRoot } from './paths.js' + +/** Value type for a single field. The manifest `type` field (string / + * number / boolean) is enforced at prompt time, but we round-trip + * through JSON which only knows these three primitives anyway. */ +export type UserConfigValue = string | number | boolean + +/** Per-plugin user-config map: keyed by the manifest's `key` field. */ +export type PluginUserConfig = Record + +/** Full file layout: { [pluginId]: PluginUserConfig }. */ +type UserConfigFile = Record + +function userConfigPath(): string { + return path.join(pluginsRoot(), 'user-config.json') +} + +async function readFile(): Promise { + try { + const raw = await fs.readFile(userConfigPath(), 'utf-8') + const parsed = JSON.parse(raw) as unknown + if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {} + return parsed as UserConfigFile + } catch (err) { + if ((err as NodeJS.ErrnoException).code === 'ENOENT') return {} + debugLog('plugins.user-config-read-error', String(err)) + return {} + } +} + +async function writeFile(data: UserConfigFile): Promise { + const p = userConfigPath() + await fs.mkdir(path.dirname(p), { recursive: true }) + // 0600 keeps the file readable only by the owning user. On Windows + // this is a no-op (fs.chmod doesn't translate to ACLs the same way) — + // there's nothing meaningful we can do without shelling out to icacls. + // The keychain followup will solve Windows properly. + await fs.writeFile(p, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 }) +} + +/** Read the saved config for one plugin. Returns an empty object when + * the plugin has no saved config yet — caller can default keys from + * the manifest. */ +export async function getPluginUserConfig(pluginId: string): Promise { + const all = await readFile() + return all[pluginId] ?? {} +} + +/** Write the config for one plugin. Merges with existing fields rather + * than replacing — caller can call this once per field if they want + * (e.g. interactive prompt loop). */ +export async function setPluginUserConfig(pluginId: string, values: PluginUserConfig): Promise { + const all = await readFile() + all[pluginId] = { ...(all[pluginId] ?? {}), ...values } + await writeFile(all) +} + +/** Drop the config for one plugin (e.g. on uninstall). */ +export async function clearPluginUserConfig(pluginId: string): Promise { + const all = await readFile() + if (!(pluginId in all)) return + delete all[pluginId] + await writeFile(all) +} + +/** Materialise a plugin's user-config map as an env-var record ready to + * be merged into a child process's environment. Each manifest key + * becomes the env var name; numbers and booleans coerce to their + * string forms. Unset fields are skipped (env vars left untouched). */ +export async function getPluginUserConfigEnv(pluginId: string): Promise> { + const cfg = await getPluginUserConfig(pluginId) + const env: Record = {} + for (const [k, v] of Object.entries(cfg)) { + env[k] = String(v) + } + return env +} diff --git a/packages/core/src/skills/loader.ts b/packages/core/src/skills/loader.ts index 17ed4ce..ac195e2 100644 --- a/packages/core/src/skills/loader.ts +++ b/packages/core/src/skills/loader.ts @@ -5,7 +5,7 @@ // mirrors all major competitors (Gemini CLI, Opencode, Codex) and allows // future support files alongside SKILL.md. // -// Priority: project-level skills override global skills of the same name. +// Priority: project-level skills override user-level skills of the same name. // Bad files are skipped with a warning — one broken SKILL.md must never // crash the CLI. import fs from 'node:fs/promises' @@ -125,7 +125,11 @@ function parseFrontmatter(raw: string): { data: Record; body: s return { data, body } } -async function loadSkillsFromDir(dir: string, source: SkillDefinition['source']): Promise { +async function loadSkillsFromDir( + dir: string, + source: SkillDefinition['source'], + pluginId?: string, +): Promise { const skills: SkillDefinition[] = [] let entries: string[] @@ -170,6 +174,7 @@ async function loadSkillsFromDir(dir: string, source: SkillDefinition['source']) source, dir: skillDir, files, + ...(pluginId ? { pluginId } : {}), }) } catch (err) { console.error(`[skills] Skipping ${skillFile}: ${err instanceof Error ? err.message : String(err)}`) @@ -179,21 +184,49 @@ async function loadSkillsFromDir(dir: string, source: SkillDefinition['source']) return skills } -/** Load skills from global + project directories. - * Environment variable `XC_SKILLS_DIR` overrides both paths (testing only). */ -export async function loadSkills(): Promise { +export interface LoadSkillsOptions { + /** Extra skill directories to scan after the built-in user + project + * paths. Used to fold plugin-contributed `skills/` directories into + * the same registry — see packages/core/src/plugins/integration.ts. + * Order matters: later entries win on name collision. Plugin skills + * are scanned BEFORE project skills (so a user-authored project skill + * can override a plugin skill of the same name). */ + extraDirs?: ReadonlyArray<{ dir: string; pluginId: string }> +} + +/** Load skills from user + project directories, plus any extra dirs + * passed in (used by the plugin system to fold in plugin-contributed + * skill directories). Environment variable `XC_SKILLS_DIR` overrides + * the built-in paths for testing (extras are still honoured). */ +export async function loadSkills(opts: LoadSkillsOptions = {}): Promise { const override = process.env.XC_SKILLS_DIR if (override) { - return loadSkillsFromDir(override, 'project') + const overrideSkills = await loadSkillsFromDir(override, 'project') + return [...overrideSkills, ...(await loadFromExtras(opts.extraDirs))] } - const globalDir = path.join(GLOBAL_XCODE_DIR, 'skills') + const userDir = path.join(GLOBAL_XCODE_DIR, 'skills') const projectDir = path.join(process.cwd(), XCODE_DIR, 'skills') - const globalSkills = await loadSkillsFromDir(globalDir, 'global') + const userSkills = await loadSkillsFromDir(userDir, 'user') + const pluginSkills = await loadFromExtras(opts.extraDirs) const projectSkills = await loadSkillsFromDir(projectDir, 'project') - // Project skills come last so their names win over global skills - // when the registry deduplicates by name. - return [...globalSkills, ...projectSkills] + // Merge order — last-wins in the registry (project overrides plugin + // overrides user builtin). This matches the precedence we tell users: + // a project-level skill always overrides anything from a plugin. + return [...userSkills, ...pluginSkills, ...projectSkills] +} + +async function loadFromExtras(extras: LoadSkillsOptions['extraDirs']): Promise { + if (!extras || extras.length === 0) return [] + const out: SkillDefinition[] = [] + for (const { dir, pluginId } of extras) { + // Plugin-provided skills' filesystem source is technically the cache + // dir under ~/.x-code/plugins/cache/..., which makes 'user' the + // closest fit (it's installed user-wide, not per-project). `pluginId` + // carries the real provenance for the UI. + out.push(...(await loadSkillsFromDir(dir, 'user', pluginId))) + } + return out } diff --git a/packages/core/src/skills/registry.ts b/packages/core/src/skills/registry.ts index 52537c7..4880d5c 100644 --- a/packages/core/src/skills/registry.ts +++ b/packages/core/src/skills/registry.ts @@ -15,14 +15,14 @@ // every other code path that captured `options.skillRegistry` (agent // loop's buildTools, App.tsx's slash-command tab completion, …) stays // pointed at the right thing without needing to be re-wired. -import { loadSkills } from './loader.js' +import { type LoadSkillsOptions, loadSkills } from './loader.js' import { loadDisabledSkillsSet } from './settings.js' export interface SkillDefinition { name: string description: string content: string - source: 'global' | 'project' + source: 'user' | 'project' /** Absolute path to the skill's directory (the one containing SKILL.md). * Used at activation time so the model can resolve relative paths to * bundled scripts / references / assets. */ @@ -32,6 +32,10 @@ export interface SkillDefinition { * so the model knows what bundled resources exist without globbing. Capped * at MAX_LISTED_FILES — long lists get truncated with a "... N more" marker. */ files: string[] + /** When this skill comes from a plugin contribution, the owning plugin's + * id (`name@marketplace`). UI shows this as "(from plugin: …)" and + * `/skill remove` redirects to `/plugin uninstall`. */ + pluginId?: string } export interface SkillEntry extends SkillDefinition { @@ -164,8 +168,8 @@ export function wrapActivatedSkill(skill: SkillDefinition): string { return `\n${formatSkillActivationBody(skill)}\n` } -export async function createSkillRegistry(): Promise { - const [skills, disabled] = await Promise.all([loadSkills(), loadDisabledSkillsSet()]) +export async function createSkillRegistry(opts: LoadSkillsOptions = {}): Promise { + const [skills, disabled] = await Promise.all([loadSkills(opts), loadDisabledSkillsSet()]) return new SkillRegistry(skills, disabled) } @@ -173,7 +177,10 @@ export async function createSkillRegistry(): Promise { * registry in place. Caller is responsible for invalidating any * systemPromptCache that embedded the previous skill list — the * /skill refresh handler does exactly this. */ -export async function reloadSkillRegistry(registry: SkillRegistry): Promise { - const [skills, disabled] = await Promise.all([loadSkills(), loadDisabledSkillsSet()]) +export async function reloadSkillRegistry( + registry: SkillRegistry, + opts: LoadSkillsOptions = {}, +): Promise { + const [skills, disabled] = await Promise.all([loadSkills(opts), loadDisabledSkillsSet()]) return registry.reload(skills, disabled) } diff --git a/packages/core/src/skills/settings.ts b/packages/core/src/skills/settings.ts index dcb2b75..641e0dd 100644 --- a/packages/core/src/skills/settings.ts +++ b/packages/core/src/skills/settings.ts @@ -1,12 +1,12 @@ // Skill settings — disabledSkills list per scope. // -// Global scope: ~/.x-code/settings.json +// User scope: ~/.x-code/settings.json // Project scope: /.x-code/settings.local.json (gitignored) // // Both files share the shape `{ disabledSkills?: string[] }`. A skill is // effectively disabled when its name appears in EITHER scope's list — we -// take the union, not an override. To re-enable from a global disable -// while keeping it disabled elsewhere, remove the name from the global +// take the union, not an override. To re-enable from a user-scope disable +// while keeping it disabled elsewhere, remove the name from the user-scope // list. The settings files are session-immutable: SkillRegistry filters // on this list at startup, so toggle/remove takes effect on next launch. import fs from 'node:fs/promises' @@ -14,14 +14,14 @@ import path from 'node:path' import { GLOBAL_XCODE_DIR, XCODE_DIR } from '../utils.js' -export type SkillSettingsScope = 'global' | 'project' +export type SkillSettingsScope = 'user' | 'project' export interface SkillSettings { disabledSkills?: string[] } export function skillSettingsPath(scope: SkillSettingsScope): string { - if (scope === 'global') return path.join(GLOBAL_XCODE_DIR, 'settings.json') + if (scope === 'user') return path.join(GLOBAL_XCODE_DIR, 'settings.json') return path.join(process.cwd(), XCODE_DIR, 'settings.local.json') } @@ -68,9 +68,9 @@ async function writeSettings(scope: SkillSettingsScope, settings: SkillSettings) } export async function loadDisabledSkillsSet(): Promise> { - const [g, p] = await Promise.all([readSettings('global'), readSettings('project')]) + const [u, p] = await Promise.all([readSettings('user'), readSettings('project')]) const merged = new Set() - for (const name of g.disabledSkills ?? []) merged.add(name) + for (const name of u.disabledSkills ?? []) merged.add(name) for (const name of p.disabledSkills ?? []) merged.add(name) return merged } diff --git a/packages/core/src/types/index.ts b/packages/core/src/types/index.ts index 5d01211..ab86391 100644 --- a/packages/core/src/types/index.ts +++ b/packages/core/src/types/index.ts @@ -4,8 +4,11 @@ import type { LanguageModel, ModelMessage } from 'ai' import type { EditDiffPayload } from '../agent/diff.js' import type { SubAgentRegistry } from '../agent/sub-agents/registry.js' import type { SubAgentEvent } from '../agent/sub-agents/types.js' +import type { CommandRegistry } from '../commands/registry.js' +import type { HookBus } from '../hooks/bus.js' import type { McpPermissionStore } from '../mcp/permissions.js' import type { McpRegistry } from '../mcp/registry.js' +import type { PluginRegistry } from '../plugins/registry.js' import type { SkillRegistry } from '../skills/registry.js' // ─── Permission ─── @@ -234,6 +237,35 @@ export interface AgentOptions { * caches the persisted always-allow list + session-scoped allows. * Absent ⇒ tool-execution falls back to ask-every-time semantics. */ mcpPermissionStore?: McpPermissionStore + + // ── Plugin support ── + + /** Plugin registry, populated at CLI startup by loadAllPlugins. Holds + * every successfully-loaded plugin (enabled + disabled), exposed so + * the `/plugin ...` slash command family can list / inspect / toggle + * without re-scanning the cache. Plugin contributions (skills / + * agents / mcp) are already merged into their respective registries + * by the CLI startup wiring — this field is only the metadata + * surface for the slash command UI. Absent ⇒ plugins disabled + * (`--no-plugins`) or no plugins installed. */ + pluginRegistry?: PluginRegistry + + /** Hook bus built from enabled plugins' `hooks` contributions. The + * agent loop emits SessionStart / UserPromptSubmit / TurnComplete / + * SessionEnd events through it; tool-execution adds PreToolUse / + * PostToolUse. Absent ⇒ no hook emission (the agent loop skips + * emit-sites entirely). Use `emptyHookBus()` for tests / sub-agents + * that should be allowed to call into the emit-sites but have no + * listeners. */ + hookBus?: HookBus + + /** File-based slash command registry built from plugin-contributed + * `commands/` directories. The App.tsx default slash dispatcher + * checks this after the built-in command list and skill registry; + * matching a name here expands the command body (with $ARGUMENTS + * / ${CLAUDE_PLUGIN_ROOT} substitution) and submits as a model + * prompt. Absent ⇒ no plugin commands available. */ + commandRegistry?: CommandRegistry } // ─── Knowledge ─── @@ -262,7 +294,7 @@ export interface KnowledgeFact { * a fact to AutoMemory. Lets the UI render a "Remembered: …" line in * scrollback so the user has visibility into otherwise-silent writes. */ export interface MemoryWriteNotice { - scope: 'project' | 'global' + scope: 'project' | 'user' category: KnowledgeCategory key: string fact: string diff --git a/packages/core/src/utils.ts b/packages/core/src/utils.ts index 7b58bdc..d8824af 100644 --- a/packages/core/src/utils.ts +++ b/packages/core/src/utils.ts @@ -108,8 +108,29 @@ function truncateForLog(s: string, maxBytes: number): string { return `${truncated}…<+${dropped}c truncated>` } +/** Narrow opt-in: when set by the CLI's `--plugin-debug` flag (or + * `XC_PLUGIN_DEBUG=1`), debugLog also mirrors lines tagged with one of + * the plugin-related prefixes to stderr, so the user can watch plugin + * / hook / marketplace activity live without `DEBUG_STDOUT=1`'s firehose. + * Kept as module state instead of an arg to debugLog so existing call + * sites don't need touching. */ +let pluginDebugMirror = false +const PLUGIN_DEBUG_TAG_PREFIXES = ['plugins.', 'plugin.', 'hooks.', 'marketplace.'] + +export function setPluginDebugMirror(enabled: boolean): void { + pluginDebugMirror = enabled +} + +function isPluginRelatedTag(tag: string): boolean { + for (const p of PLUGIN_DEBUG_TAG_PREFIXES) { + if (tag.startsWith(p)) return true + } + return false +} + export function debugLog(tag: string, content: string): void { - if (!DEBUG) return + const mirrorToStderr = pluginDebugMirror && isPluginRelatedTag(tag) + if (!DEBUG && !mirrorToStderr) return try { const safeContent = truncateForLog(content, MAX_LINE_BYTES) const ts = new Date().toISOString() @@ -117,12 +138,23 @@ export function debugLog(tag: string, content: string): void { // lands on ONE line in the log — much easier to grep across turns, // and multi-line text-deltas don't visually merge with neighbours. const line = `[${ts}] ${tag} ${JSON.stringify(safeContent)}\n` - const bytes = Buffer.byteLength(line, 'utf8') - rotateIfNeeded(bytes) - ensureLogReady() - if (logFd !== null) { - fsSync.writeSync(logFd, line) - currentLogBytes += bytes + if (DEBUG) { + const bytes = Buffer.byteLength(line, 'utf8') + rotateIfNeeded(bytes) + ensureLogReady() + if (logFd !== null) { + fsSync.writeSync(logFd, line) + currentLogBytes += bytes + } + } + if (mirrorToStderr) { + // Use the raw fd to avoid Node's stderr stream buffering — we want + // each line to appear immediately even if the agent loop is busy. + try { + fsSync.writeSync(2, line) + } catch { + // stderr write failure shouldn't crash the agent + } } } catch { // best effort — never crash the agent just because we can't log diff --git a/packages/core/tests/api-errors.test.ts b/packages/core/tests/api-errors.test.ts index 8e1a3e9..8a6b9f5 100644 --- a/packages/core/tests/api-errors.test.ts +++ b/packages/core/tests/api-errors.test.ts @@ -12,9 +12,6 @@ describe('extractHttpStatus', () => { it('extracts leading NNN', () => { expect(extractHttpStatus('503 Service Unavailable')).toBe(503) }) - it('returns 0 when no status found', () => { - expect(extractHttpStatus('some random error')).toBe(0) - }) }) describe('isContextTooLongError', () => { @@ -27,9 +24,6 @@ describe('isContextTooLongError', () => { it('detects prompt is too long', () => { expect(isContextTooLongError(new Error('prompt is too long'))).toBe(true) }) - it('returns false for unrelated errors', () => { - expect(isContextTooLongError(new Error('network timeout'))).toBe(false) - }) it('detects HTTP 413 (permanentErrorFetch rewrites context overflow to 413)', () => { expect(isContextTooLongError(new Error('Request failed with status code 413'))).toBe(true) }) diff --git a/packages/core/tests/cache-control.test.ts b/packages/core/tests/cache-control.test.ts index b3ad6ef..d8dcdb0 100644 --- a/packages/core/tests/cache-control.test.ts +++ b/packages/core/tests/cache-control.test.ts @@ -123,27 +123,6 @@ describe('applyCacheControl', () => { expect((tools.write as { providerOptions?: unknown }).providerOptions).toBeUndefined() }) - it('handles missing tools gracefully', () => { - const out = applyCacheControl({ - system: 'sys', - messages: baseMessages, - modelId: 'anthropic:claude-opus-4-7', - sessionId: 'abc', - }) - expect(out.tools).toBeUndefined() - }) - - it('handles empty tools record', () => { - const out = applyCacheControl({ - system: 'sys', - messages: baseMessages, - tools: {}, - modelId: 'anthropic:claude-opus-4-7', - sessionId: 'abc', - }) - expect(out.tools).toEqual({}) - }) - it('merges with any pre-existing tool providerOptions', () => { const tools = { read: {}, diff --git a/packages/core/tests/commands.test.ts b/packages/core/tests/commands.test.ts new file mode 100644 index 0000000..48ee576 --- /dev/null +++ b/packages/core/tests/commands.test.ts @@ -0,0 +1,148 @@ +// Tests for the file-based slash command subsystem (loader / registry / +// body expansion). The real regression risk is `$ARGUMENTS` and +// `${CLAUDE_PLUGIN_ROOT}` substitution and frontmatter parsing of the +// `allowed-tools:` form Claude Code uses (long, comma-separated, often +// folded across lines). +import { describe, expect, it } from 'vitest' + +import fs from 'node:fs/promises' +import os from 'node:os' +import path from 'node:path' + +import { CommandRegistry, expandCommandBody, loadPluginCommands } from '../src/commands/index.js' + +async function writeCommand(dir: string, name: string, frontmatter: string, body: string): Promise { + await fs.mkdir(dir, { recursive: true }) + await fs.writeFile(path.join(dir, `${name}.md`), `---\n${frontmatter}\n---\n${body}`, 'utf-8') +} + +describe('loadPluginCommands', () => { + it('loads each commands/.md as a CommandDefinition with name = basename', async () => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-cmds-')) + await writeCommand(dir, 'code-review', 'description: Review code', 'Body of code-review') + await writeCommand(dir, 'commit', 'description: Make a commit', 'Body of commit') + + const out = await loadPluginCommands({ + extraDirs: [{ dir, pluginId: 'demo@local', pluginRoot: '/abs/root' }], + }) + + expect(out.map((c) => c.name).sort()).toEqual(['code-review', 'commit']) + const cr = out.find((c) => c.name === 'code-review')! + expect(cr.description).toBe('Review code') + expect(cr.body).toBe('Body of code-review') + expect(cr.pluginId).toBe('demo@local') + expect(cr.pluginRoot).toBe('/abs/root') + }) + + it('handles real Claude Code multi-line allowed-tools frontmatter without crashing', async () => { + // This is the actual form from anthropics/claude-code's + // code-review plugin — `allowed-tools` is comma-separated, often + // long enough to wrap visually. Our minimal YAML parser folds + // indented continuation lines; the value we read for + // `allowed-tools` is currently ignored (no enforcement), but the + // parse must not reject the whole file. + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-cmds-allowed-')) + await writeCommand( + dir, + 'real-shape', + 'allowed-tools: Bash(gh issue view:*), Bash(gh search:*), mcp__github_inline_comment__create_inline_comment\ndescription: Code review', + 'Body', + ) + + const out = await loadPluginCommands({ + extraDirs: [{ dir, pluginId: 'demo@local', pluginRoot: '/r' }], + }) + expect(out).toHaveLength(1) + expect(out[0]!.description).toBe('Code review') + expect(out[0]!.body).toBe('Body') + }) + + it('treats a file with no frontmatter as a body-only command (no description)', async () => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-cmds-nofm-')) + await fs.writeFile(path.join(dir, 'bare.md'), 'just the body', 'utf-8') + + const out = await loadPluginCommands({ + extraDirs: [{ dir, pluginId: 'demo@local', pluginRoot: '/r' }], + }) + expect(out).toHaveLength(1) + expect(out[0]!.name).toBe('bare') + expect(out[0]!.description).toBeUndefined() + expect(out[0]!.body).toBe('just the body') + }) + + it("returns empty when the dir does not exist (broken plugin shouldn't crash boot)", async () => { + const out = await loadPluginCommands({ + extraDirs: [{ dir: '/nonexistent', pluginId: 'ghost@local', pluginRoot: '/r' }], + }) + expect(out).toEqual([]) + }) +}) + +describe('expandCommandBody', () => { + function cmd(body: string, root = '/abs/plugin'): import('../src/commands/types.js').CommandDefinition { + return { name: 't', body, source: 'plugin', pluginId: 'demo@local', pluginRoot: root } + } + + it('substitutes $ARGUMENTS and ${ARGUMENTS} with the user-typed argument string', () => { + expect(expandCommandBody(cmd('Run: $ARGUMENTS'), '123')).toBe('Run: 123') + expect(expandCommandBody(cmd('Run: ${ARGUMENTS}'), 'abc def')).toBe('Run: abc def') + }) + + it('substitutes ${CLAUDE_PLUGIN_ROOT} with the plugin root path', () => { + const out = expandCommandBody(cmd('cd ${CLAUDE_PLUGIN_ROOT} && ./scripts/x.sh', '/abs/p'), '') + expect(out).toBe('cd /abs/p && ./scripts/x.sh') + }) + + it('leaves $ARGUMENTS as empty string when no argument was given', () => { + expect(expandCommandBody(cmd('"$ARGUMENTS"'), '')).toBe('""') + }) + + it('substitutes ${CLAUDE_PLUGIN_DATA} with the plugin data dir and auto-creates it', async () => { + const tmpHome = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-cmd-data-')) + const prev = process.env.XC_PLUGINS_DIR + process.env.XC_PLUGINS_DIR = tmpHome + try { + const out = expandCommandBody(cmd('cat ${CLAUDE_PLUGIN_DATA}/notes.md'), '') + // The body still names the plugin, so the substitution yields a path + // under our temp plugins root. + expect(out.startsWith('cat ')).toBe(true) + const dataPath = out.slice('cat '.length).replace(/\/notes\.md$/, '') + const stat = await fs.stat(dataPath) + expect(stat.isDirectory()).toBe(true) + } finally { + if (prev === undefined) delete process.env.XC_PLUGINS_DIR + else process.env.XC_PLUGINS_DIR = prev + await fs.rm(tmpHome, { recursive: true, force: true }).catch(() => {}) + } + }) + + it('${CLAUDE_PLUGIN_DATA} stays empty when body has no plugin context to resolve', () => { + // Synthesize a command def with no pluginId — should NOT mkdir or substitute. + const c: import('../src/commands/types.js').CommandDefinition = { + name: 't', + body: 'echo ${CLAUDE_PLUGIN_DATA}/foo', + source: 'plugin', + pluginRoot: '/abs/p', + } + expect(expandCommandBody(c, '')).toBe('echo /foo') + }) +}) + +describe('CommandRegistry', () => { + it('looks up by name and returns undefined for misses', () => { + const reg = new CommandRegistry([ + { name: 'foo', body: 'b', source: 'plugin', pluginId: 'demo@local', pluginRoot: '/r' }, + ]) + expect(reg.get('foo')!.name).toBe('foo') + expect(reg.get('bar')).toBeUndefined() + }) + + it('last-write-wins on name collision (mirrors SkillRegistry semantics)', () => { + const reg = new CommandRegistry([ + { name: 'foo', body: 'first', source: 'plugin', pluginId: 'a@local', pluginRoot: '/a' }, + { name: 'foo', body: 'second', source: 'plugin', pluginId: 'b@local', pluginRoot: '/b' }, + ]) + expect(reg.get('foo')!.body).toBe('second') + expect(reg.get('foo')!.pluginId).toBe('b@local') + }) +}) diff --git a/packages/core/tests/context-window.test.ts b/packages/core/tests/context-window.test.ts index cfb820b..12ff516 100644 --- a/packages/core/tests/context-window.test.ts +++ b/packages/core/tests/context-window.test.ts @@ -89,8 +89,4 @@ describe('estimateTokenCount', () => { const tokens = estimateTokenCount(messages) expect(tokens).toBe(Math.ceil(5 / 3.0)) }) - - it('returns 0 for empty messages', () => { - expect(estimateTokenCount([])).toBe(0) - }) }) diff --git a/packages/core/tests/diff.test.ts b/packages/core/tests/diff.test.ts index dab5455..d3eeac3 100644 --- a/packages/core/tests/diff.test.ts +++ b/packages/core/tests/diff.test.ts @@ -54,9 +54,4 @@ describe('computeEditDiff', () => { expect(result!.isCreate).toBe(true) expect(result!.additions).toBe(0) }) - - it('preserves filePath in payload', () => { - const result = computeEditDiff('/path/to/file.ts', null, 'content\n') - expect(result!.filePath).toBe('/path/to/file.ts') - }) }) diff --git a/packages/core/tests/file-ingest.test.ts b/packages/core/tests/file-ingest.test.ts index df6ea95..04f46ce 100644 --- a/packages/core/tests/file-ingest.test.ts +++ b/packages/core/tests/file-ingest.test.ts @@ -39,18 +39,15 @@ vi.mock('tesseract.js', () => ({ let tmpDir: string let textFile: string let jsonFile: string -let unknownFile: string let imageFile: string beforeAll(async () => { tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'xcc-ingest-')) textFile = path.join(tmpDir, 'hello.md') jsonFile = path.join(tmpDir, 'data.json') - unknownFile = path.join(tmpDir, 'no-extension') imageFile = path.join(tmpDir, 'fake.png') await fs.writeFile(textFile, '# Hello\nLine 2') await fs.writeFile(jsonFile, '{"ok":true}') - await fs.writeFile(unknownFile, 'plain body') // Empty file is fine — classifyFile picks .png by extension and the // mocked captionImage never reads the bytes. ingestFile only reads the // buffer for the multimodal-provider path, which we don't exercise here. @@ -79,11 +76,6 @@ describe('extractFileReferences', () => { expect(refs).toHaveLength(1) }) - it('ignores tokens without path separators', () => { - const refs = extractFileReferences('call fs.readFile then foo.bar.baz') - expect(refs).toHaveLength(0) - }) - it('de-duplicates repeated references', () => { const refs = extractFileReferences('@/a/b.md vs @/a/b.md') expect(refs).toHaveLength(1) @@ -99,10 +91,6 @@ describe('classifyFile', () => { expect(await classifyFile(jsonFile)).toBe('text') }) - it('recognizes extensions without a dot fallback', async () => { - expect(await classifyFile(unknownFile)).toBe('text') - }) - it('recognizes .png as image by extension', async () => { // Doesn't need the file to exist — extension-only check. expect(await classifyFile('/does/not/exist.png')).toBe('image') diff --git a/packages/core/tests/glob-tool.test.ts b/packages/core/tests/glob-tool.test.ts index 374afbc..5f68dbe 100644 --- a/packages/core/tests/glob-tool.test.ts +++ b/packages/core/tests/glob-tool.test.ts @@ -108,21 +108,6 @@ describe('glob tool', () => { await fs.rm(tmpDir, { recursive: true }) }) - it('returns absolute paths', async () => { - const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-glob-abs-')) - await fs.writeFile(path.join(tmpDir, 'x.ts'), '') - - const result = (await glob.execute!( - { pattern: '*.ts', cwd: tmpDir }, - { toolCallId: 'test', messages: [], abortSignal: undefined as any }, - )) as string - - const line = result.split('\n').find((l) => l.endsWith('x.ts')) ?? '' - expect(path.isAbsolute(line)).toBe(true) - - await fs.rm(tmpDir, { recursive: true }) - }) - // Regression: ripgrep's `--glob "**/*"` is treated as a whitelist that // overrides .gitignore, so feeding the model's catch-all pattern through // verbatim returns tens of thousands of node_modules / .git files. The diff --git a/packages/core/tests/hooks.test.ts b/packages/core/tests/hooks.test.ts new file mode 100644 index 0000000..08c13af --- /dev/null +++ b/packages/core/tests/hooks.test.ts @@ -0,0 +1,360 @@ +// Tests for hooks subsystem: variables, config-schema, registry, bus, +// executor (via a real node subprocess to exercise the stdin/stdout +// protocol portably). +import { describe, expect, it } from 'vitest' + +import fs from 'node:fs/promises' +import os from 'node:os' +import path from 'node:path' + +import { + HookBus, + HookConfigParseError, + HookRegistry, + aggregatePostToolUse, + aggregatePreToolUse, + aggregateUserPromptSubmit, + buildHookRegistry, + buildVariableContext, + executeHook, + expandVariables, + parseHookConfig, +} from '../src/hooks/index.js' +import type { HookEvent, RegisteredHook } from '../src/hooks/index.js' + +// ── variables ─────────────────────────────────────────────────────────── + +describe('expandVariables', () => { + const ctx = buildVariableContext({ pluginDir: '/abs/plugin', cwd: '/abs/cwd' }) + + it('expands the four built-in names', () => { + expect(expandVariables('${pluginDir}/run', ctx)).toBe('/abs/plugin/run') + expect(expandVariables('cd ${cwd}', ctx)).toBe('cd /abs/cwd') + expect(expandVariables('home=${homedir}', ctx)).toContain('home=') + expect(expandVariables('s${sep}', ctx)).toBe(`s${path.sep}`) + }) + + it('reads ${env:NAME} from process.env', () => { + process.env.XC_HOOK_TEST_VAR = 'hello' + try { + expect(expandVariables('echo ${env:XC_HOOK_TEST_VAR}', ctx)).toBe('echo hello') + } finally { + delete process.env.XC_HOOK_TEST_VAR + } + }) + + it('leaves unknown variables verbatim (typos surface as shell errors, not silent expansion)', () => { + expect(expandVariables('${nope}', ctx)).toBe('${nope}') + expect(expandVariables('${unknown:foo}', ctx)).toBe('${unknown:foo}') + }) + + it('${pluginDataDir} expands and auto-creates the dir when pluginId is supplied', async () => { + const tmpHome = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-data-ctx-')) + const prev = process.env.XC_PLUGINS_DIR + process.env.XC_PLUGINS_DIR = tmpHome + try { + const c = buildVariableContext({ + pluginDir: '/abs/plugin', + cwd: '/abs/cwd', + pluginId: 'demo@local', + }) + const expanded = expandVariables('write ${pluginDataDir}/state.json', c) + // The expanded path must live under our temp plugins root. + expect(expanded.startsWith('write ')).toBe(true) + const dataPath = expanded.slice('write '.length).replace(/\/state\.json$/, '') + const stat = await fs.stat(dataPath) + expect(stat.isDirectory()).toBe(true) + } finally { + if (prev === undefined) delete process.env.XC_PLUGINS_DIR + else process.env.XC_PLUGINS_DIR = prev + await fs.rm(tmpHome, { recursive: true, force: true }).catch(() => {}) + } + }) + + it('${pluginDataDir} stays verbatim when no pluginId was supplied (e.g. hook with no owner context)', () => { + const c = buildVariableContext({ pluginDir: '/abs/plugin', cwd: '/abs/cwd' }) + expect(expandVariables('${pluginDataDir}/state', c)).toBe('${pluginDataDir}/state') + }) +}) + +// ── config-schema ────────────────────────────────────────────────────── + +describe('parseHookConfig', () => { + it('strips unknown event names (forward compat)', () => { + const c = parseHookConfig({ PreToolUse: [{ command: 'a' }], SomeFutureEvent: [{ command: 'b' }] }, 'demo') + expect(c.PreToolUse).toBeDefined() + expect((c as Record).SomeFutureEvent).toBeUndefined() + }) + + it('rejects entries missing a command', () => { + expect(() => parseHookConfig({ PreToolUse: [{ matcher: 'edit_file' }] }, 'demo')).toThrow(HookConfigParseError) + }) + + it('caps timeout at 30 seconds', () => { + expect(() => parseHookConfig({ PreToolUse: [{ command: 'x', timeout: 60_000 }] }, 'demo')).toThrow( + HookConfigParseError, + ) + }) + + it('accepts the 4 new event names (PreCompact / PostCompact / SubagentStart / SubagentStop)', () => { + const c = parseHookConfig( + { + PreCompact: [{ command: 'echo pre' }], + PostCompact: [{ command: 'echo post' }], + SubagentStart: [{ command: 'echo start' }], + SubagentStop: [{ command: 'echo stop' }], + }, + 'demo', + ) + expect(c.PreCompact?.[0]?.command).toBe('echo pre') + expect(c.PostCompact?.[0]?.command).toBe('echo post') + expect(c.SubagentStart?.[0]?.command).toBe('echo start') + expect(c.SubagentStop?.[0]?.command).toBe('echo stop') + }) + + it('accepts the platform-specific command overrides', () => { + const c = parseHookConfig( + { + PreToolUse: [ + { + command: 'node script.js', + commandWindows: 'node "script.js"', + commandDarwin: 'node script.js', + commandLinux: 'node script.js', + }, + ], + }, + 'demo', + ) + expect(c.PreToolUse?.[0]?.commandWindows).toBe('node "script.js"') + expect(c.PreToolUse?.[0]?.commandDarwin).toBe('node script.js') + }) +}) + +// ── registry ─────────────────────────────────────────────────────────── + +describe('buildHookRegistry', () => { + it('groups hooks by event in registration order', () => { + const reg = buildHookRegistry([ + { pluginId: 'a@local', pluginDir: '/a', config: { PreToolUse: [{ command: 'a1' }, { command: 'a2' }] } }, + { pluginId: 'b@local', pluginDir: '/b', config: { PreToolUse: [{ command: 'b1' }] } }, + ]) + const list = reg.get('PreToolUse') + expect(list.map((h) => h.entry.command)).toEqual(['a1', 'a2', 'b1']) + expect(list.map((h) => h.pluginId)).toEqual(['a@local', 'a@local', 'b@local']) + }) +}) + +// ── aggregators ──────────────────────────────────────────────────────── + +describe('aggregate helpers', () => { + it('aggregatePreToolUse stops at first deny', () => { + const eff = aggregatePreToolUse([ + { decision: 'allow' }, + { decision: 'deny', reason: 'no' }, + { decision: 'modify', args: { x: 1 } }, // ignored — comes after deny + ]) + expect(eff.decision).toBe('deny') + expect(eff.reason).toBe('no') + }) + + it('aggregatePreToolUse stacks modify args (later wins)', () => { + const eff = aggregatePreToolUse([ + { decision: 'modify', args: { x: 1 } }, + { decision: 'modify', args: { x: 2, y: 3 } }, + ]) + expect(eff.decision).toBe('allow') + expect(eff.args).toEqual({ x: 2, y: 3 }) + }) + + it('aggregatePostToolUse uses last modify.output', () => { + const eff = aggregatePostToolUse([ + { decision: 'modify', output: 'first' }, + { decision: 'modify', output: 'second' }, + ]) + expect(eff.output).toBe('second') + }) + + it('aggregateUserPromptSubmit concatenates contexts', () => { + const eff = aggregateUserPromptSubmit([ + { decision: 'allow', context: 'a' }, + { decision: 'modify', context: 'b' }, + ]) + expect(eff.decision).toBe('allow') + expect(eff.context).toBe('a\n\nb') + }) + + it('aggregateUserPromptSubmit deny clears context', () => { + const eff = aggregateUserPromptSubmit([ + { decision: 'allow', context: 'a' }, + { decision: 'deny', reason: 'sensitive' }, + ]) + expect(eff.decision).toBe('deny') + expect(eff.context).toBe('') + }) +}) + +// ── bus matcher ──────────────────────────────────────────────────────── + +describe('HookBus matcher behaviour', () => { + function makeHook(matcher: string | undefined, command = 'node -e "process.exit(0)"'): RegisteredHook { + return { + pluginId: 'demo@local', + pluginDir: process.cwd(), + event: 'PreToolUse', + entry: { command, matcher }, + } + } + + it('filters by matcher regex (PreToolUse only)', async () => { + // We exercise the matcher filter at the bus level — to avoid spawning + // shell processes, use commands that exit 0 immediately so any matched + // hook runs successfully. + const reg = new HookRegistry([makeHook('write_file', 'node -e "process.exit(0)"')]) + const bus = new HookBus(reg) + + // No match: empty decisions array (no hook ran). + const noMatch = await bus.emit({ + name: 'PreToolUse', + session: { cwd: process.cwd(), modelId: 'm' }, + tool: { name: 'edit_file', args: {}, callId: 'c1' }, + }) + expect(noMatch).toEqual([]) + + // Match: one hook ran (we got one decision back). + const match = await bus.emit({ + name: 'PreToolUse', + session: { cwd: process.cwd(), modelId: 'm' }, + tool: { name: 'write_file', args: {}, callId: 'c2' }, + }) + expect(match).toHaveLength(1) + expect(match[0]!.decision).toBe('allow') + }, 15_000) + + it('treats bad-regex matcher as "match all" (degrade rather than disable)', async () => { + const reg = new HookRegistry([makeHook('(', 'node -e "process.exit(0)"')]) + const bus = new HookBus(reg) + const decisions = await bus.emit({ + name: 'PreToolUse', + session: { cwd: process.cwd(), modelId: 'm' }, + tool: { name: 'anything', args: {}, callId: 'c' }, + }) + expect(decisions).toHaveLength(1) + }, 15_000) +}) + +// ── executor (real subprocess) ───────────────────────────────────────── + +describe('executeHook (real subprocess)', () => { + async function writeHookScript(contents: string): Promise { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-hook-script-')) + const file = path.join(dir, 'hook.js') + await fs.writeFile(file, contents, 'utf-8') + return file + } + + function hookFor(file: string, overrides: Partial = {}): RegisteredHook { + return { + pluginId: 'demo@local', + pluginDir: process.cwd(), + event: 'PreToolUse', + entry: { command: `node "${file}"`, ...overrides }, + } + } + + function preEvent(): HookEvent { + return { + name: 'PreToolUse', + session: { cwd: process.cwd(), modelId: 'm' }, + tool: { name: 'write_file', args: { path: 'a.txt' }, callId: 'c1' }, + } + } + + it('reads stdin event JSON and returns parsed decision JSON from stdout', async () => { + const script = await writeHookScript(` + let data = '' + process.stdin.on('data', (c) => { data += c }) + process.stdin.on('end', () => { + const e = JSON.parse(data) + if (e.tool && e.tool.name === 'write_file') { + console.log(JSON.stringify({ decision: 'deny', reason: 'no writes today' })) + } else { + console.log(JSON.stringify({ decision: 'allow' })) + } + }) + `) + const d = await executeHook(hookFor(script), preEvent()) + expect(d.decision).toBe('deny') + if (d.decision === 'deny') expect(d.reason).toBe('no writes today') + }, 15_000) + + it('treats empty stdout as default allow', async () => { + const script = await writeHookScript('process.exit(0)') + const d = await executeHook(hookFor(script), preEvent()) + expect(d.decision).toBe('allow') + }, 15_000) + + it('failurePolicy:allow → non-zero exit becomes allow', async () => { + const script = await writeHookScript('process.exit(7)') + const d = await executeHook(hookFor(script), preEvent()) + expect(d.decision).toBe('allow') + }, 15_000) + + it('failurePolicy:block → non-zero exit becomes deny', async () => { + const script = await writeHookScript('process.exit(7)') + const d = await executeHook(hookFor(script, { failurePolicy: 'block' }), preEvent()) + expect(d.decision).toBe('deny') + }, 15_000) + + it('picks the platform-specific command over the base when current OS matches', async () => { + // Each candidate emits a unique reason so we can tell which one ran. + // Whichever process.platform we're on, the matching override wins. + const base = await writeHookScript('console.log(JSON.stringify({decision:"deny",reason:"BASE"}))') + const win = await writeHookScript('console.log(JSON.stringify({decision:"deny",reason:"WIN"}))') + const mac = await writeHookScript('console.log(JSON.stringify({decision:"deny",reason:"MAC"}))') + const lin = await writeHookScript('console.log(JSON.stringify({decision:"deny",reason:"NIX"}))') + + const hook: RegisteredHook = { + pluginId: 'demo@local', + pluginDir: process.cwd(), + event: 'PreToolUse', + entry: { + command: `node "${base}"`, + commandWindows: `node "${win}"`, + commandDarwin: `node "${mac}"`, + commandLinux: `node "${lin}"`, + }, + } + const d = await executeHook(hook, preEvent()) + expect(d.decision).toBe('deny') + const expected = + process.platform === 'win32' + ? 'WIN' + : process.platform === 'darwin' + ? 'MAC' + : process.platform === 'linux' + ? 'NIX' + : 'BASE' + if (d.decision === 'deny') expect(d.reason).toBe(expected) + }, 15_000) + + it('falls back to base command when current OS has no override', async () => { + const base = await writeHookScript('console.log(JSON.stringify({decision:"deny",reason:"BASE-WINS"}))') + // Set overrides only for OSes that we're NOT on. + const other = await writeHookScript('console.log(JSON.stringify({decision:"deny",reason:"OTHER"}))') + const hook: RegisteredHook = { + pluginId: 'demo@local', + pluginDir: process.cwd(), + event: 'PreToolUse', + entry: { + command: `node "${base}"`, + commandWindows: process.platform === 'win32' ? undefined : `node "${other}"`, + commandDarwin: process.platform === 'darwin' ? undefined : `node "${other}"`, + commandLinux: process.platform === 'linux' ? undefined : `node "${other}"`, + }, + } + const d = await executeHook(hook, preEvent()) + expect(d.decision).toBe('deny') + if (d.decision === 'deny') expect(d.reason).toBe('BASE-WINS') + }, 15_000) +}) diff --git a/packages/core/tests/knowledge.test.ts b/packages/core/tests/knowledge.test.ts index 5b02a5a..3a817f6 100644 --- a/packages/core/tests/knowledge.test.ts +++ b/packages/core/tests/knowledge.test.ts @@ -19,10 +19,6 @@ describe('AutoMemory', () => { memory = createTestMemory() }) - it('starts empty', () => { - expect(memory.getAll()).toEqual([]) - }) - it('adds a fact', () => { const fact: KnowledgeFact = { key: 'user-role', @@ -71,10 +67,6 @@ describe('AutoMemory', () => { expect(found!.fact).toBe('no mocks') }) - it('returns undefined for non-existent fact', () => { - expect(memory.find('nonexistent')).toBeUndefined() - }) - it('deletes a fact by key', () => { memory.add({ key: 'user-role', fact: 'senior Go engineer', category: 'user', date: '2026-04-01' }) memory.delete('user-role') diff --git a/packages/core/tests/lru-cache.test.ts b/packages/core/tests/lru-cache.test.ts index e735c27..cd5b4c9 100644 --- a/packages/core/tests/lru-cache.test.ts +++ b/packages/core/tests/lru-cache.test.ts @@ -69,28 +69,4 @@ describe('LruCache', () => { expect(cache.get('key')).toBe('value') }) }) - - it('has() returns correct boolean', () => { - const cache = new LruCache({ maxEntries: 10 }) - cache.set('x', 42) - expect(cache.has('x')).toBe(true) - expect(cache.has('y')).toBe(false) - }) - - it('tracks size correctly', () => { - const cache = new LruCache({ maxEntries: 5 }) - expect(cache.size).toBe(0) - cache.set('a', 1) - expect(cache.size).toBe(1) - cache.set('b', 2) - expect(cache.size).toBe(2) - }) - - it('overwrites existing key', () => { - const cache = new LruCache({ maxEntries: 5 }) - cache.set('a', 1) - cache.set('a', 99) - expect(cache.get('a')).toBe(99) - expect(cache.size).toBe(1) - }) }) diff --git a/packages/core/tests/mcp-config-schema.test.ts b/packages/core/tests/mcp-config-schema.test.ts index c7ccf7a..fea4901 100644 --- a/packages/core/tests/mcp-config-schema.test.ts +++ b/packages/core/tests/mcp-config-schema.test.ts @@ -51,9 +51,4 @@ describe('parseServersBlock', () => { expect(r.errors).toHaveLength(1) expect(r.errors[0].name).toBe('bad') }) - - it('rejects non-object root', () => { - const r = parseServersBlock([1, 2, 3]) - expect(r.errors[0].message).toMatch(/must be an object/) - }) }) diff --git a/packages/core/tests/media-type.test.ts b/packages/core/tests/media-type.test.ts index df9fed5..1981eae 100644 --- a/packages/core/tests/media-type.test.ts +++ b/packages/core/tests/media-type.test.ts @@ -38,9 +38,4 @@ describe('mediaTypeFor', () => { expect(mediaTypeFor('photo.PNG')).toBe('image/png') expect(mediaTypeFor('photo.WebP')).toBe('image/webp') }) - - it('works with full paths', () => { - expect(mediaTypeFor('/home/user/images/photo.jpg')).toBe('image/jpeg') - expect(mediaTypeFor('C:\\Users\\img\\shot.png')).toBe('image/png') - }) }) diff --git a/packages/core/tests/message-helpers.test.ts b/packages/core/tests/message-helpers.test.ts index 2cfd41a..e744c39 100644 --- a/packages/core/tests/message-helpers.test.ts +++ b/packages/core/tests/message-helpers.test.ts @@ -24,19 +24,4 @@ describe('extractText', () => { ] expect(extractText(content as any)).toBe('visible text') }) - - it('returns empty string for empty array', () => { - expect(extractText([])).toBe('') - }) - - it('returns empty string for non-string non-array content', () => { - expect(extractText(undefined as any)).toBe('') - expect(extractText(null as any)).toBe('') - expect(extractText(42 as any)).toBe('') - }) - - it('handles parts with missing text field', () => { - const content = [{ type: 'text' }, { type: 'text', text: 'ok' }] - expect(extractText(content as any)).toBe('ok') - }) }) diff --git a/packages/core/tests/messages.test.ts b/packages/core/tests/messages.test.ts index 20ebe7b..8dff29d 100644 --- a/packages/core/tests/messages.test.ts +++ b/packages/core/tests/messages.test.ts @@ -41,12 +41,6 @@ describe('userMessage', () => { }) }) -describe('toolErrorString', () => { - it('prefixes the message with "Error: "', () => { - expect(toolErrorString('boom')).toBe('Error: boom') - }) -}) - describe('toolErrorFromUnknown', () => { it('extracts the message from an Error instance', () => { expect(toolErrorFromUnknown(new Error('disk full'))).toBe('Error: disk full') diff --git a/packages/core/tests/permissions.test.ts b/packages/core/tests/permissions.test.ts index 8ac5c00..1b70a7d 100644 --- a/packages/core/tests/permissions.test.ts +++ b/packages/core/tests/permissions.test.ts @@ -19,10 +19,6 @@ describe('getPermissionLevel', () => { expect(getPermissionLevel('writeFile', {})).toBe('ask') }) - it('returns ask for unknown tools', () => { - expect(getPermissionLevel('unknownTool', {})).toBe('ask') - }) - it('returns always-allow for read-only shell commands', () => { expect(getPermissionLevel('shell', { command: 'ls -la' })).toBe('always-allow') expect(getPermissionLevel('shell', { command: 'pwd' })).toBe('always-allow') diff --git a/packages/core/tests/plugins-consent.test.ts b/packages/core/tests/plugins-consent.test.ts new file mode 100644 index 0000000..23c4a2c --- /dev/null +++ b/packages/core/tests/plugins-consent.test.ts @@ -0,0 +1,158 @@ +// Tests for the install-time consent preview and the default-marketplace seed. +import { afterEach, beforeEach, describe, expect, it } from 'vitest' + +import fs from 'node:fs/promises' +import os from 'node:os' +import path from 'node:path' + +import { buildConsentPreview } from '../src/plugins/consent.js' +import { installPlugin } from '../src/plugins/installer.js' +import { ensureDefaultMarketplaces, readKnownMarketplaces } from '../src/plugins/marketplace.js' + +let originalPluginsDir: string | undefined + +async function writeFileAt(file: string, body: string): Promise { + await fs.mkdir(path.dirname(file), { recursive: true }) + await fs.writeFile(file, body, 'utf-8') +} + +beforeEach(async () => { + originalPluginsDir = process.env.XC_PLUGINS_DIR + const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-plugin-consent-test-')) + process.env.XC_PLUGINS_DIR = tmp +}) + +afterEach(() => { + if (originalPluginsDir === undefined) delete process.env.XC_PLUGINS_DIR + else process.env.XC_PLUGINS_DIR = originalPluginsDir +}) + +describe('buildConsentPreview', () => { + it('extracts hook event names from an inline hook block', () => { + const preview = buildConsentPreview({ + pluginId: 'demo@local', + marketplace: 'local', + source: { kind: 'local', path: '/p' }, + manifest: { + schemaVersion: '1', + name: 'demo', + version: '1.0.0', + hooks: { PreToolUse: [{ command: 'lint.sh' }], TurnComplete: [{ command: 'notify.sh' }] }, + }, + }) + expect(preview.hookEvents).toEqual(['PreToolUse', 'TurnComplete']) + expect(preview.hasPathHooks).toBe(false) + }) + + it('extracts inline mcpServer names', () => { + const preview = buildConsentPreview({ + pluginId: 'demo@local', + marketplace: 'local', + source: { kind: 'local', path: '/p' }, + manifest: { + schemaVersion: '1', + name: 'demo', + version: '1.0.0', + mcpServers: { gh: { command: 'gh-mcp' }, lin: { command: 'linear-mcp' } }, + }, + }) + expect(preview.inlineMcpServerNames.sort()).toEqual(['gh', 'lin']) + expect(preview.hasPathMcpServers).toBe(false) + }) +}) + +describe('installPlugin + consent', () => { + async function makeLocalPlugin(): Promise { + const src = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-consent-src-')) + await writeFileAt( + path.join(src, 'plugin.json'), + JSON.stringify({ + name: 'demo', + version: '1.0.0', + hooks: { PreToolUse: [{ command: 'x' }] }, + mcpServers: { gh: { command: 'gh' } }, + }), + ) + return src + } + + it('passes a preview reflecting the manifest to the consent callback', async () => { + const src = await makeLocalPlugin() + let received: { pluginId: string; hookEvents: string[]; mcpNames: string[] } | null = null + await installPlugin({ + source: { kind: 'local', path: src }, + marketplace: 'local', + consent: async (preview) => { + received = { + pluginId: preview.pluginId, + hookEvents: preview.hookEvents, + mcpNames: preview.inlineMcpServerNames, + } + return true + }, + }) + expect(received).toEqual({ + pluginId: 'demo@local', + hookEvents: ['PreToolUse'], + mcpNames: ['gh'], + }) + }) + + it('aborts install + cleans cache when consent returns false', async () => { + const src = await makeLocalPlugin() + await expect( + installPlugin({ + source: { kind: 'local', path: src }, + marketplace: 'local', + consent: async () => false, + }), + ).rejects.toThrow(/consent/) + + // installed_plugins.json should NOT have an entry + const { listInstalledPlugins } = await import('../src/plugins/installer.js') + expect(await listInstalledPlugins()).toEqual([]) + }) + + it('proceeds without prompting when no consent callback is given', async () => { + const src = await makeLocalPlugin() + const result = await installPlugin({ + source: { kind: 'local', path: src }, + marketplace: 'local', + }) + expect(result.pluginId).toBe('demo@local') + }) +}) + +describe('ensureDefaultMarketplaces', () => { + it('writes anthropic-marketplace on first run', async () => { + await ensureDefaultMarketplaces() + const km = await readKnownMarketplaces() + expect(km.marketplaces.map((m) => m.name)).toEqual(['anthropic-marketplace']) + expect(km.marketplaces[0]!.reservedName).toBe(true) + expect(km.marketplaces[0]!.officialSource).toBe('anthropics') + }) + + it('is idempotent on repeated runs', async () => { + await ensureDefaultMarketplaces() + await ensureDefaultMarketplaces() + await ensureDefaultMarketplaces() + const km = await readKnownMarketplaces() + expect(km.marketplaces).toHaveLength(1) + }) + + it('does not re-add when the user explicitly removed the subscription', async () => { + await ensureDefaultMarketplaces() + const { removeKnownMarketplace } = await import('../src/plugins/marketplace.js') + await removeKnownMarketplace('anthropic-marketplace') + + await ensureDefaultMarketplaces() + + // ensureDefaultMarketplaces re-adds when the entry is absent, so this + // re-run WILL re-subscribe. That's intentional: "missing" looks the + // same as "first run" to keep the seed simple. Verify the current + // behaviour so future-us doesn't regress it accidentally without + // a conscious choice. + const km = await readKnownMarketplaces() + expect(km.marketplaces).toHaveLength(1) + }) +}) diff --git a/packages/core/tests/plugins-install-load.test.ts b/packages/core/tests/plugins-install-load.test.ts new file mode 100644 index 0000000..bc76adf --- /dev/null +++ b/packages/core/tests/plugins-install-load.test.ts @@ -0,0 +1,454 @@ +// Tests for installer (local source path) + loader integration +import { afterEach, beforeEach, describe, expect, it } from 'vitest' + +import fs from 'node:fs/promises' +import os from 'node:os' +import path from 'node:path' + +import { + InstallError, + findInstalledPlugin, + installPlugin, + listInstalledPlugins, + uninstallPlugin, +} from '../src/plugins/installer.js' +import { loadAllPlugins, resolveContributions } from '../src/plugins/loader.js' +import { pluginCacheDir } from '../src/plugins/paths.js' + +let originalPluginsDir: string | undefined + +async function makeTempPlugin(body: Record, rel = 'plugin.json'): Promise { + const root = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-plugin-src-')) + const file = path.join(root, rel) + await fs.mkdir(path.dirname(file), { recursive: true }) + await fs.writeFile(file, JSON.stringify(body, null, 2), 'utf-8') + return root +} + +beforeEach(async () => { + originalPluginsDir = process.env.XC_PLUGINS_DIR + const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-plugins-cache-test-')) + process.env.XC_PLUGINS_DIR = tmp +}) + +afterEach(() => { + if (originalPluginsDir === undefined) delete process.env.XC_PLUGINS_DIR + else process.env.XC_PLUGINS_DIR = originalPluginsDir +}) + +// ── installer ────────────────────────────────────────────────────────── + +describe('installPlugin (local source)', () => { + it('copies a local plugin into the cache + records it', async () => { + const src = await makeTempPlugin({ name: 'demo', version: '1.0.0', description: 'd' }) + + const result = await installPlugin({ + source: { kind: 'local', path: src }, + marketplace: 'local', + }) + + expect(result.pluginId).toBe('demo@local') + expect(result.manifest.name).toBe('demo') + expect(result.rootDir).toBe(pluginCacheDir('local', 'demo', '1.0.0')) + + // Cached manifest should be present + expect( + await fs + .access(path.join(result.rootDir, 'plugin.json')) + .then(() => true) + .catch(() => false), + ).toBe(true) + + // Record landed + const installed = await listInstalledPlugins() + expect(installed).toHaveLength(1) + expect(installed[0]!.id).toBe('demo@local') + expect(installed[0]!.version).toBe('1.0.0') + }) + + it('rejects a Gemini-only source with a friendly error', async () => { + const src = await makeTempPlugin({ name: 'demo', version: '1.0.0' }, 'gemini-extension.json') + + await expect(installPlugin({ source: { kind: 'local', path: src }, marketplace: 'local' })).rejects.toThrow( + /Gemini extension/, + ) + }) + + it('rejects a source with no manifest', async () => { + const src = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-plugin-empty-')) + await expect(installPlugin({ source: { kind: 'local', path: src }, marketplace: 'local' })).rejects.toBeInstanceOf( + InstallError, + ) + }) + + it('enforces expectedName when set', async () => { + const src = await makeTempPlugin({ name: 'actually-this', version: '1.0.0' }) + await expect( + installPlugin({ + source: { kind: 'local', path: src }, + marketplace: 'local', + expectedName: 'something-else', + }), + ).rejects.toThrow(/does not match/) + }) + + it('re-installs over an existing same-version install (wipes first)', async () => { + const src1 = await makeTempPlugin({ name: 'demo', version: '1.0.0' }) + await installPlugin({ source: { kind: 'local', path: src1 }, marketplace: 'local' }) + + // Stash a marker file in the cache dir + const dir = pluginCacheDir('local', 'demo', '1.0.0') + await fs.writeFile(path.join(dir, 'stale.txt'), 'should not survive') + + const src2 = await makeTempPlugin({ name: 'demo', version: '1.0.0', description: 'updated' }) + await installPlugin({ source: { kind: 'local', path: src2 }, marketplace: 'local' }) + + // Stale file should be gone after the wipe-and-replace + const staleExists = await fs + .access(path.join(dir, 'stale.txt')) + .then(() => true) + .catch(() => false) + expect(staleExists).toBe(false) + }) + + it('also copies non-manifest files (skills/, agents/, etc.) into the cache', async () => { + const src = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-plugin-rich-')) + await fs.writeFile( + path.join(src, 'plugin.json'), + JSON.stringify({ name: 'demo', version: '1.0.0', skills: './skills' }), + ) + await fs.mkdir(path.join(src, 'skills', 'foo'), { recursive: true }) + await fs.writeFile(path.join(src, 'skills', 'foo', 'SKILL.md'), '---\nname: foo\ndescription: d\n---\n') + + const result = await installPlugin({ source: { kind: 'local', path: src }, marketplace: 'local' }) + const skillFile = path.join(result.rootDir, 'skills', 'foo', 'SKILL.md') + expect( + await fs + .access(skillFile) + .then(() => true) + .catch(() => false), + ).toBe(true) + }) +}) + +describe('install policy gates (strictKnownMarketplaces + blockedPlugins)', () => { + // These two known_marketplaces.json fields exist to give admins + // enforceable control over what gets installed. Both used to be + // parsed but never checked — these tests pin the new enforcement. + + it('strictKnownMarketplaces rejects installs from a non-subscribed marketplace', async () => { + const file = path.join(process.env.XC_PLUGINS_DIR!, 'known_marketplaces.json') + await fs.mkdir(path.dirname(file), { recursive: true }) + await fs.writeFile(file, JSON.stringify({ marketplaces: [], strictKnownMarketplaces: true })) + + const src = await makeTempPlugin({ name: 'demo', version: '1.0.0' }) + await expect(installPlugin({ source: { kind: 'local', path: src }, marketplace: 'local' })).rejects.toThrow( + /strict marketplace mode/, + ) + }) + + it('strictKnownMarketplaces accepts installs whose marketplace IS subscribed', async () => { + const file = path.join(process.env.XC_PLUGINS_DIR!, 'known_marketplaces.json') + await fs.mkdir(path.dirname(file), { recursive: true }) + await fs.writeFile( + file, + JSON.stringify({ + marketplaces: [{ name: 'official', source: 'github:foo/official' }], + strictKnownMarketplaces: true, + }), + ) + + const src = await makeTempPlugin({ name: 'demo', version: '1.0.0' }) + const result = await installPlugin({ source: { kind: 'local', path: src }, marketplace: 'official' }) + expect(result.pluginId).toBe('demo@official') + }) + + it('blockedPlugins rejects matching id regardless of marketplace / consent', async () => { + const file = path.join(process.env.XC_PLUGINS_DIR!, 'known_marketplaces.json') + await fs.mkdir(path.dirname(file), { recursive: true }) + await fs.writeFile(file, JSON.stringify({ marketplaces: [], blockedPlugins: ['demo@local'] })) + + const src = await makeTempPlugin({ name: 'demo', version: '1.0.0' }) + await expect(installPlugin({ source: { kind: 'local', path: src }, marketplace: 'local' })).rejects.toThrow( + /blockedPlugins/, + ) + }) +}) + +describe('uninstallPlugin', () => { + it('removes cache + record + returns the version it cleaned up', async () => { + const src = await makeTempPlugin({ name: 'demo', version: '1.0.0' }) + await installPlugin({ source: { kind: 'local', path: src }, marketplace: 'local' }) + + const result = await uninstallPlugin('demo@local') + expect(result.removedRecord).toBe(true) + expect(result.removedVersions).toEqual(['1.0.0']) + + expect(await findInstalledPlugin('demo@local')).toBeUndefined() + }) + + it('is a no-op for an unknown plugin', async () => { + const result = await uninstallPlugin('ghost@local') + expect(result).toEqual({ removedRecord: false, removedVersions: [] }) + }) +}) + +// ── loader ───────────────────────────────────────────────────────────── + +describe('loadAllPlugins', () => { + it('returns empty registry when disabled', async () => { + const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-loader-cwd-')) + const result = await loadAllPlugins({ cwd, disabled: true }) + expect(result.registry.list()).toEqual([]) + expect(result.contributions.size).toBe(0) + }) + + it('loads globally-installed plugins from installed_plugins.json', async () => { + const src = await makeTempPlugin({ name: 'demo', version: '1.0.0', skills: './skills' }) + await installPlugin({ source: { kind: 'local', path: src }, marketplace: 'local' }) + + const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-loader-cwd-')) + const result = await loadAllPlugins({ cwd }) + + const list = result.registry.listAll() + expect(list).toHaveLength(1) + expect(list[0]!.id).toBe('demo@local') + expect(list[0]!.enabled).toBe(true) // default-enable + + const contrib = result.contributions.get('demo@local') + expect(contrib?.skillsDir).toBe(path.resolve(list[0]!.rootDir, './skills')) + }) + + it('loads project-local plugins from /.x-code/plugins//', async () => { + const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-loader-cwd-')) + const pluginDir = path.join(cwd, '.x-code', 'plugins', 'inhouse') + await fs.mkdir(pluginDir, { recursive: true }) + await fs.writeFile(path.join(pluginDir, 'plugin.json'), JSON.stringify({ name: 'inhouse', version: '0.1.0' })) + + const result = await loadAllPlugins({ cwd }) + const list = result.registry.listAll() + expect(list).toHaveLength(1) + expect(list[0]!.id).toBe('inhouse@local') + expect(list[0]!.scope).toBe('project') + }) + + it('records load errors for broken manifests without aborting', async () => { + const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-loader-cwd-')) + const broken = path.join(cwd, '.x-code', 'plugins', 'broken') + await fs.mkdir(broken, { recursive: true }) + await fs.writeFile(path.join(broken, 'plugin.json'), '{ not json', 'utf-8') + + const good = path.join(cwd, '.x-code', 'plugins', 'good') + await fs.mkdir(good, { recursive: true }) + await fs.writeFile(path.join(good, 'plugin.json'), JSON.stringify({ name: 'good', version: '1.0.0' })) + + const result = await loadAllPlugins({ cwd }) + expect(result.registry.listAll()).toHaveLength(1) + expect(result.registry.listAll()[0]!.id).toBe('good@local') + expect(result.registry.loadErrors()).toHaveLength(1) + expect(result.registry.loadErrors()[0]!.path).toBe(broken) + }) + + it('records a Gemini-extension load error without crashing', async () => { + const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-loader-cwd-')) + const gemini = path.join(cwd, '.x-code', 'plugins', 'gemini-plugin') + await fs.mkdir(gemini, { recursive: true }) + await fs.writeFile( + path.join(gemini, 'gemini-extension.json'), + JSON.stringify({ name: 'gemini-plugin', version: '1.0.0' }), + ) + + const result = await loadAllPlugins({ cwd }) + expect(result.registry.listAll()).toHaveLength(0) + expect(result.registry.loadErrors()).toHaveLength(1) + expect(result.registry.loadErrors()[0]!.message).toMatch(/Gemini/) + }) + + it('respects enable flags from /.x-code/settings.local.json', async () => { + const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-loader-cwd-')) + const pluginDir = path.join(cwd, '.x-code', 'plugins', 'disabled-one') + await fs.mkdir(pluginDir, { recursive: true }) + await fs.writeFile(path.join(pluginDir, 'plugin.json'), JSON.stringify({ name: 'disabled-one', version: '1.0.0' })) + + await fs.writeFile( + path.join(cwd, '.x-code', 'settings.local.json'), + JSON.stringify({ enabledPlugins: { 'disabled-one@local': false } }), + ) + + const result = await loadAllPlugins({ cwd }) + const list = result.registry.listAll() + expect(list).toHaveLength(1) + expect(list[0]!.enabled).toBe(false) + expect(result.registry.list()).toHaveLength(0) // hidden by .list() filter + }) +}) + +describe('resolveContributions', () => { + it('resolves manifest-declared paths against rootDir', async () => { + const plugin = { + id: 'demo@local', + manifest: { + schemaVersion: '1', + name: 'demo', + version: '1.0.0', + skills: './skills', + agents: './agents', + mcpServers: './mcp.json', + }, + rootDir: '/abs/root', + manifestPath: '/abs/root/plugin.json', + manifestFormat: 'bare' as const, + source: undefined, + marketplace: 'local', + scope: 'project' as const, + enabled: true, + } + const c = await resolveContributions(plugin) + expect(c.skillsDir).toBe(path.resolve('/abs/root', './skills')) + expect(c.agentsDir).toBe(path.resolve('/abs/root', './agents')) + expect(c.mcpServers).toEqual({ kind: 'path', path: path.resolve('/abs/root', './mcp.json') }) + }) + + it('auto-discovers commands/ agents/ skills/ when manifest omits them (Claude Code convention)', async () => { + // Build a real on-disk plugin so the convention-based fs.stat + // probes have something to find. + const root = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-resolve-conv-')) + await fs.writeFile(path.join(root, 'plugin.json'), JSON.stringify({ name: 'demo', version: '1.0.0' })) + await fs.mkdir(path.join(root, 'commands'), { recursive: true }) + await fs.mkdir(path.join(root, 'agents'), { recursive: true }) + await fs.writeFile(path.join(root, '.mcp.json'), JSON.stringify({ mcpServers: {} })) + + const plugin = { + id: 'demo@local', + manifest: { schemaVersion: '1', name: 'demo', version: '1.0.0' }, + rootDir: root, + manifestPath: path.join(root, 'plugin.json'), + manifestFormat: 'bare' as const, + source: undefined, + marketplace: 'local', + scope: 'project' as const, + enabled: true, + } + const c = await resolveContributions(plugin) + expect(c.commandsDir).toBe(path.join(root, 'commands')) + expect(c.agentsDir).toBe(path.join(root, 'agents')) + expect(c.skillsDir).toBeUndefined() // no skills/ dir → undefined + expect(c.mcpServers).toEqual({ kind: 'path', path: path.join(root, '.mcp.json') }) + }) +}) + +// ── userConfig install-time prompt ───────────────────────────────────── + +describe('installPlugin (userConfig prompt)', () => { + it('passes manifest userConfig fields to the callback and persists the returned values', async () => { + const { getPluginUserConfig } = await import('../src/plugins/user-config.js') + const src = await makeTempPlugin({ + name: 'cfg-demo', + version: '1.0.0', + userConfig: [ + { key: 'API_KEY', type: 'string', sensitive: true, prompt: 'Enter the key' }, + { key: 'BASE_URL', type: 'string', default: 'https://api.example.com' }, + ], + }) + + let receivedFields: unknown + const result = await installPlugin({ + source: { kind: 'local', path: src }, + marketplace: 'local', + userConfigPrompt: async (fields) => { + receivedFields = fields + return { API_KEY: 'sk-test', BASE_URL: 'https://override' } + }, + }) + + // Callback saw both fields verbatim. + expect(Array.isArray(receivedFields)).toBe(true) + expect((receivedFields as Array<{ key: string }>).map((f) => f.key)).toEqual(['API_KEY', 'BASE_URL']) + + // Persisted to user-config.json under the plugin id. + const stored = await getPluginUserConfig(result.pluginId) + expect(stored).toEqual({ API_KEY: 'sk-test', BASE_URL: 'https://override' }) + }) + + it('aborts the install when the userConfig prompt returns null', async () => { + const src = await makeTempPlugin({ + name: 'aborted', + version: '1.0.0', + userConfig: [{ key: 'TOKEN', type: 'string', required: true }], + }) + + await expect( + installPlugin({ + source: { kind: 'local', path: src }, + marketplace: 'local', + userConfigPrompt: async () => null, + }), + ).rejects.toThrow(/userConfig/) + + // No cache entry created (aborted before move). + const installed = await listInstalledPlugins() + expect(installed).toHaveLength(0) + }) + + it('skips the prompt entirely when manifest declares no userConfig', async () => { + const src = await makeTempPlugin({ name: 'no-cfg', version: '1.0.0' }) + let calls = 0 + await installPlugin({ + source: { kind: 'local', path: src }, + marketplace: 'local', + userConfigPrompt: async () => { + calls++ + return {} + }, + }) + expect(calls).toBe(0) + }) +}) + +// ── /plugin refresh hot reload ───────────────────────────────────────── + +describe('refreshPluginContributions', () => { + it('detects an added plugin between two scans and folds it into the skill registry', async () => { + const { refreshPluginContributions } = await import('../src/plugins/refresh.js') + const { createSkillRegistry } = await import('../src/skills/registry.js') + + // Install one plugin with a skill, build registries from that snapshot. + const src1 = await makeTempPlugin({ name: 'p1', version: '1.0.0' }) + // Add a skill dir so resolveContributions auto-detects it. + await fs.mkdir(path.join(src1, 'skills', 'hello'), { recursive: true }) + await fs.writeFile( + path.join(src1, 'skills', 'hello', 'SKILL.md'), + '---\nname: hello\ndescription: greet\n---\nBody', + 'utf-8', + ) + await installPlugin({ source: { kind: 'local', path: src1 }, marketplace: 'local' }) + + const initialLoad = await loadAllPlugins({ cwd: process.cwd() }) + const { buildPluginIntegration } = await import('../src/plugins/integration.js') + const initialIntegration = await buildPluginIntegration(initialLoad) + const skillRegistry = await createSkillRegistry({ extraDirs: initialIntegration.skillsDirs }) + expect(skillRegistry.get('hello')).toBeDefined() + + // Install a second plugin AFTER initial load. The new skill should + // NOT show up until /plugin refresh runs. + const src2 = await makeTempPlugin({ name: 'p2', version: '1.0.0' }) + await fs.mkdir(path.join(src2, 'skills', 'world'), { recursive: true }) + await fs.writeFile( + path.join(src2, 'skills', 'world', 'SKILL.md'), + '---\nname: world\ndescription: w\n---\nBody', + 'utf-8', + ) + await installPlugin({ source: { kind: 'local', path: src2 }, marketplace: 'local' }) + expect(skillRegistry.get('world')).toBeUndefined() + + // Refresh: rebuilds plugin registry and folds new skills in. + const summary = await refreshPluginContributions({ + pluginRegistry: initialLoad.registry, + skillRegistry, + }) + expect(summary.plugins.added).toContain('p2@local') + expect(skillRegistry.get('world')).toBeDefined() + // Existing plugin still loaded. + expect(skillRegistry.get('hello')).toBeDefined() + }) +}) diff --git a/packages/core/tests/plugins-integration.test.ts b/packages/core/tests/plugins-integration.test.ts new file mode 100644 index 0000000..d4629ec --- /dev/null +++ b/packages/core/tests/plugins-integration.test.ts @@ -0,0 +1,218 @@ +// Tests for plugin → existing-loader integration +import { afterEach, beforeEach, describe, expect, it } from 'vitest' + +import fs from 'node:fs/promises' +import os from 'node:os' +import path from 'node:path' + +import { installPlugin } from '../src/plugins/installer.js' +import { buildPluginIntegration } from '../src/plugins/integration.js' +import { loadAllPlugins } from '../src/plugins/loader.js' + +let originalPluginsDir: string | undefined + +async function writeFileAt(file: string, body: string): Promise { + await fs.mkdir(path.dirname(file), { recursive: true }) + await fs.writeFile(file, body, 'utf-8') +} + +beforeEach(async () => { + originalPluginsDir = process.env.XC_PLUGINS_DIR + const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-plugins-int-test-')) + process.env.XC_PLUGINS_DIR = tmp +}) + +afterEach(() => { + if (originalPluginsDir === undefined) delete process.env.XC_PLUGINS_DIR + else process.env.XC_PLUGINS_DIR = originalPluginsDir +}) + +describe('buildPluginIntegration', () => { + it('lists skill + agent dirs for each enabled plugin (resolved absolute)', async () => { + // Build a source plugin tree with skills/ and agents/ dirs + const src = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-plugin-src-')) + await writeFileAt( + path.join(src, 'plugin.json'), + JSON.stringify({ name: 'demo', version: '1.0.0', skills: './skills', agents: './agents' }), + ) + await fs.mkdir(path.join(src, 'skills'), { recursive: true }) + await fs.mkdir(path.join(src, 'agents'), { recursive: true }) + + await installPlugin({ source: { kind: 'local', path: src }, marketplace: 'local' }) + + const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-cwd-')) + const load = await loadAllPlugins({ cwd }) + const out = await buildPluginIntegration(load) + + expect(out.skillsDirs).toHaveLength(1) + expect(out.skillsDirs[0]!.pluginId).toBe('demo@local') + expect(path.isAbsolute(out.skillsDirs[0]!.dir)).toBe(true) + expect(out.agentsDirs[0]!.dir).toContain('agents') + }) + + it('surfaces commandsDirs for any plugin with a commands/ contribution', async () => { + const src = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-plugin-src-')) + await writeFileAt( + path.join(src, 'plugin.json'), + JSON.stringify({ name: 'demo', version: '1.0.0', commands: './cmds' }), + ) + await fs.mkdir(path.join(src, 'cmds'), { recursive: true }) + + await installPlugin({ source: { kind: 'local', path: src }, marketplace: 'local' }) + const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-cwd-')) + const out = await buildPluginIntegration(await loadAllPlugins({ cwd })) + + expect(out.commandsDirs).toHaveLength(1) + expect(out.commandsDirs[0]!.pluginId).toBe('demo@local') + expect(out.commandsDirs[0]!.pluginRoot).toBeDefined() + }) + + it('builds a HookRegistry from inline hooks contributions', async () => { + const src = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-plugin-src-')) + await writeFileAt( + path.join(src, 'plugin.json'), + JSON.stringify({ + name: 'demo', + version: '1.0.0', + hooks: { PreToolUse: [{ command: 'lint.sh' }] }, + }), + ) + await installPlugin({ source: { kind: 'local', path: src }, marketplace: 'local' }) + + const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-cwd-')) + const out = await buildPluginIntegration(await loadAllPlugins({ cwd })) + + expect(out.pluginHooks).toHaveLength(1) + expect(out.pluginHooks[0]!.events).toEqual(['PreToolUse']) + expect(out.hookRegistry.has('PreToolUse')).toBe(true) + expect(out.hookRegistry.get('PreToolUse')).toHaveLength(1) + expect(out.hookRegistry.get('PreToolUse')[0]!.pluginId).toBe('demo@local') + expect(out.hookErrors).toEqual([]) + }) + + it('records hook config parse errors per plugin without crashing the rest', async () => { + const bad = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-plugin-bad-')) + await writeFileAt( + path.join(bad, 'plugin.json'), + JSON.stringify({ + name: 'badhook', + version: '1.0.0', + // missing command — schema rejects + hooks: { PreToolUse: [{ matcher: 'edit_file' }] }, + }), + ) + await installPlugin({ source: { kind: 'local', path: bad }, marketplace: 'local' }) + + const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-cwd-')) + const out = await buildPluginIntegration(await loadAllPlugins({ cwd })) + + expect(out.hookErrors).toHaveLength(1) + expect(out.hookErrors[0]!.pluginId).toBe('badhook@local') + expect(out.hookRegistry.list()).toHaveLength(0) + }) + + it('parses path-style mcpServers from a JSON file at the plugin root', async () => { + const src = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-plugin-src-')) + await writeFileAt( + path.join(src, 'plugin.json'), + JSON.stringify({ name: 'demo', version: '1.0.0', mcpServers: './mcp.json' }), + ) + await writeFileAt(path.join(src, 'mcp.json'), JSON.stringify({ mcpServers: { gh: { command: 'gh-mcp' } } })) + await installPlugin({ source: { kind: 'local', path: src }, marketplace: 'local' }) + + const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-cwd-')) + const out = await buildPluginIntegration(await loadAllPlugins({ cwd })) + + expect(out.mcpServers.gh).toBeDefined() + expect((out.mcpServers.gh as { command?: string }).command).toBe('gh-mcp') + }) + + it('resolves mcpServers name collisions first-wins + records the loser', async () => { + // Two plugins both contribute a server named "gh" + const srcA = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-plugin-srcA-')) + await writeFileAt( + path.join(srcA, 'plugin.json'), + JSON.stringify({ + name: 'aaa-first', + version: '1.0.0', + mcpServers: { gh: { command: 'first-cmd' } }, + }), + ) + await installPlugin({ source: { kind: 'local', path: srcA }, marketplace: 'local' }) + + const srcB = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-plugin-srcB-')) + await writeFileAt( + path.join(srcB, 'plugin.json'), + JSON.stringify({ + name: 'bbb-second', + version: '1.0.0', + mcpServers: { gh: { command: 'second-cmd' } }, + }), + ) + await installPlugin({ source: { kind: 'local', path: srcB }, marketplace: 'local' }) + + const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-cwd-')) + const out = await buildPluginIntegration(await loadAllPlugins({ cwd })) + + // First install wins (installed_plugins.json order) + expect((out.mcpServers.gh as { command?: string }).command).toBe('first-cmd') + expect(out.mcpCollisions).toHaveLength(1) + expect(out.mcpCollisions[0]).toEqual({ + name: 'gh', + droppedFrom: 'bbb-second@local', + keptFrom: 'aaa-first@local', + }) + }) + + it('records mcp parse errors per plugin without killing the others', async () => { + const bad = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-plugin-bad-')) + await writeFileAt( + path.join(bad, 'plugin.json'), + JSON.stringify({ + name: 'badmcp', + version: '1.0.0', + // Has neither command nor url — mcp config schema must reject this entry + mcpServers: { broken: { args: ['x'] } }, + }), + ) + await installPlugin({ source: { kind: 'local', path: bad }, marketplace: 'local' }) + + const good = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-plugin-good-')) + await writeFileAt( + path.join(good, 'plugin.json'), + JSON.stringify({ + name: 'goodmcp', + version: '1.0.0', + mcpServers: { ok: { command: 'echo' } }, + }), + ) + await installPlugin({ source: { kind: 'local', path: good }, marketplace: 'local' }) + + const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-cwd-')) + const out = await buildPluginIntegration(await loadAllPlugins({ cwd })) + + expect(out.mcpErrors).toHaveLength(1) + expect(out.mcpErrors[0]!.pluginId).toBe('badmcp@local') + // Good plugin's server still landed + expect(out.mcpServers.ok).toBeDefined() + }) + + it('skips contributions from disabled plugins', async () => { + const src = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-plugin-src-')) + await writeFileAt( + path.join(src, 'plugin.json'), + JSON.stringify({ name: 'demo', version: '1.0.0', mcpServers: { gh: { command: 'gh-mcp' } } }), + ) + await installPlugin({ source: { kind: 'local', path: src }, marketplace: 'local' }) + + const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-int-cwd-')) + // Disable the plugin via project settings + await writeFileAt( + path.join(cwd, '.x-code', 'settings.local.json'), + JSON.stringify({ enabledPlugins: { 'demo@local': false } }), + ) + + const out = await buildPluginIntegration(await loadAllPlugins({ cwd })) + expect(out.mcpServers).toEqual({}) + }) +}) diff --git a/packages/core/tests/plugins-manifest.test.ts b/packages/core/tests/plugins-manifest.test.ts new file mode 100644 index 0000000..3ee5343 --- /dev/null +++ b/packages/core/tests/plugins-manifest.test.ts @@ -0,0 +1,125 @@ +// Tests for plugin manifest discovery + parsing +import { describe, expect, it } from 'vitest' + +import fs from 'node:fs/promises' +import os from 'node:os' +import path from 'node:path' + +import { ManifestParseError, discoverManifest, parseManifest } from '../src/plugins/manifest.js' + +async function makeTempPluginDir(): Promise { + return fs.mkdtemp(path.join(os.tmpdir(), 'xc-plugin-test-')) +} + +async function writeManifest(rootDir: string, rel: string, body: unknown): Promise { + const full = path.join(rootDir, rel) + await fs.mkdir(path.dirname(full), { recursive: true }) + await fs.writeFile(full, JSON.stringify(body, null, 2), 'utf-8') + return full +} + +describe('discoverManifest', () => { + it('returns null when no manifest exists', async () => { + const root = await makeTempPluginDir() + expect(await discoverManifest(root)).toBeNull() + }) + + it('finds .x-code-plugin/plugin.json (native, highest priority)', async () => { + const root = await makeTempPluginDir() + const expected = await writeManifest(root, '.x-code-plugin/plugin.json', { name: 'foo', version: '1.0.0' }) + // Also write a competing claude manifest — native must still win. + await writeManifest(root, '.claude-plugin/plugin.json', { name: 'foo', version: '1.0.0' }) + + const result = await discoverManifest(root) + expect(result).toEqual({ manifestPath: expected, format: 'native' }) + }) + + it('finds .claude-plugin/plugin.json (Claude Code compat)', async () => { + const root = await makeTempPluginDir() + const expected = await writeManifest(root, '.claude-plugin/plugin.json', { name: 'foo', version: '1.0.0' }) + + const result = await discoverManifest(root) + expect(result).toEqual({ manifestPath: expected, format: 'claude' }) + }) + + it('flags gemini-extension.json as unsupported (not silently ignored)', async () => { + const root = await makeTempPluginDir() + const expected = await writeManifest(root, 'gemini-extension.json', { name: 'foo', version: '1.0.0' }) + + const result = await discoverManifest(root) + expect(result).toEqual({ manifestPath: expected, format: 'gemini' }) + }) +}) + +describe('parseManifest', () => { + it('parses a minimal valid manifest', async () => { + const root = await makeTempPluginDir() + const file = await writeManifest(root, 'plugin.json', { name: 'foo', version: '1.0.0' }) + + const manifest = await parseManifest(file) + expect(manifest).toMatchObject({ + schemaVersion: '1', + name: 'foo', + version: '1.0.0', + }) + }) + + it('accepts inline mcpServers and hooks objects', async () => { + const root = await makeTempPluginDir() + const file = await writeManifest(root, 'plugin.json', { + name: 'foo', + version: '1.0.0', + mcpServers: { my_server: { command: 'node', args: ['server.js'] } }, + hooks: { PreToolUse: [{ command: 'lint.sh' }] }, + }) + + const manifest = await parseManifest(file) + expect(typeof manifest.mcpServers).toBe('object') + expect(typeof manifest.hooks).toBe('object') + }) + + it('normalises string author to object form', async () => { + const root = await makeTempPluginDir() + const file = await writeManifest(root, 'plugin.json', { + name: 'foo', + version: '1.0.0', + author: 'Some Author', + }) + + const manifest = await parseManifest(file) + expect(manifest.author).toEqual({ name: 'Some Author' }) + }) + + it('silently strips unknown top-level fields (forward compat)', async () => { + const root = await makeTempPluginDir() + const file = await writeManifest(root, 'plugin.json', { + name: 'foo', + version: '1.0.0', + // Claude Code-only fields we don't implement — must not reject. + 'output-styles': './styles', + lspServers: { foo: { command: 'lsp' } }, + unknownFutureField: 42, + }) + + const manifest = await parseManifest(file) + expect(manifest.name).toBe('foo') + // Unknown fields are dropped. + expect((manifest as Record)['output-styles']).toBeUndefined() + expect((manifest as Record).lspServers).toBeUndefined() + }) + + it('rejects invalid name (uppercase)', async () => { + const root = await makeTempPluginDir() + const file = await writeManifest(root, 'plugin.json', { name: 'Foo', version: '1.0.0' }) + + await expect(parseManifest(file)).rejects.toBeInstanceOf(ManifestParseError) + }) + + it('rejects malformed JSON with a path-tagged error', async () => { + const root = await makeTempPluginDir() + const file = path.join(root, 'plugin.json') + await fs.writeFile(file, '{ not json', 'utf-8') + + await expect(parseManifest(file)).rejects.toBeInstanceOf(ManifestParseError) + }) +}) diff --git a/packages/core/tests/plugins-marketplace.test.ts b/packages/core/tests/plugins-marketplace.test.ts new file mode 100644 index 0000000..c16029f --- /dev/null +++ b/packages/core/tests/plugins-marketplace.test.ts @@ -0,0 +1,238 @@ +// Tests for marketplace parsing + known_marketplaces.json registry +import { afterEach, beforeEach, describe, expect, it } from 'vitest' + +import fs from 'node:fs/promises' +import os from 'node:os' +import path from 'node:path' + +import { + MarketplaceParseError, + RESERVED_MARKETPLACE_NAMES, + addKnownMarketplace, + parseMarketplace, + readAllCachedMarketplaces, + readKnownMarketplaces, + removeKnownMarketplace, + resolveCloneUrl, +} from '../src/plugins/marketplace.js' +import { knownMarketplacesPath, marketplaceIndexPath } from '../src/plugins/paths.js' + +let originalPluginsDir: string | undefined + +beforeEach(async () => { + originalPluginsDir = process.env.XC_PLUGINS_DIR + const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'xc-plugins-mp-test-')) + process.env.XC_PLUGINS_DIR = tmp +}) + +afterEach(() => { + if (originalPluginsDir === undefined) delete process.env.XC_PLUGINS_DIR + else process.env.XC_PLUGINS_DIR = originalPluginsDir +}) + +describe('parseMarketplace', () => { + it('parses a minimal valid marketplace (legacy {kind} source)', () => { + const raw = JSON.stringify({ + name: 'official', + plugins: [{ name: 'linear', source: { kind: 'github', owner: 'foo', repo: 'linear' } }], + }) + const m = parseMarketplace(raw, 'official') + expect(m.schemaVersion).toBe('1') + expect(m.plugins).toHaveLength(1) + expect(m.plugins[0]!.name).toBe('linear') + }) + + it('normalises every real Claude Code source variant', () => { + // This is the regression test for the v0.x bug where our schema + // only accepted {kind: 'git'|'github'|'local'} objects and rejected + // every real-world Claude Code marketplace. The wire-format shapes + // below were sampled from anthropics/claude-code and + // anthropics/claude-plugins-official as of April 2026. + const raw = JSON.stringify({ + name: 'mixed', + plugins: [ + { name: 'rel', source: './plugins/rel-one' }, + { name: 'github-short', source: 'github:foo/bar' }, + { name: 'http-git', source: 'https://gitlab.example/x.git' }, + { + name: 'git-subdir', + source: { + source: 'git-subdir', + url: 'https://github.com/42Crunch-AI/claude-plugins.git', + path: 'plugins/api', + ref: 'v1.5.5', + sha: 'a175b24', + }, + }, + { name: 'url-form', source: { source: 'url', url: 'https://example.com/x.git', sha: '5ddccc3' } }, + { name: 'github-form', source: { source: 'github', owner: 'foo', repo: 'bar', ref: 'main' } }, + { + name: 'github-combined', + source: { source: 'github', repo: 'fullstorydev/fullstory-skills', commit: '1ec5865' }, + }, + ], + }) + const m = parseMarketplace(raw, 'mixed', { + marketplaceCloneUrl: 'https://github.com/foo/mixed.git', + }) + expect(m.plugins).toHaveLength(7) + expect(m.plugins[0]!.source).toEqual({ + kind: 'git', + url: 'https://github.com/foo/mixed.git', + subdir: 'plugins/rel-one', + }) + expect(m.plugins[1]!.source).toEqual({ kind: 'github', owner: 'foo', repo: 'bar' }) + expect(m.plugins[3]!.source).toEqual({ + kind: 'git', + url: 'https://github.com/42Crunch-AI/claude-plugins.git', + subdir: 'plugins/api', + ref: 'v1.5.5', + }) + expect(m.plugins[6]!.source).toEqual({ + kind: 'github', + owner: 'fullstorydev', + repo: 'fullstory-skills', + ref: '1ec5865', + }) + }) + + it('relative source without marketplaceCloneUrl context surfaces a helpful error', () => { + // When marketplace was fetched from a raw HTTPS URL (no repo to + // subdir into) but the JSON contains "./plugins/foo" entries, the + // per-entry error should mention the missing context — and the + // overall parse still throws because no plugin entries succeeded. + const raw = JSON.stringify({ + name: 'no-ctx', + plugins: [{ name: 'rel', source: './plugins/foo' }], + }) + expect(() => parseMarketplace(raw, 'no-ctx')).toThrow(/marketplaceCloneUrl|requires.*clone URL/) + }) + + it('skips individual bad source entries when other entries succeed', () => { + // Real-world marketplaces sometimes carry one weird entry the + // schema doesn't recognise — that one should be dropped, not kill + // the whole catalog. + const raw = JSON.stringify({ + name: 'mixed-bad', + plugins: [ + { name: 'good', source: 'github:foo/bar' }, + { name: 'bad', source: { source: 'mysterious-future-form', whatever: 1 } }, + ], + }) + const m = parseMarketplace(raw, 'mixed-bad') + expect(m.plugins.map((p) => p.name)).toEqual(['good']) + }) + + it('rejects schema violations with field-path message', () => { + const raw = JSON.stringify({ name: 'official', plugins: [{ name: 'foo' }] }) // missing source + try { + parseMarketplace(raw, 'official') + throw new Error('expected throw') + } catch (err) { + expect(err).toBeInstanceOf(MarketplaceParseError) + expect((err as Error).message).toContain('plugins.0.source') + } + }) +}) + +describe('addKnownMarketplace + removeKnownMarketplace', () => { + it('writes a new entry into known_marketplaces.json', async () => { + await addKnownMarketplace({ name: 'community', source: 'github:foo/community' }) + const km = await readKnownMarketplaces() + expect(km.marketplaces).toHaveLength(1) + expect(km.marketplaces[0]!.name).toBe('community') + }) + + it('is idempotent — re-adding updates the source in place', async () => { + await addKnownMarketplace({ name: 'community', source: 'github:foo/community' }) + await addKnownMarketplace({ name: 'community', source: 'github:bar/community' }) + const km = await readKnownMarketplaces() + expect(km.marketplaces).toHaveLength(1) + expect(km.marketplaces[0]!.source).toBe('github:bar/community') + }) + + it('rejects a reserved name pointing at a non-canonical source', async () => { + await expect( + addKnownMarketplace({ name: 'anthropic-marketplace', source: 'github:malicious/marketplace' }), + ).rejects.toThrow(/reserved/) + }) + + it('accepts a reserved name pointing at the canonical org', async () => { + const expectedOrg = RESERVED_MARKETPLACE_NAMES['anthropic-marketplace']! + await addKnownMarketplace({ + name: 'anthropic-marketplace', + source: `github:${expectedOrg}/claude-plugins-official`, + }) + const km = await readKnownMarketplaces() + expect(km.marketplaces[0]!.reservedName).toBe(true) + expect(km.marketplaces[0]!.officialSource).toBe(expectedOrg) + }) + + it('removes entries', async () => { + await addKnownMarketplace({ name: 'community', source: 'github:foo/community' }) + expect(await removeKnownMarketplace('community')).toBe('removed') + expect(await removeKnownMarketplace('community')).toBe('noop') + const km = await readKnownMarketplaces() + expect(km.marketplaces).toEqual([]) + }) + + it('preserves unrelated fields in known_marketplaces.json on write', async () => { + // Pre-write a file with extra fields the loader knows nothing about. + const file = knownMarketplacesPath() + await fs.mkdir(path.dirname(file), { recursive: true }) + await fs.writeFile( + file, + JSON.stringify({ marketplaces: [], strictKnownMarketplaces: true, futureField: 42 }, null, 2), + ) + await addKnownMarketplace({ name: 'community', source: 'github:foo/community' }) + const after = JSON.parse(await fs.readFile(file, 'utf-8')) as Record + expect(after.futureField).toBe(42) + expect(after.strictKnownMarketplaces).toBe(true) + }) +}) + +describe('readAllCachedMarketplaces', () => { + it('reads cached marketplace.json for each subscribed marketplace', async () => { + await addKnownMarketplace({ name: 'community', source: 'github:foo/community' }) + + // Hand-place a cached marketplace.json + const cached = JSON.stringify({ + name: 'community', + plugins: [{ name: 'foo', source: { kind: 'local', path: '/tmp/foo' } }], + }) + const idx = marketplaceIndexPath('community') + await fs.mkdir(path.dirname(idx), { recursive: true }) + await fs.writeFile(idx, cached, 'utf-8') + + const all = await readAllCachedMarketplaces() + expect(all).toHaveLength(1) + expect(all[0]!.plugins[0]!.name).toBe('foo') + }) + + it('skips marketplaces with broken cached indexes (one bad does not break others)', async () => { + await addKnownMarketplace({ name: 'good', source: 'github:foo/good' }) + await addKnownMarketplace({ name: 'broken', source: 'github:foo/broken' }) + + const goodIdx = marketplaceIndexPath('good') + await fs.mkdir(path.dirname(goodIdx), { recursive: true }) + await fs.writeFile(goodIdx, JSON.stringify({ name: 'good', plugins: [] })) + + const brokenIdx = marketplaceIndexPath('broken') + await fs.mkdir(path.dirname(brokenIdx), { recursive: true }) + await fs.writeFile(brokenIdx, '{ not json', 'utf-8') + + const all = await readAllCachedMarketplaces() + expect(all.map((m) => m.name)).toEqual(['good']) + }) +}) + +describe('resolveCloneUrl', () => { + it('translates github:owner/repo → https URL', () => { + expect(resolveCloneUrl('github:foo/bar')).toBe('https://github.com/foo/bar.git') + }) + + it('preserves an existing .git suffix as a single suffix', () => { + // github:foo/bar.git → still ends in single .git, not double + expect(resolveCloneUrl('github:foo/bar.git')).toBe('https://github.com/foo/bar.git') + }) +}) diff --git a/packages/core/tests/shell-error.test.ts b/packages/core/tests/shell-error.test.ts index 6199e8e..6c36ffb 100644 --- a/packages/core/tests/shell-error.test.ts +++ b/packages/core/tests/shell-error.test.ts @@ -11,15 +11,6 @@ The string is missing the terminator: ". + FullyQualifiedErrorId : TerminatorExpectedAtEndOfString` describe('foldShellErrorNoise', () => { - it('passes through empty input', () => { - expect(foldShellErrorNoise('')).toBe('') - }) - - it('passes through plain output with no PS blocks', () => { - const plain = 'hello\nworld\nexit code 0' - expect(foldShellErrorNoise(plain)).toBe(plain) - }) - it('folds a full PS error block into a single line', () => { const out = foldShellErrorNoise(PS_ERROR_SAMPLE) const lines = out.split('\n').filter((l) => l.trim()) @@ -46,9 +37,4 @@ describe('foldShellErrorNoise', () => { expect(out).toContain('At line:') expect(out).not.toContain('CategoryInfo') }) - - it('fast-path: no `At line:` substring returns input unchanged', () => { - const plain = 'some output with + symbols and + tildes but no shell errors' - expect(foldShellErrorNoise(plain)).toBe(plain) - }) }) diff --git a/packages/core/tests/skills.test.ts b/packages/core/tests/skills.test.ts index e45cc62..08422d3 100644 --- a/packages/core/tests/skills.test.ts +++ b/packages/core/tests/skills.test.ts @@ -215,21 +215,6 @@ describe('loadSkills bundled-resources support', () => { expect(skills).toHaveLength(1) expect(skills[0].files).toEqual(['real.txt']) }) - - it('returns empty files array when skill directory has only SKILL.md', async () => { - const dir = await makeTempSkillsDir([ - { - dir: 'only-md', - frontmatter: 'name: only-md\ndescription: Just markdown', - body: 'Body', - }, - ]) - process.env.XC_SKILLS_DIR = dir - - const skills = await loadSkills() - expect(skills).toHaveLength(1) - expect(skills[0].files).toEqual([]) - }) }) // ── wrapActivatedSkill / formatSkillActivationBody ─────────────────────────── @@ -241,7 +226,7 @@ describe('wrapActivatedSkill', () => { name: 'demo', description: 'desc', content: 'Do the thing.', - source: 'global' as const, + source: 'user' as const, dir: '/abs/path/to/skills/demo', files: ['scripts/run.sh', 'references/notes.md'], } @@ -260,7 +245,7 @@ describe('wrapActivatedSkill', () => { name: 'pure', description: 'desc', content: 'Plain prompt.', - source: 'global' as const, + source: 'user' as const, dir: '/abs/pure', files: [], } @@ -276,7 +261,7 @@ describe('wrapActivatedSkill', () => { name: 'big', description: 'desc', content: 'Body', - source: 'global' as const, + source: 'user' as const, dir: '/abs/big', files, } @@ -291,24 +276,13 @@ describe('wrapActivatedSkill', () => { // ── SkillRegistry ───────────────────────────────────────────────────────────── describe('SkillRegistry', () => { - it('starts empty when given no skills', () => { - const registry = new SkillRegistry([]) - expect(registry.list()).toEqual([]) - expect(registry.names()).toEqual([]) - }) - - it('get returns undefined for unknown skill', () => { - const registry = new SkillRegistry([]) - expect(registry.get('nonexistent')).toBeUndefined() - }) - it('get returns the skill by name', () => { const registry = new SkillRegistry([ { name: 'review', description: 'Code review', content: 'Review...', - source: 'global', + source: 'user', dir: '/skills/review', files: [], }, @@ -321,7 +295,7 @@ describe('SkillRegistry', () => { it('list returns all skills', () => { const defs = [ - { name: 'a', description: 'A', content: 'Body A', source: 'global' as const, dir: '/skills/a', files: [] }, + { name: 'a', description: 'A', content: 'Body A', source: 'user' as const, dir: '/skills/a', files: [] }, { name: 'b', description: 'B', content: 'Body B', source: 'project' as const, dir: '/skills/b', files: [] }, ] const registry = new SkillRegistry(defs) @@ -330,8 +304,8 @@ describe('SkillRegistry', () => { it('names returns all skill names', () => { const defs = [ - { name: 'alpha', description: 'Alpha', content: '', source: 'global' as const, dir: '/skills/alpha', files: [] }, - { name: 'beta', description: 'Beta', content: '', source: 'global' as const, dir: '/skills/beta', files: [] }, + { name: 'alpha', description: 'Alpha', content: '', source: 'user' as const, dir: '/skills/alpha', files: [] }, + { name: 'beta', description: 'Beta', content: '', source: 'user' as const, dir: '/skills/beta', files: [] }, ] const registry = new SkillRegistry(defs) expect(registry.names().sort()).toEqual(['alpha', 'beta']) @@ -345,7 +319,7 @@ describe('SkillRegistry', () => { name: 'review', description: 'Global review', content: 'Global body', - source: 'global' as const, + source: 'user' as const, dir: '/global/skills/review', files: [], }, @@ -366,7 +340,7 @@ describe('SkillRegistry', () => { it('different names are not deduplicated', () => { const defs = [ - { name: 'a', description: 'A', content: '', source: 'global' as const, dir: '/skills/a', files: [] }, + { name: 'a', description: 'A', content: '', source: 'user' as const, dir: '/skills/a', files: [] }, { name: 'b', description: 'B', content: '', source: 'project' as const, dir: '/skills/b', files: [] }, ] const registry = new SkillRegistry(defs) @@ -375,12 +349,12 @@ describe('SkillRegistry', () => { it('disabled skills are hidden from list/names/get but appear in listAll', () => { const defs = [ - { name: 'on-skill', description: 'On', content: '', source: 'global' as const, dir: '/skills/on', files: [] }, + { name: 'on-skill', description: 'On', content: '', source: 'user' as const, dir: '/skills/on', files: [] }, { name: 'off-skill', description: 'Off', content: '', - source: 'global' as const, + source: 'user' as const, dir: '/skills/off', files: [], }, @@ -418,7 +392,7 @@ describe('SkillRegistry', () => { name: 'alpha', description: 'A v1', content: 'body A v1', - source: 'global' as const, + source: 'user' as const, dir: '/skills/alpha', files: [], }, @@ -426,7 +400,7 @@ describe('SkillRegistry', () => { name: 'beta', description: 'B v1', content: 'body B v1', - source: 'global' as const, + source: 'user' as const, dir: '/skills/beta', files: [], }, @@ -440,7 +414,7 @@ describe('SkillRegistry', () => { name: 'alpha', description: 'A v1', content: 'body A v1', - source: 'global' as const, + source: 'user' as const, dir: '/skills/alpha', files: [], }, @@ -448,7 +422,7 @@ describe('SkillRegistry', () => { name: 'beta', description: 'B v2', content: 'body B v1', - source: 'global' as const, + source: 'user' as const, dir: '/skills/beta', files: [], }, @@ -456,7 +430,7 @@ describe('SkillRegistry', () => { name: 'gamma', description: 'G', content: 'body G', - source: 'global' as const, + source: 'user' as const, dir: '/skills/gamma', files: [], }, @@ -482,11 +456,11 @@ describe('SkillRegistry', () => { name: 'alpha', description: 'A', content: 'body A', - source: 'global' as const, + source: 'user' as const, dir: '/skills/alpha', files: [], }, - { name: 'beta', description: 'B', content: 'body B', source: 'global' as const, dir: '/skills/beta', files: [] }, + { name: 'beta', description: 'B', content: 'body B', source: 'user' as const, dir: '/skills/beta', files: [] }, ] const registry = new SkillRegistry(v1) @@ -496,7 +470,7 @@ describe('SkillRegistry', () => { name: 'alpha', description: 'A', content: 'body A', - source: 'global' as const, + source: 'user' as const, dir: '/skills/alpha', files: [], }, @@ -511,7 +485,7 @@ describe('SkillRegistry', () => { it('reload() reports a disable toggle as changed', () => { const defs = [ - { name: 'alpha', description: 'A', content: 'body', source: 'global' as const, dir: '/skills/alpha', files: [] }, + { name: 'alpha', description: 'A', content: 'body', source: 'user' as const, dir: '/skills/alpha', files: [] }, ] const registry = new SkillRegistry(defs) expect(registry.get('alpha')).toBeDefined() diff --git a/packages/core/tests/tool-registry.test.ts b/packages/core/tests/tool-registry.test.ts index aa92bbc..5fd44ce 100644 --- a/packages/core/tests/tool-registry.test.ts +++ b/packages/core/tests/tool-registry.test.ts @@ -23,11 +23,6 @@ vi.mock('turndown', () => ({ })) describe('truncateToolResult', () => { - it('does not truncate short results', () => { - const short = 'hello world' - expect(truncateToolResult(short)).toBe(short) - }) - it('does not truncate results at exactly the byte limit', () => { const exact = 'x'.repeat(MAX_TOOL_RESULT_BYTES) expect(truncateToolResult(exact)).toBe(exact) diff --git a/packages/core/tests/tool-result-sanitize.test.ts b/packages/core/tests/tool-result-sanitize.test.ts index f819754..fc63390 100644 --- a/packages/core/tests/tool-result-sanitize.test.ts +++ b/packages/core/tests/tool-result-sanitize.test.ts @@ -41,14 +41,6 @@ function toolMsg(toolName: string, value: string): ModelMessage { } describe('truncateToolResultsInMessages', () => { - it('is a no-op when all results fit the budget', () => { - const messages: ModelMessage[] = [toolMsg('grep', 'short result')] - const originalValue = (messages[0].content as unknown as Array<{ output: { value: string } }>)[0].output.value - truncateToolResultsInMessages(messages) - const after = (messages[0].content as unknown as Array<{ output: { value: string } }>)[0].output.value - expect(after).toBe(originalValue) - }) - it('truncates an oversized readFile result in place', () => { const huge = 'line\n'.repeat(5000) // 5000 lines, over default 2000 const messages: ModelMessage[] = [toolMsg('readFile', huge)] diff --git a/packages/core/tests/truncate.test.ts b/packages/core/tests/truncate.test.ts index e03e669..ec5817f 100644 --- a/packages/core/tests/truncate.test.ts +++ b/packages/core/tests/truncate.test.ts @@ -9,10 +9,6 @@ describe('truncateToolResult', () => { expect(truncateToolResult('hello world')).toBe('hello world') }) - it('returns empty string unchanged', () => { - expect(truncateToolResult('')).toBe('') - }) - it('returns exact byte-limit ASCII unchanged', () => { const exact = 'x'.repeat(MAX_TOOL_RESULT_BYTES) expect(truncateToolResult(exact)).toBe(exact) diff --git a/packages/core/tests/vision-fallback.test.ts b/packages/core/tests/vision-fallback.test.ts index 5d9aa7f..60bae9d 100644 --- a/packages/core/tests/vision-fallback.test.ts +++ b/packages/core/tests/vision-fallback.test.ts @@ -26,15 +26,6 @@ describe('pickVisionProvider', () => { beforeEach(clearAllKeys) afterEach(clearAllKeys) - it('returns null when no provider keys are configured', () => { - expect(pickVisionProvider()).toBeNull() - }) - - it('returns null when only DeepSeek key is configured (text-only)', () => { - process.env.DEEPSEEK_API_KEY = 'test' - expect(pickVisionProvider()).toBeNull() - }) - it('returns null when only custom OpenAI-compatible endpoint is configured', () => { // Custom is treated as text-only by default — even with both env vars set, // the user has not opted into vision support.