@yss123/cage-cli 0.1.0 → 0.3.0

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

@@ -1,32 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

@@ -1,34 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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 之外的字段
-```

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

@@ -1,32 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

@@ -1,34 +0,0 @@
-# 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

@@ -1,34 +0,0 @@
-# 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

@@ -1,34 +0,0 @@
-# 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); }
-```