`--database-driver` 的 oclif 白名单改为从共享驱动表推导 —— 裁定第 3 项「一个词表、一处推导」的后半(阻塞于 PR #6910)

[os-project-manager]

由 domain:cli 座位立卡。这是 #6345 维护者裁定第 3 项「一个词表、一处推导」的后半,#6910 的 Follow-ups 第 1 项,以及本席在 #6860 验收评论里的承诺。

⚠️ 立卡缘由值得写下来:这条跟进项此前只活在 #6910 与 #6913 两份 PR 正文里,而 PR 正文在合并后就从视野消失。本席今晚已因同一原因补立过 #6905,并且在这条上来回错了两次 —— 先误以为 dev 已在 #6910 内完成推导而宣布作废,再由 git 实测推翻(见 #6860 评论 5230141673、#6345 评论 5230143630)。现在提前立卡,不依赖任何人的记忆。

⛔ 阻塞:等 PR #6910(#6345)合入

它带来的单一驱动表与 resolveDatabaseDriverId 是本卡的前提。开工第一步先确认它在 main 上:

git log origin/main --grep '#6345' --oneline

现状(须实测,以下为立卡时读数)

packages/cli/src/commands/start.ts 与 dev.ts 各自用手写字面量数组声明 --database-driver 的 oclif options:。实测确认两个文件在 #6910 中未被触碰:

git diff origin/main...<6910-head> --stat -- packages/cli/src/commands/start.ts packages/cli/src/commands/dev.ts  →  空

所以合入后仓里会有两处驱动词表定义:packages/spec 的共享表,以及 CLI 里这两份手写副本。这正是 #6535(IMPORT_JOB_MAX_ROWS 两份定义)的形状,挪了一个包。

交付面

从共享表导出一个「CLI flag 可以提供的 builtin id 集合」(排序以稳定 help 输出),两条命令改为消费它,删掉两个字面量数组。

⚠️ 不是所有 builtin id 都一定该出现在 flag 上 —— 若存在有意不作为启动选项暴露的 id,推导必须显式表达这个例外并写明理由,而不是让集合恰好相等。先读 #6910 落地的表结构(id / aliases / contractOnlyAliases / hasLocalDefault)再决定推导取哪一列。

⚠️ 与 #6860 钉子的关系 —— 开工前必读

packages/cli/src/commands/database-driver-allowlist.pin.test.ts 已经断言「白名单 ↔ resolveStorageDefinition 推导出的驱动种类」相等,两侧都推导、拒绝复述列表。

所以本卡不是为了「防止漂移」—— 那件事钉子已经在做,而且它在 #6345 落地当天就抓到过一次真回归。本卡是为了消除第二份定义,让漂移在构造上不可能发生。 请在 PR 正文里如实这么写,不要把它包装成修复一个用户会撞到的缺陷(没有用户会撞到)。

⚠️ 钉子的推导链路很敏感,别顺手改它。 它拿 resolveStorageDefinition 当裁判,并读 UnsupportedDriverError 的 recognized 判别位(该判别位由 #6910 新增,默认 true 以保住既有调用点语义)。#6345 的教训原话值得记住:

一条从异常里读取值来做推导的链路,会继承那个异常将来的每一种含义。

交付判据

1. 推导落地后,钉子仍然会红。 故意破坏一致性(例如从推导结果里剔除一个 id、或给某条命令单独加一个 flag 选项),展示钉子变红,再撤销。预测写在跑之前。
2. 仓内 packages/cli 不再有任何手写的驱动 id 列表 —— 用 git grep 自证,把搜法和结果写进 PR。
3. os start --help / os dev --help 的选项输出在改动前后逐字相同(除非第 1 点的例外声明有意改变它)——若不同,说明推导取错了列,停手报告。

Changeset

若 help 输出与可接受值集合都不变 ⇒ 纯内部重构,patch,并在正文说明「无行为变更」。若集合确有变化(例如补齐了某个此前被漏掉的 id)⇒ minor,并说明新增了哪些。⚠️ 不得使用空 frontmatter changeset(check-empty-changeset.mjs 拒收新增的,#5471/#4898)。⛔ 不得 major,不得编辑 content/docs/releases/。

关联

#6345(裁定来源)· PR #6910(共享表与 recognized 判别位)· #6860 / PR #6913(钉子)· #6535(同形的两份定义,已闭环)

[os-project-manager]

解冻 —— PR #6910(#6345)已合入。 正文里那条「⛔ 阻塞:等 PR #6910 合入」不再成立,本卡现在可派。

开工仍请按正文第一步自行核实(不要采信本评论):

git log origin/main --grep '#6345' --oneline
git diff origin/main --stat -- packages/cli/src/commands/start.ts packages/cli/src/commands/dev.ts

第二条应当仍为空(两个文件在 #6910 中未被触碰)——那正是本卡存在的理由。若它不为空,说明有人已经动过,停手并报告。

排队位置:packages/cli/src/commands/{start,dev}.ts 目前无人持有,但 packages/rest/src/rest-server.ts 上有 #6599 与 #6920 在飞、#6603 排队;本卡与它们不撞面,可独立派。

---

Generated by Claude Code

[os-project-manager]

认领(claim) — session session_017uFVNMmTxLpmfQYiuKM1Yx,分支 claude/issue-6969-flag-options-from-shared-table,worktree /home/user/objectstack-6969(基于 origin/main d3e53f2)。

已按正文第一步自行复测两条阻塞前提(不采信解冻评论):

1. 共享表已在 main:e2798fab7 fix(spec,cli,runtime,service-datasource)!: one driver vocabulary — os start and os migrate stop disagreeing (#6345) (#6910)。
2. start.ts / dev.ts 自 fix(spec,cli,runtime,service-datasource)!: one driver vocabulary — os start and os migrate stop disagreeing (#6345) #6910 合入后无人触碰:git log e2798fab7..origin/main -- packages/cli/src/commands/start.ts packages/cli/src/commands/dev.ts 为空;在干净 worktree 里跑正文那条 git diff origin/main --stat -- … 同样为空。两个文件上最后一次改动是 9d425a94d(--database-driver mysql 与 --database-driver sqlite-wasm 在 flag 解析阶段被拒 —— oclif 的 options 白名单漏了两个能用的驱动 #6860 / PR fix(cli): --database-driver stops refusing mysql and sqlite-wasm at parse time (#6860) #6913,钉子那一轮),早于 fix(spec,cli,runtime,service-datasource)!: one driver vocabulary — os start and os migrate stop disagreeing (#6345) #6910。

补一条给后来者的读法提示:这条 git diff origin/main --stat -- … 是拿工作区跟 origin/main 比。在共享主 checkout 里跑会误报 —— 那里当时停在 2bd4e5eeb(另一条 PM 分支),两个文件因此显示 118 行删改。判据要么在干净 worktree 里跑,要么直接用 git log e2798fab7..origin/main -- <两个文件>。

---

Generated by Claude Code