feat: Update environment variable handling for multi-project support and refine documentation

Author: hotlong

ROADMAP.md

@@ -160,7 +160,7 @@ Ordered by dependency. Items higher in the list unblock those below them.
 明确 ObjectOS 启动输入 = **Artifact**（不可变、可缓存的元数据信封）+ **Deployment Config**（业务 DB 坐标、凭据、项目身份、密钥；不进 artifact）。详见 [north-star.mdx §6.3](content/docs/concepts/north-star.mdx)。
 
 - [x] north-star.mdx §6.3 增补 Runtime Inputs 节（含本地单 project env 表 + 反模式说明）
-- [x] 实现本地单 project env 路径：`OBJECTSTACK_PROJECT_ID` / `OBJECTSTACK_DATABASE_URL` / `OBJECTSTACK_DATABASE_DRIVER` / `OBJECTSTACK_ARTIFACT_PATH`（默认 `./dist/objectstack.json`）/ `OBJECTSTACK_CLOUD_URL`（可选，留空即离线）/ `AUTH_SECRET`
+- [x] 实现本地 single / multi-project env 路径：`OBJECTSTACK_MULTI_PROJECT` / `OBJECTSTACK_PROJECT_ID` / `OBJECTSTACK_DATABASE_URL` / `OBJECTSTACK_DATABASE_DRIVER` / `OBJECTSTACK_ARTIFACT_PATH`（默认 `./dist/objectstack.json`）/ `AUTH_SECRET`
 - [x] 修复 Drift：`ProjectKernelFactory` 不再直连控制面 DB 读 `sys_project` / `sys_project_credential`，改走 Artifact API + Deployment Config 注入（`localProject` 分支）
 - [x] [apps/server/objectstack.config.ts](apps/server/objectstack.config.ts) 的 env 命名收敛到 `OBJECTSTACK_*` 前缀，`isLocalMode` 分流本地/云端路径
 

apps/server/objectstack.config.ts

@@ -7,7 +7,7 @@
  *
  * ## Boot modes
  *
- * ### Local mode  (`OBJECTSTACK_CLOUD_URL` is unset)
+ * ### Single-project mode (`OBJECTSTACK_MULTI_PROJECT` is unset or false)
  *
  * Single-project, offline-first.  No control-plane DB is required.
  * Required env vars:
@@ -22,7 +22,7 @@
  *   TURSO_DATABASE_URL            — libsql:// or https:// Turso URL (fallback alias for OBJECTSTACK_DATABASE_URL)
  *   TURSO_AUTH_TOKEN              — Turso auth token (fallback alias for OBJECTSTACK_DATABASE_AUTH_TOKEN)
  *
- * ### Cloud mode  (`OBJECTSTACK_CLOUD_URL` is set)
+ * ### Multi-project mode (`OBJECTSTACK_MULTI_PROJECT=true`)
  *
  * Multi-project, control-plane connected.
  * Required env vars:
@@ -31,7 +31,7 @@
  *   AUTH_SECRET / NEXT_PUBLIC_BASE_URL — same as local
  *
  * The control-plane driver URL accepts:
- *   - unset / `file:<path>`  → SQLite (better-sqlite3)  [default: .objectstack/data/control.db]
+ *   - unset / `file:<path>`  → local SQLite (better-sqlite3)  [default: .objectstack/data/control.db]
  *   - `libsql://…`           → libSQL / Turso
  *   - `http(s)://…`          → libSQL / sqld over HTTP
  */
@@ -50,8 +50,12 @@ import { templateRegistry } from './server/templates/registry.js';
 
 type IDataDriver = Contracts.IDataDriver;
 
-// ── Discriminator ─────────────────────────────────────────────────────────────
-const isLocalMode = !process.env.OBJECTSTACK_CLOUD_URL;
+function envFlag(name: string): boolean {
+    return ['1', 'true', 'yes', 'on'].includes((process.env[name] ?? '').trim().toLowerCase());
+}
+
+// ── Boot mode ─────────────────────────────────────────────────────────────────
+const isLocalMode = !envFlag('OBJECTSTACK_MULTI_PROJECT');
 
 const authSecret = process.env.AUTH_SECRET
     ?? 'dev-secret-please-change-in-production-min-32-chars';

apps/server/test/multi-project-e2e.test.ts

@@ -3,7 +3,7 @@
 /**
  * Multi-Project End-to-End Smoke Test
  *
- * Boots the Server in `multi-project-local` mode against an ephemeral
+ * Boots the Server in `multi-project` mode against an ephemeral
  * SQLite control DB, then exercises the complete Supabase-style flow:
  *
  *   1. Create an organization
@@ -74,6 +74,7 @@ function expect(actual: any) {
 const workdir = mkdtempSync(join(tmpdir(), 'objectstack-e2e-'));
 const controlDb = join(workdir, 'control.db');
 
+process.env.OBJECTSTACK_MULTI_PROJECT = 'true';
 process.env.OBJECTSTACK_DATABASE_URL = `file:${controlDb}`;
 process.env.AUTH_SECRET = 'e2e-test-secret-must-be-at-least-32-characters-long-xxxx';
 process.env.PORT = '0';

content/docs/concepts/north-star.mdx

@@ -406,7 +406,7 @@ ObjectOS 启动时必须从外部注入：
 | `OBJECTSTACK_DATABASE_URL` | 业务 DB URL | 例：`file:./.data/app.db` |
 | `OBJECTSTACK_DATABASE_DRIVER` | 业务 DB driver | `turso` / `sqlite` / `memory` |
 | `OBJECTSTACK_ARTIFACT_PATH` | 本地 artifact 路径 | 默认 `./dist/objectstack.json`；填了即跳过 Artifact API |
-| `OBJECTSTACK_CLOUD_URL` | 控制面 URL | 留空即「纯本地离线」；填了即「本地 ObjectOS + 远端控制面」 |
+| `OBJECTSTACK_MULTI_PROJECT` | 多项目开关 | `true` 时 `OBJECTSTACK_DATABASE_URL` 解释为控制面 DB URL |
 | `AUTH_SECRET` | 进程级密钥 | |
 
 本地模式可以用磁盘 `dist/objectstack.json` 直接喂内核（用 `commitId: 'local-dev'` 之类的占位 envelope），不需要控制面在场。

content/docs/guides/cloud-deployment.mdx

@@ -1,25 +1,24 @@
 ---
 title: Deployment & Multi-Project
-description: Run a single ObjectStack Server process in single-kernel, multi-project (local sqlite) or multi-project (remote turso) shape. Covers env vars, hostname routing, and Fly.io / Docker deployment.
+description: Run a single ObjectStack Server process in single-kernel or multi-project shape. Covers control-plane DB URLs, hostname routing, and Fly.io / Docker deployment.
 ---
 
 # Deployment & Multi-Project
 
-The same `apps/server` binary boots into one of three shapes. Which one you get
+The same `apps/server` binary boots into one of two shapes. Which one you get
 depends only on the environment variables you set — the code and Docker image
 are identical.
 
 | Shape                        | Control plane           | Projects    | Hostname routing | Typical use                          |
 | ---------------------------- | ----------------------- | ----------- | ---------------- | ------------------------------------ |
-| **single**                   | — (single kernel)       | 1           | ❌                | OSS single-project deploy, local dev |
-| **multi-project-local**      | Local SQLite file       | 1 – N       | ✅                | Self-hosted multi-project            |
-| **multi-project-remote**     | Remote Turso DB         | 1 – N       | ✅                | SaaS (Supabase-style, many replicas) |
+| **single**                   | — (single kernel)       | 1           | ❌                | OSS single-project deploy            |
+| **multi-project**            | `OBJECTSTACK_DATABASE_URL` | 1 – N    | ✅                | Framework Studio dev, self-hosted multi-project, SaaS |
 
-All three shapes reuse:
+Both shapes reuse:
 
 - `KernelManager` + `DefaultProjectKernelFactory` for per-project kernels
 - `DefaultEnvironmentDriverRegistry` for hostname → project resolution
-- `createControlPlanePlugins()` (multi-project shapes only) to install
+- `createControlPlanePlugins()` (multi-project only) to install
   tenant / auth / security / audit / package plugins onto the control DB.
 
 ---
@@ -35,22 +34,24 @@ One `ObjectKernel`, every plugin from `apps/server/objectstack.config.ts`, no
 per-project isolation. This is what you want on a laptop or for an OSS
 single-app install.
 
-Set no special env vars — the absence of `OBJECTSTACK_MULTI_PROJECT` and
-`OBJECTSTACK_CONTROL_PLANE_URL` selects this shape automatically.
+Leave `OBJECTSTACK_MULTI_PROJECT` unset (or set it to `false`) to use this
+shape.
 
 ---
 
-## Shape 2 — multi-project-local
+## Shape 2 — multi-project
 
 ```bash
 OBJECTSTACK_MULTI_PROJECT=true \
-OBJECTSTACK_CONTROL_DB=./.objectstack/data/control.db \
+OBJECTSTACK_DATABASE_URL=file:./.objectstack/data/control.db \
 AUTH_SECRET=$(openssl rand -hex 32) \
-pnpm --filter @objectstack/server dev:node
+pnpm --filter @objectstack/server dev
 ```
 
 - Control-plane tables (`sys_project`, `sys_project_credential`, …) live in
-  the SQLite file at `OBJECTSTACK_CONTROL_DB`.
+  the database configured by `OBJECTSTACK_DATABASE_URL`. Use `file:...` for a
+  local SQLite control plane, or `libsql://...` / `https://...` for a remote
+  Turso/libSQL control plane.
 - Projects are created through Studio / `POST /api/v1/cloud/projects`. Each
   project binds its own driver (sqlite / libsql / turso / postgres).
 - Incoming requests are routed to per-project kernels by the `Host` header
@@ -64,22 +65,19 @@ registered drivers: `memory`, `sqlite`, `turso` / `libsql`, or `postgres`.
 The factory switch lives in
 `packages/runtime/src/project-kernel-factory.ts::createDriver`.
 
----
-
-## Shape 3 — multi-project-remote
+For a remote shared control plane, only the URL changes:
 
 ```bash
-OBJECTSTACK_CONTROL_PLANE_URL=https://control.example.com \
-TURSO_DATABASE_URL=libsql://control.turso.io \
-TURSO_AUTH_TOKEN=... \
+OBJECTSTACK_MULTI_PROJECT=true \
+OBJECTSTACK_DATABASE_URL=libsql://control.turso.io \
+OBJECTSTACK_DATABASE_AUTH_TOKEN=... \
 AUTH_SECRET=$(openssl rand -hex 32) \
-pnpm --filter @objectstack/server dev:node
+pnpm --filter @objectstack/server dev
 ```
 
-Same code path as Shape 2, but the control-plane driver is a `TursoDriver`
-pointing at a shared remote DB. Multiple replicas of the Server can now share
-one sys_* schema; `DefaultEnvironmentDriverRegistry`'s per-replica cache is
-coherent within its TTL (5 min default), and credential rotation fires
+Multiple Server replicas can share the same remote `sys_*` schema;
+`DefaultEnvironmentDriverRegistry`'s per-replica cache is coherent within its
+TTL (5 min default), and credential rotation fires
 `envRegistry.invalidate(projectId)` so stale entries drop out within one TTL.
 
 ---
@@ -156,7 +154,7 @@ docker build -f apps/server/Dockerfile -t objectstack/server:local .
 docker run --rm -p 3000:3000 \
   -v $(pwd)/data:/data \
   -e OBJECTSTACK_MULTI_PROJECT=true \
-  -e OBJECTSTACK_CONTROL_DB=/data/control.db \
+  -e OBJECTSTACK_DATABASE_URL=file:/data/control.db \
   -e AUTH_SECRET=$(openssl rand -hex 32) \
   objectstack/server:local
 
@@ -172,11 +170,9 @@ point a wildcard DNS (`*.example.com`) at it. The container does the rest.
 
 | Variable                          | Shape(s)                  | Purpose                                                                          |
 | --------------------------------- | ------------------------- | -------------------------------------------------------------------------------- |
-| `OBJECTSTACK_MULTI_PROJECT`       | multi-project-local       | `true` opts into the SQLite-backed control plane.                                |
-| `OBJECTSTACK_CONTROL_DB`          | multi-project-local       | Filesystem path for the local control DB (default `./.objectstack/data/control.db`). |
-| `OBJECTSTACK_CONTROL_PLANE_URL`   | multi-project-remote      | Presence opts into remote-Turso control plane.                                   |
-| `TURSO_DATABASE_URL`              | multi-project-remote      | Turso URL for the control DB.                                                    |
-| `TURSO_AUTH_TOKEN`                | multi-project-remote      | Auth token for the control DB.                                                   |
+| `OBJECTSTACK_MULTI_PROJECT`       | all                       | `true` enables the multi-project control plane. Unset/false runs single-project mode. |
+| `OBJECTSTACK_DATABASE_URL`        | all                       | In `single`, the project business DB URL. In `multi-project`, the control-plane DB URL (`file:`, `libsql://`, or `https://`). |
+| `OBJECTSTACK_DATABASE_AUTH_TOKEN` | all                       | Auth token for `OBJECTSTACK_DATABASE_URL` when using libSQL/Turso.               |
 | `TURSO_ORG_NAME` + `TURSO_API_TOKEN` | multi-project (any)    | Used by `TursoProjectDatabaseAdapter` to provision per-project databases.        |
 | `OBJECTSTACK_KERNEL_CACHE_SIZE`   | multi-project (any)       | LRU size for per-project kernels (default 32, fly.toml defaults to 50).          |
 | `OBJECTSTACK_KERNEL_TTL_MS`       | multi-project (any)       | Idle eviction TTL in ms (default 900000, fly.toml defaults to 1800000).          |

package.json

@@ -5,7 +5,7 @@
   "description": "ObjectStack Protocol & Specification - Monorepo for TypeScript Interfaces, JSON Schemas, and Convention Configurations",
   "scripts": {
     "build": "turbo run build --filter=!@objectstack/docs",
-    "dev": "pnpm --filter @objectstack/server dev",
+    "dev": "OBJECTSTACK_MULTI_PROJECT=true pnpm --filter @objectstack/server dev",
     "start": "pnpm --filter @objectstack/server start",
     "studio:dev": "pnpm --filter @objectstack/studio dev",
     "studio:start": "pnpm --filter @objectstack/studio start",

packages/cli/src/commands/dev.ts

@@ -64,12 +64,6 @@ export default class Dev extends Command {
         OBJECTSTACK_PROJECT_ID: process.env.OBJECTSTACK_PROJECT_ID ?? 'proj_local',
         OBJECTSTACK_ARTIFACT_PATH: process.env.OBJECTSTACK_ARTIFACT_PATH ?? artifactPath,
       };
-      // Ensure OBJECTSTACK_CLOUD_URL is absent so apps/server boots in local mode.
-      // Only delete if the user has not explicitly set it.
-      if (!process.env.OBJECTSTACK_CLOUD_URL) {
-        delete localEnv.OBJECTSTACK_CLOUD_URL;
-      }
-
       printKV('Project ID', localEnv.OBJECTSTACK_PROJECT_ID!, '🎯');
       printKV('Artifact', path.relative(process.cwd(), localEnv.OBJECTSTACK_ARTIFACT_PATH!), '📦');
 

packages/cli/src/commands/start.ts

@@ -40,10 +40,6 @@ export default class Start extends Command {
       ...(flags.port ? { PORT: String(flags.port) } : {}),
     };
 
-    if (!process.env.OBJECTSTACK_CLOUD_URL) {
-      delete localEnv.OBJECTSTACK_CLOUD_URL;
-    }
-
     printKV('Project ID', localEnv.OBJECTSTACK_PROJECT_ID!, '🎯');
 
     const binPath = process.argv[1];