@yss123/cage-cli 0.1.0 → 0.3.0

package/templates/app/docs/errors/CAGE-STRUCT-001.md

@@ -0,0 +1,51 @@
+# CAGE-STRUCT-001：业务源码目录不符合模块约定
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：check / analyze / verify（structure: modular）。
+
+启用 structure: modular 后，domain/web 的 src 根目录出现业务文件，或使用约定之外的顶层源码目录。
+
+## 修复步骤
+
+1. 前端使用 app / modules / shared，src 根目录只保留 main.tsx；领域使用 modules / workflows / integrations / shared，根目录只保留 index.ts。
+2. 把页面、表单、hooks 和业务辅助代码放在同一业务模块，需要时再拆文件；不要创建空目录凑层级。测试就近放置，类型声明 .d.ts 不受入口约束。
+3. 目录调整后修正导入并运行 cage check、gen、verify；完整规范见 docs/ai/project-structure.md。
+
+## 正例
+
+```text
+apps/web/src/modules/expense/pages/expense-list-page.tsx
+packages/domain/src/modules/expense/expense.ts
+```
+
+## 反例
+
+```text
+apps/web/src/expense-list.tsx
+packages/domain/src/expense.ts
+```
+
+## 修复后验证
+
+按 docs/ai/project-structure.md 整理归属和导入后重跑 cage check 与 verify；不关闭目录规则，也不改业务表或能力标识。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/project-structure.ts:74`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+        findings.push({
+          code: 'CAGE-STRUCT-001',
+          at,
+          reason: `${kind} 源码没有放入约定模块：${from.path}`,
+          fix: `src 根目录只保留${kind === 'domain' ? '领域 index.ts' : '浏览器 main.tsx'}；业务按归属放入 ${layers.join(' / ')}，见 docs/ai/project-structure.md`,
+```

package/templates/app/docs/errors/CAGE-STRUCT-002.md

@@ -0,0 +1,51 @@
+# CAGE-STRUCT-002：源码依赖越过模块边界
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：check / analyze / verify（structure: modular）。
+
+共享代码反向依赖业务，前端业务互相穿透，领域模块依赖组合层，或跨模块导入了内部文件。
+
+## 修复步骤
+
+1. app 组合前端模块；各模块只用自己的实现和 shared，通过 props/回调协作。shared 不放具体业务请求、文案和状态。
+2. 领域模块间确有 reads 等依赖时从目标 index.ts 导入；跨模块事件反应写到 workflows，外部协议写到 integrations。
+3. 不要用领域总入口反向导入模块内部。公开入口仅转导出，依赖必须保持单向，禁止通过路径别名或转导出绕开规则。
+
+## 正例
+
+```text
+// 领域采购模块读取库存公开声明
+import { Inventory } from '../inventory/index.js';
+```
+
+## 反例
+
+```text
+// shared 反向依赖某项业务页面
+import { ExpensePage } from '../../modules/expense/pages/expense-page';
+```
+
+## 修复后验证
+
+按 docs/ai/project-structure.md 整理归属和导入后重跑 cage check 与 verify；不关闭目录规则，也不改业务表或能力标识。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/project-structure.ts:124`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+          findings.push({
+            code: 'CAGE-STRUCT-002',
+            at: `${at}:${source.slice(0, spec.pos).split('\n').length}`,
+            reason: `${reason}（${spec.fileName}）`,
+            fix: '调整依赖归属；共用纯逻辑下沉到 shared，页面协作由 app 传参，领域交互通过模块公开声明。见 docs/ai/project-structure.md',
+```

package/templates/app/docs/errors/CAGE-SYNC-001.md

@@ -0,0 +1,49 @@
+# CAGE-SYNC-001：AGENTS 托管区过期或标记损坏
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：sync / verify。
+
+sync --check 发现框架规则需更新，或 begin/end 标记缺失一边、重复、顺序错误。
+
+## 修复步骤
+
+1. 保留唯一且有序的 begin/end，项目业务约定移到标记外，再运行 pnpm exec cage sync。同步只替换托管区，不升级业务和文档。
+
+## 正例
+
+```text
+一个完整托管区，前后保留自己的业务规则
+```
+
+## 反例
+
+```text
+复制两段 begin/end，或只删除 end 标记
+```
+
+## 修复后验证
+
+运行 cage sync 后再 sync --check，确认标记外业务约定保持不变。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/sync.ts:149`
+- `packages/cli/src/sync.ts:156`
+- `packages/cli/src/sync.ts:167`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (starts.length !== 1 || ends.length !== 1 || ends[0].index! < starts[0].index!) {
+    throw new Error('[CAGE-SYNC-001] 托管区标记不完整或重复，请修复 AGENTS.md 的 begin/end 标记');
+  }
+  return current.slice(0, starts[0].index) + latest + current.slice(ends[0].index! + ends[0][0].length);
+}
+```

package/templates/app/docs/errors/CAGE-TEST-001.md

@@ -0,0 +1,47 @@
+# CAGE-TEST-001：测试进程没有生成结果报告
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：test / verify。
+
+测试未输出当前运行的 JSON 结果，CLI 无法认定测试通过。
+
+## 修复步骤
+
+1. 查看 Vitest 的启动/配置错误并重跑，确认当前 .cage/test-results.json；不复用旧报告，不将 skipped 当作 passed。
+
+## 正例
+
+```text
+测试正常退出并生成当前结果，分别报告 passed/failed/skipped
+```
+
+## 反例
+
+```text
+测试没启动，却读取上次 success:true 当作本次成功
+```
+
+## 修复后验证
+
+确认当前运行退出码与 JSON 报告，分别报告通过、失败和跳过。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/verify.ts:48`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (code !== 0) return code;
+  if (!existsSync(report)) throw new Error('[CAGE-TEST-001] 测试进程未输出结果报告，不能判定通过');
+  const result = JSON.parse(readFileSync(report, 'utf8'));
+  if (result.numPendingTests) console.log(`覆盖提示：${result.numPendingTests} 个用例跳过，请结合业务测试验收。`);
+  return result.success ? 0 : 1;
+```

package/templates/app/docs/errors/CAGE-TEST-002.md

@@ -0,0 +1,50 @@
+# CAGE-TEST-002：派生测试准备或初始夹具失败
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：test / verify。
+
+派生测试在业务命令执行前无法构造合法夹具，或初始记录已经违反不变量。
+
+## 修复步骤
+
+1. 按 trace 的阶段、种子、fixture 和前置不变量修复准备数据；必要时提供业务 fixture。
+2. 使用相同随机种子重放；区分准备失败与合法初始状态下的真实业务反例，不放宽不变量。
+
+## 正例
+
+```text
+derived(domain, { seed: 20261103, /* 按公开类型提供合法 fixture */ })
+```
+
+## 反例
+
+```text
+初始预算已经不守恒，却报告命令破坏预算守恒
+```
+
+## 修复后验证
+
+确认当前运行退出码与 JSON 报告，分别报告通过、失败和跳过。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/testkit/src/derived-diagnostics.ts:73`
+- `packages/testkit/src/derived-diagnostics.ts:77`
+- `packages/testkit/src/derived-diagnostics.ts:82`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+/**
+ * 携带结构化失败轨迹的测试异常，统一标识为 CAGE-TEST-002。
+ * 构造前由调用方脱敏 detail，消息序列化同一轨迹，phase/aggregate/seed 提供快速定位字段。
+ */
+export class DerivedTestError extends Error {
+```

package/templates/app/docs/errors/CAGE-TEST-003.md

@@ -0,0 +1,52 @@
+# CAGE-TEST-003：测试数据库目录归属不匹配
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：test / verify。
+
+临时 PostgreSQL 的目录、归属标记、实际 data_directory 或端口与本次启动实例不符。
+
+## 修复步骤
+
+1. 保留诊断并核对本次测试自己的实例；修复路径或生命周期后重新运行。
+2. 已有目录明确使用 persistent: true；不删除未知目录、不按进程名批量终止 PostgreSQL。
+
+## 正例
+
+```text
+测试工具停止自己创建且验证归属的临时实例
+```
+
+## 反例
+
+```text
+将已有业务目录作为自动清理目录，或为了退出测试结束所有 postgres 进程
+```
+
+## 修复后验证
+
+确认当前运行退出码与 JSON 报告，分别报告通过、失败和跳过。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/testkit/src/pg.ts:63`
+- `packages/testkit/src/pg.ts:65`
+- `packages/testkit/src/pg.ts:90`
+- `packages/testkit/src/pg.ts:96`
+- `packages/testkit/src/pg.ts:107`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const dir = resolve(opts.dir ?? mkdtempSync(join(tmpdir(), 'cage-pg-')));
+  if (dir === parse(dir).root) throw new Error('[CAGE-TEST-003] 内嵌 PostgreSQL 目录不能是文件系统根目录');
+  const fresh = !existsSync(join(dir, 'PG_VERSION'));
+  if (!persistent && !fresh) throw new Error('[CAGE-TEST-003] 不允许将已有 PostgreSQL 目录作为自动删除的临时实例；使用 persistent: true');
+  if (persistent) mkdirSync(dir, { recursive: true });
+```

package/templates/app/docs/errors/CAGE-UNSAFE-001.md

@@ -0,0 +1,49 @@
+# CAGE-UNSAFE-001：逃生口缺少原因或负责人
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / lint / budget。
+
+unsafe 的 reason/owner 缺失或为空，运行时或 lint 拒绝。
+
+## 修复步骤
+
+1. 先尝试正常声明；确需逃生口写清业务必要性、负责人和评审依据，并通过预算检查。它不会自动授予额外权限。
+
+## 正例
+
+```text
+unsafe({ reason: '已评审的历史数据修复', owner: '数据负责人' }, action)
+```
+
+## 反例
+
+```text
+unsafe({ reason: '', owner: '' }, action)
+```
+
+## 修复后验证
+
+运行相关 lint、budget 和真正业务用例，保留原因与负责人。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:383`
+- `packages/lint/src/rules/unsafe-needs-reason.ts:10`
+- `packages/lint/src/rules/unsafe-needs-reason.ts:17`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+export function unsafe<T>(tag: UnsafeTag, fn: () => T): T {
+  if (!tag?.reason || !tag?.owner) throw declError('CAGE-UNSAFE-001', 'unsafe 必须写明 reason 和 owner');
+  return fn();
+}
+(unsafe as any)[UNSAFE] = true;
+```

package/templates/app/docs/errors/CAGE-UPGRADE-001.md

@@ -0,0 +1,48 @@
+# CAGE-UPGRADE-001：升级版本或 codemod 有歧义
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：upgrade。
+
+当前 CLI 不含目标版本迁移，或 command 同时存在旧 caller 与新 invokedBy。
+
+## 修复步骤
+
+1. 先安装目标版本 CLI；dry-run 审查迁移。新旧属性同时存在时人工确定语义并保留一种，不让工具猜测。
+
+## 正例
+
+```text
+安装目标 CLI → upgrade --dry-run → 审查后 upgrade
+```
+
+## 反例
+
+```text
+command(A, { caller: 'user', invokedBy: 'process', ... })
+```
+
+## 修复后验证
+
+审查 dry-run 后升级，再按新版本运行 gen/verify，报告尚未完成的数据库/外部联调。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/upgrade.ts:60`
+- `packages/cli/src/upgrade.ts:79`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (old && obj?.getProperty('invokedBy'))
+      throw new Error('[CAGE-UPGRADE-001] command 同时包含 caller 与 invokedBy，请手工消除歧义');
+    old?.rename('invokedBy');
+  }
+  return file.getFullText();
+```

package/templates/app/docs/errors/CAGE-WORKER-001.md

@@ -0,0 +1,48 @@
+# CAGE-WORKER-001：缺少必要后台引擎
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：worker 启动 / 投递 / 停机。
+
+声明存在审批等必要消费者，但启动 worker 时没有提供相应引擎。
+
+## 修复步骤
+
+1. 按 domain 声明装配真实审批引擎和连接器运行环境，检查 worker manifest。
+2. 不要删除审批声明或把必需引擎缺失降级为警告。
+
+## 正例
+
+```text
+使用标准 createWorker 入口装配声明要求的审批引擎
+```
+
+## 反例
+
+```text
+带审批绑定的注册表启动时跳过审批引擎
+```
+
+## 修复后验证
+
+核对同版本注册指纹、消费者清单、心跳和时间线，再验证投递及停机恢复。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/worker/consumers.ts:66`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (!engine) {
+      throw new Error(`[CAGE-WORKER-001] 审批绑定 ${name} 缺少流程 ${a.process} 的审批引擎；补齐路由或装配引擎后再启动 worker`);
+    }
+    out.push({
+      name: `approval:${name}:start`,
+```

package/templates/app/docs/errors/CAGE-WORKER-002.md

@@ -0,0 +1,50 @@
+# CAGE-WORKER-002：事件与消费者清单不匹配
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：worker 启动 / 投递 / 停机。
+
+worker 收到未知事件或缺少声明要求的消费者，消息不能静默完成。
+
+## 修复步骤
+
+1. 通过 doctor/timeline 核对 API 与 worker 的版本、注册指纹、消费者清单和心跳。
+2. 首阶段停止旧进程后同版本升级 API 与 worker，再检查死信并按允许方式恢复；不要直接修改 done 状态。
+
+## 正例
+
+```text
+更新匹配版本后重放死信，确认消费者处理证据
+```
+
+## 反例
+
+```text
+旧 worker 对新关键事件找不到消费者仍标记 done
+```
+
+## 修复后验证
+
+核对同版本注册指纹、消费者清单、心跳和时间线，再验证投递及停机恢复。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:289`
+- `packages/kernel/src/worker/outbox.ts:40`
+- `packages/kernel/src/worker/outbox.ts:106`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    async handle(row, tx, _kernel, prepared) {
+      if (!prepared) throw new Error('[CAGE-WORKER-002] 出站消费者必须经 worker prepare 阶段执行');
+      const result = prepared as OutboundPrepared;
+      if (result.skipped) return;
+      if (ob.onSuccess) {
+```

package/templates/app/docs/errors/CAGE-WORKER-003.md

@@ -0,0 +1,48 @@
+# CAGE-WORKER-003：后台任务未在停机时限内结束
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：worker 启动 / 投递 / 停机。
+
+停止接收新任务并取消外部 IO 后，在途任务仍超过退出时限。
+
+## 修复步骤
+
+1. 检查任务、网络超时和阻塞阶段；等待在途任务结束后再释放锁与连接。
+2. 核对恢复记录和远端幂等结果；不要在任务还执行时强行释放互斥锁。
+
+## 正例
+
+```text
+先停止领取，再等待并核对运行任务的退出结果
+```
+
+## 反例
+
+```text
+停机时直接关锁连接，允许第二个实例和旧任务同时执行
+```
+
+## 修复后验证
+
+核对同版本注册指纹、消费者清单、心跳和时间线，再验证投递及停机恢复。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/worker/index.ts:269`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+        const timeout = setTimeout(() => {
+          state.lastError = `[CAGE-WORKER-003] 停机等待超时，在途任务：${snapshot().inFlight.join(', ')}`;
+          log.error({ err: state.lastError }, 'worker 停机超时；任务结束前保留锁和连接');
+          reject(new Error(state.lastError));
+        }, opts.shutdownTimeoutMs ?? 30_000);
+```