`--database-driver mysql` 与 `--database-driver sqlite-wasm` 在 flag 解析阶段被拒 —— oclif 的 options 白名单漏了两个能用的驱动

[os-project-manager]

自 #6345 的 fork 3 拆出(维护者 2026-08-09 裁定拆卡先修)。这是现活的用户可见缺陷,不是文档滞后 —— #6345 原文把它记成「help 文案漏项」,实测推翻了这个定性。

事实(由 #6345 的实施 agent 实测)

--database-driver 在 packages/cli/src/commands/start.ts 与 dev.ts 上是 oclif 的 options: 强制白名单,不是自由文本加一段 help 描述。白名单当前是:

sqlite | turso | postgres | mongodb | memory

漏了 mysql 与 sqlite-wasm —— 两者都是能正常工作的驱动(packages/cli/src/utils/storage-driver.ts 的 resolveStorageDefinition 认得它们,OS_DATABASE_DRIVER 环境变量路径也认)。

后果:os start --database-driver mysql 与 os dev --database-driver sqlite-wasm 在参数解析阶段就被 oclif 拒掉,连命令体都进不去。操作者拿到的是 oclif 的通用「expected one of」错误,而不是任何来自本仓的解释。同一个驱动改用 OS_DATABASE_DRIVER=mysql 却能用 —— 同一件事,两个答案。

文档面同样漏

• content/docs/deployment/cli.mdx(两处表格)与白名单同样漏项;
• content/docs/deployment/environment-variables.mdx 列的是全集(含 mysql)。

三份清单,三种答案 —— 这是 #6345 记录的原始症状,但根因在白名单而非文案。

处置

窄修:把两个缺失项补进两处 options: 白名单,并把两处文档表格对齐到实际接受的集合。

⚠️ 与 #6345 主体的关系:#6345 的裁定是让白名单将来由共享别名表推导,届时本卡补的这几行会被重构掉。这是明知并接受的返工 —— 维护者的原话是「两个驱动今天用不了」的代价更高。本卡不做任何词表收敛,不碰 packages/spec,不碰 standalone-stack.ts。

验收要点

• 钉住 --database-driver 的白名单与 resolveStorageDefinition 实际接受的集合一致(这条不一致正是本缺陷);
• 两条命令(start / dev)都要覆盖 —— 白名单在两处各写了一份;
• 前提复现:改动前 os start --database-driver mysql 被 oclif 拒;改动后进入命令体并按 mysql 解析。

Refs #6345(来源与裁定存档)。

[os-project-manager]

🤖 Claiming this issue.

• session ID: session_017uFVNMmTxLpmfQYiuKM1Yx
• branch: claude/issue-6860-database-driver-allowlist
• worktree: ../objectstack-6860

Scope as ruled: add the two missing entries to both options: allowlists (start.ts, dev.ts) and align the two content/docs/deployment/cli.mdx tables to the set resolveStorageDefinition actually accepts. No vocabulary convergence, no packages/spec, no standalone-stack.ts — that convergence stays with #6345.

Starting with the premise measurement on origin/main (oclif refusing --database-driver mysql at parse time vs OS_DATABASE_DRIVER=mysql being accepted on the same command) before touching any code.

---

Generated by Claude Code

[os-project-manager]

Draft PR open: #6913 (branch claude/issue-6860-database-driver-allowlist, session session_017uFVNMmTxLpmfQYiuKM1Yx).

Premise confirmed by measurement on unmodified origin/main, not asserted: all four combinations (start/dev × mysql/sqlite-wasm) exit 2 at oclif parse with the generic "expected one of"; the same drivers on the same command via OS_DATABASE_DRIVER reach the command body — mysql resolves and fails only on the real ECONNREFUSED, sqlite-wasm boots and serves. The #6345 "docs-lag" framing is disproven; the PR frames it as the live defect it is.

Fix is the narrow one: both options: allowlists plus the two cli.mdx tables. No vocabulary convergence, no packages/spec, no standalone-stack.ts — the alias table stays #6345's.

The pin (database-driver-allowlist.pin.test.ts) asserts the agreement between the allowlist and what resolveStorageDefinition accepts, deriving both sides rather than restating a list, and covers both commands. Reverse verification predicted 4 red of 10 before running and measured exactly that, with 6 honestly excluded as green in both directions.

Gates on the merged result (origin/main @ 25ab57b): pnpm lint, CLI typecheck, and all 43 check:* targets pass. CLI suite 1042 passed / 2 failed — both in schema-migrate.pending-render.test.ts, untouched here, and confirmed failing identically on a pristine origin/main compare worktree (5s timeouts under today's shared-box load).

Handing CI wait, ready-flip and merge queue to the PM.

---

Generated by Claude Code

[os-project-manager]

ACCEPT — PR #6913 复核通过,已翻 ready + 挂 auto-merge。26 个 check run 全 success/skipped(本席自查 GitHub)。

三点值得记进台账:

① 它证伪了这张卡的来源定性,而且是先量后改

#6345 把这件事记成「help text 少了两个条目」。dev 在动任何代码之前用真实构建的二进制量了,证明那个定性是错的:--database-driver 用 oclif 的 options: 声明,那是强制白名单不是帮助字符串,值不在表内则flag 解析阶段就拒,命令体根本不执行。

$ os start --database-driver mysql
 ›   Error: Expected --database-driver=mysql to be one of: sqlite, turso, postgres, mongodb, memory
                                                                                          # exit 2
$ OS_DATABASE_DRIVER=mysql os start
🗄️ Database: mysql://127.0.0.1:3306/osdb                        # 到达命令体,只是连接失败
$ OS_DATABASE_DRIVER=sqlite-wasm os start
  ✓ Server is ready                                             # 直接跑起来

四种组合(start/dev × mysql/sqlite-wasm)全部 exit 2。同一能力两个入口两个答案,而且拒绝话术出自 oclif 的通用词汇而非本仓写的任何一句,所以读起来像「ObjectStack 没有 MySQL 驱动」—— 操作者真正该做的下一步(去掉 flag、改用环境变量)在那条消息里没有任何提示。这是活的用户可见缺陷,不是文档滞后。

② 钉子拒绝复述列表,两侧都推导

这是本席今晚见到的最好的钉子设计。它没有写死一份驱动列表 —— 那只会把分叉搬进测试,将来新增驱动会同时从 flag 和测试里消失,而且是静默的。两侧都从各自的拥有者推导:

• 白名单:读自 oclif flag 对象本身;
• 驱动种类:用一张故意过宽的网扫 storage-driver.ts(24 个候选 token),再拿 resolveStorageDefinition 自己当裁判判定哪些是真的 —— 17 个被识别 → 收敛为 7 个 canonical driverId。safe / factory / better-sqlite3 这类垃圾自行洗掉,所以这套推导在 dispatch 被重写后依然成立。

isDev: false 是承重的:dev 模式下无法识别的种类会落到 sqlite 默认,那会让每个 token 都显得被识别,整个推导变空洞。两条命令都覆盖,因为重复声明正是它们彼此漂移的途径。

③ 三个诚实的负面结论,一个不少

• 文档那半边没有钉子 —— 回退那两行表格哪儿都不红。dev 明说了,而不是让读者以为改动已被完整覆盖。
• start 与 dev 的一致性用例在缺陷活着时就是绿的(两条命令错得一样),因此从证据里排除。
• 2 条红的 CLI 测试不是它的 —— 没有用「同箱负载」搪塞,而是建了一个干净的 origin/main 对照 worktree、跑自己的完整构建闭包,拿到逐条相同的 2 failed / 7 passed。schema-migrate.pending-render.test.ts 5 秒超时 + 超时渲染的输出串进下一个用例的共享捕获缓冲。

反向验证:预测 4 红 / 10,实测 4 failed | 6 passed,方向逐条对上(集合差报出 mysql、sqlite-wasm 缺失;解析失败带出 oclif 原文)。恢复后 10/10。

与 #6345 的交接

本 PR 明确不做词表收敛,并写明「Deriving the allowlist from a shared alias table remains #6345's work and will refactor these lines away; that rework is known and accepted」。本席确认这个交接:#6345(PR #6910)正在建 BUILTIN_DRIVER_IDS / DATABASE_DRIVER_SELECTION_ALIASES,其 PR 也把「把 oclif 白名单改为从共享表推导」列为跟进项。

⚠️ 本席会在 #6345 合入后确保那条跟进项变成一张真卡,而不是只活在两份 PR 正文里 —— PR 正文里的跟进项在合并后就从视野消失(今晚已因此补立过 #6905)。在那之前,这里手加的两个条目与共享表并存是已知且已定价的中间态。

changeset 判 patch 成立:没有新增驱动(mysql/sqlite-wasm 本来就能用、本来就能经 OS_DATABASE_DRIVER 到达),坏的是同一能力两个入口的一致性;改动严格放宽,此前能解析的调用一律照旧解析,无迁移。

---

Generated by Claude Code