@yss123/cage-cli 0.0.0-stage → 0.1.0

package/managed/errors/CAGE-APPR-001.md

@@ -0,0 +1,32 @@
+# CAGE-APPR-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/flow.ts:134](../../packages/kernel/src/primitives/flow.ts)
+
+```ts
+  for (const f of def.routable) {
+    if (!(f in agg.fields)) throw declError('CAGE-APPR-001', `可路由字段 ${agg.name}.${f} 不存在`);
+  }
+  for (const c of [def.onApproved, def.onRejected]) {
+    if (c.agg !== agg) throw declError('CAGE-APPR-002', `审批结论命令必须属于 ${agg.name}`);
+    if (!c.invokedBy.includes('process')) {
+```
+
+## 怎么修
+
+核对流程绑定、可路由字段、结论命令及审批人配置。结论只能调用所属聚合的 process 命令。
+
+## 正例
+
+```text
+onApproved: approve // approve 声明 invokedBy: 'process'
+```
+
+## 反例
+
+```text
+onApproved: otherAggregateCommand // 结论落到了错误聚合
+```

package/managed/errors/CAGE-APPR-002.md

@@ -0,0 +1,32 @@
+# CAGE-APPR-002
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/flow.ts:137](../../packages/kernel/src/primitives/flow.ts)
+
+```ts
+  for (const c of [def.onApproved, def.onRejected]) {
+    if (c.agg !== agg) throw declError('CAGE-APPR-002', `审批结论命令必须属于 ${agg.name}`);
+    if (!c.invokedBy.includes('process')) {
+      throw declError('CAGE-APPR-003', `审批结论命令必须声明 invokedBy: 'process'`);
+    }
+  }
+```
+
+## 怎么修
+
+核对流程绑定、可路由字段、结论命令及审批人配置。结论只能调用所属聚合的 process 命令。
+
+## 正例
+
+```text
+onApproved: approve // approve 声明 invokedBy: 'process'
+```
+
+## 反例
+
+```text
+onApproved: otherAggregateCommand // 结论落到了错误聚合
+```

package/managed/errors/CAGE-APPR-003.md

@@ -0,0 +1,32 @@
+# CAGE-APPR-003
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/flow.ts:139](../../packages/kernel/src/primitives/flow.ts)
+
+```ts
+    if (!c.invokedBy.includes('process')) {
+      throw declError('CAGE-APPR-003', `审批结论命令必须声明 invokedBy: 'process'`);
+    }
+  }
+  return Object.freeze({
+    [APPROVAL]: true as const,
+```
+
+## 怎么修
+
+核对流程绑定、可路由字段、结论命令及审批人配置。结论只能调用所属聚合的 process 命令。
+
+## 正例
+
+```text
+onApproved: approve // approve 声明 invokedBy: 'process'
+```
+
+## 反例
+
+```text
+onApproved: otherAggregateCommand // 结论落到了错误聚合
+```

package/managed/errors/CAGE-APPR-004.md

@@ -0,0 +1,32 @@
+# CAGE-APPR-004
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/approval/src/bridge.ts:8](../../packages/approval/src/bridge.ts)
+
+```ts
+  const binding = k.registry.approvalByProcess(r.process);
+  if (!binding) throw new Error(`[CAGE-APPR-004] 没有流程 ${r.process} 的审批绑定`);
+  const cmd = r.outcome === 'approved' ? binding.a.onApproved : binding.a.onRejected;
+  const ctx = k.processCtx({
+    process: r.process,
+    tenantId: r.tenantId,
+```
+
+## 怎么修
+
+核对流程绑定、可路由字段、结论命令及审批人配置。结论只能调用所属聚合的 process 命令。
+
+## 正例
+
+```text
+onApproved: approve // approve 声明 invokedBy: 'process'
+```
+
+## 反例
+
+```text
+onApproved: otherAggregateCommand // 结论落到了错误聚合
+```

package/managed/errors/CAGE-APPR-005.md

@@ -0,0 +1,32 @@
+# CAGE-APPR-005
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/approval/src/route.ts:96](../../packages/approval/src/route.ts)
+
+```ts
+export function route(process: string, nodes: RouteNode[]): Route {
+  if (!/^[a-z][a-z0-9-]*$/.test(process)) throw declError('CAGE-APPR-005', `流程名 ${process} 必须是小写短横线`);
+  if (nodes.length === 0) throw declError('CAGE-APPR-006', `流程 ${process} 至少需要一个步骤`);
+  const fields = new Set<string>();
+  for (const n of nodes) {
+    const steps = n.kind === 'step' ? [n] : n.steps;
+```
+
+## 怎么修
+
+核对流程绑定、可路由字段、结论命令及审批人配置。结论只能调用所属聚合的 process 命令。
+
+## 正例
+
+```text
+onApproved: approve // approve 声明 invokedBy: 'process'
+```
+
+## 反例
+
+```text
+onApproved: otherAggregateCommand // 结论落到了错误聚合
+```

package/managed/errors/CAGE-APPR-006.md

@@ -0,0 +1,32 @@
+# CAGE-APPR-006
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/approval/src/route.ts:97](../../packages/approval/src/route.ts)
+
+```ts
+  if (!/^[a-z][a-z0-9-]*$/.test(process)) throw declError('CAGE-APPR-005', `流程名 ${process} 必须是小写短横线`);
+  if (nodes.length === 0) throw declError('CAGE-APPR-006', `流程 ${process} 至少需要一个步骤`);
+  const fields = new Set<string>();
+  for (const n of nodes) {
+    const steps = n.kind === 'step' ? [n] : n.steps;
+    if (n.kind === 'when') fields.add(n.cond.field);
+```
+
+## 怎么修
+
+核对流程绑定、可路由字段、结论命令及审批人配置。结论只能调用所属聚合的 process 命令。
+
+## 正例
+
+```text
+onApproved: approve // approve 声明 invokedBy: 'process'
+```
+
+## 反例
+
+```text
+onApproved: otherAggregateCommand // 结论落到了错误聚合
+```

package/managed/errors/CAGE-APPR-007.md

@@ -0,0 +1,32 @@
+# CAGE-APPR-007
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/approval/src/engine.ts:64](../../packages/approval/src/engine.ts)
+
+```ts
+    if (who.length === 0) {
+      throw new Error(`[CAGE-APPR-007] 流程 ${this.route.process} 第 ${index + 1} 步「${s.title}」找不到审批人，请在 /admin 配置部门负责人或角色`);
+    }
+    for (const assignee of new Set(who)) {
+      await tx.insertInto('flow.approval_task').values({ instance_id: instanceId, tenant_id: tenantId, step: index, title: s.title, assignee }).execute();
+    }
+```
+
+## 怎么修
+
+核对流程绑定、可路由字段、结论命令及审批人配置。结论只能调用所属聚合的 process 命令。
+
+## 正例
+
+```text
+onApproved: approve // approve 声明 invokedBy: 'process'
+```
+
+## 反例
+
+```text
+onApproved: otherAggregateCommand // 结论落到了错误聚合
+```

package/managed/errors/CAGE-APPR-010.md

@@ -0,0 +1,32 @@
+# CAGE-APPR-010
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/rules.ts:140](../../packages/cli/src/rules.ts)
+
+```ts
+
+/** CAGE-APPR-010：invokedBy 为 process 的命令必须有审批绑定或反应调用它，否则没有人能调用 */
+export function checkProcessCommands(g: Ontology): Finding[] {
+  const { into } = index(g);
+  const findings: Finding[] = [];
+  for (const c of g.nodes.filter((n) => n.kind === 'command')) {
+```
+
+## 怎么修
+
+核对流程绑定、可路由字段、结论命令及审批人配置。结论只能调用所属聚合的 process 命令。
+
+## 正例
+
+```text
+onApproved: approve // approve 声明 invokedBy: 'process'
+```
+
+## 反例
+
+```text
+onApproved: otherAggregateCommand // 结论落到了错误聚合
+```

package/managed/errors/CAGE-AUTH-001.md

@@ -0,0 +1,32 @@
+# CAGE-AUTH-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/http/src/oidc.ts:20](../../packages/http/src/oidc.ts)
+
+```ts
+    (disco ??= fetch(new URL('.well-known/openid-configuration', o.issuer.endsWith('/') ? o.issuer : `${o.issuer}/`)).then(async (r) => {
+      if (!r.ok) throw new Error(`[CAGE-AUTH-001] OIDC 发现文档获取失败：${r.status}`);
+      return (await r.json()) as Discovery;
+    }));
+  const secure = opts.cookieSecure ?? process.env.NODE_ENV === 'production';
+
+```
+
+## 怎么修
+
+核对 OIDC 发现文档、issuer 和客户端配置，在部署环境配置所需变量。
+
+## 正例
+
+```text
+OIDC_ISSUER + OIDC_CLIENT_ID + OIDC_REDIRECT_URI
+```
+
+## 反例
+
+```text
+// issuer 不匹配或缺少客户端配置
+```

package/managed/errors/CAGE-BUDGET-001.md

@@ -0,0 +1,32 @@
+# CAGE-BUDGET-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/budget.ts:45](../../packages/cli/src/budget.ts)
+
+```ts
+    findings.push({
+      code: 'CAGE-BUDGET-001',
+      reason: `内核 ${lines} 行，超过 5000 行预算`,
+      fix: '拆出扩展职责，或提交架构评审调整预算',
+    });
+  if (primitives !== null && primitives > 16)
+```
+
+## 怎么修
+
+减少内核职责，移除不必要的 unsafe；预算调整及基线更新必须经过评审。
+
+## 正例
+
+```text
+node packages/cli/bin/cage.js budget
+```
+
+## 反例
+
+```text
+// 未评审就增加公共原语或 unsafe 数量
+```

package/managed/errors/CAGE-BUDGET-002.md

@@ -0,0 +1,32 @@
+# CAGE-BUDGET-002
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/budget.ts:51](../../packages/cli/src/budget.ts)
+
+```ts
+    findings.push({
+      code: 'CAGE-BUDGET-002',
+      reason: `品牌原语 ${primitives} 个，超过 16 个预算`,
+      fix: '优先使用组合子，避免新增原语',
+    });
+  const allowance = base?.unsafeCount ?? 0;
+```
+
+## 怎么修
+
+减少内核职责，移除不必要的 unsafe；预算调整及基线更新必须经过评审。
+
+## 正例
+
+```text
+node packages/cli/bin/cage.js budget
+```
+
+## 反例
+
+```text
+// 未评审就增加公共原语或 unsafe 数量
+```

package/managed/errors/CAGE-BUDGET-003.md

@@ -0,0 +1,32 @@
+# CAGE-BUDGET-003
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/budget.ts:58](../../packages/cli/src/budget.ts)
+
+```ts
+    findings.push({
+      code: 'CAGE-BUDGET-003',
+      reason: `unsafe 从 ${allowance} 增加到 ${graph.unsafeCount}`,
+      fix: '移除新增逃生口，或在评审完成后更新受审基线',
+    });
+  return { metrics: { kernelLines: lines, primitives, unsafe: graph.unsafeCount }, findings };
+```
+
+## 怎么修
+
+减少内核职责，移除不必要的 unsafe；预算调整及基线更新必须经过评审。
+
+## 正例
+
+```text
+node packages/cli/bin/cage.js budget
+```
+
+## 反例
+
+```text
+// 未评审就增加公共原语或 unsafe 数量
+```

package/managed/errors/CAGE-CMD-002.md

@@ -0,0 +1,32 @@
+# CAGE-CMD-002
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/command.ts:142](../../packages/kernel/src/primitives/command.ts)
+
+```ts
+  if (from !== 'new' && input instanceof z.ZodObject && !('id' in input.shape)) {
+    throw declError('CAGE-CMD-002', `${agg.name} 的非新建命令输入必须包含 id`);
+  }
+  if (def.name !== undefined && !/^[a-z][A-Za-z0-9]*$/.test(def.name)) {
+    throw declError('CAGE-NAME-004', `命令名 ${def.name} 必须是小驼峰`);
+  }
+```
+
+## 怎么修
+
+非新建命令的输入必须含 id；from/to、调用身份和聚合定义保持一致。
+
+## 正例
+
+```text
+input: z.object({ id: z.string().uuid(), note: z.string() })
+```
+
+## 反例
+
+```text
+input: z.object({ note: z.string() }) // 非新建命令缺少 id
+```

package/managed/errors/CAGE-CMD-003.md

@@ -0,0 +1,34 @@
+# CAGE-CMD-003
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/command.ts:135](../../packages/kernel/src/primitives/command.ts)
+
+```ts
+  if (from === 'new' && def.to === null) {
+    throw declError('CAGE-CMD-003', `${agg.name} 的新建命令必须指定目标状态，不能使用 to: null`);
+  }
+  if (def.to !== null && !hasStates(agg, def.to as string)) {
+    throw declError('CAGE-STATE-001', `${agg.name} 的命令 to 是未声明的状态：${String(def.to)}`);
+  }
+```
+
+## 怎么修
+
+新建命令必须指定聚合中声明的目标状态。to: null 仅用于已有记录的字段更新；它保留加锁读出的状态，不跳过 from、权限、版本及审计检查。
+
+## 正例
+
+```text
+command(Order, { from: 'new', to: 'draft', handler: o => o });
+// 晚到回执可以保留终态
+command(Order, { from: ['approved', 'cancelled'], to: null, handler: o => o });
+```
+
+## 反例
+
+```text
+command(Order, { from: 'new', to: null, handler: o => o }); // 新记录没有可保留的状态
+```

package/managed/errors/CAGE-CONN-001.md

@@ -0,0 +1,32 @@
+# CAGE-CONN-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/connectors/src/primitives.ts:56](../../packages/connectors/src/primitives.ts)
+
+```ts
+export function connector<Ops extends Record<string, OpDef<any, any>>>(name: string, def: ConnectorDef<Ops>): Connector<Ops> {
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) throw declError('CAGE-CONN-001', `连接器名 ${name} 必须是小写短横线`);
+  for (const h of Object.values(def.hosts)) {
+    if (h && /[/:\s]/.test(h.replace(/:\d+$/, ''))) throw declError('CAGE-CONN-003', `地址白名单只能写主机名（可带端口）：${h}`);
+  }
+  const c: any = {
+```
+
+## 怎么修
+
+核对 host 白名单、操作名、字段 schema 和签名。永久失败应先修正配置再重放死信。
+
+## 正例
+
+```text
+hosts: { test: 'erp-sandbox.example.com', prod: 'erp.example.com' }
+```
+
+## 反例
+
+```text
+// outbound 映射发送了 request schema 之外的字段
+```

package/managed/errors/CAGE-CONN-002.md

@@ -0,0 +1,32 @@
+# CAGE-CONN-002
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/connectors/src/primitives.ts:29](../../packages/connectors/src/primitives.ts)
+
+```ts
+export function op<Req extends z.ZodObject<any>, Res extends z.ZodType>(def: OpDef<Req, Res>): OpDef<Req, Res> {
+  if (!def.path.startsWith('/')) throw declError('CAGE-CONN-002', `操作路径 ${def.path} 必须以 / 开头`);
+  return def;
+}
+
+export interface ConnectorDef<Ops extends Record<string, OpDef<any, any>>> {
+```
+
+## 怎么修
+
+核对 host 白名单、操作名、字段 schema 和签名。永久失败应先修正配置再重放死信。
+
+## 正例
+
+```text
+hosts: { test: 'erp-sandbox.example.com', prod: 'erp.example.com' }
+```
+
+## 反例
+
+```text
+// outbound 映射发送了 request schema 之外的字段
+```

package/managed/errors/CAGE-CONN-003.md

@@ -0,0 +1,32 @@
+# CAGE-CONN-003
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/connectors/src/primitives.ts:58](../../packages/connectors/src/primitives.ts)
+
+```ts
+  for (const h of Object.values(def.hosts)) {
+    if (h && /[/:\s]/.test(h.replace(/:\d+$/, ''))) throw declError('CAGE-CONN-003', `地址白名单只能写主机名（可带端口）：${h}`);
+  }
+  const c: any = {
+    [CONNECTOR]: true,
+    name,
+```
+
+## 怎么修
+
+核对 host 白名单、操作名、字段 schema 和签名。永久失败应先修正配置再重放死信。
+
+## 正例
+
+```text
+hosts: { test: 'erp-sandbox.example.com', prod: 'erp.example.com' }
+```
+
+## 反例
+
+```text
+// outbound 映射发送了 request schema 之外的字段
+```

package/managed/errors/CAGE-CONN-004.md

@@ -0,0 +1,32 @@
+# CAGE-CONN-004
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/connectors/src/primitives.ts:99](../../packages/connectors/src/primitives.ts)
+
+```ts
+): Outbound<E, O> {
+  if (operation.effect === 'read') throw declError('CAGE-CONN-004', '只读操作不能用于出站映射');
+  const o: any = {
+    [OUTBOUND]: true,
+    event: ev,
+    op: operation,
+```
+
+## 怎么修
+
+核对 host 白名单、操作名、字段 schema 和签名。永久失败应先修正配置再重放死信。
+
+## 正例
+
+```text
+hosts: { test: 'erp-sandbox.example.com', prod: 'erp.example.com' }
+```
+
+## 反例
+
+```text
+// outbound 映射发送了 request schema 之外的字段
+```

package/managed/errors/CAGE-CONN-005.md

@@ -0,0 +1,32 @@
+# CAGE-CONN-005
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/connectors/src/primitives.ts:153](../../packages/connectors/src/primitives.ts)
+
+```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'`);
+  }
+  return Object.freeze({ [INBOUND]: true as const, connector: conn, event: eventName, ...def });
+```
+
+## 怎么修
+
+核对 host 白名单、操作名、字段 schema 和签名。永久失败应先修正配置再重放死信。
+
+## 正例
+
+```text
+hosts: { test: 'erp-sandbox.example.com', prod: 'erp.example.com' }
+```
+
+## 反例
+
+```text
+// outbound 映射发送了 request schema 之外的字段
+```

package/managed/errors/CAGE-CONN-006.md

@@ -0,0 +1,32 @@
+# CAGE-CONN-006
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/connectors/src/primitives.ts:155](../../packages/connectors/src/primitives.ts)
+
+```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 });
+}
+
+```
+
+## 怎么修
+
+核对 host 白名单、操作名、字段 schema 和签名。永久失败应先修正配置再重放死信。
+
+## 正例
+
+```text
+hosts: { test: 'erp-sandbox.example.com', prod: 'erp.example.com' }
+```
+
+## 反例
+
+```text
+// outbound 映射发送了 request schema 之外的字段
+```