fago-cli 常用命令

源码位于 fago/fago-server/apps/fago-cli/，module为 fago.local/fago/apps/fago-cli；与API/worker同仓维护，不再需要独立CLI子模块。二进制及以下命令保持不变。

在外层编排仓根目录执行，并先 source scripts/go-env.sh（与 scripts/database-profile.sh 在涉及构建标签时一并 source）。运维子命令与工具链子命令统一经 scripts/fago.sh 转发到 fago-cli 子模块。

规划与分期见 fago-cli 功能规划。

运维

命令	说明
scripts/fago.sh migrate	将当前库升到已发布 schema
scripts/fago.sh migrate status	只读版本与 dirty；不可服务时退出码 1
scripts/fago.sh migrate status --json	同上，JSON 输出
scripts/fago.sh bootstrap	显式初始化租户/平台账号（口令仅环境变量）
scripts/fago.sh gen-encryption-key -output <path>	生成 API 内容加密私钥

本地开发

命令	说明
scripts/fago.sh env doctor	检查 Go、module proxy、子模块与依赖端口
scripts/fago.sh dev up	启动 compose 中的 MySQL 与 Redis
scripts/fago.sh dev run api	启动 API（等同原 fago.sh api）
scripts/fago.sh dev run web	前端 dev（默认 127.0.0.1:5174）

质量门（节选）

命令	说明
scripts/fago.sh test unit	后端 workspace 与独立模块测试
scripts/fago.sh check contract	OpenAPI 静态合同
scripts/fago.sh check all	M4 顺序静态检查（需已 build 时 web-bundle 才通过）
scripts/fago.sh build release [mysql\|postgres\|dm]	三二进制 + manifest

涉及源码编排的工具链命令必须在完整克隆的外层仓库内运行；在仅有发布二进制、无 fago/ 与 api/openapi.yaml 的环境会失败（退出码2）。codegen diff 只读两个本地包，不要求源码树。

全局 --json 可用于 version、env print、migrate status、codegen verify 等子命令的自动化输出（经 scripts/fago.sh cli --json … 传递根标志）。

原生 SSO

fago-cli auth native 已提供系统浏览器PKCE、本人/设备读取、刷新和本地/RP退出的有限脚本；只在当前进程保存凭据。前置配置、三种内容协议、等待另一应用退出和失败处理见原生SSO验收客户端。

代码生成（R2 预览）

当前新增 tenant-crud-v1 可执行模板，用于明确归属为租户共享、全部业务字段经过审查且非敏感的简单资源。生成包需人工评审后接入，不自动修改已发布迁移、正式路由或工作区。默认 crud-v0 保留历史占位预览行为；它的绿色检查不能证明可执行 CRUD。R2.4受限模板已通过双库真实浏览器CRUD、分页、只读按钮和租户切换，并读回数据库确认版本/软删/审计；本地工程基线通过，见 M5 记录。

完整编排仓中使用 configs/codegen/catalog.project.json 查看配置。templateVersion 明确选择 tenant-crud-v1，表的 resourceScope 必须为 tenant-shared，业务列逐一声明 exposure: plain。支持必填 varchar（200字）、text（4000字）、bool/boolean、bigint；bigint 按十进制字符串传输。可空列、明显敏感的凭证/个人信息列、关系和归属范围规则明确拒绝或需独立设计，不能靠字段名推断。

已存在 codegen_* 元数据的数据库可先导出待编辑配置。此命令读取配置的数据库，在同一repeatable-read只读快照保存项目/表/列，不猜测公开分类；LoadProject公开契约拒绝已开始的外层事务，避免savepoint忽略隔离选项：

scripts/fago.sh codegen import --project-code <项目code> --tenant-id <所属租户ID> --format config --output .cache/imported-config.json

平台元数据显式使用 --tenant-id 0。操作者审查逻辑类型、非空语义、资源范围与字段分类后，再执行预览。preview/export/import 仅创建新目标，已有文件、目录或叶级符号链接均拒绝；文件权限0600，父目录须由操作者准备。不要覆盖旧包，后续用 diff 比较。

scripts/fago.sh codegen preview --config configs/codegen/catalog.project.json --output .cache/catalog-preview.zip
scripts/fago.sh cli --json codegen verify --zip .cache/catalog-preview.zip --r2-offline-gates

tenant-crud-v1 的离线门禁校验包结构、当前内置模板来源和权限种子，在私有 Go 宿主副本构建 MySQL/PostgreSQL 实际 API 入口，并在私有前端源码副本登记同包 API/列表/表单、执行 Vben 类型检查与生产构建。前端须已安装锁文件依赖；只复用既有依赖目录，业务源码及正式清单不写入。逐文件 SHA 证明内容完整性，执行前还须与当前受信模板重新渲染的结果一致；自行改写并重算 SHA 的包不获执行信任。

生成表单绑定独立draft，保存通过父页面请求；布尔列显式显示“是/否”，bigint保持规范十进制字符串。列表删除末页最后一行后回退有效页；只读账号可以查看数据，但不显示新增/编辑/删除按钮。页面按钮不能替代后端授权，更新/删除均携带当前版本。

生成后端复用正式认证、Origin、当前授权、统一 JSON/JWE 出口和租户写事务；版本 CAS、软删除及审计同事务提交。公开 DTO 不接受 tenant_id、删除标记或审计列；创建不接受非零 version，更新/删除须提供当前版本，冲突后不会自动重试。列表 count 与分页来自同一只读快照。代码、OpenAPI 业务 schema、两种明确方言迁移及权限/菜单种子均在同包；migration.sql.txt 只提示选取明确方言，不能直接执行。

仅对受审目录配置提供内置真实 HTTP 夹具；其他资源的类型/构建通过不代替其业务验收。本地专用 MySQL/PostgreSQL Docker 服务可用时执行：

scripts/fago.sh cli --json codegen verify --zip .cache/catalog-preview.zip --r2-offline-gates --with-generated-integration

集成入口自行分配随机专用库，不使用调用方已有 DSN。将原 ZIP 迁移与种子加入私有迁移副本的下一版本，运行同包处理器/服务；覆盖双租户 CRUD、分页、false 持久化、版本、软删除、四类撤权及审计失败回滚，采集真实响应验证同包合同。另从该库实际导入元数据、显式配置，再生成逐字节相同 ZIP。进程组关闭后删除本次专用库、源码副本、原始响应和二进制；已发布 schema 仍为 v19。错误只给固定诊断，不输出 DSN、口令、token 或原始错误链。

人工接入时，按 ZIP 的 README 放置同包后端文件、显式注册路由，将业务 SQL/权限/菜单种子作为下一版迁移评审，登记前端受信组件与路径清单，并合并 OpenAPI 的 paths/components.schemas。公共 JWE、bearer 和错误响应引用宿主定义；片段不能覆盖根合同。审计只记录生成资源 ID/版本，未知动态资源的审计投影仍按宿主规则脱敏。

历史 codegen pipeline、widgets/posts HTTP 和 crud-v0 门禁只作为旧预览工具，不作为上述真实生成验收。旧CLI编译/类型flag现也统一在私有宿主中执行，逐表保存API/Vue/Go，JSON报告实际legacy私有门禁名称；不写真实工作区或固定全局临时文件。--with-contract 检查的是已发布根合同；本轮同包实际响应合同由 --with-generated-integration 执行。

比较两次预览

同一输入的 ZIP 字节稳定，缺省模板版本明确为当前内置 crud-v0；未知版本不会悄悄回退。先分别导出到两个新文件，再只读比较（不需要运行数据库）：

scripts/fago.sh codegen preview --config configs/codegen/example.project.json --output .cache/preview-before.zip
# 修改待评审配置后选择新的文件名，不能覆盖之前的包。
scripts/fago.sh codegen preview --config configs/codegen/example.project.json --output .cache/preview-after.zip
scripts/fago.sh codegen diff --before .cache/preview-before.zip --after .cache/preview-after.zip
scripts/fago.sh cli --json codegen diff --before .cache/preview-before.zip --after .cache/preview-after.zip

diff 的相对路径按当前目录解释，可单独用于两个本地预览包。输出按路径排序，包含 added/removed/modified、SHA-256 与文本变化；旧包 manifest 的 time 字段不参与比较，生成器、模板和其他内容变化仍显示。无变化时 JSON 的 files 为 []。成功比较返回0（有差异也返回0），缺少参数返回2，包/IO失败返回1。命令不会解压到工作区、修改输入或自动应用补丁。

每个 ZIP 最大16MiB、512个文件，单文件解压最大1MiB，总解压最大16MiB；必须是完整的固定产物集，无重复、未知路径或符号链接条目。差异正文每文件最多400行/64KiB，整包最多1MiB，超限明确 patchTruncated=true 并保留摘要。截断预览不是可应用补丁，合入前须完整比较原包。拒绝非法UTF-8、ANSI/格式控制字符和裸回车；CRLF文本可以比较。比较输出可能包含生成源码，仅在有权限的本地评审环境保存。

复验多表及边界类型可使用 configs/codegen/type-matrix.project.json，先preview到新ZIP，再运行同一 --r2-offline-gates。它只做宿主类型/构建矩阵，不适用目录专用HTTP夹具。旧占位兼容矩阵为 configs/codegen/legacy-multi.project.json；两者均为验收配置，不自动注册为正式业务资源。