@yss123/cage-cli 0.1.0 → 0.2.0

package/templates/blank/docs/errors/CAGE-STATE-001.md

@@ -0,0 +1,49 @@
+# CAGE-STATE-001：引用了未声明状态
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+command.from/to 或 states.initial/terminal 包含状态集合中不存在的值。
+
+## 修复步骤
+
+1. 检查拼写并在同一状态集中声明；new 是创建命令来源，不是需要放进 states 的普通状态。
+
+## 正例
+
+```text
+states('draft', 'done', { terminal: ['done'] })；to: 'done'
+```
+
+## 反例
+
+```text
+to: 'finished'，状态集中只有 done
+```
+
+## 修复后验证
+
+重跑 cage check、gen，审查状态图和相关状态迁移用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/command.ts:130`
+- `packages/kernel/src/primitives/command.ts:138`
+- `packages/kernel/src/primitives/states.ts:29`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (from !== 'new' && !hasStates(agg, from)) {
+    throw declError('CAGE-STATE-001', `${agg.name} 的命令 from 里有未声明的状态：${[from].flat().join(', ')}`);
+  }
+  // 回执等异步元数据可能在单据取消/完成后到达。允许显式保留当前状态，
+  // 避免业务 handler 通过篡改 status 绕过状态机；新建命令必须有实际目标状态。
+```

package/templates/blank/docs/errors/CAGE-STATE-002.md

@@ -0,0 +1,47 @@
+# CAGE-STATE-002：状态集合为空
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+states 没有任何字符串状态。
+
+## 修复步骤
+
+1. 声明实际业务状态；无需自定义生命周期时可使用聚合默认状态，但写命令仍需声明。
+
+## 正例
+
+```text
+states('active', 'archived', { terminal: ['archived'] })
+```
+
+## 反例
+
+```text
+states()
+```
+
+## 修复后验证
+
+重跑 cage check、gen，审查状态图和相关状态迁移用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/states.ts:22`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const values = all.filter((a): a is S => typeof a === 'string');
+  if (values.length === 0) throw declError('CAGE-STATE-002', 'states() 至少需要一个状态');
+  for (const v of values) {
+    if (!/^[a-z][a-z0-9_]*$/.test(v)) throw declError('CAGE-STATE-003', `状态名 ${v} 必须是小写下划线`);
+  }
+```

package/templates/blank/docs/errors/CAGE-STATE-003.md

@@ -0,0 +1,47 @@
+# CAGE-STATE-003：状态名称格式错误
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+状态名称不是小写字母开头的小写下划线格式。
+
+## 修复步骤
+
+1. 状态标识使用 pending_approval 等，中文名称通过页面/graph.labels 显示。
+
+## 正例
+
+```text
+states('draft', 'pending_approval', 'done')
+```
+
+## 反例
+
+```text
+states('PendingApproval', '已完成')
+```
+
+## 修复后验证
+
+重跑 cage check、gen，审查状态图和相关状态迁移用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/states.ts:24`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  for (const v of values) {
+    if (!/^[a-z][a-z0-9_]*$/.test(v)) throw declError('CAGE-STATE-003', `状态名 ${v} 必须是小写下划线`);
+  }
+  if (new Set(values).size !== values.length) throw declError('CAGE-STATE-004', '状态名重复');
+  const terminal = opts.terminal ?? [];
+```

package/templates/blank/docs/errors/CAGE-STATE-004.md

@@ -0,0 +1,47 @@
+# CAGE-STATE-004：状态名称重复
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+同一 states 集合内出现相同标识。
+
+## 修复步骤
+
+1. 保留唯一标识，需要不同含义的阶段使用不同状态名。
+
+## 正例
+
+```text
+states('draft', 'approved')
+```
+
+## 反例
+
+```text
+states('draft', 'draft')
+```
+
+## 修复后验证
+
+重跑 cage check、gen，审查状态图和相关状态迁移用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/states.ts:26`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  }
+  if (new Set(values).size !== values.length) throw declError('CAGE-STATE-004', '状态名重复');
+  const terminal = opts.terminal ?? [];
+  for (const t of [...terminal, ...(opts.initial ? [opts.initial] : [])]) {
+    if (!values.includes(t)) throw declError('CAGE-STATE-001', `状态 ${t} 未在 states 中声明`);
+```

package/templates/blank/docs/errors/CAGE-STATE-005.md

@@ -0,0 +1,48 @@
+# CAGE-STATE-005：状态声明位置冲突
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+状态集放在 fields 非 status 键，或同时通过 aggregate.states 与 fields.status 定义。
+
+## 修复步骤
+
+1. 只选择一种位置：推荐 aggregate.states，fields 中不再重复。
+
+## 正例
+
+```text
+fields: { amount: money() }, states: POStatus
+```
+
+## 反例
+
+```text
+fields: { stage: POStatus }，或 states 与 fields.status 同时提供
+```
+
+## 修复后验证
+
+重跑 cage check、gen，审查状态图和相关状态迁移用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/aggregate.ts:78`
+- `packages/kernel/src/primitives/aggregate.ts:79`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (isStates(v)) {
+      if (k !== 'status') throw declError('CAGE-STATE-005', `状态集只能放在 status 字段上（发现 ${name}.${k}）`);
+      if (st) throw declError('CAGE-STATE-005', `${name} 同时在 states 和 fields.status 里声明了状态`);
+      st = v;
+      continue;
+```

package/templates/blank/docs/errors/CAGE-STATE-010.md

@@ -0,0 +1,48 @@
+# CAGE-STATE-010：状态不可达
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+图规则从创建/初始状态沿声明的迁移无法到达某状态。
+
+## 修复步骤
+
+1. 补真实进入路径或移除无用状态，确保命令从入口导出；不要用不可调用的假命令连线。
+
+## 正例
+
+```text
+draft 经 submit 到 pending_approval，再经 approve 到 approved
+```
+
+## 反例
+
+```text
+states 包含 received，却没有任何命令迁移到它
+```
+
+## 修复后验证
+
+重跑 cage check、gen，审查状态图和相关状态迁移用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:67`
+- `packages/cli/src/rules.ts:93`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-STATE-010：每个状态都能从初始状态到达；CAGE-STATE-011：非终态必须有出边 */
+export function checkStates(g: Ontology): Finding[] {
+  const { get } = index(g);
+  const findings: Finding[] = [];
+```

package/templates/blank/docs/errors/CAGE-STATE-011.md

@@ -0,0 +1,48 @@
+# CAGE-STATE-011：非终态没有后续操作
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+自定义非终态在图中没有出边，单据可能永久停住。
+
+## 修复步骤
+
+1. 若业务结束则列入 terminal；否则补真实可执行的后续命令。默认生命周期有框架特别处理，不能据此忽略自定义状态。
+
+## 正例
+
+```text
+states('draft', 'done', { terminal: ['done'] })，draft 有提交路径
+```
+
+## 反例
+
+```text
+声明 pending_approval 非终态，却没有批准/驳回/取消
+```
+
+## 修复后验证
+
+重跑 cage check、gen，审查状态图和相关状态迁移用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:67`
+- `packages/cli/src/rules.ts:102`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-STATE-010：每个状态都能从初始状态到达；CAGE-STATE-011：非终态必须有出边 */
+export function checkStates(g: Ontology): Finding[] {
+  const { get } = index(g);
+  const findings: Finding[] = [];
+```

package/templates/blank/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:58`
+
+实现片段（位置随框架版本更新）：
+
+```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/blank/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:108`
+
+实现片段（位置随框架版本更新）：
+
+```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/blank/docs/errors/CAGE-SYNC-001.md

@@ -0,0 +1,48 @@
+# 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:97`
+- `packages/cli/src/sync.ts:110`
+
+实现片段（位置随框架版本更新）：
+
+```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/blank/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:36`
+
+实现片段（位置随框架版本更新）：
+
+```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/blank/docs/errors/CAGE-UNSAFE-001.md

@@ -0,0 +1,48 @@
+# 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:219`
+- `packages/lint/src/rules/unsafe-needs-reason.ts:8`
+
+实现片段（位置随框架版本更新）：
+
+```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/blank/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:45`
+- `packages/cli/src/upgrade.ts:58`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (old && obj?.getProperty('invokedBy'))
+      throw new Error('[CAGE-UPGRADE-001] command 同时包含 caller 与 invokedBy，请手工消除歧义');
+    old?.rename('invokedBy');
+  }
+  return file.getFullText();
+```