@lovrabet/rabetbase-cli 2.5.1 → 2.5.2-beta.2

package/skills/rabetbase/references/rabetbase-deployment-sync.md

@@ -1,44 +1,29 @@
 # rabetbase deployment sync
 
-将当前应用中指定数据库连接下的少量研发元数据同步到独立部署目标。命令只同步显式给出的业务编码，支持 `dataset`、`bff`、`sql`。
+将当前应用中的少量研发元数据同步到独立部署系统。命令只同步显式给出的业务编码，支持 `dataset`、`bff`、`sql`。
+
+需要同步当前应用中服务端支持的全部研发元数据时，不要猜测或枚举资源类型和编码，改用本文后半部分的 `deployment sync-all`。
 
 ## 使用前确认
 
 - 已完成 rabetbase 认证，并明确目标应用的 `appCode`。
-- 从可信事实中取得基础 dblink／环境连接组 ID 和业务编码，不猜测 ID 或编码。
-- `--target-env` 只选择服务端维护的环境连接映射；CLI 不保存数据库 URL、账号、密码或环境到连接 ID 的映射。
-- 服务端同步接口会检查目标 appCode 的一键部署开关；未开启时正常跳过，不属于异常或无权限。
-- 同一批最多 100 个编码；需要分批时逐批确认结果，不并发执行。
+- 从可信事实中取得业务编码，不猜测 DatasetCode、function name 或 sqlCode。
+- Agent 只提供下方列出的业务参数。
+- 服务端会检查 appCode 白名单；未开启时正常跳过，不属于异常或无权限。
+- 一次命令最多 100 个编码；CLI 串行处理，不并发执行。
 
 ## 先预览
 
-环境部署：
-
 ```sh
 rabetbase deployment sync \
   --appcode <appCode> \
-  --db-id <dbLinkId> \
-  --target-env test \
   --type dataset \
   --codes <code1,code2> \
   --dry-run \
   --format compress
 ```
 
-直连部署：
-
-```sh
-rabetbase deployment sync \
-  --appcode <appCode> \
-  --db-id <dbLinkId> \
-  --direct \
-  --type bff \
-  --codes <code1> \
-  --dry-run \
-  --format compress
-```
-
-检查输出中的 `data.selector.targetMode`、`data.selector.targetEnv`、`data.selector.bizType`、`data.selector.bizCodes` 和 `data.selector.dbLinkId`。dry-run 不发起同步请求。
+检查 `data.selector.bizType` 和 `data.selector.bizCodes`；dry-run 不发起同步请求。
 
 ## 正式执行
 
@@ -47,8 +32,6 @@ rabetbase deployment sync \
 ```sh
 rabetbase deployment sync \
   --appcode <appCode> \
-  --db-id <dbLinkId> \
-  --target-env test \
   --type dataset \
   --codes <code1,code2> \
   --confirm \
@@ -58,35 +41,60 @@ rabetbase deployment sync \
 
 ## 参数约束
 
-- `--db-id`：正整数基础 dblink／环境连接组 ID；不是某个环境的最终连接 ID。
-- `--target-env dev|test|pre|prod`：服务端环境连接映射选择器；与 `--direct` 必须且只能选择一个。
 - `--type dataset|bff|sql`：同步资源类型。
 - `--codes`：逗号分隔；命令 trim、过滤空项并按首次出现顺序去重，最多 100 个。
-- 全局 `--env production|daily` 只决定 CLI 服务域，不是部署目标；不要用它替代 `--target-env`。
+- Agent 只提供 `--type`、`--codes` 和执行确认。
 
 ## 结果与失败处理
 
 - 退出码 `0`：服务端没有返回 `FAILED`；`SKIPPED`、`UNCHANGED` 等 no-op action 或空 items 均表示无需执行，不作为异常。
-- 退出码 `1`：至少一个条目为 `FAILED`。读取结构化输出的 `data.items[]`，保留成功项和失败项的完整事实，不要把整批误报为失败或成功，也不要自动重提整批。
-- 退出码 `2`：写请求响应丢失或响应无法证明结果。同步可能已经生效；先人工核对目标部署，再决定是否处理未完成项，禁止直接重试。
+- 退出码 `1`：至少一个条目为 `FAILED`。读取结构化输出的 `data.items[]`，只人工处理明确失败的 code，不自动重提整批。
+- 退出码 `2`：写请求响应丢失或响应无法证明结果。同步可能已经生效；先人工核对目标部署，再决定后续处理，禁止直接重试。
 
-Dataset 同步会先确保目标数据库连接存在，再逐项同步 Dataset，不是跨资源原子事务。命令当前不提供目标端只读回查；部署后的业务可用性仍需单独验收。
+Dataset 同步会逐项处理 Dataset 元数据，不是跨资源原子事务。命令当前不提供目标端只读回查；部署后的业务可用性仍需单独验收。
 
 ## 日常 BFF / SQL push 自动同步
 
-只有用户明确要求将日常开发变更持续同步到独立部署测试环境时，才写入 app profile：
+存在实际变更且主 push 成功后，CLI 自动提交精确同步意图；服务端原子检查 appCode 白名单并处理目标。未开启时返回成功空结果，表示无需执行，不是异常或无权限。
+
+- `bff push` 只同步当前 push 中上传成功且完成缓存清理的 function name。
+- `sql push` 只同步当前 push 中成功写入的 sqlCode；未变化项不触发同步。
+- 主 push 或 BFF 缓存清理失败时不调用同步接口。
+- dry-run 展示服务端托管的同步意图和精确 code，但不调用 `/sync`。
+- Dataset 没有统一 push 入口，继续使用显式 `deployment sync --type dataset`；不要在 `dataset generate-status` 等只读命令中触发同步。
+- 主 push 成功但后置同步失败时，不声称回滚主操作；按 `data.deploymentSync.recoveryCommand` 人工处理。
+- `partial_failure`、`failed`、`outcome_unknown` 均不得自动重试。
+
+## 应用范围同步
+
+用户明确要求同步当前应用全部已支持研发元数据时，先预览：
 
 ```sh
-rabetbase workspace use --app <appName> --appcode <appCode> \
-  --deployment-db-id <dbLinkId> --deployment-target-env dev
+rabetbase deployment sync-all \
+  --appcode <appCode> \
+  --dry-run \
+  --format compress
 ```
 
-- 自动目标仅允许 `dev`、`test`、`pre`；生产和直连仍用显式命令并要求确认。
-- 每个 app profile 只保存一个明确的自动目标，不根据 Git 分支、CLI 服务域或登录状态推断环境。
-- 存在实际变更且主 push 成功后调用一次同步接口，由服务端检查 appCode 开关并按 `(dbLinkId, targetEnv)` 解析真实连接；未开启时正常 no-op，环境映射缺失则是配置错误。
-- `bff push` 只同步本次上传成功且完成缓存清理的 function name。
-- `sql push` 只同步本次 pushed sqlCode；未变化项不触发同步。
-- Dataset 没有统一 push 入口，暂不自动同步。
-- dry-run 展示配置目标和精确 code，但不发请求。
-- 主 push 成功但后置同步失败时，不声称回滚主操作；只有同步请求已提交后才按 `data.deploymentSync.recoveryCommand` 人工处理。
-- `partial_failure`、`failed`、`outcome_unknown` 均不得自动重试。
+经用户确认后，复用预览中的 appCode 提交：
+
+```sh
+rabetbase deployment sync-all \
+  --appcode <appCode> \
+  --confirm \
+  --yes \
+  --format compress
+```
+
+- `outcome=not_needed`：服务端判定当前应用无需同步，属于正常完成，不解释为异常或无权限。
+- `outcome=submitted`：保存 `jobId`，再用 `deployment sync-status` 查询同一任务。
+- 提交结果未知：不得再次执行 `sync-all`；先用 `deployment sync-jobs` 查找近期任务。
+
+任务查询：
+
+```sh
+rabetbase deployment sync-status --job-id <jobId> --format compress
+rabetbase deployment sync-jobs --appcode <appCode> --format compress
+```
+
+只根据 `isTerminal` 判断是否已知终态；若为 `null`，保留服务端状态并交给用户判断。逐项资源类型和 action 都是服务端开放字符串，Agent 不建立枚举闭集，也不因新值自动重提。

package/skills/rabetbase/references/rabetbase-instant-api-policy.md

@@ -0,0 +1,92 @@
+# rabetbase instant-api-policy
+
+管理应用级 Instant API 数据集访问策略。策略可以按 `datasetCode + api` 放行、禁止，或路由到同一应用的普通 Backend Function ENDPOINT。
+
+## 固定本地文件
+
+每个应用只有一个 CLI 策略源文件：
+
+```text
+.rabetbase/instant-api-policy/<appCode>/policy.json
+```
+
+`init`、`pull`、`validate` 和 `publish` 只使用该路径，不提供 `--file`。目标应用来自当前工作区、`--app <name>` 或 `--appcode <code>`。策略不存入 `.rabetbase.json` 或运行态 app-config。
+
+`version` 固定为字符串 `"1"`，表示 JSON 结构版本。`revision` 是服务端发布历史版本，首次发布为 1，后续发布和回滚递增；两者含义不同。
+
+## 配置结构
+
+```json
+{
+  "version": "1",
+  "appCode": "app-example",
+  "defaults": {
+    "instantApi": "allow"
+  },
+  "rules": [
+    {
+      "name": "route-student-filter",
+      "description": "学生筛选交给业务 Backend Function",
+      "datasets": [
+        {
+          "datasetCode": "student23"
+        }
+      ],
+      "apis": ["filter"],
+      "action": "route",
+      "backendFunction": "filterStudents"
+    }
+  ]
+}
+```
+
+- `defaults.instantApi` 只允许 `allow` 或 `deny`，不能是 `route`。
+- `rules[].action` 允许 `allow`、`deny`、`route`。
+- `route` 必须填写 `backendFunction`；其他 action 禁止填写。
+- `datasets[]` 至少填写 `datasetCode` 或 `tableName`；建议优先使用稳定的 `datasetCode`。两者同时填写时必须指向同一 Dataset。
+- 同一个 `datasetCode + api` 只能命中一条规则；重复覆盖会校验失败。
+- `apis` 的每个元素是一个独立值。`["filter,create"]` 或包含中文逗号的 `["filter，create"]` 都不是两个 API。
+- 支持的 API：`getSelectOptions`、`getList`、`excelExport`、`filter`、`aggregate`、`getOne`、`getOneOrigin`、`create`、`batchCreate`、`update`、`delete`。
+
+路由目标必须属于同一应用、类型为 `ENDPOINT`、不是 Personal Backend Function，并且函数配置可被 Runtime 解析。命中 route 后直接执行 Backend Function，原 Dataset 操作、Dynamic Hook 和通知链路不执行。策略判定优先于 Dynamic Hook。
+
+## 本地配置工作流
+
+```bash
+# 没有远端策略时创建默认放行草稿
+rabetbase instant-api-policy init --format compress
+
+# 已有远端策略时拉到固定文件；本地不同内容不会被静默覆盖
+rabetbase instant-api-policy pull --format compress
+rabetbase instant-api-policy pull --force --yes --format compress
+
+# 编辑固定 policy.json 后进行服务端校验
+rabetbase instant-api-policy validate --format compress
+
+# 预览发布；0 表示预期当前尚未配置
+rabetbase instant-api-policy publish --expected-revision 0 --change-summary "initial policy" --dry-run --format compress
+
+# 人工确认高风险影响后发布
+rabetbase instant-api-policy publish --expected-revision 0 --change-summary "initial policy" --yes --format compress
+```
+
+`init --default-action deny` 可以创建默认禁止草稿。`init` 和 `pull` 遇到不同的既有文件时停止；只有 `--force --yes` 可以替换。
+
+`validate` 调用服务端完整校验，返回 `configHash` 和 `normalizedConfig`，但不发布、不生成 revision。Dataset、API、规则重叠以及 Backend Function 合法性以该结果为准。
+
+`publish` 和 `rollback` 是 `high-risk-write`。它们受 CLI `riskLevel` 门禁约束；Agent 和自动化脚本不得修改 `riskLevel` 提权。正式执行需要 `--yes`，建议使用 `--expected-revision` 做写前漂移检查。该检查是非原子的，因为服务端 mutation 请求没有 revision 条件。
+
+## 查询与回滚
+
+```bash
+rabetbase instant-api-policy current --format compress
+rabetbase instant-api-policy revisions --format compress
+rabetbase instant-api-policy revision --revision 2 --format compress
+
+rabetbase instant-api-policy rollback --revision 2 --expected-revision 5 --dry-run --format compress
+rabetbase instant-api-policy rollback --revision 2 --expected-revision 5 --change-summary "restore revision 2" --yes --format compress
+```
+
+回滚不会把 revision 倒退，也不会覆盖历史。例如当前 revision 为 5，恢复 revision 2 后会生成新的 revision 6。
+
+发布和回滚最多提交一次。CLI 随后读取当前策略，要求 configHash 匹配且 revision 推进。响应丢失但回读可以证明结果时返回 verified；证据不足时停止并提示执行 `current`，不得自动重提。Runtime 最迟约 30 秒感知新策略。

package/skills/rabetbase.manifest.json

@@ -2,8 +2,8 @@
   "schemaVersion": 1,
   "name": "rabetbase",
   "packageName": "@lovrabet/rabetbase-cli",
-  "packageVersion": "2.5.1",
-  "skillVersion": "2.5.1",
+  "packageVersion": "2.5.2-beta.2",
+  "skillVersion": "2.5.2-beta.2",
   "files": [
     "SKILL.md",
     "guides/backend-function.md",
@@ -85,6 +85,7 @@
     "references/rabetbase-doctor.md",
     "references/rabetbase-file.md",
     "references/rabetbase-init.md",
+    "references/rabetbase-instant-api-policy.md",
     "references/rabetbase-issue-report.md",
     "references/rabetbase-kb.md",
     "references/rabetbase-menu-asset-update.md",
@@ -138,5 +139,5 @@
     "references/rabetbase-user-account.md",
     "references/rabetbase-workspace.md"
   ],
-  "digest": "e7dfbbba5a00b0bd70afeea096c0484a3c13b1abbffc3418d1d31e4cf8143dad"
+  "digest": "0367fd969de461022c6e87709aa5802f1c1403aaec8165599f0c49716d438912"
 }

package/lib/config/deployment-sync.d.ts

@@ -1,10 +0,0 @@
-import type { FlagDef } from "../framework/types.js";
-export declare const AUTO_DEPLOYMENT_TARGET_ENVS: readonly ["dev", "test", "pre"];
-export type AutoDeploymentTargetEnv = typeof AUTO_DEPLOYMENT_TARGET_ENVS[number];
-export interface DeploymentSyncProfile {
-    dbLinkId: number;
-    targetEnv: AutoDeploymentTargetEnv;
-}
-export declare function getDeploymentSyncProfileFlagDefs(): FlagDef[];
-export declare function collectDeploymentSyncProfile(getFlagValue: (name: string) => string): DeploymentSyncProfile | undefined;
-export declare function validateDeploymentSyncProfile(value: unknown): DeploymentSyncProfile;

package/lib/config/deployment-sync.js

@@ -1 +0,0 @@
-const a217_0x340a1c=a217_0x15a5;(function(_0x178fcf,_0x1bca70){const _0x28e996=a217_0x15a5,_0xf12f2=_0x178fcf();while(!![]){try{const _0x5282b0=parseInt(_0x28e996(0x158))/0x1*(parseInt(_0x28e996(0x14e))/0x2)+parseInt(_0x28e996(0x154))/0x3+-parseInt(_0x28e996(0x156))/0x4+parseInt(_0x28e996(0x14a))/0x5*(parseInt(_0x28e996(0x15a))/0x6)+parseInt(_0x28e996(0x157))/0x7+-parseInt(_0x28e996(0x15b))/0x8+-parseInt(_0x28e996(0x150))/0x9*(parseInt(_0x28e996(0x15e))/0xa);if(_0x5282b0===_0x1bca70)break;else _0xf12f2['push'](_0xf12f2['shift']());}catch(_0x4f0a61){_0xf12f2['push'](_0xf12f2['shift']());}}}(a217_0x4d10,0x9f67a));function a217_0x4d10(){const _0x15dca6=['isSafeInteger','deployment-db-id','1186029ALyMSK','dev','2006224pcWXau','7477323wOzRVU','634526vUBTuI','trim','1565796zSkHWL','6091248lTyhtZ','includes','deployment-target-env','30TmvdPA','Base\x20dblink\x20ID\x20whose\x20server-side\x20environment\x20mapping\x20selects\x20the\x20automatic\x20sync\x20target','targetEnv','object','validation','Non-production\x20target\x20selected\x20by\x20the\x20server-side\x20environment\x20mapping','20pPURDK','test','string','dbLinkId','4FtBmkU','deploymentSync\x20must\x20contain\x20dbLinkId\x20and\x20targetEnv.','5581692zUUipB','number'];a217_0x4d10=function(){return _0x15dca6;};return a217_0x4d10();}import{CliErrors}from'../errors.js';export const AUTO_DEPLOYMENT_TARGET_ENVS=[a217_0x340a1c(0x155),a217_0x340a1c(0x14b),'pre'];function a217_0x15a5(_0x3691e1,_0x1a519c){_0x3691e1=_0x3691e1-0x145;const _0x4d1098=a217_0x4d10();let _0x15a513=_0x4d1098[_0x3691e1];return _0x15a513;}export function getDeploymentSyncProfileFlagDefs(){const _0x539c5a=a217_0x340a1c;return[{'name':'deployment-db-id','type':_0x539c5a(0x151),'description':_0x539c5a(0x145)},{'name':_0x539c5a(0x15d),'type':_0x539c5a(0x14c),'enum':[...AUTO_DEPLOYMENT_TARGET_ENVS],'description':_0x539c5a(0x149)}];}export function collectDeploymentSyncProfile(_0x393fc1){const _0x261b59=a217_0x340a1c,_0x50f040=_0x393fc1(_0x261b59(0x153))['trim'](),_0x51b9f4=_0x393fc1(_0x261b59(0x15d))[_0x261b59(0x159)]();if(!_0x50f040&&!_0x51b9f4)return undefined;return validateDeploymentSyncProfile({'dbLinkId':_0x50f040?Number(_0x50f040):undefined,'targetEnv':_0x51b9f4||undefined});}export function validateDeploymentSyncProfile(_0x291bcf){const _0x349eb1=a217_0x340a1c;if(!_0x291bcf||typeof _0x291bcf!==_0x349eb1(0x147)||Array['isArray'](_0x291bcf))throw CliErrors[_0x349eb1(0x148)](_0x349eb1(0x14f));const _0x13975c=_0x291bcf,_0x1661d5=Number(_0x13975c[_0x349eb1(0x14d)]);if(!Number[_0x349eb1(0x152)](_0x1661d5)||_0x1661d5<=0x0)throw CliErrors[_0x349eb1(0x148)]('--deployment-db-id\x20must\x20be\x20a\x20positive\x20safe\x20integer.');const _0xfe77b5=typeof _0x13975c['targetEnv']==='string'?_0x13975c[_0x349eb1(0x146)]['trim']():'';if(!AUTO_DEPLOYMENT_TARGET_ENVS[_0x349eb1(0x15c)](_0xfe77b5))throw CliErrors['validation']('--deployment-target-env\x20must\x20be\x20one\x20of:\x20'+AUTO_DEPLOYMENT_TARGET_ENVS['join'](',\x20')+'.','Production\x20and\x20direct\x20targets\x20must\x20use\x20`rabetbase\x20deployment\x20sync`\x20with\x20explicit\x20confirmation.');return{'dbLinkId':_0x1661d5,'targetEnv':_0xfe77b5};}