@yss123/cage-cli 0.1.0 → 0.2.0

package/templates/app/docs/errors/CAGE-CONN-012.md

@@ -0,0 +1,47 @@
+# CAGE-CONN-012：外部专用命令没有声明调用者
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+external 专用命令没有 inbound 或 outbound.onSuccess 等图内调用者；当前图规则给出 warning。
+
+## 修复步骤
+
+1. 补真实回调/成功映射并从入口导出，或明确这是暂未接线的功能。warning 不代表外部链路已完成。
+
+## 正例
+
+```text
+recordErpNo 被 pushToErp.onSuccess.command 引用
+```
+
+## 反例
+
+```text
+定义 markReceived，却没有验签回调或其他外部调用入口
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:157`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      findings.push({
+        code: 'CAGE-CONN-012',
+        at: at(c),
+        reason: `命令 ${c.id} 只接受外部调用，但没有入站回调或出站映射调用它`,
+        fix: '用 inbound(...) 或 outbound(..., { onSuccess }) 调用它',
+```

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

@@ -0,0 +1,52 @@
+# CAGE-CREATE-001：项目创建参数或模板资源有误
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：create-cage-app / cage create。
+
+目标目录已存在、模板参数不属于 blank/purchase、非交互环境缺少目录或模板，或 CLI 包缺少所选模板。
+
+## 修复步骤
+
+1. 选择未存在的目录；若是缺模板，核对 CLI 安装版本/分发包，框架维护者检查构建资源。不要覆盖现有项目。
+2. 交互终端可直接运行脚手架选择；CI/管道中显式传入目录及 --template blank 或 --template purchase。
+
+## 正例
+
+```text
+pnpm exec cage create ../new-business-app --template blank
+```
+
+## 反例
+
+```text
+cage create . 覆盖当前已有业务项目
+```
+
+## 修复后验证
+
+向一个新目录创建，检查 AGENTS.md、业务源码、docs/ai 和 docs/errors，然后按 README 安装/构建。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/create-prompt.ts:12`
+- `packages/cli/src/create-prompt.ts:17`
+- `packages/cli/src/create.ts:20`
+- `packages/cli/src/create.ts:22`
+- `packages/cli/src/create.ts:29`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (template !== undefined && !isAppTemplate(template))
+    throw new Error('[CAGE-CREATE-001] --template 只能是 blank 或 purchase');
+
+  // 管道和 CI 没有可操作的终端，不隐式选择业务模板，也不让安装任务挂在提示上。
+  if ((!target || !template) && (!process.stdin.isTTY || !process.stdout.isTTY))
+```

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

@@ -0,0 +1,48 @@
+# CAGE-DECL-001：声明不在可抽取的顶层常量
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：静态检查 / 注册。
+
+原语调用藏在函数、条件、循环中，或没有赋给顶层常量。
+
+## 修复步骤
+
+1. 改为模块顶层 export const，让注册表和静态抽取器都能看到；动态部分放在受支持的 handler/map 等函数。
+
+## 正例
+
+```text
+export const Order = aggregate('Order', definition)
+```
+
+## 反例
+
+```text
+export function build() { return aggregate('Order', definition); }
+```
+
+## 修复后验证
+
+重跑 cage check/analyze，确认声明出现在本体图，再运行 gen。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/static-check.ts:188`
+- `packages/cli/src/static-check.ts:195`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+            findings.push({
+              code: 'CAGE-DECL-001',
+              at: loc(node),
+              reason: `原语 ${name}() 写在函数、条件或循环里，抽取器看不到它`,
+              fix: '原语必须在模块顶层用 export const 声明',
+```

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

@@ -0,0 +1,47 @@
+# CAGE-DECL-002：声明没有从 domain 入口导出
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：静态检查 / 注册。
+
+文件里有声明，但 domain/index.ts 最终导出集合中没有它。
+
+## 修复步骤
+
+1. 在统一入口 re-export，确认没有 export * 的同名冲突；只创建文件不会自动注册。
+
+## 正例
+
+```text
+export * from './purchase-order.js'; // index.ts
+```
+
+## 反例
+
+```text
+文件存在，但 index.ts 未导出
+```
+
+## 修复后验证
+
+重跑 cage check/analyze，确认声明出现在本体图，再运行 gen。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/static-check.ts:254`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    .map((s) => ({
+      code: 'CAGE-DECL-002',
+      at: `${s.file}:${s.line}`,
+      reason: `声明 ${s.exportName} 没有从 domain 入口导出，内核和抽取器都看不到它`,
+      fix: `从所属模块 index.ts 导出 ${s.exportName}，再由 domain 的统一入口转导出；源文件 ${s.file}`,
+```

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

@@ -0,0 +1,47 @@
+# CAGE-DECL-003：声明不是 export const
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：静态检查 / 注册。
+
+顶层声明没有同时使用 export 和 const。
+
+## 修复步骤
+
+1. 使用稳定的模块顶层 export const；不要用可变声明或只保留文件内私有声明。
+
+## 正例
+
+```text
+export const OrderSubmitted = event('OrderSubmitted', fields)
+```
+
+## 反例
+
+```text
+const OrderSubmitted = event('OrderSubmitted', fields)
+```
+
+## 修复后验证
+
+重跑 cage check/analyze，确认声明出现在本体图，再运行 gen。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/static-check.ts:207`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+                findings.push({
+                  code: 'CAGE-DECL-003',
+                  at: loc(node),
+                  reason: `声明 ${topDecl.name.getText()} 没有用 export const 导出`,
+                  fix: '加上 export const，并确认它从 domain 的 index.ts 导出',
+```

package/templates/app/docs/errors/CAGE-DECL-004.md

@@ -0,0 +1,47 @@
+# CAGE-DECL-004：跨文件导出名冲突
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：静态检查 / 注册。
+
+多个文件导出了同名声明，export * 汇总会产生歧义并丢失导出。
+
+## 修复步骤
+
+1. 给导出变量唯一名字；需要保留最终命令名时用 command 的 name 覆盖。
+
+## 正例
+
+```text
+export const createNote = command(Note, { name: 'create', ... })
+```
+
+## 反例
+
+```text
+note.ts 与 order.ts 都 export const create，再 export *
+```
+
+## 修复后验证
+
+重跑 cage check/analyze，确认声明出现在本体图，再运行 gen。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/static-check.ts:239`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      findings.push({
+        code: 'CAGE-DECL-004',
+        at: `${list[0].file}:${list[0].line}`,
+        reason: `导出名 ${n} 在 ${list.map((s) => s.file).join('、')} 里重复，export * 会把它们都丢掉`,
+        fix: '改成不重复的导出名；命令可以用 command(X, { name: "原名" }) 保持能力点不变',
+```

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

@@ -0,0 +1,48 @@
+# CAGE-DEP-001：领域声明直接依赖 IO
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：静态检查 / verify。
+
+domain 引入数据库、文件、网络或 HTTP 运行时等越界依赖。
+
+## 修复步骤
+
+1. 读取通过 reads，第三方交给连接器，框架装配放 apps/api；不要把 IO 移进 helper 后继续从 domain 间接调用。
+
+## 正例
+
+```text
+reads: { stock: Inventory }；handler 使用 deps.stock.findOne(...)
+```
+
+## 反例
+
+```text
+import pg from 'pg'; // domain 直接操作数据库
+```
+
+## 修复后验证
+
+重跑 cage check 和 verify，确认边界修复而不是禁用规则。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/static-check.ts:144`
+- `packages/lint/dependency-cruiser.cjs:8`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+          findings.push({
+            code: 'CAGE-DEP-001',
+            at: loc(node),
+            reason: `声明文件导入了 IO 模块 ${spec}`,
+            fix: '需要外部数据就声明 reads；需要通知外部系统就发事件，由连接器的出站映射处理',
+```

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

@@ -0,0 +1,47 @@
+# CAGE-DEP-002：适配器绕过命令写库
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：静态检查 / verify。
+
+packages/adapters 依赖数据库访问包并可能直接写业务表。
+
+## 修复步骤
+
+1. 将适配器输出映射为领域命令输入，通过命令网关落实状态、审计和权限。
+
+## 正例
+
+```text
+验签后调用 external 命令
+```
+
+## 反例
+
+```text
+适配器直接 update core.purchase_order
+```
+
+## 修复后验证
+
+重跑 cage check 和 verify，确认边界修复而不是禁用规则。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/lint/dependency-cruiser.cjs:17`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      severity: 'error',
+      comment: '[CAGE-DEP-002] 适配器必须通过命令网关写数据',
+      from: { path: '^packages/adapters' },
+      to: { path: 'node_modules/(pg|kysely)/' },
+    },
+```

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

@@ -0,0 +1,47 @@
+# CAGE-DEP-003：前端依赖服务端实现
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：静态检查 / verify。
+
+apps/web 导入 domain 或 kernel/http/admin/connectors/approval/testkit 等服务端包。
+
+## 修复步骤
+
+1. 前端使用 @app/contracts 与 @yss123/cage-client；共享快照类型通过生成契约取得。
+
+## 正例
+
+```text
+import { purchaseOrder } from '@app/contracts'
+```
+
+## 反例
+
+```text
+import { approve } from '@app/domain'
+```
+
+## 修复后验证
+
+重跑 cage check 和 verify，确认边界修复而不是禁用规则。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/lint/dependency-cruiser.cjs:24`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      severity: 'error',
+      comment: '[CAGE-DEP-003] 前端只能依赖 @app/contracts',
+      from: { path: '^apps/web' },
+      to: { path: '^packages/domain|node_modules/@yss123/cage-(kernel|http|admin|connectors|approval|testkit)/' },
+    },
+```

package/templates/app/docs/errors/CAGE-DEP-004.md

@@ -0,0 +1,47 @@
+# CAGE-DEP-004：声明或 handler 直接发请求/动态导入
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：静态检查 / verify。
+
+静态检查发现 domain 调用 fetch 或动态 import。
+
+## 修复步骤
+
+1. 把外部 IO 声明成连接器，把声明改为静态导出，避免在运行时动态生成业务规格。
+
+## 正例
+
+```text
+event → outbound → onSuccess.command
+```
+
+## 反例
+
+```text
+handler 里 await fetch(...) 或动态 import 数据库模块
+```
+
+## 修复后验证
+
+重跑 cage check 和 verify，确认边界修复而不是禁用规则。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/static-check.ts:155`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+          findings.push({
+            code: 'CAGE-DEP-004',
+            at: loc(node),
+            reason: name === 'fetch' ? 'handler 里直接发网络请求' : '声明文件里使用了动态 import',
+            fix: '第三方调用改为连接器声明 + outbound 出站映射',
+```

package/templates/app/docs/errors/CAGE-DEP-005.md

@@ -0,0 +1,47 @@
+# CAGE-DEP-005：domain 反向依赖生成物
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：静态检查 / verify。
+
+domain 引用 generated 或 packages/contracts，形成生成循环。
+
+## 修复步骤
+
+1. 领域源码是生成源头；前端/适配层使用 contracts，domain 使用本地领域类型和公开声明 API。
+
+## 正例
+
+```text
+domain 从 './purchase-order.js' 读领域符号
+```
+
+## 反例
+
+```text
+domain 从 '@app/contracts' 导入自己生成的快照
+```
+
+## 修复后验证
+
+重跑 cage check 和 verify，确认边界修复而不是禁用规则。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/lint/dependency-cruiser.cjs:31`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      severity: 'error',
+      comment: '[CAGE-DEP-005] domain 不能依赖生成物',
+      from: { path: '^packages/domain' },
+      to: { path: '^(generated|packages/contracts)/' },
+    },
+```

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

@@ -0,0 +1,48 @@
+# CAGE-DLQ-001：死信不存在或已经处理
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：系统管理接口。
+
+重放/丢弃时目标死信已被处理或不在待处理集合。
+
+## 修复步骤
+
+1. 刷新死信列表，核对 outboxId 和审计记录；确认是否已由其他人处理，不直接重建/修改系统行。
+
+## 正例
+
+```text
+查看当前状态后只处理待处理的死信
+```
+
+## 反例
+
+```text
+反复提交旧页面上的重放请求或手改 sys.outbox
+```
+
+## 修复后验证
+
+刷新死信列表并查看审计及当前处理结果；核对原始 outboxId。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/worker/outbox.ts:128`
+- `packages/kernel/src/worker/outbox.ts:139`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    const d = await tx.selectFrom('sys.dead_letter').selectAll().where('id', '=', deadLetterId).where('handled_at', 'is', null).forUpdate().executeTakeFirst();
+    if (!d) throw new Error('[CAGE-DLQ-001] 死信不存在或已处理');
+    await tx.updateTable('sys.outbox').set({ status: 'pending', attempts: 0, next_at: sql`now()`, last_error: null }).where('id', '=', d.outbox_id).execute();
+    await tx.updateTable('sys.dead_letter').set({ handled_by: handledBy, handled_at: sql`now()`, resolution: 'replayed' }).where('id', '=', deadLetterId).execute();
+    await sql`select pg_notify('cage_outbox', '')`.execute(tx);
+```

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

@@ -0,0 +1,52 @@
+# CAGE-ENV-001：缺少数据库连接配置
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：init / migrate / 启动。
+
+API、worker、迁移或初始化没有取得所需的数据库连接。
+
+## 修复步骤
+
+1. 在应用根目录 .env 配置 CAGE_ADMIN_DATABASE_URL，指向已存在的数据库，运行 pnpm exec cage init 自动生成三种账号连接。
+2. 已有账号则直接提供 APP/READ/MIGRATE URL；主机、端口、库名一致，账号各司其职。migrate 需要迁移连接。
+3. 确认运行目录、部署环境覆盖值及服务已重启；不要输出凭证，也不要给日常服务改用管理员连接。
+
+## 正例
+
+```text
+配置已有库 → cage init → gen → 审查后 migrate → dev
+```
+
+## 反例
+
+```text
+未配置连接就启动，或新增自动临时数据库兜底掩盖错误
+```
+
+## 修复后验证
+
+重跑原先失败的命令，确认使用预期库与账号；输出脱敏信息。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/init.ts:74`
+- `packages/cli/src/migrate.ts:22`
+- `packages/kernel/src/db/connect.ts:74`
+- `packages/kernel/src/kernel.ts:100`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (!configured(adminUrl)) {
+    if (!hasSaved) throw new Error('[CAGE-ENV-001] 首次初始化请在项目 .env 填写 CAGE_ADMIN_DATABASE_URL，连接已有数据库后运行 pnpm exec cage init');
+    await verifyConnections(saved);
+    return { status: 'reused', envFile };
+  }
+```

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

@@ -0,0 +1,47 @@
+# CAGE-EVENT-001：事件载荷不满足声明
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：写事务 / 基线比较。
+
+命令要写入 outbox 的载荷没有通过事件字段 schema。
+
+## 修复步骤
+
+1. 核对默认载荷映射及字段类型；需要旧状态、改名字段或复杂数据时使用 emit 显式映射。事务失败应回滚，不单独补写消息。
+
+## 正例
+
+```text
+emit(OrderCancelled, (o, _i, prev) => ({ orderId: o.id, previousStatus: prev.status }))
+```
+
+## 反例
+
+```text
+事件要求 orderId，却从错误字段映射成 undefined
+```
+
+## 修复后验证
+
+运行相关命令与消费者测试；兼容性使用修改前基线检查，考虑尚未消费的旧事件。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/kernel.ts:380`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      if (!p.success) {
+        throw new Error(`[CAGE-EVENT-001] 事件 ${ev.name} 的载荷不符合声明：${JSON.stringify(zodIssues(p.error))}`);
+      }
+      const payload = maskEventPayload(ev, p.data as Record<string, unknown>);
+      const row = await tx
+```