@yss123/cage-cli 0.0.0-stage → 0.1.0

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,32 @@
+# 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 // 没有指定基线
+```

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

@@ -0,0 +1,32 @@
+# CAGE-JOB-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/flow.ts:190](../../packages/kernel/src/primitives/flow.ts)
+
+```ts
+  if (!/^[a-z][A-Za-z0-9]*$/.test(name)) throw declError('CAGE-NAME-006', `任务名 ${name} 必须是小驼峰`);
+  if (def.cron.trim().split(/\s+/).length < 5) throw declError('CAGE-JOB-001', `任务 ${name} 的 cron 表达式不合法`);
+  return Object.freeze({
+    [JOB]: true as const,
+    name,
+    cron: def.cron,
+```
+
+## 怎么修
+
+校正 cron、reads 和 calls。任务只能读取和调用显式声明的依赖。
+
+## 正例
+
+```text
+job('expireOrders', { cron: '0 2 * * *', reads: [Order], calls: [cancel], run })
+```
+
+## 反例
+
+```text
+calls: [] // run 却调用 cancel
+```

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

@@ -0,0 +1,32 @@
+# CAGE-JOB-002
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/worker/scheduler.ts:38](../../packages/kernel/src/worker/scheduler.ts)
+
+```ts
+    async call(cmd: AnyCommand, input: unknown) {
+      if (!j.calls.includes(cmd)) throw cageError('FORBIDDEN', { message: `[CAGE-JOB-002] 任务 ${j.name} 调用了未声明的命令` });
+      return (await k.execute(cmd, input, ctx)) as any;
+    },
+  };
+}
+```
+
+## 怎么修
+
+校正 cron、reads 和 calls。任务只能读取和调用显式声明的依赖。
+
+## 正例
+
+```text
+job('expireOrders', { cron: '0 2 * * *', reads: [Order], calls: [cancel], run })
+```
+
+## 反例
+
+```text
+calls: [] // run 却调用 cancel
+```

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

@@ -0,0 +1,32 @@
+# CAGE-JOB-003
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/worker/scheduler.ts:28](../../packages/kernel/src/worker/scheduler.ts)
+
+```ts
+      async list(agg, where = {}, opts = {}) {
+        if (!allowedReads.has(agg)) throw new Error(`[CAGE-JOB-003] 任务 ${j.name} 读取了未声明的聚合 ${agg.name}`);
+        const { createdBefore, createdAfter, updatedBefore, ...eq } = where as Record<string, any>;
+        let q = scopedFind(k.app, agg, ctx, eq, { limit: opts.limit ?? 1000 });
+        if (createdBefore) q = q.where('t.created_at', '<', new Date(createdBefore));
+        if (createdAfter) q = q.where('t.created_at', '>=', new Date(createdAfter));
+```
+
+## 怎么修
+
+校正 cron、reads 和 calls。任务只能读取和调用显式声明的依赖。
+
+## 正例
+
+```text
+job('expireOrders', { cron: '0 2 * * *', reads: [Order], calls: [cancel], run })
+```
+
+## 反例
+
+```text
+calls: [] // run 却调用 cancel
+```

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

@@ -0,0 +1,32 @@
+# CAGE-LINT-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/verify.ts:95](../../packages/cli/src/verify.ts)
+
+```ts
+    f.messages.map((m): Finding => ({
+      code: /\[(CAGE-[\w-]+)\]/.exec(m.message)?.[1] ?? 'CAGE-LINT-001',
+      at: `${f.filePath}:${m.line}`,
+      reason: m.message,
+      severity: m.severity === 1 ? 'warning' : 'error',
+    })),
+```
+
+## 怎么修
+
+根据输出中的 ruleId 修复语法或规则问题，再重跑 verify。
+
+## 正例
+
+```text
+pnpm cage verify
+```
+
+## 反例
+
+```text
+// 用禁用 lint 代替修复业务边界
+```

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

@@ -0,0 +1,32 @@
+# CAGE-MIG-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/db/migrate.ts:84](../../packages/kernel/src/db/migrate.ts)
+
+```ts
+        await client.query('rollback');
+        throw new Error(`[CAGE-MIG-001] 迁移 ${m.name} 失败：${(e as Error).message}`);
+      }
+      applied.push(m.name);
+    }
+    // 安全层每次整体重建
+```
+
+## 怎么修
+
+核对迁移 SQL、账号权限和目标数据库。初始化只用于独立新集群，已发布迁移不可重写。
+
+## 正例
+
+```text
+pnpm cage migrate
+```
+
+## 反例
+
+```text
+// 用 cage_read 执行建表或覆盖已有集群角色密码
+```

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

@@ -0,0 +1,32 @@
+# CAGE-MIG-002
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/db/migrate.ts:96](../../packages/kernel/src/db/migrate.ts)
+
+```ts
+      await client.query('rollback');
+      throw new Error(`[CAGE-MIG-002] 重建安全层失败：${(e as Error).message}`);
+    }
+    log('安全层已重建');
+    return { applied, safeLayerRebuilt: true };
+  } finally {
+```
+
+## 怎么修
+
+核对迁移 SQL、账号权限和目标数据库。初始化只用于独立新集群，已发布迁移不可重写。
+
+## 正例
+
+```text
+pnpm cage migrate
+```
+
+## 反例
+
+```text
+// 用 cage_read 执行建表或覆盖已有集群角色密码
+```

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

@@ -0,0 +1,32 @@
+# CAGE-MIG-003
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/migrate.ts:15](../../packages/cli/src/migrate.ts)
+
+```ts
+  if (!/^[a-z][a-z0-9_]{0,62}$/.test(name))
+    throw new Error('[CAGE-MIG-003] 数据库名只允许小写字母、数字和下划线，以字母开头');
+  const admin = new pg.Client({ connectionString: superUrl });
+  await admin.connect();
+  try {
+    if (!(await admin.query('select 1 from pg_database where datname = $1', [name])).rowCount)
+```
+
+## 怎么修
+
+核对迁移 SQL、账号权限和目标数据库。初始化只用于独立新集群，已发布迁移不可重写。
+
+## 正例
+
+```text
+pnpm cage migrate
+```
+
+## 反例
+
+```text
+// 用 cage_read 执行建表或覆盖已有集群角色密码
+```

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

@@ -0,0 +1,32 @@
+# CAGE-MIG-004
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/migrate.ts:35](../../packages/cli/src/migrate.ts)
+
+```ts
+      throw new Error(
+        '[CAGE-MIG-004] 集群已有 cage 账号，拒绝覆盖密码；请复用已初始化的库或使用独立 PostgreSQL 集群',
+      );
+    }
+    await db.query('begin');
+    await db.query(bootstrapSql(passwords, name));
+```
+
+## 怎么修
+
+核对迁移 SQL、账号权限和目标数据库。初始化只用于独立新集群，已发布迁移不可重写。
+
+## 正例
+
+```text
+pnpm cage migrate
+```
+
+## 反例
+
+```text
+// 用 cage_read 执行建表或覆盖已有集群角色密码
+```

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

@@ -0,0 +1,32 @@
+# CAGE-MIG-005
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/db/migrate.ts:71](../../packages/kernel/src/db/migrate.ts)
+
+```ts
+      if (done.has(migration.name) && done.get(migration.name) !== checksum(migration.sql)) {
+        throw new Error(`[CAGE-MIG-005] 已执行迁移 ${migration.name} 的内容被修改，请恢复原文件并新增迁移`);
+      }
+    }
+    for (const m of all) {
+      if (done.has(m.name)) continue;
+```
+
+## 怎么修
+
+恢复已经执行的迁移文件，不要修改数据库中的校验和来绕过检查。需要变更结构时新增迁移；若仅受换行转换影响，恢复原始文件字节并使用仓库的 LF 约定。
+
+## 正例
+
+```text
+保留 0001_init.sql，新增 0002_add_field.sql，再运行 cage migrate
+```
+
+## 反例
+
+```text
+修改已执行的 0001_init.sql，或手工重写迁移历史的 checksum
+```

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

@@ -0,0 +1,32 @@
+# CAGE-NAME-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/aggregate.ts:72](../../packages/kernel/src/primitives/aggregate.ts)
+
+```ts
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) {
+    throw declError('CAGE-NAME-001', `聚合名 ${name} 必须是大驼峰`);
+  }
+  let st: StatesDef<any> | undefined = def.states;
+  const fields: Record<string, AnyField> = {};
+  for (const [k, v] of Object.entries(def.fields)) {
+```
+
+## 怎么修
+
+聚合、事件使用大驼峰；命令、任务和查询使用小驼峰，且同类名称唯一。
+
+## 正例
+
+```text
+aggregate('PurchaseOrder', definition);
+```
+
+## 反例
+
+```text
+aggregate('purchase-order', definition);
+```