@zentao-hub/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deven Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# @zentao-hub/cli
+
+English | [简体中文](README.zh-CN.md)
+
+> **Not the official [`zentao-cli`](https://github.com/easysoft/zentao-cli).** This is the companion CLI for `@zentao-hub/mcp` — it installs slash commands / prompts, MCP server entries, hooks, and per-agent instruction files for the AI agent of your choice. For general-purpose terminal CRUD against ZenTao, use the official CLI instead.
+
+The companion CLI for `@zentao-hub/mcp`. **The MCP server itself does not need it** — this CLI just bundles a handful of "manually copy or hand-write the script" tasks into subcommands:
+
+- Install `/fix-bug` and `/bug-analyze` into the chosen agent's slash-command / prompt dir
+  - `--agent claude` → `~/.claude/commands/*.md`
+  - `--agent codex` → `~/.codex/prompts/*.md`
+  - `--agent copilot` → `<repo>/.github/prompts/*.prompt.md`
+  - `--agent copilot-cli` → `~/.copilot/agents/*.agent.md`
+- Register the `zentao-hub` MCP server in the agent's config (Claude Code / Copilot in VS Code / Copilot CLI / Codex CLI)
+- Install a commit-msg hook (blocks AI signatures + enforces Conventional Commits) into a target repository
+- Drop the per-agent instructions file: `CLAUDE.md` (Claude Code), `AGENTS.md` (Codex / Copilot CLI), `.github/copilot-instructions.md` (Copilot in VS Code)
+- **Uninstall** every `install` artifact in one shot, or one target at a time
+- Initialize / inspect the bug-context workspace — **one workspace per profile** at `<$ZENTAO_HUB or ~/.zentao-hub>/<profile>/`
+- Maintain the `repos.yaml` registry inside each profile's workspace (productId → one or more repositories)
+
+> The CLI does not run the bug-fixing flow on behalf of the agent. The flow still goes through the slash commands / prompts and the MCP server, because "waiting for the user to confirm", "reading screenshots", and "exploring code" only make sense with an LLM in the loop. The CLI only handles _setting up the environment_.
+
+## Supported agents
+
+| Agent ID       | Tool                            | MCP config file                                                                   | Instructions file                              |
+| -------------- | ------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `claude`       | Claude Code                     | `~/.claude.json` or `<repo>/.mcp.json`                                            | `CLAUDE.md`                                    |
+| `copilot`      | GitHub Copilot (VS Code)        | User `User/mcp.json` or `<repo>/.vscode/mcp.json`                                 | `.github/copilot-instructions.md`              |
+| `copilot-cli`  | GitHub Copilot CLI              | `~/.copilot/mcp-config.json` (user) or `<repo>/.mcp.json` (workspace)             | `AGENTS.md`                                    |
+| `codex`        | OpenAI Codex CLI                | `~/.codex/config.toml` (user-only)                                                | `AGENTS.md`                                    |
+
+## Install
+
+```bash
+npm install -g @zentao-hub/cli
+```
+
+Or for development inside this monorepo (uses pnpm):
+
+```bash
+corepack enable
+pnpm install
+pnpm run build
+node packages/cli/dist/index.js help
+```
+
+## Usage
+
+```text
+zentao-hub <command> [options]
+
+  install <target>      install one of: commands | hooks | claude-md | mcp
+  uninstall [target]    reverse a single target, or omit for a one-shot revert
+                        of commands + hooks + claude-md (mcp not included)
+  init                  initialize the per-profile workspace
+  register <pid> <path> register a repository under a productId in the active profile's repos.yaml
+  repos [productId]     print the active profile's registry
+  workspace, ws         show the currently resolved workspace (supports --print-path for scripts)
+  login / logout / whoami / profiles / use   manage credentials
+  help                  print help
+```
+
+Run `zentao-hub help` for the full set of options.
+
+## A typical one-time setup
+
+The example below targets Claude Code (`--agent claude`). Swap `--agent` for
+`copilot` / `copilot-cli` / `codex` to set the same thing up for another
+agent — credentials, workspace, and registry are shared across agents.
+
+```bash
+# 1. Install the packages and log in once (credentials are shared across agents).
+npm install -g @zentao-hub/mcp @zentao-hub/cli
+zentao-hub login
+
+# 2. Register the zentao-hub MCP server in the agent's config.
+zentao-hub install mcp --agent claude
+
+# 3. Install the slash commands / prompts.
+zentao-hub install commands --agent claude
+
+# 4. Initialize the bug-context workspace (agent-agnostic).
+zentao-hub init
+echo 'export ZENTAO_HUB=$HOME/.zentao-hub' >> ~/.zshrc
+
+# 5. Per target repository: drop the instructions file, the commit-msg hook,
+#    and register the repo under a productId.
+cd ~/projects/venus-fe
+zentao-hub install claude-md --agent claude   # claude→CLAUDE.md, codex/copilot-cli→AGENTS.md, copilot→.github/copilot-instructions.md
+zentao-hub install hooks                      # commit-msg hook (agent-agnostic)
+zentao-hub register 2 . --name venus-frontend --tag frontend --tag electron
+```
+
+After that, open the chosen agent (Claude Code / Copilot Chat / Copilot CLI / Codex CLI) and type:
+
+```
+/bug-analyze 9634          # analyze only
+/fix-bug 27                # list active bugs assigned to you under product 27 and let you pick
+/fix-bug 27 9634           # fix it directly
+```
+
+## Workspace layout
+
+`$ZENTAO_HUB` (default `~/.zentao-hub`) is the *hub root*. The actual workspace is per-profile: `<root>/<profile>/`. This keeps bug context, registry, and attachments isolated when you have logins for multiple ZenTao instances (e.g. one per client). After `zentao-hub init --profile <name>`:
+
+```
+$ZENTAO_HUB/
+├── credentials.json                 ← shared across profiles
+├── default/                         ← profile workspace
+│   ├── repos.yaml                   ← registry: productId → list of repositories
+│   ├── repos.yaml.example           ← template
+│   └── bugs/                        ← one sub-directory per bug, written by the slash commands
+│       └── <bugId>/
+│           ├── raw.json
+│           ├── description.md
+│           ├── history.md
+│           ├── analysis.md
+│           └── attachments/
+│               ├── <id>-<title>.<ext>
+│               └── inline/
+│                   └── inline-N-<basename>
+└── client-foo/                      ← second profile, fully isolated
+    ├── repos.yaml
+    └── bugs/
+```
+
+Slash commands / prompts pick the workspace via the active `$ZENTAO_PROFILE` (which the MCP server already honors for auth). When `zentao-hub` is on `$PATH`, they run `zentao-hub workspace --profile $ZENTAO_PROFILE --print-path` to get the directory.
+
+### Migrating from the old flat layout
+
+Earlier versions wrote `bugs/` and `repos.yaml` directly under the root. If you upgrade and still have files there, `zentao-hub init --migrate-legacy` moves them into the `default/` profile workspace.
+
+## The `repos.yaml` registry
+
+A single productId can map to multiple repositories (frontend / backend / DB migrations / ...). `/fix-bug` Phase 2 supports multi-select; for cross-repo bugs it iterates per repository with worktree → commit → squash.
+
+Structure:
+
+```yaml
+products:
+  27:
+    - name: eda-schematic
+      path: /Users/you/projects/eda-studio/eda-schematic
+      tags: [frontend]
+    - name: eda-interop
+      path: /Users/you/projects/eda-studio/eda-interop
+      tags: [api]
+```
+
+You can edit it by hand, or append entries with `zentao-hub register`.
+
+## Flow overview (what the slash commands actually do)
+
+`/fix-bug` has three phases:
+
+```
+Phase 1 — Bug context (does not touch any repository)
+Phase 2 — Pick repositories (multi-select; new inputs are written back to repos.yaml)
+Phase 3 — For each chosen repo: worktree → edit → test → squash merge
+Phase 4 — Wrap-up suggestions (push / resolve_bug / delete worktree)
+```
+
+`/bug-analyze` runs only Phase 1. If you later want to actually fix the bug, run `/fix-bug <productId> <bugId>` and the previously downloaded context is reused.
+
+## Design trade-offs
+
+- **The CLI installs environment, it does not run the flow.** Slash commands / prompts are LLM-in-the-loop by design; the CLI is not a replacement.
+- **A central workspace, not a per-repo directory.** During analysis you don't yet know which repo to change; in multi-repo scenarios, putting context inside any one of them is awkward.
+- **`worktree`, not `checkout`.** Leaves the main checkout alone, and multi-repo work is naturally parallel.
+- **Squash, not fast-forward.** The main branch should see one clean `fix: #N` commit.
+- **No automatic push / resolve / branch delete.** Side-effecting cross-boundary operations are kept explicit, for the user to trigger.
+
+## License
+
+[MIT](../../LICENSE) © Deven Liu

package/README.zh-CN.md

@@ -0,0 +1,192 @@
+# @zentao-hub/cli
+
+[English](README.md) | 简体中文
+
+> **不是禅道官方的 [`zentao-cli`](https://github.com/easysoft/zentao-cli)。** 本包是 `@zentao-hub/mcp` 的配套 CLI——只装 AI agent 的 slash command / prompt、hook、模板。要在终端直接 CRUD 禅道，请用官方的 `zentao-cli`。
+
+`@zentao-hub/mcp` 的配套 CLI。**MCP server 本身不需要它** —— 它只是把原本要靠手抄/复制脚本完成的事情包成几个子命令：
+
+- 把 `/fix-bug`、`/bug-analyze` 装到目标 agent 的 slash command / prompt 目录
+  - `--agent claude` → `~/.claude/commands/*.md`
+  - `--agent codex` → `~/.codex/prompts/*.md`
+  - `--agent copilot` → `<repo>/.github/prompts/*.prompt.md`
+  - `--agent copilot-cli` → `~/.copilot/agents/*.agent.md`
+- 在目标 agent 的配置里注册 `zentao-hub` MCP server（Claude Code / Copilot in VS Code / Copilot CLI / Codex CLI 各自的 config 文件）
+- 把 commit-msg hook（拦 AI 署名 + 校 Conventional Commits）装到目标代码库
+- 按 agent 复制协作规则文件：`CLAUDE.md`（Claude Code）/ `AGENTS.md`（Codex / Copilot CLI）/ `.github/copilot-instructions.md`（Copilot in VS Code）
+- 初始化 / 查看 bug-context workspace —— **每个 profile 一个 workspace**，在 `<$ZENTAO_HUB 或 ~/.zentao-hub>/<profile>/`
+- 维护每个 profile workspace 里的 `repos.yaml` 注册表（productId → 多个代码库）
+
+> CLI 不替 agent 跑修 bug 流程 —— 流程仍然走 slash command + MCP，因为「等用户确认」「读截图」「调研代码」这些只有 LLM 在循环里才合理。CLI 只解决 _装环境_ 这一段。
+
+## 支持的 agent
+
+| Agent ID       | 说明                          | MCP 配置文件                                                         | 协作规则文件                              |
+| -------------- | ----------------------------- | -------------------------------------------------------------------- | ----------------------------------------- |
+| `claude`       | Claude Code                   | `~/.claude.json` 或 `<repo>/.mcp.json`                               | `CLAUDE.md`                               |
+| `copilot`      | GitHub Copilot (VS Code)      | 用户 `User/mcp.json` 或 `<repo>/.vscode/mcp.json`                    | `.github/copilot-instructions.md`         |
+| `copilot-cli`  | GitHub Copilot CLI            | `~/.copilot/mcp-config.json`（user）或 `<repo>/.mcp.json`（workspace）| `AGENTS.md`                               |
+| `codex`        | OpenAI Codex CLI              | `~/.codex/config.toml`（user-only）                                  | `AGENTS.md`                               |
+
+## 安装
+
+```bash
+npm install -g @zentao-hub/cli
+```
+
+或本 monorepo 内开发（使用 pnpm）：
+
+```bash
+corepack enable
+pnpm install
+pnpm run build
+node packages/cli/dist/index.js help
+```
+
+## 用法
+
+```text
+zentao-hub <command> [options]
+
+  install <target>      装其中一项：commands | hooks | claude-md | mcp
+  uninstall [target]    回滚单项，或不带 target 一键回滚 commands + hooks + claude-md
+                        （mcp 不在一键回滚里，要单独执行 uninstall mcp）
+  init                  初始化当前 profile 的 workspace
+  register <pid> <path> 把仓库登记到当前 profile 的 repos.yaml
+  repos [productId]     打印当前 profile 的注册表
+  workspace, ws         显示当前 profile 解析到的 workspace（支持 --print-path 给脚本用）
+  login / logout / whoami / profiles / use   凭据管理
+  help                  打印帮助
+```
+
+跑 `zentao-hub help` 看完整选项。
+
+## 典型一次性安装流程
+
+下面以 Claude Code 为例（`--agent claude`）。把每条命令里的 `--agent` 换成 `copilot` / `copilot-cli` / `codex` 即可装到对应 agent；凭据、workspace、注册表跨 agent 共用。
+
+```bash
+# 1. 装包 + 登录（凭据所有 agent 共用）
+npm install -g @zentao-hub/mcp @zentao-hub/cli
+zentao-hub login
+
+# 2. 在 agent 配置里注册 zentao-hub MCP server
+zentao-hub install mcp --agent claude
+
+# 3. 装 slash command / prompt
+zentao-hub install commands --agent claude
+
+# 4. 初始化 bug-context workspace（与具体 agent 无关）
+zentao-hub init
+echo 'export ZENTAO_HUB=$HOME/.zentao-hub' >> ~/.zshrc
+
+# 5. 每个目标代码库：装协作规则文件 + commit-msg hook + 登记 productId
+cd ~/projects/venus-fe
+zentao-hub install claude-md --agent claude   # claude→CLAUDE.md, codex/copilot-cli→AGENTS.md, copilot→.github/copilot-instructions.md
+zentao-hub install hooks                      # commit-msg hook（与 agent 无关）
+zentao-hub register 2 . --name venus-frontend --tag 前端 --tag electron
+```
+
+之后在所选 agent 里（Claude Code / Copilot Chat / Copilot CLI / Codex CLI）启动并输入：
+
+```
+/bug-analyze 9634          # 只分析
+/fix-bug 27                # 列产品 27 你名下 active bug 让你挑
+/fix-bug 27 9634           # 直接修
+```
+
+## 一键卸载
+
+```bash
+zentao-hub uninstall                  # 全卸：slash command + 当前仓库的 hook + 当前仓库的 CLAUDE.md
+zentao-hub uninstall --repo ~/projects/foo
+zentao-hub uninstall --keep-hooks-path
+```
+
+需要更细粒度：
+
+```bash
+zentao-hub uninstall commands
+zentao-hub uninstall hooks --repo .
+zentao-hub uninstall claude-md --repo .
+zentao-hub uninstall mcp --agent claude
+```
+
+凭据和 workspace 不会被动 —— 那是用户数据，用 `zentao-hub logout --all` 删凭据，`rm -rf <hub-root>/<profile>` 删 workspace。
+
+## Workspace 目录结构
+
+`$ZENTAO_HUB`（默认 `~/.zentao-hub`）是 *hub root*，每个 profile 一个 workspace：`<root>/<profile>/`。这样多个禅道实例（比如不同客户）的 bug 上下文、注册表、附件天然隔离。`zentao-hub init --profile <name>` 之后：
+
+```
+$ZENTAO_HUB/
+├── credentials.json                 ← 跨 profile 共用
+├── default/                         ← profile workspace
+│   ├── repos.yaml                   ← 注册表：productId → 代码库列表
+│   ├── repos.yaml.example           ← 模板
+│   └── bugs/                        ← 每个 bug 一个子目录，由 slash command 写入
+│       └── <bugId>/
+│           ├── raw.json
+│           ├── description.md
+│           ├── history.md
+│           ├── analysis.md
+│           └── attachments/
+│               ├── <id>-<title>.<ext>
+│               └── inline/
+│                   └── inline-N-<basename>
+└── client-foo/                      ← 第二个 profile，完全隔离
+    ├── repos.yaml
+    └── bugs/
+```
+
+slash command / prompt 通过当前的 `$ZENTAO_PROFILE`（MCP server 鉴权也用这个）来挑 workspace。`zentao-hub` 在 `$PATH` 上时，会跑 `zentao-hub workspace --profile $ZENTAO_PROFILE --print-path` 拿到目录。
+
+### 从老的扁平结构迁移
+
+更早的版本把 `bugs/` 和 `repos.yaml` 直接写在根目录下。如果升级后这些文件还在那儿，`zentao-hub init --migrate-legacy` 会把它们搬到 `default/` profile workspace。
+
+## 注册表 `repos.yaml`
+
+一个 productId 可以对应多个代码库（前端 / 后端 / 数据库迁移 / …）。`/fix-bug` 在 Phase 2 支持多选，跨库 bug 时按仓库循环 worktree + commit + squash。
+
+结构：
+
+```yaml
+products:
+  27:
+    - name: eda-schematic
+      path: /Users/you/projects/eda-studio/eda-schematic
+      tags: [前端]
+    - name: eda-interop
+      path: /Users/you/projects/eda-studio/eda-interop
+      tags: [api]
+```
+
+可以手工编辑，也可以用 `zentao-hub register` 追加。
+
+## 流程概览（slash command 跑的事）
+
+`/fix-bug` 三阶段：
+
+```
+Phase 1 — Bug 上下文（不依赖任何代码库）
+Phase 2 — 选代码库（多选；新输入的写回 repos.yaml）
+Phase 3 — 按每个选中的库循环：worktree → 改 → 测 → squash merge
+Phase 4 — 收尾建议（push / resolve_bug / 删 worktree）
+```
+
+`/bug-analyze` 只跑 Phase 1。之后想真修，直接 `/fix-bug <productId> <bugId>`，已下载的 context 会复用。
+
+## 设计取舍
+
+- **CLI 只装环境，不跑流程**：slash command / prompt 是 LLM-in-the-loop 的设计，CLI 不取代它。
+- **集中 workspace 而非仓库内**：bug 分析阶段不知道改哪个库；多库场景下放任何一个库都尴尬。
+- **workspace 按 profile 隔离**：多 ZenTao 实例（不同客户/环境）的 bug 上下文与注册表互不污染。
+- **worktree 而非 checkout**：主仓库不动，多库场景天然并行。
+- **squash 而非 fast-forward**：主分支只想看一个干净的「fix: #N」commit。
+- **不主动 push / resolve / 删分支**：副作用 / 跨边界操作留给用户显式触发。
+- **uninstall 不动用户数据**：凭据、workspace 不会被 uninstall 删，避免误伤。
+
+## License
+
+[MIT](../../LICENSE) © Deven Liu

package/dist/agents.d.ts

@@ -0,0 +1,62 @@
+export type AgentId = "claude" | "copilot" | "copilot-cli" | "codex";
+export interface AgentInfo {
+    id: AgentId;
+    label: string;
+}
+export declare const AGENTS: readonly AgentInfo[];
+/** Pretty label for log output. Centralized so commands don't drift. */
+export declare function describeAgent(agent: AgentId): string;
+/**
+ * Resolve which agent to target. If `explicit` is provided it must match a
+ * known id (case-insensitive). Otherwise — in interactive shells — show the
+ * menu; in non-interactive shells refuse rather than silently picking one.
+ */
+export declare function resolveAgent(explicit?: string): Promise<AgentId>;
+/**
+ * Where slash-command / prompt files live for each agent.
+ *
+ * Claude and Codex have a user-level prompts dir; Copilot has no such concept,
+ * so we drop into the repo's `.github/prompts/` (workspace-level prompts).
+ */
+export declare function resolveAgentPromptsDir(agent: AgentId, opts?: {
+    explicit?: string;
+    repo?: string;
+}): {
+    dir: string;
+    suffix: string;
+    scope: "user" | "workspace";
+};
+/**
+ * Repo-level "tell the AI how to work in this repo" file. Each agent reads a
+ * different filename, so we map agent → relative path inside the repo.
+ */
+export declare function resolveAgentInstructionsFile(agent: AgentId, repo: string): {
+    abs: string;
+    rel: string;
+};
+export interface McpTarget {
+    /** File the config will be merged into. */
+    path: string;
+    /** Format that file uses. */
+    format: "json" | "toml";
+    /** Top-level key under which servers live (JSON formats). */
+    jsonKey?: "mcpServers" | "servers";
+    /** Section header used (TOML format). */
+    tomlSectionPrefix?: string;
+    /** Whether this is a user-level or workspace-level config. */
+    scope: "user" | "workspace";
+    /** Human-friendly description for log output. */
+    describe: string;
+}
+/**
+ * Resolve where an MCP server entry should be written for the given agent.
+ *
+ * Scope:
+ *   - "user" (default for all agents): user-level config in the home dir
+ *   - "workspace": project-level config inside `<repo>` (Claude + Copilot only;
+ *     Codex has no documented workspace config so we fall back to user-level)
+ */
+export declare function resolveMcpTarget(agent: AgentId, opts?: {
+    scope?: "user" | "workspace";
+    repo?: string;
+}): McpTarget;

package/dist/agents.js

@@ -0,0 +1,202 @@
+import path from "node:path";
+import os from "node:os";
+import { CliError } from "./util.js";
+import { promptLine } from "./prompt.js";
+export const AGENTS = [
+    { id: "claude", label: "Claude Code" },
+    { id: "copilot", label: "GitHub Copilot (VS Code)" },
+    { id: "copilot-cli", label: "GitHub Copilot CLI" },
+    { id: "codex", label: "OpenAI Codex CLI" },
+];
+/** Pretty label for log output. Centralized so commands don't drift. */
+export function describeAgent(agent) {
+    return AGENTS.find((a) => a.id === agent)?.label ?? agent;
+}
+/** Resolve ~/.copilot honoring $COPILOT_HOME, used by Copilot CLI. */
+function copilotHome() {
+    return process.env.COPILOT_HOME
+        ? path.resolve(process.env.COPILOT_HOME)
+        : path.join(os.homedir(), ".copilot");
+}
+/**
+ * Resolve which agent to target. If `explicit` is provided it must match a
+ * known id (case-insensitive). Otherwise — in interactive shells — show the
+ * menu; in non-interactive shells refuse rather than silently picking one.
+ */
+export async function resolveAgent(explicit) {
+    if (explicit) {
+        const lower = explicit.toLowerCase();
+        const hit = AGENTS.find((a) => a.id === lower);
+        if (!hit) {
+            throw new CliError(`Unknown agent '${explicit}'. Supported: ${AGENTS.map((a) => a.id).join(", ")}`);
+        }
+        return hit.id;
+    }
+    if (!process.stdin.isTTY) {
+        throw new CliError(`--agent is required in non-interactive mode. Supported: ${AGENTS.map((a) => a.id).join(", ")}`);
+    }
+    process.stdout.write(`Pick a target agent:\n`);
+    AGENTS.forEach((a, i) => {
+        process.stdout.write(`  ${i + 1}) ${a.id.padEnd(8)} ${a.label}\n`);
+    });
+    const answer = (await promptLine(`Choice [1-${AGENTS.length}] (default 1): `)).trim();
+    if (!answer)
+        return AGENTS[0].id;
+    const byNum = Number(answer);
+    if (Number.isInteger(byNum) && byNum >= 1 && byNum <= AGENTS.length) {
+        return AGENTS[byNum - 1].id;
+    }
+    const byId = AGENTS.find((a) => a.id === answer.toLowerCase());
+    if (byId)
+        return byId.id;
+    throw new CliError(`Invalid choice '${answer}'`);
+}
+/**
+ * Where slash-command / prompt files live for each agent.
+ *
+ * Claude and Codex have a user-level prompts dir; Copilot has no such concept,
+ * so we drop into the repo's `.github/prompts/` (workspace-level prompts).
+ */
+export function resolveAgentPromptsDir(agent, opts = {}) {
+    if (opts.explicit) {
+        return { dir: path.resolve(opts.explicit), suffix: promptSuffix(agent), scope: "user" };
+    }
+    switch (agent) {
+        case "claude":
+            return { dir: path.join(os.homedir(), ".claude", "commands"), suffix: ".md", scope: "user" };
+        case "codex":
+            return { dir: path.join(os.homedir(), ".codex", "prompts"), suffix: ".md", scope: "user" };
+        case "copilot": {
+            const repo = path.resolve(opts.repo ?? process.cwd());
+            return { dir: path.join(repo, ".github", "prompts"), suffix: ".prompt.md", scope: "workspace" };
+        }
+        case "copilot-cli":
+            // Copilot CLI has no "slash command" concept; the closest mapping is
+            // custom agents at ~/.copilot/agents/<name>.agent.md. They run as
+            // /<name> from inside `copilot`.
+            return { dir: path.join(copilotHome(), "agents"), suffix: ".agent.md", scope: "user" };
+    }
+}
+function promptSuffix(agent) {
+    if (agent === "copilot")
+        return ".prompt.md";
+    if (agent === "copilot-cli")
+        return ".agent.md";
+    return ".md";
+}
+/**
+ * Repo-level "tell the AI how to work in this repo" file. Each agent reads a
+ * different filename, so we map agent → relative path inside the repo.
+ */
+export function resolveAgentInstructionsFile(agent, repo) {
+    const repoAbs = path.resolve(repo);
+    const rel = agentInstructionsRel(agent);
+    return { abs: path.join(repoAbs, rel), rel };
+}
+function agentInstructionsRel(agent) {
+    switch (agent) {
+        case "claude":
+            return "CLAUDE.md";
+        case "codex":
+            return "AGENTS.md";
+        case "copilot":
+            return path.join(".github", "copilot-instructions.md");
+        case "copilot-cli":
+            // Copilot CLI reads AGENTS.md as primary instructions (cross-tool
+            // standard, shared with Codex). The .github/copilot-instructions.md
+            // file is also read but already covered by the "copilot" target.
+            return "AGENTS.md";
+    }
+}
+/**
+ * Resolve where an MCP server entry should be written for the given agent.
+ *
+ * Scope:
+ *   - "user" (default for all agents): user-level config in the home dir
+ *   - "workspace": project-level config inside `<repo>` (Claude + Copilot only;
+ *     Codex has no documented workspace config so we fall back to user-level)
+ */
+export function resolveMcpTarget(agent, opts = {}) {
+    const scope = opts.scope ?? "user";
+    const repo = path.resolve(opts.repo ?? process.cwd());
+    if (agent === "claude") {
+        if (scope === "workspace") {
+            return {
+                path: path.join(repo, ".mcp.json"),
+                format: "json",
+                jsonKey: "mcpServers",
+                scope: "workspace",
+                describe: "Claude Code project-scope config (.mcp.json)",
+            };
+        }
+        return {
+            path: path.join(os.homedir(), ".claude.json"),
+            format: "json",
+            jsonKey: "mcpServers",
+            scope: "user",
+            describe: "Claude Code user config (~/.claude.json)",
+        };
+    }
+    if (agent === "copilot") {
+        if (scope === "workspace") {
+            return {
+                path: path.join(repo, ".vscode", "mcp.json"),
+                format: "json",
+                jsonKey: "servers",
+                scope: "workspace",
+                describe: "VS Code workspace MCP config (.vscode/mcp.json)",
+            };
+        }
+        return {
+            path: vsCodeUserMcpPath(),
+            format: "json",
+            jsonKey: "servers",
+            scope: "user",
+            describe: "VS Code user MCP config (User/mcp.json)",
+        };
+    }
+    if (agent === "copilot-cli") {
+        if (scope === "workspace") {
+            // Copilot CLI accepts either `<repo>/.mcp.json` or
+            // `<repo>/.github/mcp.json` at the project level. We default to
+            // `.mcp.json` because it's the shared cross-tool path also used by
+            // Claude Code's project scope — one file covers both agents.
+            return {
+                path: path.join(repo, ".mcp.json"),
+                format: "json",
+                jsonKey: "mcpServers",
+                scope: "workspace",
+                describe: "Copilot CLI project config (.mcp.json)",
+            };
+        }
+        return {
+            path: path.join(copilotHome(), "mcp-config.json"),
+            format: "json",
+            jsonKey: "mcpServers",
+            scope: "user",
+            describe: "Copilot CLI user config (~/.copilot/mcp-config.json)",
+        };
+    }
+    // codex — TOML, user-only.
+    return {
+        path: path.join(os.homedir(), ".codex", "config.toml"),
+        format: "toml",
+        tomlSectionPrefix: "mcp_servers",
+        scope: "user",
+        describe: "Codex CLI config (~/.codex/config.toml)",
+    };
+}
+function vsCodeUserMcpPath() {
+    const home = os.homedir();
+    if (process.platform === "darwin") {
+        return path.join(home, "Library", "Application Support", "Code", "User", "mcp.json");
+    }
+    if (process.platform === "win32") {
+        const appData = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
+        return path.join(appData, "Code", "User", "mcp.json");
+    }
+    // linux + others
+    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(home, ".config");
+    return path.join(xdg, "Code", "User", "mcp.json");
+}
+//# sourceMappingURL=agents.js.map

package/dist/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"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"}