fix(cli): fail loudly when turso/libSQL is selected in the open-core CLI (#3276 follow-up)

[os-zhuang]

Stacked on #3285 (base = fix/cli-memory-driver-dispatch). It builds on the storage-driver.ts file that PR introduces. Merge #3285 first, then this retargets cleanly to main. Review just the top commit / the diff-vs-base.

Problem

The same "declared ≠ enforced" bug as #3276, for turso/libSQL:

• os dev (dev.ts:89) and os start (start.ts:100) advertise turso as a --database-driver option, and libsql:// URLs in help/examples.
• inferDriverTypeFromUrl maps libsql:// and *.turso.* URLs to driver kind turso.
• But the driver dispatch had no turso branch — so selecting it (via OS_DATABASE_DRIVER=turso, --database-driver turso, or a libsql:// URL) silently fell through to the SQLite default and ignored the requested remote libSQL connection.

Why not just "add a turso driver" (option a)

Investigated: @objectstack/driver-turso is a cloud / EE package (../cloud/packages/driver-turso) — it extends SqlDriver over @libsql/client, is composed by the cloud runtime's own kernel factory (cloud-stack.ts / environment-kernel-factory.ts do new TursoDriver({ url, authToken })), and its spec schema lives in the cloud package specifically to keep it out of open-core @objectstack/spec. runtime/standalone-stack.ts explicitly stopped consuming its auth token. So turso is deliberately not an open-core engine — pulling it into open-core's dispatch would reintroduce the coupling the architecture removed.

Fix (option b, refined — recognize + fail loud)

• createStorageDriver throws a typed UnsupportedDriverError for turso/libsql, with an actionable message (names @objectstack/driver-turso, explains cloud/EE vs. explicit config, lists the open-core alternatives).
• serve.ts re-throws it from the driver block's catch so run()'s existing fatal handler restores output, prints the message, and exits 1 (dev AND prod) — never a silent SQLite boot.
• inferDriverTypeFromUrl keeps classifying libsql:// / *.turso.* as turso (not ''), so those URLs hit the same loud failure instead of the SQLite fall-through.
• No dev.ts / start.ts changes: turso is a real driver in the cloud distribution (which reuses these commands and documents OS_DATABASE_DRIVER=turso), so the honest fix is a clear error — not un-advertising it.

Verification

• ✅ End-to-end (real os serve on the host-config path): OS_DATABASE_DRIVER=turso and OS_DATABASE_URL=libsql://my-db.turso.io both exit 1 with the fatal message; control OS_DATABASE_DRIVER=memory still boots.
• ✅ Unit tests (storage-driver.test.ts) prove the branch goes red without it (dev→SqlDriver, prod→null) and assert the message is actionable. 18/18 in-file; 41/41 across serve/dev/storage suites.
• ✅ tsc -p tsconfig.build.json + eslint clean.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 19, 2026 4:54pm

[github-actions]

📓 Docs Drift Check

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

17 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/self-hosting.mdx (via @objectstack/cli)
• content/docs/getting-started/cli.mdx (via @objectstack/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/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)

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.