feat(runtime): standalone stack 分派 libsql://,经可选 Turso driver 包 (#5820)

[qq9340100]

Fixes #5820

这条路径原来是什么样

packages/runtime/src/standalone-stack.ts 的 detectDriverFromUrl() 不认 libsql://,落到末尾的 Unsupported database URL scheme throw;同文件 resolveDatabaseUrl() 却把 TURSO_DATABASE_URL 列为 URL 来源之一 —— 读得进来、认不出去。#5602 / PR #5819 让 CLI 的 os serve / os start 真的能从 libsql:// 构造 TursoDriver 之后,同一个 OS_DATABASE_URL=libsql://… 就有了两种命运:os start 正常启动,os migrate(经 createStandaloneStack,以及 migrate-occupancy-gate.ts 的 resolveStandaloneDatabase())硬失败。

前提重验(逐条实读,基线 origin/main@01faeb13a)

分诊评论的三条锚点在当前 main 上全部仍成立(行号相对 846ed1f 有漂移):

分诊记录	当前 main 实读	状态
:157 Unsupported database URL scheme throw	standalone-stack.ts:156-159	✅ 仍在
:218 ?? process.env.TURSO_DATABASE_URL?.trim()	standalone-stack.ts:218(resolveDatabaseUrl 内)	✅ 仍在
:26-28 docstring「ships separately in the ObjectStack Cloud distribution」	standalone-stack.ts:26-29	✅ 仍在

另外补两条实读,它们决定了形态:

• packages/drivers/driver-turso/ 确实在本仓(driver-turso 住在闭源 cloud 仓，却是开源 runtime 点名偏好的默认 driver — 建议把核心迁回本仓 #4645 迁回),src/index.ts:37 导出 TursoDriver —— docstring 里「ships separately」的理由已经消失,不只是描述失真;
• standalone-stack.ts:245-247 的注释写着 databaseAuthToken / OS_DATABASE_AUTH_TOKEN「preserved in the config schema ... no longer consumes them directly」—— 即 auth token 也是同一个「声明了没人读」的组合。

没有发现任何 ADR 把 standalone stack 排除在 libSQL 之外(docs/adr/ 内 grep libsql / turso 无相关裁决),所以按派工的选项 1(口径收敛)实施。

实现:与 #5819 同形态(维护者 B-lite 裁决)

• detectDriverFromUrl() 识别 libsql:// 与 http(s)://*.turso.* —— 与 CLI inferDriverTypeFromUrl() 逐字同款的两条,刻意保持一致:两个函数对同一个 OS_DATABASE_URL 回答同一个问题,分叉本身就是本单的病因;
• driver 来自可选包 @objectstack/driver-turso,在新文件 packages/runtime/src/turso-driver-factory.ts 里惰性 import(),包成 DefaultDatasourcePlugin 的 host factory —— 那个 seam 的 docstring 本来就是为「宿主的 default 需要一个开源工厂造不出的 driver(cloud 的 turso)」写的。连接路径、bootCritical fail-fast 判决、OS_ALLOW_DRIVER_CONNECT_FAILURE 逃生口、Setup → Datasources 的 retained status 全部与其他 kind 共享,只有构造不同;
• 缺包 ⇒ 响亮失败 MissingDriverPackageError,installCommand 作为数据字段(不只写在句子里),消息保留原始 import 错误;⛔ 无 SQLite 回退,理由写进消息本身(静默降级会让 os migrate 的 DDL 落到一个空的本地库,而远端 libSQL 数据原封不动 —— cli: OS_DATABASE_DRIVER=memory is advertised but serve.ts has no dispatch branch (falls through to SQLite) #3276 的账);
• 加载发生在构造 plugin 之前,所以缺包时操作者拿到的是一条清晰消息,而不是 boot later 的 connect 报错;
• Supported schemes: 列表随之更新;未知 scheme 仍然 throw(wat://nope 的 e2e 钉子 packages/cli/test/migrate-exit-code.e2e.test.ts:210 只匹配 Unsupported database URL scheme 子串,未受影响)。

TURSO_DATABASE_URL 的闭环

它一直是 resolveDatabaseUrl() 的第三顺位来源。本 PR 之后,「读得进」与「认得出」终于是同一件事:TURSO_DATABASE_URL=libsql://… 且未设 OS_DATABASE_URL 时,resolveStandaloneDatabase() 返回 { driver: 'turso' }(有钉子)。选项 2(删掉这个来源)未采纳,理由见 issue 分诊:它等于保留一个前提已不成立的排除。

authToken 的来源(实读确认后接上)

os serve 读的是 process.env.OS_DATABASE_AUTH_TOKEN || process.env.TURSO_AUTH_TOKEN(commands/serve.ts:1041),而 --database-auth-token 由 start.ts:242 / dev.ts:323 转发进 OS_DATABASE_AUTH_TOKEN。standalone stack 因此有完全对应的来源,已接上,优先级逐字对齐:cfg.databaseAuthToken → OS_DATABASE_AUTH_TOKEN → TURSO_AUTH_TOKEN(vendor 名,AGENTS.md 第 9 条明列的第三方例外)。空白值按「没有」处理,不会把 authToken: '' 递给 driver。

刻意没做的事

• 没有改 packages/runtime/package.json,因此 pnpm-lock.yaml / pnpm-workspace.yaml 零改动(锁文件独占约束)。这不是绕过声明:本仓对「可选 driver 包的动态 import」已有成例 —— service-datasource/src/default-datasource-driver-factory.ts:438 用 await import('@objectstack/driver-mongodb' as any),而 service-datasource 的 package.json 对它只有 devDependency、没有 peer 声明,靠 tsup external 兜住打包。本 PR 照抄这一形态:specifier 上的 as any 让 TS 不去解析,packages/runtime/tsup.config.ts 的 external 列表加一行让 esbuild 不去打包。测试用替身 importer,不需要装真包。若维护者希望 runtime 也像 CLI 那样显式声明 optional peer,那会动 lockfile,应当单独一单做。
• 没有把 CLI 侧的 loader 下沉合并(依赖方向只允许 cli → runtime,且会触碰 turso 迁回本仓后，CLI 的 URL→driver 解析仍对 libsql:// 抛 UnsupportedDriverError —— runtime 的 provisioning 却把 turso 排在偏好第一位，两处口径相反 #5602 刚落地的表面)—— 已另立 observation: 可选 Turso driver 的 loader 现在有两份(cli/utils/storage-driver.ts 与 runtime/turso-driver-factory.ts)—— 建议收敛到单一 owner #6268 记录。

反向验证(先预测方向,再跑)

预测:识别臂是谓词不是计数,所以标准方向 —— 临时删掉 detectDriverFromUrl() 里那两行,应有 5 个用例转红(4 个走 URL 识别的钉子 + 1 个整栈钉子),而两个走 explicit driver 的用例(databaseDriver: 'turso' / OS_DATABASE_DRIVER=turso)绕过识别,应保持绿。

实际:5 红 / 26 绿,与预测逐条一致,且红的正是 issue 描述的那句原文:

× libsql:// resolves to turso, keeps the URL, and probes no sqlite file
× an https Turso endpoint resolves to turso — the exact spelling the CLI classifies
× TURSO_DATABASE_URL now dispatches as well as resolves (the read-in/refuse-out split is gone)
× offers NO silent SQLite fallback when the package is missing
× fails with the install command instead of "Unsupported database URL scheme"

Error: [StandaloneStack] Unsupported database URL scheme: libsql://my-db.turso.io. Supported
schemes: memory://, postgres://, pg://, mongodb://, mongodb+srv://, libsql:// (optional
@objectstack/driver-turso), file:

 Test Files  1 failed (1)
      Tests  5 failed | 26 passed (31)

识别臂已还原(git diff 内不含该临时改动)。

测试

新增 packages/runtime/src/standalone-stack.libsql.test.ts(31 例),三层:

1. 识别 —— libsql / https-turso / TURSO_DATABASE_URL / explicit driver 四条正向;memory://、postgres://、postgresql://、pg://、mongodb://、mongodb+srv://、wasm-sqlite://、file:、裸路径九条阳性对照不回归;wat://nope 仍抛 Unsupported;非 Turso 的 https://example.com/db 仍抛 Unsupported(新臂是窄的);
2. 可选包两向 —— 替身 importer:在场 ⇒ 工厂只认 turso/libsql,create() 用 { url, authToken } 造出驱动、handle 的 connect/disconnect/checkHealth 可用、ownership 留默认;缺席 ⇒ MissingDriverPackageError 带 installCommand 数据字段、消息含拒绝理由与原始 import 错误、失败路径里没有任何 sqlite 形状;另有「模块解析得到但没有 TursoDriver 导出」与 CJS default 形状两例。全程不连真 Turso;
3. 整栈 —— createStandaloneStack({ databaseUrl: 'libsql://…' }) 现在不再以 Unsupported database URL scheme 收场(本工作区里走缺包臂,因为 driver-turso 刻意不是 runtime 的依赖);同一路径上 wat://nope 仍然照旧被拒。

命令与结果:

pnpm --filter @objectstack/runtime typecheck    →  tsc --noEmit,无输出
vitest run --maxWorkers=2 (packages/runtime)    →  Test Files 106 passed (106)
                                                   Tests 1537 passed (1537)
npx eslint --no-inline-config (4 个改动文件)     →  无输出,exit 0
node scripts/check-nul-bytes.mjs                →  OK (scanned 5949 tracked text files)
pnpm --filter @objectstack/runtime build        →  ESM/CJS/DTS 均 success;dist 里
                                                   import("@objectstack/driver-turso")
                                                   保持为运行期动态 import(external 生效)

另做了一次消费半径清扫:Supported schemes 字样全仓只此一处;detectDriverFromUrl / resolveStandaloneDatabase 的仓外消费者只有 cli/src/utils/migrate-occupancy-gate.ts(只读 sqliteFile,turso 恒为 null)与上面那条 e2e 钉子。

changeset

@objectstack/runtime minor —— 新增了 URL scheme 识别与一个 databaseDriver 枚举值(可授权面变大),不是纯修复,故 minor 而非 patch。

范围外发现(已查重后立单,均未认领)

• runtime(standalone-stack): mysql:// 与 #5820 的 libsql 同族 —— os migrate 抛 Unsupported scheme,而 OS_DATABASE_DRIVER 的未知值(含 mysql)静默落到 SQLite #6265 —— mysql:// 与本单 libsql 完全同形(CLI 认、standalone 不认,而共享工厂本来就能造 mysql);外加 OS_DATABASE_DRIVER 的值从来没被校验过,未知值静默落到 SQLite。concrete defect,留给 PM 分诊。
• observation: 可选 Turso driver 的 loader 现在有两份(cli/utils/storage-driver.ts 与 runtime/turso-driver-factory.ts)—— 建议收敛到单一 owner #6268 —— 可选 Turso loader 现在 cli / runtime 各一份,靠人工对齐而非结构保持一致;建议 owner 定在 runtime、CLI 薄委托。observation 类(finding,无 pm:queue)。

---

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 7, 2026 12:50pm

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/client-sdk.mdx (via packages/runtime)
• content/docs/api/index.mdx (via @objectstack/runtime)
• content/docs/api/wire-format.mdx (via @objectstack/runtime)
• content/docs/automation/hook-bodies.mdx (via @objectstack/runtime)
• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/runtime)
• content/docs/concepts/north-star.mdx (via packages/runtime)
• content/docs/data-modeling/drivers.mdx (via @objectstack/runtime)
• content/docs/deployment/index.mdx (via @objectstack/runtime)
• content/docs/deployment/production-readiness.mdx (via @objectstack/runtime)
• content/docs/deployment/single-project-mode.mdx (via @objectstack/runtime)
• content/docs/deployment/vercel.mdx (via @objectstack/runtime)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/runtime)
• content/docs/kernel/cluster.mdx (via @objectstack/runtime)
• content/docs/permissions/authentication.mdx (via @objectstack/runtime)
• content/docs/permissions/authorization.mdx (via packages/runtime)
• content/docs/plugins/packages.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/http-protocol.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/index.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/lifecycle.mdx (via @objectstack/runtime)
• content/docs/releases/implementation-status.mdx (via @objectstack/runtime)
• content/docs/releases/v17.mdx (via @objectstack/runtime)

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.