@yss123/cage-cli 0.1.0 → 0.2.0

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

@@ -0,0 +1,47 @@
+# CAGE-CONN-005：入站事件名称格式错误
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+inbound 的事件名不是小驼峰格式。
+
+## 修复步骤
+
+1. 使用小驼峰稳定标识，展示文案另设中文。
+
+## 正例
+
+```text
+inbound(erp, 'goodsReceived', definition)
+```
+
+## 反例
+
+```text
+inbound(erp, 'GoodsReceived', definition)
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/primitives.ts:153`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+): Inbound<P> {
+  if (!/^[a-z][A-Za-z0-9]*$/.test(eventName)) throw declError('CAGE-CONN-005', `入站事件名 ${eventName} 必须是小驼峰`);
+  if (!def.command.invokedBy.includes('external') && !def.command.invokedBy.includes('user')) {
+    throw declError('CAGE-CONN-006', `入站回调调用的命令必须声明 invokedBy: 'external'`);
+  }
+```

package/templates/blank/docs/errors/CAGE-CONN-006.md

@@ -0,0 +1,47 @@
+# CAGE-CONN-006：回调命令未允许 external
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+入站回调指向的命令没有声明 external 调用身份。
+
+## 修复步骤
+
+1. 为专用回调命令声明 external；验签和输入校验之后才能调用，不把内部命令暴露为普通用户接口。
+
+## 正例
+
+```text
+invokedBy: 'external'
+```
+
+## 反例
+
+```text
+invokedBy: 'user' // 作为 inbound.command
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/primitives.ts:155`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (!def.command.invokedBy.includes('external') && !def.command.invokedBy.includes('user')) {
+    throw declError('CAGE-CONN-006', `入站回调调用的命令必须声明 invokedBy: 'external'`);
+  }
+  return Object.freeze({ [INBOUND]: true as const, connector: conn, event: eventName, ...def });
+}
+```

package/templates/blank/docs/errors/CAGE-CONN-007.md

@@ -0,0 +1,47 @@
+# CAGE-CONN-007：当前环境没有连接器地址
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+非 fake 环境中，连接器 hosts 找不到当前 stage 对应的主机。
+
+## 修复步骤
+
+1. 检查 CAGE_STAGE 与 hosts.test/prod。fake 不需要真实主机；真实联调必须配置正确环境及密钥。
+
+## 正例
+
+```text
+CAGE_STAGE=test，hosts.test 指向沙箱主机
+```
+
+## 反例
+
+```text
+只配置 prod 却用 test 环境启动，或把 fake 成功称作真实联调通过
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:131`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const host = o.connector.hosts[st];
+  if (!host) throw new ConnectorError(`[CAGE-CONN-007] 连接器 ${o.connector.name} 没有 ${st} 环境的地址`, null, false);
+  const token = o.connector.secret ? await secrets.get(o.connector.secret) : undefined;
+  await take(o.connector);
+  const url = new URL(o.path, `https://${host}`);
+```

package/templates/blank/docs/errors/CAGE-CONN-008.md

@@ -0,0 +1,47 @@
+# CAGE-CONN-008：外部请求发生网络错误或超时
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+fetch 在收到有效 HTTP 响应前失败，例如 DNS、网络、TLS 或 timeout。
+
+## 修复步骤
+
+1. 核对脱敏后的主机、网络、代理和 timeoutMs；排除临时故障后由 worker 重试，不能在 handler 内加网络重试。
+
+## 正例
+
+```text
+使用同步记录定位失败阶段；保持同一业务幂等键重试
+```
+
+## 反例
+
+```text
+每次重试换远端幂等键，导致重复写入
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:151`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    await recordCall(opts.kernel, o, key, opts.tenantId ?? null, 'failed', null, body, undefined, String(e));
+    throw new ConnectorError(`[CAGE-CONN-008] 调用 ${o.connector.name}.${o.name} 失败：${String(e)}`, null, true);
+  }
+  const text = await res.text();
+  let json: unknown = null;
+```

package/templates/blank/docs/errors/CAGE-CONN-009.md

@@ -0,0 +1,47 @@
+# CAGE-CONN-009：外部服务返回非成功状态
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+连接器取得 HTTP 响应，但状态码不是成功码。
+
+## 修复步骤
+
+1. 看同步记录的状态与脱敏响应；核对鉴权、字段及限流。可重试性还受 effect 和状态码控制，不是所有 4xx 都会重试。
+
+## 正例
+
+```text
+修正 401 的运行环境密钥，确认后重放失败事件
+```
+
+## 反例
+
+```text
+把所有 4xx 改成成功，或无限重试无效请求
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:163`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    const retryable = o.effect === 'retryableWrite' || o.effect === 'read' ? res.status >= 500 || res.status === 429 : false;
+    throw new ConnectorError(`[CAGE-CONN-009] ${o.connector.name}.${o.name} 返回 ${res.status}`, res.status, retryable);
+  }
+  const parsed = o.response.safeParse(json);
+  if (!parsed.success) {
+```

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

@@ -0,0 +1,47 @@
+# CAGE-CONN-010：外部响应不符合 schema
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+外部返回成功 HTTP 状态，但内容不满足声明的 response schema。
+
+## 修复步骤
+
+1. 对照真实协议、响应样例和声明，修正一方；不要用 any 或空对象吞掉未知格式。该错误按永久失败处理。
+
+## 正例
+
+```text
+response: z.object({ erpNo: z.string() }) 与真实成功协议一致
+```
+
+## 反例
+
+```text
+后端返回 { orderNo: 123 }，却继续读取 res.erpNo
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:168`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    await recordCall(opts.kernel, o, key, opts.tenantId ?? null, 'failed', res.status, body, json, '响应格式不符合声明');
+    throw new ConnectorError(`[CAGE-CONN-010] ${o.connector.name}.${o.name} 的响应格式与声明不符`, res.status, false);
+  }
+  await recordCall(opts.kernel, o, key, opts.tenantId ?? null, 'ok', res.status, body, parsed.data);
+  return parsed.data;
+```

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

@@ -0,0 +1,47 @@
+# CAGE-CONN-011：出站永久失败进入死信
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+出站消费者将不可重试的 ConnectorError 包装为永久错误；真正原因是内层错误码。
+
+## 修复步骤
+
+1. 先按内层 CAGE-CONN-007/009/010 等修正配置/协议，再重放死信；检查远端是否已完成写入并复用业务幂等键。
+
+## 正例
+
+```text
+修复响应 schema，核对远端幂等结果，再重放指定 outboxId
+```
+
+## 反例
+
+```text
+只重启 worker，希望永久错误自动恢复或直接删 outbox
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:190`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+          // 不可重试：标成永久错误，直接进死信
+          throw Object.assign(new Error(`[CAGE-CONN-011] ${e.message}`), { permanent: true });
+        }
+        throw e;
+      }
+```

package/templates/blank/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/blank/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/blank/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/blank/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/blank/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/blank/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/blank/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；需要通知外部系统就发事件，由连接器的出站映射处理',
+```