@yss123/cage-cli 0.1.0 → 0.2.0

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

@@ -0,0 +1,47 @@
+# CAGE-READS-001：handler 使用了未声明读依赖
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：handler 执行。
+
+handler 访问 deps 中不存在的别名。
+
+## 修复步骤
+
+1. 在命令 reads 添加真实聚合与正确别名，核对入口导出。不要通过 any 或自建仓储绕过依赖声明。
+
+## 正例
+
+```text
+reads: { stock: Inventory }；使用 deps.stock.findOne({ sku })
+```
+
+## 反例
+
+```text
+reads: {}；使用 deps.stock
+```
+
+## 修复后验证
+
+检查本体图 reads 边并运行该命令的业务用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/pipeline/load.ts:86`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      if (typeof prop === 'string' && !(prop in target) && prop !== 'then' && prop !== 'toJSON') {
+        throw new Error(`[CAGE-READS-001] handler 使用了未声明的读依赖 ${prop}（详见 docs/errors/CAGE-READS-001.md）`);
+      }
+      return (target as any)[prop];
+    },
+```

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

@@ -0,0 +1,53 @@
+# CAGE-REG-001：注册表缺少被引用声明
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 执行。
+
+命令、读依赖、反应、审批或任务引用了没有从 domain 入口导出的聚合/命令，或执行时找不到命令。
+
+## 修复步骤
+
+1. 从统一入口导出依赖双方，确认引用是同一个声明对象且名字正确；修复后重新 check/gen。
+
+## 正例
+
+```text
+export * from './inventory.js'; export * from './purchase-order.js';
+```
+
+## 反例
+
+```text
+只导出反应，却没有导出它的目标命令
+```
+
+## 修复后验证
+
+重跑 cage check/analyze/gen，确认统一入口包含引用双方。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/kernel.ts:113`
+- `packages/kernel/src/registry.ts:153`
+- `packages/kernel/src/registry.ts:159`
+- `packages/kernel/src/registry.ts:164`
+- `packages/kernel/src/registry.ts:168`
+- `packages/kernel/src/registry.ts:172`
+- `packages/kernel/src/registry.ts:190`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (!rc) {
+      throw new Error(`[CAGE-REG-001] 找不到命令 ${typeof ref === 'string' ? ref : ref.agg.name + '.?'}，它是否从 domain 导出了？`);
+    }
+    return rc;
+  }
+```

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

@@ -0,0 +1,48 @@
+# CAGE-REG-002：聚合或查询注册重名
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 执行。
+
+同类聚合/查询拥有相同逻辑名称。
+
+## 修复步骤
+
+1. 保留一个规范声明，或为真正不同对象选不同逻辑名；不能通过对象复制创建同名注册。
+
+## 正例
+
+```text
+aggregate('PurchaseOrder', ...)、aggregate('Inventory', ...)
+```
+
+## 反例
+
+```text
+不同文件都 aggregate('Order', ...) 并导出
+```
+
+## 修复后验证
+
+重跑 cage check/analyze/gen，确认统一入口包含引用双方。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/registry.ts:88`
+- `packages/kernel/src/registry.ts:176`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+          if (aggregates.some((a) => a.name === (v as AnyAggregate).name)) {
+            throw declError('CAGE-REG-002', `聚合名重复：${(v as AnyAggregate).name}`);
+          }
+          aggregates.push(v as AnyAggregate);
+          break;
+```

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

@@ -0,0 +1,47 @@
+# CAGE-REG-003：命令能力点重复
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 执行。
+
+同一聚合的多个命令解析成同一个 Aggregate.command 能力点。
+
+## 修复步骤
+
+1. 为不同操作指定不同 name，跨文件导出名也保持唯一；相同操作复用同一命令对象。
+
+## 正例
+
+```text
+name: 'submit' 与 name: 'cancel'
+```
+
+## 反例
+
+```text
+同一聚合两个命令都 name: 'update'
+```
+
+## 修复后验证
+
+重跑 cage check/analyze/gen，确认统一入口包含引用双方。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/registry.ts:156`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      throw declError('CAGE-REL-001', `${c.cmd.agg.name}.related 是生成客户端的关联读取入口；请为业务命令使用其他 name`);
+    if (caps.has(c.capability)) throw declError('CAGE-REG-003', `能力点重复：${c.capability}，可用 command({ name }) 区分`);
+    caps.add(c.capability);
+    for (const [alias, a] of Object.entries(c.cmd.reads)) {
+      if (!aggSet.has(a)) throw declError('CAGE-REG-001', `命令 ${c.capability} 的 reads.${alias} 引用的聚合没有导出`);
+```

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

@@ -0,0 +1,64 @@
+# CAGE-REL-001：关系字段声明无效
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 生成。
+
+关系目标未导出、hasMany.mappedBy 不是指回当前聚合的公开 ref、关系表重名/过长，或集合关系用于不支持的位置与修饰。带关系聚合的用户命令名 related 也会占用生成客户端入口。
+
+## 修复步骤
+
+1. 把 ref/hasMany/manyToMany 的目标从 domain 入口导出；循环引用使用聚合名字符串。
+2. hasMany 的 mappedBy 写目标上的真实 ref 字段名，该字段不能 hidden 或 sensitive；修改归属调用子对象命令。
+3. 集合关系只写在聚合 fields 中，不放进 list、事件载荷或 scope 字段。不要对关系链式调用 optional/unique/hidden/sensitive；没有关联用空集合表示。
+4. 缩短或调整发生冲突的字段/表名；业务命令避开 related，运行 cage check/gen 后审查迁移。
+
+## 正例
+
+```text
+Note.fields.members = manyToMany('User', { description: '协作成员' }); // User 已导出
+Notebook.fields.notes = hasMany('Note', { mappedBy: 'notebookId' }); // Note.notebookId = ref('Notebook')
+```
+
+## 反例
+
+```text
+hasMany('Note', { mappedBy: 'title' }); // title 不是反向 ref
+list({ members: manyToMany('User') }); // JSON 明细中不能声明关系
+```
+
+## 修复后验证
+
+重跑 cage check/gen；迁移后用真实用户验证关系命令、关联分页读取和双侧范围。不要手写纯中间表聚合。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/aggregate.ts:97`
+- `packages/kernel/src/primitives/event.ts:20`
+- `packages/kernel/src/primitives/fields.ts:94`
+- `packages/kernel/src/primitives/fields.ts:99`
+- `packages/kernel/src/primitives/fields.ts:105`
+- `packages/kernel/src/primitives/fields.ts:110`
+- `packages/kernel/src/primitives/fields.ts:167`
+- `packages/kernel/src/primitives/fields.ts:174`
+- `packages/kernel/src/primitives/fields.ts:193`
+- `packages/kernel/src/registry.ts:137`
+- `packages/kernel/src/registry.ts:141`
+- `packages/kernel/src/registry.ts:147`
+- `packages/kernel/src/registry.ts:155`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (f && f !== 'id' && !(f in fields)) throw declError('CAGE-SCOPE-002', `${name} 的范围字段 ${f} 不存在`);
+    if (f && f !== 'id' && isRelation(fields[f])) throw declError('CAGE-REL-001', `${name} 的范围字段必须是主表列，不能使用集合关系 ${f}`);
+  }
+  const scope: ScopeSpec = Object.freeze({ ...sc, ownerField });
+
+```

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

@@ -0,0 +1,47 @@
+# CAGE-ROUTE-001：业务项目手写 HTTP 路由
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：lint / verify。
+
+业务代码调用 app.get/post 等手动注册接口，绕过声明生成路径。
+
+## 修复步骤
+
+1. 将普通业务写接口声明为 command、读接口声明为 query；API 入口只装配框架。协议扩展另按框架边界评估。
+
+## 正例
+
+```text
+领域 command → gen → 自动路由和前端契约
+```
+
+## 反例
+
+```text
+app.post('/api/order/submit', handler)
+```
+
+## 修复后验证
+
+重新生成，检查 generated/routes.json 和前端契约，再验证自动接口。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/lint/src/rules/no-manual-routes.ts:11`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    docs: { description: '禁止在业务项目里手写 HTTP 路由' },
+    messages: { route: '[CAGE-ROUTE-001] 不要手写路由 {{call}}：在 domain 里声明命令或查询，路由由框架生成' },
+    schema: [],
+  },
+  create(context) {
+```

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

@@ -0,0 +1,47 @@
+# CAGE-SCOPE-001：范围组合子未知
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 范围编译。
+
+角色范围数据或内部调用传入了无法编译的 combinator。
+
+## 修复步骤
+
+1. 使用框架内置 self/dept/deptSubtree/deptSet/all，核对授权数据；别把显示中文当成存储标识。
+
+## 正例
+
+```text
+combinator: 'deptSubtree'
+```
+
+## 反例
+
+```text
+combinator: '部门及下级'
+```
+
+## 修复后验证
+
+重跑 cage check；分别使用本人/部门等实际授权用户验证范围内外结果。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/scope/index.ts:66`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    default:
+      throw new Error('[CAGE-SCOPE-001] 未知的范围组合子');
+  }
+}
+
+```

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

@@ -0,0 +1,47 @@
+# CAGE-SCOPE-002：范围字段没有声明
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 范围编译。
+
+aggregate.scope 指向的部门或创建人字段不存在。
+
+## 修复步骤
+
+1. 在聚合声明真实字段，或改用正确字段名。scope.none 表示无此类字段，不代表不限权限。
+
+## 正例
+
+```text
+fields: { deptId: ref('Dept') }, scope: scope.deptSubtree('deptId')
+```
+
+## 反例
+
+```text
+scope.deptSubtree('departmentId')，fields 只有 deptId
+```
+
+## 修复后验证
+
+重跑 cage check；分别使用本人/部门等实际授权用户验证范围内外结果。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/aggregate.ts:96`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  for (const f of [sc.deptField, ownerField]) {
+    if (f && f !== 'id' && !(f in fields)) throw declError('CAGE-SCOPE-002', `${name} 的范围字段 ${f} 不存在`);
+    if (f && f !== 'id' && isRelation(fields[f])) throw declError('CAGE-REL-001', `${name} 的范围字段必须是主表列，不能使用集合关系 ${f}`);
+  }
+  const scope: ScopeSpec = Object.freeze({ ...sc, ownerField });
+```

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

@@ -0,0 +1,48 @@
+# CAGE-SECRET-001：运行环境缺少密钥
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：lint / 外呼或回调。
+
+连接器或回调验签使用的密钥名在环境/密钥提供器中没有值。
+
+## 修复步骤
+
+1. 按声明的 secret/验签密钥名在 .env 或部署密钥系统注入，重启对应进程；不把值写进 domain 或日志。
+
+## 正例
+
+```text
+secret: 'ERP_API_TOKEN'，运行环境提供该变量
+```
+
+## 反例
+
+```text
+把实际 token 填进 secret 字段，或打印所有环境变量找值
+```
+
+## 修复后验证
+
+确认源码/日志不含值，重启后验证相应外呼或签名回调。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:22`
+- `packages/http/src/routes.ts:74`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    const v = process.env[name];
+    if (!v) throw new Error(`[CAGE-SECRET-001] 缺少密钥 ${name}（由密钥管理服务或环境变量注入）`);
+    return v;
+  },
+};
+```

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

@@ -0,0 +1,47 @@
+# CAGE-SECRET-002：源码疑似包含密钥字面量
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：lint / 外呼或回调。
+
+lint 在配置或代码中发现疑似密钥值。
+
+## 修复步骤
+
+1. 删除源码密钥，改为密钥名/环境注入；真实凭证若已暴露要轮换，不仅删掉文案。
+
+## 正例
+
+```text
+verify: hmacSha256('ERP_WEBHOOK_SECRET')
+```
+
+## 反例
+
+```text
+在源码里填真实 API token 或私钥
+```
+
+## 修复后验证
+
+确认源码/日志不含值，重启后验证相应外呼或签名回调。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/lint/src/rules/no-secret-literal.ts:19`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    docs: { description: '禁止密钥字面量' },
+    messages: { secret: '[CAGE-SECRET-002] 疑似{{what}}写在了代码里：密钥只写名字，值由密钥管理服务注入' },
+    schema: [],
+  },
+  create(context) {
+```

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

@@ -0,0 +1,48 @@
+# CAGE-SENS-001：敏感字段未标注就进入事件
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：图规则。
+
+命令事件载荷包含与聚合同名的敏感字段，却没有对应 sensitive 标记。
+
+## 修复步骤
+
+1. 移除非必要敏感数据，或在事件保持一致 sensitive 标记以便掩码；自定义映射也要审查，字段改名不会自动证明安全。
+
+## 正例
+
+```text
+event('OrderChanged', { phone: text().sensitive('phone') })
+```
+
+## 反例
+
+```text
+聚合 phone 为 sensitive，事件 phone 却是普通 text()
+```
+
+## 修复后验证
+
+重跑 cage check，检查实际 outbox 载荷及普通读结果没有泄漏明文。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:114`
+- `packages/cli/src/rules.ts:128`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-SENS-001：敏感字段不得原样进入事件载荷 */
+export function checkSensitiveEvents(g: Ontology): Finding[] {
+  const { get, out } = index(g);
+  const findings: Finding[] = [];
+```

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

@@ -0,0 +1,47 @@
+# CAGE-SQL-001：SQL 拼接用户值
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：lint。
+
+lint 发现 SQL 字符串拼接或插值存在注入风险。
+
+## 修复步骤
+
+1. query.sql 使用 :name 命名参数；受支持的 Kysely 构建器绑定值。不要用替换引号等手工转义替代参数化。
+
+## 正例
+
+```text
+sql: 'select id from safe.purchase_order where status = :status'
+```
+
+## 反例
+
+```text
+'select id from safe.purchase_order where status = ' + input.status
+```
+
+## 修复后验证
+
+重跑相关 lint/verify，并用正常及特殊字符输入验证参数语义。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/lint/src/rules/no-sql-concat.ts:19`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    messages: {
+      concat: '[CAGE-SQL-001] 不要拼接 SQL 字符串，改用 sql 标签模板或查询构建器（值会自动参数化）',
+      raw: '[CAGE-SQL-002] sql.raw() 只能接收字面量',
+    },
+    schema: [],
+```

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

@@ -0,0 +1,47 @@
+# CAGE-SQL-002：sql.raw 接收动态表达式
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：lint。
+
+sql.raw 不是固定字面量，可能把输入当作 SQL 结构。
+
+## 修复步骤
+
+1. raw 仅使用固定 SQL 片段，动态值参数化，动态列/排序按声明白名单选择；不把完整用户输入塞到 raw。
+
+## 正例
+
+```text
+sql.raw('count(*)') // 固定片段
+```
+
+## 反例
+
+```text
+sql.raw(input.orderBy)
+```
+
+## 修复后验证
+
+重跑相关 lint/verify，并用正常及特殊字符输入验证参数语义。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/lint/src/rules/no-sql-concat.ts:20`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      concat: '[CAGE-SQL-001] 不要拼接 SQL 字符串，改用 sql 标签模板或查询构建器（值会自动参数化）',
+      raw: '[CAGE-SQL-002] sql.raw() 只能接收字面量',
+    },
+    schema: [],
+  },
+```