@yss123/cage-cli 0.1.0 → 0.3.0

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,32 +0,0 @@
-# CAGE-NAME-003
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/event.ts:19](../../packages/kernel/src/primitives/event.ts)
-
-```ts
-export function event<const N extends string, F extends Fields>(name: N, fields: F, opts?: { description?: string }): Event<N, F> {
-  if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) throw declError('CAGE-NAME-003', `事件名 ${name} 必须是大驼峰`);
-  return Object.freeze({
-    [EVENT]: true as const,
-    name,
-    fields: Object.freeze({ ...fields }),
-```
-
-## 怎么修
-
-聚合、事件使用大驼峰；命令、任务和查询使用小驼峰，且同类名称唯一。
-
-## 正例
-
-```text
-aggregate('PurchaseOrder', definition);
-```
-
-## 反例
-
-```text
-aggregate('purchase-order', definition);
-```

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

@@ -1,32 +0,0 @@
-# CAGE-NAME-004
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/command.ts:145](../../packages/kernel/src/primitives/command.ts)
-
-```ts
-  if (def.name !== undefined && !/^[a-z][A-Za-z0-9]*$/.test(def.name)) {
-    throw declError('CAGE-NAME-004', `命令名 ${def.name} 必须是小驼峰`);
-  }
-  return Object.freeze({
-    [COMMAND]: true as const,
-    agg,
-```
-
-## 怎么修
-
-聚合、事件使用大驼峰；命令、任务和查询使用小驼峰，且同类名称唯一。
-
-## 正例
-
-```text
-aggregate('PurchaseOrder', definition);
-```
-
-## 反例
-
-```text
-aggregate('purchase-order', definition);
-```

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

@@ -1,32 +0,0 @@
-# CAGE-NAME-005
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/flow.ts:88](../../packages/kernel/src/primitives/flow.ts)
-
-```ts
-): Query<I> {
-  if (!/^[a-z][A-Za-z0-9]*$/.test(name)) throw declError('CAGE-NAME-005', `查询名 ${name} 必须是小驼峰`);
-  if (!def.sql === !def.build) throw declError('CAGE-QUERY-001', `查询 ${name} 必须二选一：sql 或 build`);
-  if (def.sql && /\bcore\.|\bsys\./i.test(def.sql)) {
-    throw declError('CAGE-QUERY-002', `查询 ${name} 引用了基表，只能引用 safe.* 安全视图`);
-  }
-```
-
-## 怎么修
-
-聚合、事件使用大驼峰；命令、任务和查询使用小驼峰，且同类名称唯一。
-
-## 正例
-
-```text
-aggregate('PurchaseOrder', definition);
-```
-
-## 反例
-
-```text
-aggregate('purchase-order', definition);
-```

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

@@ -1,32 +0,0 @@
-# CAGE-NAME-006
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/flow.ts:189](../../packages/kernel/src/primitives/flow.ts)
-
-```ts
-): Job {
-  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,
-```
-
-## 怎么修
-
-聚合、事件使用大驼峰；命令、任务和查询使用小驼峰，且同类名称唯一。
-
-## 正例
-
-```text
-aggregate('PurchaseOrder', definition);
-```
-
-## 反例
-
-```text
-aggregate('purchase-order', definition);
-```

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

@@ -1,32 +0,0 @@
-# CAGE-ORG-001
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/cli/src/rules.ts:211](../../packages/cli/src/rules.ts)
-
-```ts
-
-/** CAGE-ORG-001：domain 必须包含框架自带的组织模型 */
-export function checkOrg(g: Ontology): Finding[] {
-  const has = (id: string) => g.nodes.some((n) => n.kind === 'aggregate' && n.id === id);
-  return has('User') && has('Dept') && has('Role')
-    ? []
-```
-
-## 怎么修
-
-从 domain 入口导出框架组织模型。
-
-## 正例
-
-```text
-export * from '@yss123/cage-admin/domain';
-```
-
-## 反例
-
-```text
-// domain 入口只导出业务聚合，遗漏组织模型
-```

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

@@ -1,33 +0,0 @@
-# CAGE-PAIR-002
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/cli/src/rules.ts:43](../../packages/cli/src/rules.ts)
-
-```ts
-
-/** CAGE-PAIR-002：进入某状态时获得了资源，从该状态出发的每一条迁移都必须释放它，或进入一个同样持有它的状态 */
-export function checkPairing(g: Ontology): Finding[] {
-  const { get } = index(g);
-  const findings: Finding[] = [];
-  const held = statesHoldingResources(g);
-```
-
-## 怎么修
-
-离开持有资源的状态时，发出事件并声明释放该资源的反应；检查每一条离开路径。
-
-## 正例
-
-```text
-reaction(OrderCancelled, { command: releaseLock, releases: 'inventory.lock', map: e => ({ id: e.orderId }) });
-```
-
-## 反例
-
-```text
-// approved 持有 inventory.lock，取消却没有 releases 反应
-command(PurchaseOrder, { from: 'approved', to: 'cancelled', handler: o => o });
-```

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

@@ -1,32 +0,0 @@
-# CAGE-QUERY-001
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/flow.ts:89](../../packages/kernel/src/primitives/flow.ts)
-
-```ts
-  if (!/^[a-z][A-Za-z0-9]*$/.test(name)) throw declError('CAGE-NAME-005', `查询名 ${name} 必须是小驼峰`);
-  if (!def.sql === !def.build) throw declError('CAGE-QUERY-001', `查询 ${name} 必须二选一：sql 或 build`);
-  if (def.sql && /\bcore\.|\bsys\./i.test(def.sql)) {
-    throw declError('CAGE-QUERY-002', `查询 ${name} 引用了基表，只能引用 safe.* 安全视图`);
-  }
-  return Object.freeze({
-```
-
-## 怎么修
-
-SQL 引用 reads 对应的 safe 视图，用命名参数绑定输入。
-
-## 正例
-
-```text
-reads: [PurchaseOrder], sql: 'select amount from safe.purchase_order where status = :status'
-```
-
-## 反例
-
-```text
-sql: 'select * from core.purchase_order'
-```

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

@@ -1,32 +0,0 @@
-# CAGE-QUERY-002
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/flow.ts:91](../../packages/kernel/src/primitives/flow.ts)
-
-```ts
-  if (def.sql && /\bcore\.|\bsys\./i.test(def.sql)) {
-    throw declError('CAGE-QUERY-002', `查询 ${name} 引用了基表，只能引用 safe.* 安全视图`);
-  }
-  return Object.freeze({
-    [QUERY]: true as const,
-    name,
-```
-
-## 怎么修
-
-SQL 引用 reads 对应的 safe 视图，用命名参数绑定输入。
-
-## 正例
-
-```text
-reads: [PurchaseOrder], sql: 'select amount from safe.purchase_order where status = :status'
-```
-
-## 反例
-
-```text
-sql: 'select * from core.purchase_order'
-```

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

@@ -1,32 +0,0 @@
-# CAGE-QUERY-003
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/cli/src/rules.ts:168](../../packages/cli/src/rules.ts)
-
-```ts
-
-/** CAGE-QUERY-003：手写 SQL 只能引用 reads 里聚合的安全视图 */
-export function checkQueries(g: Ontology): Finding[] {
-  const { get } = index(g);
-  const findings: Finding[] = [];
-  for (const q of g.nodes.filter((n) => n.kind === 'query')) {
-```
-
-## 怎么修
-
-SQL 引用 reads 对应的 safe 视图，用命名参数绑定输入。
-
-## 正例
-
-```text
-reads: [PurchaseOrder], sql: 'select amount from safe.purchase_order where status = :status'
-```
-
-## 反例
-
-```text
-sql: 'select * from core.purchase_order'
-```