docs(cli): narrow the dev --fresh isolation claim to what it actually covers (#5594)

[baozhoutao]

Fixes #5594

按 PM 裁定走 issue 的处置 1:把 --fresh 的声明口径收窄到真实覆盖面。⛔ 不做处置 2(app 声明的相对路径改锚 OS_HOME)—— 那是行为变更 + 契约题("relative to cwd" 还是 "relative to this run's home"),issue 正文自己也声明不预设,要做须另立单拍板。

前提复核(先证后改)

基于 origin/main @ 2614aefb3(≥ a287d1ce1,#5601 之后)核对,注释措辞仍在:

packages/cli/src/commands/dev.ts:183
// Creates a unique scratch dir that owns ALL persistent state for
// this run: the SQLite DB (via OS_HOME → ...

前提成立。

真实覆盖面

--fresh 覆盖的是这条命令自己放置的状态:

• dev SQLite DB —— OS_HOME 下的 data/dev.db,以 OS_DATABASE_URL 发布;
• storage 上传根 —— 以 settings 服务自有的 env 名 OS_STORAGE_LOCAL_ROOT 发布(OS_STORAGE_ROOT 对任何非默认值不生效:CLI 与设置服务的 env 通道错位,schema 默认值覆盖宿主构造配置(原报「swap 假警告」归因已被 #4096 时间线推翻,警告本身是准确的) #4968 之后);
• 其他以 OS_HOME 为键的插件态。

一句话:OS_HOME 键控的框架态 + 本块向 serve 子进程发布的 env 通道。

不覆盖:app 自己声明的相对路径所指向的状态。这类路径由各自的消费者按进程 cwd 解析,而 --fresh 并不移动 cwd,于是文件落在项目树里、退出后仍在。活体样本是刻意设计而非 bug —— showcase 的 showcase-external datasource 声明 filename: '.objectstack/data/showcase_external.db',其自身注释就写明按项目 cwd 解析;因此 --fresh 跑 showcase 会留下该文件(含 -wal/-shm)。本 PR 未改动该 datasource 声明。

改动面

• packages/cli/src/commands/dev.ts
  • run() 里的 --fresh 注释块:逐条列出覆盖面,并显式点出相对路径不在承诺内 + 为什么不在这里改锚;OS_STORAGE_ROOT 对任何非默认值不生效:CLI 与设置服务的 env 通道错位,schema 默认值覆盖宿主构造配置(原报「swap 假警告」归因已被 #4096 时间线推翻,警告本身是准确的) #4968 那段关于 OS_STORAGE_LOCAL_ROOT 名字来源的准确叙述原样保留。
  • flag 声明处的注释 + --fresh 的 flag help 文本(os dev --help 的用户可见面)同步收窄。
• content/docs/deployment/cli.mdx
  • os dev 选项表里 --fresh 一行改写;
  • 表下新增一段 "What --fresh covers" Callout,写明覆盖面、不覆盖什么、以及想让 datasource 跟随 --fresh 时应声明绝对路径。
• ⛔ 未触碰 content/docs/releases/;未触碰 doctor 文件族(doctor-ledger-read-failure.test.ts 整块 7 条在 origin/main 上就是红的 —— os doctor 对坏 ledger 一行都不报，#5413/#5424 的报告面测不出来 #5612 在飞)与 packages/runtime(callData 的 delete 成功体两条路径不同形状:protocol 回 {success:true}(合规范),ObjectQL 兜底回 {deleted:true}(spec 未声明的键) #5581 在飞)。

未改 serve.ts:2987:那里是 #4968 的历史叙述,原文以过去时引用旧承诺("dev --fresh promised … uploads actually landed under the project cwd"),作为 bug 史实仍然准确,且 serve.ts 是 CLI 里最热的文件,不必为一句历史引用制造冲突面。

验证

零行为变更(只改注释、help 字符串与文档),故无新增测试;既有测试无一断言 "ALL state" 措辞(packages/cli/test/commands.test.ts 只断言 command 级 description,flag description 无 pin)。

• pnpm --filter @objectstack/cli test → Test Files 82 passed (82) / Tests 812 passed (812)
• pnpm --filter @objectstack/cli typecheck → tsc --noEmit,无输出
• node scripts/check-role-word.mjs → OK(43 baselined,无新增)
• node scripts/check-doc-authoring.mjs → 362 files clean
• node scripts/docs-audit/check-audit-scope.mjs → in sync
• node scripts/check-nul-bytes.mjs → OK(5537 files,无裸控制字节)

Changeset

带了 .changeset/dev-fresh-claim-scope.md(@objectstack/cli: patch)。虽是口径修正,但 --fresh 的 flag help 文本随包发布、用户 --help 直接可见,属用户可见变更,按 AGENTS.md 走真实 changeset 而非 skip-changeset 标签;若 PM 判定不该发版,改挂 skip-changeset 并删除该 changeset 即可。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 5, 2026 9:22pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli.

21 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/skills-reference.mdx (via packages/cli)
• content/docs/api/client-sdk.mdx (via @objectstack/cli)
• content/docs/api/data-flow.mdx (via @objectstack/cli)
• content/docs/api/environment-routing.mdx (via @objectstack/cli)
• content/docs/api/error-catalog.mdx (via @objectstack/cli)
• content/docs/automation/hook-bodies.mdx (via packages/cli)
• content/docs/deployment/backup-restore.mdx (via @objectstack/cli)
• content/docs/deployment/cli.mdx (via @objectstack/cli)
• content/docs/deployment/self-hosting.mdx (via @objectstack/cli)
• content/docs/deployment/validating-metadata.mdx (via packages/cli)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/cli)
• content/docs/kernel/runtime-services/data-service.mdx (via packages/cli)
• content/docs/kernel/runtime-services/index.mdx (via packages/cli)
• content/docs/permissions/authentication.mdx (via @objectstack/cli)
• content/docs/plugins/index.mdx (via @objectstack/cli)
• content/docs/plugins/packages.mdx (via @objectstack/cli)
• content/docs/protocol/kernel/plugin-spec.mdx (via @objectstack/cli)
• content/docs/protocol/kernel/realtime-protocol.mdx (via @objectstack/cli)
• content/docs/releases/implementation-status.mdx (via @objectstack/cli)
• content/docs/releases/v16.mdx (via @objectstack/cli)
• content/docs/releases/v17.mdx (via @objectstack/cli)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.