@xcompiler/cli 0.2.2

package/docs/acp.md

@@ -0,0 +1,64 @@
+# XCompiler ACP Adapter
+
+XCompiler exposes an ACP Code Agent adapter over stdio:
+
+```bash
+xcompiler acp
+```
+
+The adapter is protocol-facing only. It maps ACP requests to the XCompiler Runtime and streams Runtime progress back through `session/update`.
+
+## Supported ACP v1 Flow
+
+- `initialize`
+- `session/new`
+- `session/prompt`
+- `session/cancel`
+- `session/close`
+- `session/update`
+- `session/request_permission`
+
+The adapter keeps stdout reserved for JSON-RPC messages. Runtime logs and adapter diagnostics must go to stderr.
+
+## Zed Local Configuration
+
+When XCompiler is installed on PATH:
+
+```json
+{
+  "agent_servers": {
+    "XCompiler": {
+      "command": "xcompiler",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+For local development from this repository:
+
+```json
+{
+  "agent_servers": {
+    "XCompiler Dev": {
+      "command": "node",
+      "args": [
+        "--import",
+        "tsx",
+        "/Users/ddk/Documents/Workspace/TOAA/src/cli/xcompiler.ts",
+        "acp"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+## Current Limitations
+
+- The adapter supports Code Agent task execution, not general chat.
+- Build-stage confirm/select interactions are mapped to `session/request_permission`.
+- Free-form build-stage follow-up text is not yet modeled as a multi-turn ACP prompt loop.
+- Runtime cancellation is best-effort until Runtime exposes hard cancellation.
+- Official ACP registry publication still requires a real Zed smoke test and final registry metadata alignment.

package/docs/plugin_api.md

@@ -0,0 +1,106 @@
+# XCompiler Plugin API
+
+XCompiler 的插件层位于核心流程与扩展能力之间。既支持直接传入 `XCompilerPlugin[]`，也提供 `loadPluginSources()` 从分离的 manifest 与模块入口执行 manifest-first 加载；当前仍不负责从网络安装第三方包或维护 marketplace。自举编排可通过 `@xcompiler/cli/runtime` 调用 `runBootstrap`，候选内部的 compile / run 仍触发相同生命周期 Hook。
+
+## 清单与版本兼容
+
+设计参考 [VS Code Extension Manifest](https://code.visualstudio.com/api/references/extension-manifest)：插件元数据与可执行入口分离，唯一 ID、插件 SemVer 和宿主兼容声明都是必填项。XCompiler 使用可序列化的 `manifest`；`loadPluginSources()` 会先读取并检查全部 manifest，全部通过后才 import 任一模块，因此 registry / marketplace 可在不执行插件代码的前提下索引和预检。
+
+XCompiler 核心版本和 Plugin API 版本独立演进：核心使用 SemVer（当前 `0.1.3`），Plugin API 使用整数主版本（当前 `1`）。每个插件清单必须声明：
+
+| 字段 | 必填 | 语义 |
+|---|---|---|
+| `id` | 是 | 全局唯一稳定 ID；小写字母/数字/点/连字符/下划线 |
+| `version` | 是 | 插件自身 SemVer |
+| `apiVersion` | 是 | 插件面向的 XCompiler Plugin API 主版本 |
+| `minXCompilerVersion` | 是 | 插件可运行的最低 XCompiler 核心 SemVer |
+| `displayName/description/license/homepage/keywords` | 否 | 目录与展示元数据 |
+
+`loadPluginSources()` 在模块 import 前检查全部 manifest 和重复 ID，并校验模块导出的运行时 manifest 与预检文件一致；拒绝事件可写入审计日志。直接传入已经 import 的 `XCompilerPlugin[]` 时，`PluginHost` 仍保证在任何 `setup()` 前完成同样检查，但无法撤销调用方此前执行的模块顶层代码。`checkPluginCompatibility()` 可供安装器、插件目录或配置预检复用。
+
+版本常量从 `@xcompiler/cli/plugins` 导出；插件在 `setup(api)` 中也可读取 `api.xcompilerVersion` 和 `api.pluginApiVersion`。插件升级自身实现时递增 `manifest.version`；需要较新核心能力时提高 `manifest.minXCompilerVersion`；只有公共插件接口发生不兼容变化时，XCompiler 才递增 Plugin API 主版本。
+
+## 模块边界
+
+| 模块 | 责任 | 插件扩展点 |
+|---|---|---|
+| `cli/compile` | 需求输入、澄清、计划生成和人工门 | `compile.*` |
+| `llm/router` | provider 选择、fallback、审计 | `llm.*` |
+| `core/engine` | V 模型调度、DEBUG 重试、质量门 | `run.*`、`step.*` |
+| `agents/executor` | 单 Step 多轮工具执行 | 通过 `step.attempt.*` 和 `tool.*` 观察 |
+| `tools` / `skills` | 原子能力与高阶能力组合 | `registerTool`、`registerSkill` |
+| `plugins` | 注册、排序、异常隔离和 Hook 调度 | 公共插件 API |
+
+安全边界保持不变：插件注册的 Tool 进入与内置 Tool 相同的白名单选择和 `EditGuard`；Hook 不能绕过 workspace 写入限制。
+
+## 生命周期 Hooks
+
+| Hook | 触发位置 |
+|---|---|
+| `compile.start` | 配置、审计和插件初始化完成后 |
+| `compile.afterClarify` | 澄清问答及用户补充收集后 |
+| `compile.beforeDecompose` | Planner 生成计划之前 |
+| `compile.afterPlan` | 计划校准后、Schema/Lint 之前 |
+| `compile.finish` | 计划和文档持久化后 |
+| `llm.before/after/error` | 每次完整 LLM 调用外围 |
+| `run.before/after/error` | PhaseEngine 整体运行外围 |
+| `step.before/after/error` | 单个 V 模型 Step 外围 |
+| `step.attempt.before/after` | 正常执行或 DEBUG retry 的每次尝试外围 |
+| `tool.before/after/error` | Tool 调用外围（仍受 EditGuard 保护） |
+
+同一 Hook 按 `priority` 从大到小执行；优先级相同时保持插件数组与注册顺序。插件错误默认记录审计并继续，插件可声明 `failureMode: 'fail'`，宿主也可启用 `strict` 强制失败。
+
+## 示例
+
+```ts
+import type { XCompilerPlugin } from '@xcompiler/cli/plugins';
+import { XCOMPILER_PLUGIN_API_VERSION } from '@xcompiler/cli/plugins';
+import { runExecute } from '@xcompiler/cli/runtime';
+
+export const policyPlugin: XCompilerPlugin = {
+  manifest: {
+    id: 'example.policy',
+    displayName: 'Example Policy',
+    description: 'Enforces organization plan policies.',
+    version: '1.0.0',
+    apiVersion: XCOMPILER_PLUGIN_API_VERSION,
+    minXCompilerVersion: '0.1.3',
+    license: 'Apache-2.0',
+    keywords: ['policy', 'compliance'],
+  },
+  failureMode: 'fail',
+  setup(api) {
+    api.on('compile.afterPlan', ({ plan }) => {
+      if (!plan.steps.some((step) => step.phase === 'TEST')) {
+        throw new Error('Every plan must contain a TEST step.');
+      }
+    }, { priority: 100 });
+
+    api.on('tool.before', ({ tool, args }) => {
+      // 只做策略检查；实际写入仍由 Tool + EditGuard 完成。
+      if (tool === 'write_file') console.log('write_file', args);
+    });
+  },
+};
+```
+
+程序化调用：
+
+```ts
+import { loadPluginSources } from '@xcompiler/cli/plugins';
+
+const plugins = await loadPluginSources({
+  baseDir: process.cwd(),
+  sources: [{
+    manifestPath: 'plugins/example/plugin.json',
+    entryPath: 'plugins/example/index.js',
+  }],
+});
+
+await runExecute({
+  workspace,
+  planPath,
+  plugins,
+  pluginStrict: true,
+});
+```

package/docs/self_bootstrap.md

@@ -0,0 +1,88 @@
+# XCompiler 功能自举设计
+
+## 目标
+
+功能自举指稳定版本 XCompiler-N 能读取自身工程，以完整 V 模型规划、实现并验证下一代
+XCompiler-N+1；N+1 晋级后能够继续执行下一轮自举。自举不等同于进程内热更新，正在运行的
+N 在本轮结束前始终是可信执行器。
+
+## 信任与隔离边界
+
+```text
+宿主 checkout（XCompiler-N，必须 clean）
+        │
+        ├── base commit ──► 隔离 worktree / 候选分支
+        │                         │
+        │                         ├── intent=self 编译 V 模型计划
+        │                         ├── 执行 CODE / TEST / DEBUG / DELIVERY
+        │                         └── 确定性质量门
+        │
+        └── 人工晋级门 ──► git merge --ff-only ──► XCompiler-N+1
+```
+
+- Step 内的 `git add .`、快照提交和 `reset --hard` 只允许发生在候选 worktree。
+- 默认 worktree 位于 `.xcompiler/bootstrap/worktrees/<run-id>`，该目录不进入版本控制。
+- 候选分支使用 `xcompiler/bootstrap/<run-id>`，报告位于
+  `.xcompiler/bootstrap/reports/<run-id>.md`。
+- 自举开始时宿主必须 clean；晋级时再次验证宿主 HEAD 等于基线提交且仍为 clean。
+- 质量门开始前记录候选 commit；门禁结束后候选 HEAD 必须未变化且 worktree 仍为 clean。
+- 晋级合并已验证的精确 commit SHA，不按可能漂移的候选分支头合并。
+
+## Self 计划约束
+
+`self` 属于增量意图，加载已有 plan、项目记忆、源码/测试树、manifest，以及
+`XCompiler_design.md`、本设计、实施计划和插件 API。
+
+Planner 必须遵守：
+
+- 保留现有 `package.json`、`tsconfig`、bin、CLI 入口、模块布局和公共导出。
+- 不得为了满足新建工程规则创建 `src/main.ts`。
+- 未涉及依赖或脚本时，不得把 `package.json` / `tsconfig.json` 列为 Step 输出。
+- 每个 CODE / REFACTOR Step 只覆盖本次增量，并保留 ARCH → CODE → TEST 可追踪性。
+
+## 质量门
+
+候选版本执行完成后按顺序运行：
+
+1. `npm run version:check`（必选；校验 package、lockfile 与运行时版本常量）
+2. `npm run typecheck`（必选；缺少 script 也视为失败）
+3. `npm test`（必选）
+4. `npm run build`（必选）
+5. `npm run lint`（必选；缺少 script 也视为失败）
+6. 使用 `package.json.bin` 的首个入口执行 `node <entry> --help`（必选；缺少 bin 也视为失败）
+7. 执行 `node <entry> bootstrap --help`，确认 N+1 仍暴露下一代自举入口（必选）
+8. `npm pack --dry-run --json`（必选）
+
+任一必选门失败，候选状态为 `qualification-failed`，禁止晋级。LLM 服务是否在线只影响
+计划生成和 Step 执行，不改变确定性质量门的判定标准。
+
+质量门当前优先运行在 subprocess 沙箱中：依赖使用锁文件执行 `npm ci --ignore-scripts`，
+并使用独立 HOME、TMPDIR、npm cache 与最小环境变量，不继承 provider key、代理或其它
+进程机密。subprocess 不能提供 Docker 级别的网络与资源硬隔离，因此候选 commit 完整性
+检查仍是强制门禁。Docker 环境尚未完成实际环境验证，仅在显式传入
+`--docker-qualification` 时实验启用；该模式把候选脚本置于 `--network none`、CPU / 内存 /
+PID 限制和 `no-new-privileges` 下执行。
+
+## CLI
+
+```bash
+# 默认：生成候选分支、保留 worktree、写报告，不修改当前分支
+xcompiler bootstrap -r /path/to/XCompiler -i self_req.md --yes
+
+# 全部门禁通过后，在同一次运行末尾显式快进晋级
+xcompiler bootstrap -r /path/to/XCompiler -i self_req.md --yes --promote
+
+# 写完报告后删除 worktree，候选分支仍保留
+xcompiler bootstrap -r /path/to/XCompiler -i self_req.md --yes --cleanup
+
+# 实验选项：显式使用尚未完成环境验证的 Docker 质量门
+xcompiler bootstrap -r /path/to/XCompiler -i self_req.md --yes --docker-qualification
+```
+
+## 回滚与失败处理
+
+- compile 取消、Step 失败或质量门失败：保留候选分支和 worktree供诊断，宿主不变。
+- 晋级前失败：删除 worktree 和候选分支即可，不需要重置宿主仓库。
+- 晋级后发现问题：通过新的修复提交或版本化 revert 处理，不复用执行期的硬重置。
+- 自举报告记录 base/candidate commit、检查命令、耗时和变更文件，作为下一轮输入证据；
+  报告中的手工晋级命令绑定 candidate commit SHA，而不是分支名。

package/docs/versioning.md

@@ -0,0 +1,33 @@
+# XCompiler 版本管理
+
+`package.json` 是 XCompiler 核心版本和 Plugin API 版本的唯一真源：
+
+```json
+{
+  "version": "0.1.3",
+  "xcompiler": { "pluginApiVersion": 1 }
+}
+```
+
+`src/version.ts` 是自动生成的运行时常量，`package-lock.json` 由同一工具同步。不要手工修改这两个位置。
+
+`npm run build` 通过 npm 的 `prebuild` 生命周期强制先执行 `version:check`；直接调用底层 `tsup` 不属于受支持的发布路径。`prepack` 和自举 qualification 也会独立重复校验，避免调用方使用 `--ignore-scripts` 时漏掉版本门禁。
+
+## 常用命令
+
+```bash
+# 检查 package、lockfile、CLI 运行时常量是否一致
+npm run version:check
+
+# 重新按 package.json 生成其他版本元数据
+npm run version:sync
+
+# 设置下一个核心版本并同步全部位置
+npm run version:set -- 0.1.4
+```
+
+核心版本遵循 SemVer。发布 tag 必须是 `v<package version>`，例如 `v0.1.3`；Release workflow 会在测试和打包前强制校验，版本不一致时停止发布。二进制分发包内包含 `VERSION` 文件，CLI 的 `--version` 也读取同一个生成常量。
+
+Plugin API 版本独立于核心版本，只在插件公共接口出现不兼容修改时递增整数主版本。插件自身使用 SemVer，并在 manifest 中强制声明 `apiVersion` 和 `minXCompilerVersion`；详细规则见 [plugin_api.md](plugin_api.md)。
+
+审计内容默认使用 `redacted` 模式遮蔽 API key、token、密码等凭据。需要最小化留存时设置 `XC_AUDIT_CONTENT_MODE=metadata`（只保留长度和 SHA-256）；只有在受控环境确实需要完整回放时才使用 `full`。

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "@xcompiler/cli",
+  "version": "0.2.2",
+  "description": "XCompiler — AI Software Factory: V-model driven, multi-LLM orchestrated software development agent.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TreeNeeBee/XCompiler.git"
+  },
+  "bin": {
+    "xcompiler": "dist/cli/xcompiler.js",
+    "xcompiler_build": "dist/cli/xcompiler_build.js",
+    "xcompiler_run": "dist/cli/xcompiler_run.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/runtime/runtime.d.ts",
+      "import": "./dist/runtime/runtime.js"
+    },
+    "./plugins": {
+      "types": "./dist/plugins/index.d.ts",
+      "import": "./dist/plugins/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/runtime.d.ts",
+      "import": "./dist/runtime/runtime.js"
+    },
+    "./acp": {
+      "types": "./dist/acp/index.d.ts",
+      "import": "./dist/acp/index.js"
+    }
+  },
+  "files": [
+    "dist/cli",
+    "dist/plugins",
+    "dist/runtime",
+    "dist/acp",
+    "docs/acp.md",
+    "docs/plugin_api.md",
+    "docs/self_bootstrap.md",
+    "docs/versioning.md",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "version:check": "node scripts/version.mjs check",
+    "version:sync": "node scripts/version.mjs sync",
+    "version:set": "node scripts/version.mjs set",
+    "prepack": "npm run version:check",
+    "prebuild": "npm run version:check",
+    "build": "tsup",
+    "dev": "tsx src/cli/xcompiler.ts",
+    "dev:build": "tsx src/cli/xcompiler_build.ts",
+    "dev:run": "tsx src/cli/xcompiler_run.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "smoke:ollama": "node --import tsx scripts/smoke_ollama.ts",
+    "lint": "eslint \"src/**/*.ts\"",
+    "build:pkg": "tsup --config tsup.pkg.config.ts",
+    "package": "bash scripts/package.sh",
+    "package:native": "bash scripts/package.sh native",
+    "package:all": "bash scripts/package.sh all",
+    "package:linux-x64": "bash scripts/package.sh linux-x64",
+    "package:linux-arm64": "bash scripts/package.sh linux-arm64",
+    "package:macos-arm64": "bash scripts/package.sh macos-arm64",
+    "package:macos-x64": "bash scripts/package.sh macos-x64",
+    "package:win-x64": "bash scripts/package.sh win-x64"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.5.2",
+    "chalk": "^5.3.0",
+    "commander": "^15.0.0",
+    "dotenv": "^17.4.2",
+    "jsonrepair": "^3.15.0",
+    "ora": "^9.4.1",
+    "simple-git": "^3.27.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.13.2",
+    "@yao-pkg/pkg": "^6.21.0",
+    "eslint": "^10.6.0",
+    "tsup": "^8.3.5",
+    "tsx": "^4.23.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.1",
+    "vitest": "^4.1.10"
+  },
+  "overrides": {
+    "esbuild": "0.28.1",
+    "tar": "7.5.19"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "xcompiler": {
+    "pluginApiVersion": 1
+  }
+}