@yss123/cage-cli 0.1.0 → 0.3.0

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

@@ -0,0 +1,48 @@
+# CAGE-GEN-001：契约等生成结果过期
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：gen --check / verify。
+
+gen --check/verify 比较发现需提交的生成文件缺失或与声明不一致。
+
+## 修复步骤
+
+1. 改源声明后运行 pnpm gen，审查并提交结果；手改生成物会被覆盖，不靠更新预期掩盖错误。
+
+## 正例
+
+```text
+修改 domain → pnpm gen → pnpm exec cage gen --check
+```
+
+## 反例
+
+```text
+直接编辑 packages/contracts/src/aggregates/purchase-order/index.ts
+```
+
+## 修复后验证
+
+重新生成并审查后执行 cage gen --check；结构变化还需审查并执行 migrate。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/gen/index.ts:76`
+- `packages/cli/src/gen/index.ts:122`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  findings: Finding[],
+  code = 'CAGE-GEN-001',
+) {
+  const cur = existsSync(path) ? readFileSync(path, 'utf8') : null;
+  if (cur === content) return;
+```

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

@@ -0,0 +1,47 @@
+# CAGE-GEN-002：声明结构没有对应迁移
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：gen --check / verify。
+
+声明的期望结构与最后一个迁移内嵌的结构快照不一致。
+
+## 修复步骤
+
+1. 运行 pnpm gen 生成新迁移草稿，审查回填、非空与破坏性变更后提交；实际落库还需 pnpm migrate。
+
+## 正例
+
+```text
+新增字段 → gen → 审查新迁移 → migrate
+```
+
+## 反例
+
+```text
+修改已执行 0001_init.sql，或把 gen 当作已更新数据库
+```
+
+## 修复后验证
+
+重新生成并审查后执行 cage gen --check；结构变化还需审查并执行 migrate。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/gen/index.ts:209`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      findings.push({
+        code: 'CAGE-GEN-002',
+        at: cfg.migrations,
+        reason: `声明的表结构与迁移不一致（${stmts.length} 处变化）`,
+        fix: '运行 cage gen 生成迁移草稿，人审后提交',
+```

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

@@ -0,0 +1,53 @@
+# CAGE-GEN-003：输入校验需要服务端执行
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：gen --check / verify。
+
+refine/superRefine、transform 等可执行校验无法无损转换到生成的客户端 schema，报告包含字段路径。
+
+## 修复步骤
+
+1. 阅读诊断定位的命令和字段；把可表达规则声明成标准 schema，保留服务端作为最终校验。
+2. 确需自定义逻辑时，在页面解释业务拒绝并处理领域错误；不要认为契约生成成功代表执行函数已被复制。
+
+## 正例
+
+```text
+strict、multipleOf、default 使用标准 Zod 声明；自定义规则按字段报告降级
+```
+
+## 反例
+
+```text
+把服务端 refine 丢失当作客户端校验完全等价
+```
+
+## 修复后验证
+
+重新生成并审查后执行 cage gen --check；结构变化还需审查并执行 migrate。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/gen/index.ts:159`
+- `packages/cli/src/gen/zod-code.ts:64`
+- `packages/cli/src/gen/zod-code.ts:84`
+- `packages/cli/src/gen/zod-code.ts:120`
+- `packages/cli/src/gen/zod-code.ts:140`
+- `packages/cli/src/gen/zod-code.ts:217`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    for (const diagnostic of schemaDiagnostics(entry.input)) findings.push({
+      code: 'CAGE-GEN-003', severity: 'warning', at: `${entry.name}:${diagnostic.path}`,
+      reason: diagnostic.reason, fix: '前端校验只提供即时提示，以服务端命令校验为准；不要复制可执行函数到契约。',
+    });
+
+```

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

@@ -0,0 +1,49 @@
+# CAGE-GRANT-001：授予超出自己的能力或额度
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：组织命令。
+
+管理员授予自己没有的能力/更高参数，或分配含越权能力的角色。
+
+## 修复步骤
+
+1. 由具备足够能力和参数的管理员操作；降低授予范围到自身权限内，不禁用防提权约束。
+
+## 正例
+
+```text
+有 approve=100000 额度的管理员授予不超过自身的额度
+```
+
+## 反例
+
+```text
+自己没有采购审批能力，却给别人分配该能力或包含它的角色
+```
+
+## 修复后验证
+
+用真实操作人验证允许与拒绝场景，检查目标角色最终能力、参数和范围。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/admin/src/domain/constraints.ts:39`
+- `packages/admin/src/domain/constraints.ts:42`
+- `packages/admin/src/domain/constraints.ts:78`
+
+实现片段（位置随框架版本更新）：
+
+```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]}`);
+```

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

@@ -0,0 +1,48 @@
+# CAGE-GRANT-002：授予超出自己的数据范围
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：组织命令。
+
+设置范围或分配角色时，目标范围比操作人自身范围更宽。
+
+## 修复步骤
+
+1. 核对操作人在该聚合的范围，由具有足够范围的管理员配置；部门限定还需对应范围字段。
+
+## 正例
+
+```text
+自己有 all 范围时，按业务需求授予部门范围
+```
+
+## 反例
+
+```text
+仅有本人范围的管理员给角色授予全部部门
+```
+
+## 修复后验证
+
+用真实操作人验证允许与拒绝场景，检查目标角色最终能力、参数和范围。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/admin/src/domain/constraints.ts:59`
+- `packages/admin/src/domain/constraints.ts:82`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    const want = COMBINATOR_WIDTH[input.combinator as Combinator] ?? 99;
+    return want <= ownWidth(ctx, input.aggregate) ? ok() : violation('[CAGE-GRANT-002] 不能授出比自己更宽的数据范围');
+  },
+});
+
+```

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

@@ -0,0 +1,48 @@
+# CAGE-GRANT-003：能力不在代码目录中
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：组织命令。
+
+授权请求引用了注册表没有声明的能力点。
+
+## 修复步骤
+
+1. 先在 domain 声明并导出相应命令/聚合，再查看能力目录；不要在管理页面凭空发明能力名称。
+
+## 正例
+
+```text
+PurchaseOrder.submit // 由已导出的命令形成
+```
+
+## 反例
+
+```text
+PurchaseOrder.anything // 没有对应声明
+```
+
+## 修复后验证
+
+用真实操作人验证允许与拒绝场景，检查目标角色最终能力、参数和范围。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/admin/src/domain/constraints.ts:21`
+- `packages/admin/src/domain/constraints.ts:26`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+ * 构造目录存在性约束。check 使用内核提供的实时目录核对 input.capability，
+ * 未知能力返回 CAGE-GRANT-003；该检查不负责判断操作者是否拥有这个能力。
+ */
+export const knownCapability = (): Constraint => ({
+  name: 'knownCapability',
+```

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

@@ -0,0 +1,48 @@
+# CAGE-IMPACT-001：影响分析没有可用基线
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：impact / 基线加载。
+
+impact 未指定基线，或 Git 基线无法加载/抽取。
+
+## 修复步骤
+
+1. 使用真实存在且能加载的提交，或修改前保存的完整 ontology.json。基线失败不能当作没有变化。
+
+## 正例
+
+```text
+pnpm exec cage impact --base-file .cage/before-change.json
+```
+
+## 反例
+
+```text
+修改后才保存旧图，或指定不存在的提交并忽略失败
+```
+
+## 修复后验证
+
+使用可靠基线重新 impact，确认报告中的变化与本次需求相符。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/baseline.ts:58`
+- `packages/cli/src/main.ts:287`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    );
+    if (code !== 0) throw new Error('[CAGE-IMPACT-001] 基线抽取失败，请修复基线声明或使用保存的 --base-file');
+    return readOntology(join(project, '.cage/ontology.json'));
+  } finally {
+    // 先断开本次建立的 junction，避免清理工作树时遍历共享依赖目录。
+```

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

@@ -0,0 +1,52 @@
+# CAGE-IMPACT-002：命名本体快照无效
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：impact / 基线加载。
+
+快照名非法、同名已存在、指定快照不存在，或快照格式损坏。
+
+## 修复步骤
+
+1. 先 cage snapshot list 核对已有名称，再用新的稳定名称保存。
+2. 保存后通过 impact --snapshot 比较；不要覆盖旧基线或把修改后的图当成修改前状态。
+
+## 正例
+
+```text
+cage snapshot save before-rental-change；cage impact --snapshot before-rental-change
+```
+
+## 反例
+
+```text
+多次使用同名快照覆盖唯一旧图
+```
+
+## 修复后验证
+
+使用可靠基线重新 impact，确认报告中的变化与本次需求相符。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/impact.ts:95`
+- `packages/cli/src/snapshots.ts:24`
+- `packages/cli/src/snapshots.ts:27`
+- `packages/cli/src/snapshots.ts:56`
+- `packages/cli/src/snapshots.ts:58`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const graph = value.graph ?? value;
+  if (graph.version !== 1 || !Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) throw new Error('[CAGE-IMPACT-002] 基线文件不是有效本体图或命名快照');
+  return graph as Ontology;
+}
+
+```

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

@@ -0,0 +1,47 @@
+# CAGE-INIT-001：管理员 URL 没有数据库名
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：init。
+
+init 的管理员连接没有指定一个明确的已有数据库。
+
+## 修复步骤
+
+1. 在 URL 路径填写实际数据库名，确认该库已经存在；init 不负责创建数据库。
+
+## 正例
+
+```text
+postgresql://postgres:已编码密码@主机:端口/business_db
+```
+
+## 反例
+
+```text
+postgresql://postgres:密码@主机:端口/
+```
+
+## 修复后验证
+
+恢复/核对配置后运行 cage init 验证，随后按流程 gen、审查迁移并 migrate；不输出凭证。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/init.ts:100`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (!target.pathname || target.pathname === '/') {
+    throw new Error('[CAGE-INIT-001] 管理员连接必须指定已经存在的数据库名，例如 postgresql://postgres:密码@localhost:5432/business_db');
+  }
+  const admin = new pg.Client({ connectionString: adminUrl, connectionTimeoutMillis: 5000, application_name: 'cage-init' });
+  let staged: string | undefined;
+```

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

@@ -0,0 +1,49 @@
+# CAGE-INIT-002：集群已有账号但缺少原凭证
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：init。
+
+PostgreSQL 集群已经存在 Cage 登录角色，而本项目没有保存可复用的三种连接。
+
+## 修复步骤
+
+1. 从已有项目或管理员安全取得对应角色的原连接，填入本项目 .env，再运行 init 验证。
+2. 角色名在集群共享；不要为新项目随机重置 cage_app/read/migrate 的密码，影响其他项目。
+3. 如需完全隔离的账号策略，先规划集群/角色隔离方案；不删除共享角色绕过检查。
+
+## 正例
+
+```text
+复用原 APP/READ/MIGRATE 凭证，指向本项目实际同一库
+```
+
+## 反例
+
+```text
+ALTER ROLE 重置共享账号密码，导致已有应用断连
+```
+
+## 修复后验证
+
+恢复/核对配置后运行 cage init 验证，随后按流程 gen、审查迁移并 migrate；不输出凭证。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/init.ts:114`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      if (existing.rowCount !== 4 || !hasSaved) {
+        throw new Error('[CAGE-INIT-002] PostgreSQL 集群已有 Cage 账号；请在 .env 提供已有的 APP / READ / MIGRATE 连接后重试。初始化不会重置这些账号的密码');
+      }
+      if (new URL(saved.APP).host !== target.host || new URL(saved.APP).pathname !== target.pathname) {
+        throw new Error('[CAGE-INIT-003] 已有账号连接与管理员连接必须指向同一个数据库；请检查 .env');
+```

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

@@ -0,0 +1,48 @@
+# CAGE-INIT-003：三种连接身份或目标不一致
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：init。
+
+APP/READ/MIGRATE 账号不是各自 Cage 账号，或三者及管理员连接不指向同一目标数据库。
+
+## 修复步骤
+
+1. 核对 URL 的用户名、主机、端口、数据库名；各自使用正确账号，并连接同一个库，不输出密码。
+
+## 正例
+
+```text
+cage_app/cage_read/cage_migrate 均连接同一 host:port/business_db
+```
+
+## 反例
+
+```text
+app 连接 business_db，而 read/migrate 指向另一个库
+```
+
+## 修复后验证
+
+恢复/核对配置后运行 cage init 验证，随后按流程 gen、审查迁移并 migrate；不输出凭证。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/init.ts:30`
+- `packages/cli/src/init.ts:117`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (url.username !== accounts[key] || url.host !== target.host || url.pathname !== target.pathname) {
+      throw new Error('[CAGE-INIT-003] APP / READ / MIGRATE 需使用各自的 cage 账号，指向同一个数据库；请检查 .env');
+    }
+    const client = new pg.Client({ connectionString: urls[key], connectionTimeoutMillis: 5000 });
+    try {
+```

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:142`
+
+实现片段（位置随框架版本更新）：
+
+```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-INIT-005.md

@@ -0,0 +1,52 @@
+# CAGE-INIT-005：显式组织初始化或凭据交付失败
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：init。
+
+bootstrap 配置不完整，凭据文件已存在、权限无法限制，或组织初始化事务失败。
+
+## 修复步骤
+
+1. 审查执行迁移后，提供新的凭据文件路径和实际可用连接；父目录需存在。
+2. 先修复文件权限或数据库错误，再重新执行；不能把密码转而打印到服务日志。
+
+## 正例
+
+```text
+cage bootstrap --credentials-file .cage/admin-credentials.json // 新受限文件
+```
+
+## 反例
+
+```text
+覆盖已有凭据文件，或初始化失败后继续输出“成功”
+```
+
+## 修复后验证
+
+恢复/核对配置后运行 cage init 验证，随后按流程 gen、审查迁移并 migrate；不输出凭证。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/bootstrap.ts:19`
+- `packages/cli/src/bootstrap.ts:23`
+- `packages/cli/src/bootstrap.ts:32`
+- `packages/cli/src/bootstrap.ts:45`
+- `packages/cli/src/bootstrap.ts:61`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+ * @param file 已解析的目标路径，父目录必须存在，目标不得已存在。
+ * @throws 创建或 ACL 限制失败时抛出 CAGE-INIT-005；已创建空文件可能保留，不能视为交付成功。
+ */
+export function protectCredentialFile(file: string): void {
+  try { closeSync(openSync(file, 'wx', 0o600)); }
+```