@yss123/cage-cli 0.0.0-stage → 0.1.0

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,32 @@
+# CAGE-CONN-011
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/connectors/src/runtime.ts:190](../../packages/connectors/src/runtime.ts)
+
+```ts
+          // 不可重试：标成永久错误，直接进死信
+          throw Object.assign(new Error(`[CAGE-CONN-011] ${e.message}`), { permanent: true });
+        }
+        throw e;
+      }
+      if (ob.onSuccess) {
+```
+
+## 怎么修
+
+核对 host 白名单、操作名、字段 schema 和签名。永久失败应先修正配置再重放死信。
+
+## 正例
+
+```text
+hosts: { test: 'erp-sandbox.example.com', prod: 'erp.example.com' }
+```
+
+## 反例
+
+```text
+// outbound 映射发送了 request schema 之外的字段
+```

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

@@ -0,0 +1,32 @@
+# CAGE-CONN-012
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/rules.ts:157](../../packages/cli/src/rules.ts)
+
+```ts
+      findings.push({
+        code: 'CAGE-CONN-012',
+        at: at(c),
+        reason: `命令 ${c.id} 只接受外部调用，但没有入站回调或出站映射调用它`,
+        fix: '用 inbound(...) 或 outbound(..., { onSuccess }) 调用它',
+        severity: 'warning',
+```
+
+## 怎么修
+
+核对 host 白名单、操作名、字段 schema 和签名。永久失败应先修正配置再重放死信。
+
+## 正例
+
+```text
+hosts: { test: 'erp-sandbox.example.com', prod: 'erp.example.com' }
+```
+
+## 反例
+
+```text
+// outbound 映射发送了 request schema 之外的字段
+```

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

@@ -0,0 +1,32 @@
+# CAGE-CREATE-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/create.ts:8](../../packages/cli/src/create.ts)
+
+```ts
+  const root = resolve(target);
+  if (existsSync(root)) throw new Error('[CAGE-CREATE-001] 目标路径已存在，请选择新目录');
+  const here = dirname(fileURLToPath(import.meta.url));
+  const template = [resolve(here, '../templates/app'), resolve(here, '../../../templates/app')].find(
+    existsSync,
+  );
+```
+
+## 怎么修
+
+选择尚不存在的目标目录，并确认 CLI 安装包包含 templates/app。
+
+## 正例
+
+```text
+cage create new-app
+```
+
+## 反例
+
+```text
+cage create existing-project // 拒绝覆盖已有项目
+```

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

@@ -0,0 +1,34 @@
+# CAGE-DECL-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/static-check.ts:188](../../packages/cli/src/static-check.ts)
+
+```ts
+            findings.push({
+              code: 'CAGE-DECL-001',
+              at: loc(node),
+              reason: `原语 ${name}() 写在函数、条件或循环里，抽取器看不到它`,
+              fix: '原语必须在模块顶层用 export const 声明',
+            });
+```
+
+## 怎么修
+
+将声明放在模块顶层，用唯一的 export const 名称声明，并从 domain/index.ts 导出。
+
+## 正例
+
+```text
+export const Order = aggregate('Order', definition);
+// index.ts
+export * from './order.js';
+```
+
+## 反例
+
+```text
+function build() { return aggregate('Order', definition); }
+```

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

@@ -0,0 +1,34 @@
+# CAGE-DECL-002
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/static-check.ts:254](../../packages/cli/src/static-check.ts)
+
+```ts
+    .map((s) => ({
+      code: 'CAGE-DECL-002',
+      at: `${s.file}:${s.line}`,
+      reason: `声明 ${s.exportName} 没有从 domain 入口导出，内核和抽取器都看不到它`,
+      fix: `在 domain 的 index.ts 里加上 export * from './${s.file
+        .split('/')
+```
+
+## 怎么修
+
+将声明放在模块顶层，用唯一的 export const 名称声明，并从 domain/index.ts 导出。
+
+## 正例
+
+```text
+export const Order = aggregate('Order', definition);
+// index.ts
+export * from './order.js';
+```
+
+## 反例
+
+```text
+function build() { return aggregate('Order', definition); }
+```

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

@@ -0,0 +1,34 @@
+# CAGE-DECL-003
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/static-check.ts:207](../../packages/cli/src/static-check.ts)
+
+```ts
+                findings.push({
+                  code: 'CAGE-DECL-003',
+                  at: loc(node),
+                  reason: `声明 ${topDecl.name.getText()} 没有用 export const 导出`,
+                  fix: '加上 export const，并确认它从 domain 的 index.ts 导出',
+                });
+```
+
+## 怎么修
+
+将声明放在模块顶层，用唯一的 export const 名称声明，并从 domain/index.ts 导出。
+
+## 正例
+
+```text
+export const Order = aggregate('Order', definition);
+// index.ts
+export * from './order.js';
+```
+
+## 反例
+
+```text
+function build() { return aggregate('Order', definition); }
+```

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

@@ -0,0 +1,34 @@
+# CAGE-DECL-004
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/static-check.ts:239](../../packages/cli/src/static-check.ts)
+
+```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: "原名" }) 保持能力点不变',
+      });
+```
+
+## 怎么修
+
+将声明放在模块顶层，用唯一的 export const 名称声明，并从 domain/index.ts 导出。
+
+## 正例
+
+```text
+export const Order = aggregate('Order', definition);
+// index.ts
+export * from './order.js';
+```
+
+## 反例
+
+```text
+function build() { return aggregate('Order', definition); }
+```

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

@@ -0,0 +1,34 @@
+# CAGE-DEP-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/static-check.ts:144](../../packages/cli/src/static-check.ts)
+
+```ts
+          findings.push({
+            code: 'CAGE-DEP-001',
+            at: loc(node),
+            reason: `声明文件导入了 IO 模块 ${spec}`,
+            fix: '需要外部数据就声明 reads；需要通知外部系统就发事件，由连接器的出站映射处理',
+          });
+```
+
+## 怎么修
+
+移除业务层的 IO 或越层依赖。读取放进 reads，外部调用放进 outbound，前端依赖 contracts。
+
+## 正例
+
+```text
+reads: { stock: Inventory }
+// handler 中
+await deps.stock.get(id);
+```
+
+## 反例
+
+```text
+import pg from 'pg'; // domain 中禁止直接访问数据库
+```

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

@@ -0,0 +1,34 @@
+# CAGE-DEP-002
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/lint/dependency-cruiser.cjs:17](../../packages/lint/dependency-cruiser.cjs)
+
+```ts
+      severity: 'error',
+      comment: '[CAGE-DEP-002] 适配器必须通过命令网关写数据',
+      from: { path: '^packages/adapters' },
+      to: { path: 'node_modules/(pg|kysely)/' },
+    },
+    {
+```
+
+## 怎么修
+
+移除业务层的 IO 或越层依赖。读取放进 reads，外部调用放进 outbound，前端依赖 contracts。
+
+## 正例
+
+```text
+reads: { stock: Inventory }
+// handler 中
+await deps.stock.get(id);
+```
+
+## 反例
+
+```text
+import pg from 'pg'; // domain 中禁止直接访问数据库
+```

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

@@ -0,0 +1,34 @@
+# CAGE-DEP-003
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/lint/dependency-cruiser.cjs:24](../../packages/lint/dependency-cruiser.cjs)
+
+```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)/' },
+    },
+    {
+```
+
+## 怎么修
+
+移除业务层的 IO 或越层依赖。读取放进 reads，外部调用放进 outbound，前端依赖 contracts。
+
+## 正例
+
+```text
+reads: { stock: Inventory }
+// handler 中
+await deps.stock.get(id);
+```
+
+## 反例
+
+```text
+import pg from 'pg'; // domain 中禁止直接访问数据库
+```

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

@@ -0,0 +1,34 @@
+# CAGE-DEP-004
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/static-check.ts:155](../../packages/cli/src/static-check.ts)
+
+```ts
+          findings.push({
+            code: 'CAGE-DEP-004',
+            at: loc(node),
+            reason: name === 'fetch' ? 'handler 里直接发网络请求' : '声明文件里使用了动态 import',
+            fix: '第三方调用改为连接器声明 + outbound 出站映射',
+          });
+```
+
+## 怎么修
+
+移除业务层的 IO 或越层依赖。读取放进 reads，外部调用放进 outbound，前端依赖 contracts。
+
+## 正例
+
+```text
+reads: { stock: Inventory }
+// handler 中
+await deps.stock.get(id);
+```
+
+## 反例
+
+```text
+import pg from 'pg'; // domain 中禁止直接访问数据库
+```

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

@@ -0,0 +1,34 @@
+# CAGE-DEP-005
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/lint/dependency-cruiser.cjs:31](../../packages/lint/dependency-cruiser.cjs)
+
+```ts
+      severity: 'error',
+      comment: '[CAGE-DEP-005] domain 不能依赖生成物',
+      from: { path: '^packages/domain' },
+      to: { path: '^(generated|packages/contracts)/' },
+    },
+  ],
+```
+
+## 怎么修
+
+移除业务层的 IO 或越层依赖。读取放进 reads，外部调用放进 outbound，前端依赖 contracts。
+
+## 正例
+
+```text
+reads: { stock: Inventory }
+// handler 中
+await deps.stock.get(id);
+```
+
+## 反例
+
+```text
+import pg from 'pg'; // domain 中禁止直接访问数据库
+```

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

@@ -0,0 +1,32 @@
+# CAGE-DLQ-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/worker/outbox.ts:128](../../packages/kernel/src/worker/outbox.ts)
+
+```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);
+  });
+```
+
+## 怎么修
+
+检查死信详情和事件顺序，修复原因后用管理接口重放或丢弃，不直接改业务表。
+
+## 正例
+
+```text
+在 /admin 的死信列表检查错误并重放
+```
+
+## 反例
+
+```text
+直接更新 sys.outbox 绕过死信处理流程
+```

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

@@ -0,0 +1,32 @@
+# CAGE-ENV-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/migrate.ts:51](../../packages/cli/src/migrate.ts)
+
+```ts
+  const urls = urlsFromEnv(env);
+  if (!urls.migrate) throw new Error('[CAGE-ENV-001] 设置 CAGE_MIGRATE_DATABASE_URL');
+  if (init) {
+    if (!env.CAGE_SUPER_DATABASE_URL) throw new Error('[CAGE-ENV-001] 初始化需要 CAGE_SUPER_DATABASE_URL');
+    const password = (url: string) => {
+      const pw = decodeURIComponent(new URL(url).password);
+```
+
+## 怎么修
+
+在运行环境设置 app/read/migrate 三种连接串，检查连接账号与库名。不要把凭证写进源码。
+
+## 正例
+
+```text
+CAGE_APP_DATABASE_URL / CAGE_READ_DATABASE_URL / CAGE_MIGRATE_DATABASE_URL
+```
+
+## 反例
+
+```text
+// 未配置数据库连接就启动 API
+```

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

@@ -0,0 +1,32 @@
+# CAGE-EVENT-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/kernel.ts:365](../../packages/kernel/src/kernel.ts)
+
+```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
+        .insertInto('sys.outbox')
+```
+
+## 怎么修
+
+保留旧事件字段及类型，新加字段设为 optional；不兼容含义使用新事件名。
+
+## 正例
+
+```text
+event("OrderChanged", { orderId: id(), note: text().optional() })
+```
+
+## 反例
+
+```text
+// 给已有事件新增必填 note，旧 outbox 消息无法提供它
+```

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

@@ -0,0 +1,32 @@
+# CAGE-EVENT-002
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/rules.ts:225](../../packages/cli/src/rules.ts)
+
+```ts
+
+/** CAGE-EVENT-002：事件载荷只允许向后兼容的变更（只能新增可选字段） */
+export function checkEventCompat(base: Ontology, head: Ontology): Finding[] {
+  const findings: Finding[] = [];
+  const b = new Map(base.nodes.filter((n) => n.kind === 'event').map((n) => [n.id, n]));
+  for (const ev of head.nodes.filter((n) => n.kind === 'event')) {
+```
+
+## 怎么修
+
+保留旧事件字段及类型，新加字段设为 optional；不兼容含义使用新事件名。
+
+## 正例
+
+```text
+event("OrderChanged", { orderId: id(), note: text().optional() })
+```
+
+## 反例
+
+```text
+// 给已有事件新增必填 note，旧 outbox 消息无法提供它
+```