@yss123/cage-cli 0.1.0 → 0.2.0

package/templates/app/docs/errors/CAGE-INIT-004.md

@@ -0,0 +1,48 @@
+# CAGE-INIT-004：账号已创建但 .env 替换失败
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：init。
+
+数据库账号权限已提交，随机凭证仍保存在错误指出的 .env.cage-init-*.tmp 恢复文件中。
+
+## 修复步骤
+
+1. 保留恢复文件，解除文件占用或修复项目目录权限，将该文件恢复为项目 .env。
+2. 恢复后运行 init 验证连接，不重新生成密码；恢复文件及 .env 均含凭证，不提交到 Git，不发到聊天。
+
+## 正例
+
+```text
+按报错路径恢复 .env 后验证并继续 gen/migrate
+```
+
+## 反例
+
+```text
+删除恢复文件，丢失刚创建角色的随机密码
+```
+
+## 修复后验证
+
+恢复/核对配置后运行 cage init 验证，随后按流程 gen、审查迁移并 migrate；不输出凭证。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/init.ts:122`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    } catch {
+      throw new Error(`[CAGE-INIT-004] 账号权限已准备，但无法替换 .env；凭证保存在 ${staged}，请将它恢复为项目 .env 后继续`);
+    }
+    staged = undefined;
+    return { status: reuse ? 'reused' : 'created', envFile };
+```

package/templates/app/docs/errors/CAGE-JOB-001.md

@@ -0,0 +1,47 @@
+# CAGE-JOB-001：定时表达式不合法
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / worker。
+
+job 声明的 cron 缺少基本时间字段，后续解析也可能发现具体表达式错误。
+
+## 修复步骤
+
+1. 使用受支持的 cron 表达式并按业务明确运行频率；不要将无效配置静默改成每分钟执行。
+
+## 正例
+
+```text
+cron: '0 2 * * *'
+```
+
+## 反例
+
+```text
+cron: '每天两点'
+```
+
+## 修复后验证
+
+先 cage check，再在独立测试环境用目标任务数据验证读取、调用与审计；不要等待生产定时器试错。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:190`
+
+实现片段（位置随框架版本更新）：
+
+```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,
+```

package/templates/app/docs/errors/CAGE-JOB-002.md

@@ -0,0 +1,47 @@
+# CAGE-JOB-002：任务调用了未声明的命令
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / worker。
+
+job.run 中 call 的命令不在该任务的 calls 列表里。
+
+## 修复步骤
+
+1. 在 calls 显式列出实际允许调用且已导出的命令，核对命令身份；不能借任务绕过命令网关。
+
+## 正例
+
+```text
+calls: [cancel]，run 使用 call(cancel, { id })
+```
+
+## 反例
+
+```text
+calls: []，run 却调用 cancel
+```
+
+## 修复后验证
+
+先 cage check，再在独立测试环境用目标任务数据验证读取、调用与审计；不要等待生产定时器试错。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/worker/scheduler.ts:38`
+
+实现片段（位置随框架版本更新）：
+
+```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;
+    },
+  };
+```

package/templates/app/docs/errors/CAGE-JOB-003.md

@@ -0,0 +1,47 @@
+# CAGE-JOB-003：任务读取了未声明的聚合
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / worker。
+
+job.run 的 query.list 读取目标不在 reads 中。
+
+## 修复步骤
+
+1. 在 job.reads 列出实际读取聚合并从入口导出；保留可追踪的读依赖。
+
+## 正例
+
+```text
+reads: [PurchaseOrder]，query.list(PurchaseOrder, ...)
+```
+
+## 反例
+
+```text
+reads: []，却 query.list(PurchaseOrder, ...)
+```
+
+## 修复后验证
+
+先 cage check，再在独立测试环境用目标任务数据验证读取、调用与审计；不要等待生产定时器试错。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/worker/scheduler.ts:28`
+
+实现片段（位置随框架版本更新）：
+
+```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));
+```

package/templates/app/docs/errors/CAGE-LINT-001.md

@@ -0,0 +1,47 @@
+# CAGE-LINT-001：lint 语法或规则错误
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：verify。
+
+verify 将没有专属 CAGE 码的 ESLint 诊断汇总为该码。
+
+## 修复步骤
+
+1. 看同条诊断的 ruleId、文件和行号，修复具体语法/规则后重跑；不要把通用码当成单一故障。
+
+## 正例
+
+```text
+按原 ESLint 诊断修复后运行 pnpm verify
+```
+
+## 反例
+
+```text
+删除 lint 配置或全局 disable
+```
+
+## 修复后验证
+
+按原诊断的文件、行号和 ruleId 修复，再运行相关 lint/verify。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/verify.ts:95`
+
+实现片段（位置随框架版本更新）：
+
+```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',
+```

package/templates/app/docs/errors/CAGE-MIG-001.md

@@ -0,0 +1,47 @@
+# CAGE-MIG-001：迁移事务执行失败
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：migrate。
+
+某个系统或业务迁移 SQL 执行出错；错误信息附迁移名和 PostgreSQL 原因。
+
+## 修复步骤
+
+1. 核对迁移账号、依赖顺序、旧数据与 SQL；失败事务已回滚，修复未执行草稿后重跑。已执行历史不得改写。
+
+## 正例
+
+```text
+修复尚未执行草稿中的非空字段回填，再运行 pnpm migrate
+```
+
+## 反例
+
+```text
+用读账号迁移，或忽略失败继续启动业务
+```
+
+## 修复后验证
+
+在合适数据库上重新 migrate，确认迁移历史及 safe 读写权限，已执行文件保持原样。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/db/migrate.ts:84`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+        await client.query('rollback');
+        throw new Error(`[CAGE-MIG-001] 迁移 ${m.name} 失败：${(e as Error).message}`);
+      }
+      applied.push(m.name);
+    }
+```

package/templates/app/docs/errors/CAGE-MIG-002.md

@@ -0,0 +1,47 @@
+# CAGE-MIG-002：安全层重建失败
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：migrate。
+
+迁移后的 safe 视图、范围函数或授权重建事务失败。
+
+## 修复步骤
+
+1. 核对 init 是否完成、迁移角色权限、聚合引用与安全层 SQL。修复后重新 migrate；不改读侧去访问基表。
+
+## 正例
+
+```text
+用正确迁移账号重建安全层，验证普通用户读路径
+```
+
+## 反例
+
+```text
+为绕过视图错误，把查询改成 core.* 或管理员连接
+```
+
+## 修复后验证
+
+在合适数据库上重新 migrate，确认迁移历史及 safe 读写权限，已执行文件保持原样。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/db/migrate.ts:96`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      await client.query('rollback');
+      throw new Error(`[CAGE-MIG-002] 重建安全层失败：${(e as Error).message}`);
+    }
+    log('安全层已重建');
+    return { applied, safeLayerRebuilt: true };
+```

package/templates/app/docs/errors/CAGE-MIG-003.md

@@ -0,0 +1,5 @@
+# CAGE-MIG-003
+
+此错误码属于 npm 0.1.0 的旧数据库初始化流程，当前源码已移除该流程，保留本页供历史错误查询。
+
+当前项目首次在根目录 `.env` 填写 `CAGE_ADMIN_DATABASE_URL`，运行 `pnpm exec cage init` 自动准备账号与连接，再执行 `pnpm migrate` 更新表结构。已有集群角色需复用原凭证，不能覆盖其他项目正在使用的密码。

package/templates/app/docs/errors/CAGE-MIG-004.md

@@ -0,0 +1,5 @@
+# CAGE-MIG-004
+
+此错误码属于 npm 0.1.0 的旧数据库初始化流程，当前源码已移除该流程，保留本页供历史错误查询。
+
+当前项目首次在根目录 `.env` 填写 `CAGE_ADMIN_DATABASE_URL`，运行 `pnpm exec cage init` 自动准备账号与连接，再执行 `pnpm migrate` 更新表结构。已有集群角色需复用原凭证，不能覆盖其他项目正在使用的密码。

package/templates/app/docs/errors/CAGE-MIG-005.md

@@ -0,0 +1,47 @@
+# CAGE-MIG-005：已执行迁移内容被修改
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：migrate。
+
+迁移文件校验和与 sys.schema_migrations 中记录不符。
+
+## 修复步骤
+
+1. 恢复执行时的原文件；结构更新新增迁移。换行引起差异时恢复原始字节并遵守仓库 LF 约定，不改数据库 checksum。
+
+## 正例
+
+```text
+保留 0001_init.sql，新增 0002_add_field.sql
+```
+
+## 反例
+
+```text
+重写 0001，或手工修改迁移历史 checksum
+```
+
+## 修复后验证
+
+在合适数据库上重新 migrate，确认迁移历史及 safe 读写权限，已执行文件保持原样。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/db/migrate.ts:71`
+
+实现片段（位置随框架版本更新）：
+
+```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) {
+```

package/templates/app/docs/errors/CAGE-NAME-001.md

@@ -0,0 +1,47 @@
+# CAGE-NAME-001：聚合名必须大驼峰
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+aggregate 名称不是大写字母开头的字母数字标识。
+
+## 修复步骤
+
+1. 聚合使用稳定英文大驼峰，中文显示名写 description/graph.labels。
+
+## 正例
+
+```text
+aggregate('PurchaseOrder', definition)
+```
+
+## 反例
+
+```text
+aggregate('purchase-order', definition)
+```
+
+## 修复后验证
+
+重跑 cage check/gen；改动线上标识时还要审查能力、路由、迁移及旧消费者影响。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/aggregate.ts:72`
+
+实现片段（位置随框架版本更新）：
+
+```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> = {};
+```

package/templates/app/docs/errors/CAGE-NAME-002.md

@@ -0,0 +1,47 @@
+# CAGE-NAME-002：字段名必须小驼峰
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+聚合字段名不是小写字母开头的字母数字标识。
+
+## 修复步骤
+
+1. 业务字段使用小驼峰；数据库 snake_case 由框架转换，中文列名写在页面或图谱显示配置。
+
+## 正例
+
+```text
+fields: { supplierPhone: text() }
+```
+
+## 反例
+
+```text
+fields: { supplier_phone: text() }
+```
+
+## 修复后验证
+
+重跑 cage check/gen；改动线上标识时还要审查能力、路由、迁移及旧消费者影响。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/aggregate.ts:87`
+
+实现片段（位置随框架版本更新）：
+
+```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;
+```

package/templates/app/docs/errors/CAGE-NAME-003.md

@@ -0,0 +1,47 @@
+# CAGE-NAME-003：事件名必须大驼峰
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+event 名称格式不满足大驼峰。
+
+## 修复步骤
+
+1. 使用表示已发生事实的稳定大驼峰事件名，避免中文或短横线标识。
+
+## 正例
+
+```text
+event('OrderSubmitted', fields)
+```
+
+## 反例
+
+```text
+event('order-submitted', fields)
+```
+
+## 修复后验证
+
+重跑 cage check/gen；改动线上标识时还要审查能力、路由、迁移及旧消费者影响。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/event.ts:19`
+
+实现片段（位置随框架版本更新）：
+
+```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} 必须是大驼峰`);
+  if (Object.values(fields).some(isRelation)) throw declError('CAGE-REL-001', '事件载荷不声明持久化关系；传递 ID 数组请使用 list(id())');
+  return Object.freeze({
+    [EVENT]: true as const,
+```

package/templates/app/docs/errors/CAGE-NAME-004.md

@@ -0,0 +1,47 @@
+# CAGE-NAME-004：命令名必须小驼峰
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+command 显式 name 不是小驼峰。
+
+## 修复步骤
+
+1. name 使用小驼峰；中文按钮与图谱展示名另配，导出变量可用唯一业务前缀。
+
+## 正例
+
+```text
+name: 'submit'
+```
+
+## 反例
+
+```text
+name: '提交审批'
+```
+
+## 修复后验证
+
+重跑 cage check/gen；改动线上标识时还要审查能力、路由、迁移及旧消费者影响。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/command.ts:145`
+
+实现片段（位置随框架版本更新）：
+
+```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,
+```

package/templates/app/docs/errors/CAGE-NAME-005.md

@@ -0,0 +1,47 @@
+# CAGE-NAME-005：查询名必须小驼峰
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+query 名称格式不满足小驼峰。
+
+## 修复步骤
+
+1. 使用小驼峰查询名，保持生成契约与路由的稳定标识。
+
+## 正例
+
+```text
+query('poByStatus', definition)
+```
+
+## 反例
+
+```text
+query('PO_BY_STATUS', definition)
+```
+
+## 修复后验证
+
+重跑 cage check/gen；改动线上标识时还要审查能力、路由、迁移及旧消费者影响。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:88`
+
+实现片段（位置随框架版本更新）：
+
+```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.* 安全视图`);
+```

package/templates/app/docs/errors/CAGE-NAME-006.md

@@ -0,0 +1,47 @@
+# CAGE-NAME-006：任务名必须小驼峰
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+job 名称格式不满足小驼峰。
+
+## 修复步骤
+
+1. 任务使用稳定的小驼峰名，中文意图放 description。
+
+## 正例
+
+```text
+job('expireStaleOrders', definition)
+```
+
+## 反例
+
+```text
+job('Expire-Stale-Orders', definition)
+```
+
+## 修复后验证
+
+重跑 cage check/gen；改动线上标识时还要审查能力、路由、迁移及旧消费者影响。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:189`
+
+实现片段（位置随框架版本更新）：
+
+```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,
+```