@yss123/cage-cli 0.1.0 → 0.2.0

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

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

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

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

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

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

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

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

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

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

@@ -1,32 +0,0 @@
-# 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 消息无法提供它
-```

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

@@ -1,32 +0,0 @@
-# CAGE-FIELD-001
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/fields.ts:92](../../packages/kernel/src/primitives/fields.ts)
-
-```ts
-  sensitive(kind: SensitiveKind): Field<T, Opt> {
-    if (!SENSITIVE_KINDS.includes(kind)) throw declError('CAGE-FIELD-001', `未知的敏感种类 ${kind}`);
-    return this.with({ sensitiveKind: kind });
-  }
-  /** 唯一约束（租户内） */
-  unique(): Field<T, Opt> {
-```
-
-## 怎么修
-
-使用 field 工厂声明字段，避免覆盖 id/status/version 等系统列，引用指向存在的聚合。
-
-## 正例
-
-```text
-fields: { deptId: ref('Dept'), amount: money() }
-```
-
-## 反例
-
-```text
-fields: { version: text() } // 系统版本号不能改作业务字段
-```

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

@@ -1,32 +0,0 @@
-# CAGE-FIELD-002
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/fields.ts:149](../../packages/kernel/src/primitives/fields.ts)
-
-```ts
-  const target = typeof to === 'string' ? to : to?.name;
-  if (!target) throw declError('CAGE-FIELD-002', 'ref() 的目标为空，可能是循环导入；可改为 ref("聚合名")');
-  return mk(z.string().uuid(), { kind: 'ref', sql: 'uuid', ref: target });
-}
-
-type ShapeZod<S extends Fields> = {
-```
-
-## 怎么修
-
-使用 field 工厂声明字段，避免覆盖 id/status/version 等系统列，引用指向存在的聚合。
-
-## 正例
-
-```text
-fields: { deptId: ref('Dept'), amount: money() }
-```
-
-## 反例
-
-```text
-fields: { version: text() } // 系统版本号不能改作业务字段
-```

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

@@ -1,32 +0,0 @@
-# CAGE-FIELD-003
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/aggregate.ts:83](../../packages/kernel/src/primitives/aggregate.ts)
-
-```ts
-    }
-    if (!isField(v)) throw declError('CAGE-FIELD-003', `${name}.${k} 不是字段原语`);
-    if ((RESERVED_FIELDS as readonly string[]).includes(k)) {
-      throw declError('CAGE-FIELD-004', `${name}.${k} 是保留字段名，由内核维护`);
-    }
-    if (!/^[a-z][A-Za-z0-9]*$/.test(k)) throw declError('CAGE-NAME-002', `字段名 ${name}.${k} 必须是小驼峰`);
-```
-
-## 怎么修
-
-使用 field 工厂声明字段，避免覆盖 id/status/version 等系统列，引用指向存在的聚合。
-
-## 正例
-
-```text
-fields: { deptId: ref('Dept'), amount: money() }
-```
-
-## 反例
-
-```text
-fields: { version: text() } // 系统版本号不能改作业务字段
-```

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

@@ -1,32 +0,0 @@
-# CAGE-FIELD-004
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/aggregate.ts:85](../../packages/kernel/src/primitives/aggregate.ts)
-
-```ts
-    if ((RESERVED_FIELDS as readonly string[]).includes(k)) {
-      throw declError('CAGE-FIELD-004', `${name}.${k} 是保留字段名，由内核维护`);
-    }
-    if (!/^[a-z][A-Za-z0-9]*$/.test(k)) throw declError('CAGE-NAME-002', `字段名 ${name}.${k} 必须是小驼峰`);
-    fields[k] = v;
-  }
-```
-
-## 怎么修
-
-使用 field 工厂声明字段，避免覆盖 id/status/version 等系统列，引用指向存在的聚合。
-
-## 正例
-
-```text
-fields: { deptId: ref('Dept'), amount: money() }
-```
-
-## 反例
-
-```text
-fields: { version: text() } // 系统版本号不能改作业务字段
-```

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

@@ -1,33 +0,0 @@
-# CAGE-GEN-001
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/cli/src/gen/index.ts:48](../../packages/cli/src/gen/index.ts)
-
-```ts
-  findings: Finding[],
-  code = 'CAGE-GEN-001',
-) {
-  const cur = existsSync(path) ? readFileSync(path, 'utf8') : null;
-  if (cur === content) return;
-  if (check) {
-```
-
-## 怎么修
-
-运行 cage gen，检查生成契约与迁移草稿后提交；不要手改生成文件。
-
-## 正例
-
-```text
-pnpm cage gen
-pnpm cage gen --check
-```
-
-## 反例
-
-```text
-// 修改了 domain，但提交旧 contracts
-```

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

@@ -1,33 +0,0 @@
-# CAGE-GEN-002
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/cli/src/gen/index.ts:122](../../packages/cli/src/gen/index.ts)
-
-```ts
-      findings.push({
-        code: 'CAGE-GEN-002',
-        at: cfg.migrations,
-        reason: `声明的表结构与迁移不一致（${stmts.length} 处变化）`,
-        fix: '运行 cage gen 生成迁移草稿，人审后提交',
-      });
-```
-
-## 怎么修
-
-运行 cage gen，检查生成契约与迁移草稿后提交；不要手改生成文件。
-
-## 正例
-
-```text
-pnpm cage gen
-pnpm cage gen --check
-```
-
-## 反例
-
-```text
-// 修改了 domain，但提交旧 contracts
-```

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

@@ -1,32 +0,0 @@
-# CAGE-GRANT-001
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/admin/src/domain/constraints.ts:21](../../packages/admin/src/domain/constraints.ts)
-
-```ts
-    const mine = ctx.capabilities.get(input.capability);
-    if (!mine) return violation('[CAGE-GRANT-001] 不能授出自己没有的能力点');
-    for (const [k, v] of Object.entries(input.params ?? {})) {
-      if (typeof v === 'number' && typeof mine[k] === 'number' && v > (mine[k] as number)) {
-        return violation(`[CAGE-GRANT-001] 参数 ${k}=${v} 超过了你自己的 ${mine[k]}`);
-      }
-```
-
-## 怎么修
-
-先声明能力点，再由具有该能力和范围的管理员分配，不能通过界面发明能力。
-
-## 正例
-
-```text
-capability: 'PurchaseOrder.read'
-```
-
-## 反例
-
-```text
-capability: 'PurchaseOrder.nonexistent'
-```

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

@@ -1,32 +0,0 @@
-# CAGE-GRANT-002
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/admin/src/domain/constraints.ts:37](../../packages/admin/src/domain/constraints.ts)
-
-```ts
-    const want = COMBINATOR_WIDTH[input.combinator as Combinator] ?? 99;
-    return want <= ownWidth(ctx, input.aggregate) ? ok() : violation('[CAGE-GRANT-002] 不能授出比自己更宽的数据范围');
-  },
-});
-
-/** 分配角色也是授权：被分配角色里的每个能力点和范围，操作人自己都必须有 */
-```
-
-## 怎么修
-
-先声明能力点，再由具有该能力和范围的管理员分配，不能通过界面发明能力。
-
-## 正例
-
-```text
-capability: 'PurchaseOrder.read'
-```
-
-## 反例
-
-```text
-capability: 'PurchaseOrder.nonexistent'
-```

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

@@ -1,32 +0,0 @@
-# CAGE-GRANT-003
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/admin/src/domain/constraints.ts:13](../../packages/admin/src/domain/constraints.ts)
-
-```ts
-  check: (_role, _ctx, input, meta) =>
-    meta.catalog().includes(input.capability) ? ok() : violation(`[CAGE-GRANT-003] 能力点 ${input.capability} 不在能力目录里`),
-});
-
-/** 防提权：不能授出自己没有的能力点；数值参数（额度）不能超过自己的 */
-export const noEscalation = (): Constraint => ({
-```
-
-## 怎么修
-
-先声明能力点，再由具有该能力和范围的管理员分配，不能通过界面发明能力。
-
-## 正例
-
-```text
-capability: 'PurchaseOrder.read'
-```
-
-## 反例
-
-```text
-capability: 'PurchaseOrder.nonexistent'
-```

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

@@ -1,32 +0,0 @@
-# CAGE-IMPACT-001
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/cli/src/baseline.ts:45](../../packages/cli/src/baseline.ts)
-
-```ts
-    );
-    if (code !== 0) throw new Error('[CAGE-IMPACT-001] 基线抽取失败，请修复基线声明或使用保存的 --base-file');
-    return readOntology(join(project, '.cage/ontology.json'));
-  } finally {
-    // 先断开本次建立的 junction，避免清理工作树时遍历共享依赖目录。
-    for (const link of links) unlinkSync(link);
-```
-
-## 怎么修
-
-指定存在的 Git 提交，或保存过的完整 ontology.json。基线错误不能当作无变化。
-
-## 正例
-
-```text
-cage impact --base-file baseline.json
-```
-
-## 反例
-
-```text
-cage impact // 没有指定基线
-```