Refactor single-project plugin and server configuration

- Updated the single-project plugin to support project mode with a new identity seeding mechanism.
- Removed deprecated API routes and consolidated server logic for clarity.
- Introduced a new configuration file for ObjectStack server to manage boot modes and environment variables.
- Added a new utility for ensuring local identity in project mode, handling organization and project seeding.
- Deleted obsolete server entry points and API routes to streamline the codebase.

Author: hotlong

CHANGELOG.md

@@ -8,6 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Changed
+- **`OBJECTSTACK_MODE` redefined into three values** — Boot-mode selection now accepts `project` (default), `cloud`, and `standalone`. The previous semantics — where `standalone` meant "single-project local dev with full Auth + Studio" — moved under `project`. The new `standalone` value is **runtime-only**: ObjectQL + REST + Driver, no Auth, no control plane, no Studio data. Designed for embedding ObjectStack in other frameworks. Aliases `local` / `single-project` continue to map to `project`; `multi-project` continues to map to `cloud`. Default also changed: an unset `OBJECTSTACK_MODE` now resolves to `project` (was: `standalone`).
+  - **Migration:** users running with `OBJECTSTACK_MODE=standalone` and expecting Auth/Studio should switch to `OBJECTSTACK_MODE=project` (or unset it).
+  - **Internals:** `apps/server/objectstack.config.ts` now drives `project` mode through `createCloudStack()` with two local SQLite files (`control.db` for the control plane and `proj_local.db` for the single project's data), instead of a separate plugin stack. `apps/server/server/single-project-plugin.ts` is reduced to (a) seeding a real `sys_organization` + `sys_project` row into the control plane via `ensure-local-identity.ts` so `KernelManager` resolves `proj_local` exactly as in cloud mode, and (b) overriding `GET /api/v1/studio/runtime-config` with `{ singleProject: true, … }`. Synthetic `/cloud/projects` rows are gone — both modes now serve real DB-backed records. `apps/studio/server/index.ts` no longer wraps the kernel app in an outer Hono router for single-project mode.
 - **`OBJECTSTACK_MODE` replaces `OBJECTSTACK_MULTI_PROJECT`** — Boot-mode selection is now driven by a single `OBJECTSTACK_MODE` variable accepting `standalone` (default) or `cloud`. The legacy `OBJECTSTACK_MULTI_PROJECT=true` flag remains as a deprecated alias (with a one-shot console warning at boot) and will be removed in the next major release. Root `pnpm dev` now starts in standalone mode; use `pnpm dev:cloud` for the multi-project / control-plane shape. Updated `apps/server/objectstack.config.ts`, `apps/studio/server/index.ts`, `.env.example`, the cloud-deployment guide, and the north-star env table.
 
 ### Added

apps/server/objectstack.config.ts

@@ -8,43 +8,47 @@
  * ## Boot modes
  *
  * Selected via the `OBJECTSTACK_MODE` environment variable:
- *   - `standalone` (default)  — single-project, no control plane
- *   - `cloud`                 — multi-project, control plane + per-project DBs
+ *
+ *   - `project`   (default) — local single-project deployment. Reuses the
+ *                            cloud (multi-project) plugin stack but backs
+ *                            it with two SQLite files (`control.db` for
+ *                            the control plane, `proj_local.db` for the
+ *                            single project's business data). Studio +
+ *                            Auth fully operational. Aliases: `local`,
+ *                            `single-project`.
+ *
+ *   - `cloud`              — multi-project, control-plane connected. See
+ *                            @objectstack/service-cloud for details.
+ *                            Alias: `multi-project`.
+ *
+ *   - `standalone`         — runtime-only (ObjectQL + REST + Driver). No
+ *                            authentication, no Studio, no control plane.
+ *                            For embedding in other frameworks or running
+ *                            an internal-only data API.
  *
  * The legacy flag `OBJECTSTACK_MULTI_PROJECT=true` is still honoured as a
  * deprecated alias for `OBJECTSTACK_MODE=cloud` and will be removed in a
  * future major release.
  *
- * ### Standalone mode (`OBJECTSTACK_MODE` unset or `standalone`)
- *
- * Single-project, offline-first.  No control-plane DB is required.
- * Authentication is fully real — first-run users are walked through `/setup`
- * to create the owner account; thereafter every request requires a session.
- * Required env vars:
- *   OBJECTSTACK_PROJECT_ID        — project identity (e.g. "proj_local")
- *   OBJECTSTACK_DATABASE_URL      — project business DB (file:./app.db, memory://mydb, libsql://…, https://…)
- *   OBJECTSTACK_DATABASE_AUTH_TOKEN — optional auth token for libSQL/Turso URLs
- *   OBJECTSTACK_DATABASE_DRIVER   — driver name: sqlite | memory | turso (auto-detected from URL)
- *   OBJECTSTACK_ARTIFACT_PATH     — path to compiled artifact (default: ./dist/objectstack.json)
- *   AUTH_SECRET                   — JWT signing secret (≥32 chars)
+ * ### Common env vars
  *
- * For Vercel / serverless deployments use a Turso database:
- *   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)
+ *   AUTH_SECRET               — JWT signing secret (≥32 chars)
+ *   NEXT_PUBLIC_BASE_URL      — public origin used by better-auth
+ *   OBJECTSTACK_PROJECT_ID    — local project id (default: `proj_local`)
+ *   OBJECTSTACK_ARTIFACT_PATH — compiled artifact (default: ./dist/objectstack.json)
  *
- * ### Cloud mode (`OBJECTSTACK_MODE=cloud`)
+ * ### Project / Standalone DB
  *
- * Multi-project, control-plane connected. See @objectstack/service-cloud for details.
- * Required env vars:
- *   OBJECTSTACK_DATABASE_URL      — control-plane DB URL
- *   OBJECTSTACK_DATABASE_AUTH_TOKEN — optional, for libSQL/Turso URLs
- *   AUTH_SECRET / NEXT_PUBLIC_BASE_URL — same as standalone
+ *   OBJECTSTACK_DATABASE_URL        — overrides default file SQLite path
+ *   OBJECTSTACK_DATABASE_AUTH_TOKEN — auth token for libSQL/Turso URLs
+ *   OBJECTSTACK_DATABASE_DRIVER     — driver name: sqlite | memory | turso
+ *   TURSO_DATABASE_URL / TURSO_AUTH_TOKEN — fallback aliases
  */
 
 import { resolve as resolvePath, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { mkdirSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { AppPlugin } from '@objectstack/runtime';
 import { createCloudStack } from '@objectstack/service-cloud';
 import { createSingleProjectPlugin } from './server/single-project-plugin.js';
 import { templateRegistry } from './server/templates/registry.js';
@@ -54,16 +58,24 @@ function envFlag(name: string): boolean {
     return ['1', 'true', 'yes', 'on'].includes((process.env[name] ?? '').trim().toLowerCase());
 }
 
+type Mode = 'project' | 'cloud' | 'standalone';
+
 /**
  * Resolve the deployment mode from environment.
+ *
+ * Default changed from `standalone` (legacy) to `project` (current). The
+ * legacy `standalone` semantics — single-project local dev with full
+ * Auth + Studio — moved under `project`. The new `standalone` value
+ * means runtime-only (no Auth, no Studio).
  */
-function resolveMode(): 'standalone' | 'cloud' {
+function resolveMode(): Mode {
     const raw = process.env.OBJECTSTACK_MODE?.trim().toLowerCase();
-    if (raw === 'cloud' || raw === 'multi-project' /* legacy alias */) return 'cloud';
-    if (raw === 'standalone' || raw === 'local' || raw === 'single-project') return 'standalone';
+    if (raw === 'cloud' || raw === 'multi-project') return 'cloud';
+    if (raw === 'standalone') return 'standalone';
+    if (raw === 'project' || raw === 'local' || raw === 'single-project') return 'project';
     if (raw && raw.length > 0) {
         // eslint-disable-next-line no-console
-        console.warn(`[objectstack] Unknown OBJECTSTACK_MODE=${raw}; falling back to "standalone".`);
+        console.warn(`[objectstack] Unknown OBJECTSTACK_MODE=${raw}; falling back to "project".`);
     }
     if (envFlag('OBJECTSTACK_MULTI_PROJECT')) {
         // eslint-disable-next-line no-console
@@ -72,12 +84,10 @@ function resolveMode(): 'standalone' | 'cloud' {
         );
         return 'cloud';
     }
-    return 'standalone';
+    return 'project';
 }
 
-// ── Boot mode ─────────────────────────────────────────────────────────────────
 const mode = resolveMode();
-const isStandaloneMode = mode === 'standalone';
 
 const authSecret = process.env.AUTH_SECRET
     ?? 'dev-secret-please-change-in-production-min-32-chars';
@@ -90,33 +100,106 @@ const baseUrl = process.env.NEXT_PUBLIC_BASE_URL
         : undefined)
     ?? `http://localhost:${process.env.PORT ?? 3000}`;
 
-// ── STANDALONE MODE ───────────────────────────────────────────────────────────
-
+const serverDir = dirname(fileURLToPath(import.meta.url));
 const localProjectId = process.env.OBJECTSTACK_PROJECT_ID ?? 'proj_local';
 const localArtifactPath = process.env.OBJECTSTACK_ARTIFACT_PATH
-    ?? resolvePath(dirname(fileURLToPath(import.meta.url)), 'dist/objectstack.json');
+    ?? resolvePath(serverDir, 'dist/objectstack.json');
+
+// ── PROJECT MODE ─────────────────────────────────────────────────────────────
+//
+// Reuses `createCloudStack()` with two local SQLite files. The frontend
+// detects single-project mode via the `singleProject: true` payload from
+// `single-project-plugin`; everything else (auth, control plane,
+// kernel resolution, REST routing) follows the cloud code path.
+
+async function createProjectStack() {
+    const dataDir = resolvePath(serverDir, '.objectstack/data');
+    mkdirSync(dataDir, { recursive: true });
+
+    const controlDbUrl = `file:${resolvePath(dataDir, 'control.db')}`;
+    const projectDbUrl = `file:${resolvePath(dataDir, 'proj_local.db')}`;
+
+    const stack = await createCloudStack({
+        authSecret,
+        baseUrl,
+        controlDriverUrl: controlDbUrl,
+        appBundles: createFsAppBundleResolver(),
+        // Project-mode per-project plugins. Identical to the cloud default
+        // except for the AppPlugin tail — we eagerly load the local
+        // artifact bundle (if present) so the single project picks up
+        // schema definitions without needing a control-plane app row.
+        basePlugins: async ({ projectId }: { projectId: string }) => {
+            const { ObjectQLPlugin } = await import('@objectstack/objectql');
+            const { MetadataPlugin } = await import('@objectstack/metadata');
+            const { createTenantPlugin } = await import('@objectstack/service-tenant');
+            const { AuthPlugin } = await import('@objectstack/plugin-auth');
+            const { SecurityPlugin } = await import('@objectstack/plugin-security');
+            const { AuditPlugin } = await import('@objectstack/plugin-audit');
+            const { AppPlugin } = await import('@objectstack/runtime');
 
-async function buildStandalonePlugins() {
+            let artifactBundle: any = null;
+            try {
+                const raw = await readFile(localArtifactPath, 'utf8');
+                const parsed = JSON.parse(raw);
+                artifactBundle = (parsed?.schemaVersion != null && parsed?.metadata !== undefined)
+                    ? parsed.metadata
+                    : parsed;
+            } catch {
+                // First boot before `objectstack build` — AppPlugin skipped.
+            }
+
+            const plugins: any[] = [
+                new ObjectQLPlugin({ environmentId: projectId }),
+                new MetadataPlugin({
+                    watch: false,
+                    environmentId: projectId,
+                    artifactSource: { mode: 'local-file', path: localArtifactPath },
+                }),
+                createTenantPlugin({ registerSystemObjects: true }),
+                new AuthPlugin({ secret: authSecret, baseUrl }),
+                new SecurityPlugin(),
+                new AuditPlugin(),
+            ];
+            if (artifactBundle) plugins.push(new AppPlugin(artifactBundle));
+            return plugins;
+        },
+    });
+
+    // The cloud preset registers a `studio/runtime-config` route returning
+    // `{ singleProject: false }`. Hono is first-match-wins, so we drop that
+    // plugin and substitute our own which seeds local identity AND emits
+    // `{ singleProject: true, … }`.
+    const filtered = stack.plugins.filter(
+        (p: any) => p?.name !== 'com.objectstack.studio.runtime-config',
+    );
+    filtered.push(
+        createSingleProjectPlugin({
+            projectId: localProjectId,
+            projectDatabaseUrl: projectDbUrl,
+            projectDatabaseDriver: 'sqlite',
+        }),
+    );
+
+    return {
+        plugins: filtered,
+        api: stack.api,
+    };
+}
+
+// ── STANDALONE MODE ──────────────────────────────────────────────────────────
+//
+// Runtime-only: ObjectQL + Driver + REST. No Auth, no Studio, no control
+// plane. Designed for embedding ObjectStack in other frameworks or
+// internal back-end services.
+
+async function buildRuntimeOnlyConfig() {
     const { ObjectQLPlugin } = await import('@objectstack/objectql');
     const { MetadataPlugin } = await import('@objectstack/metadata');
-    const { AuthPlugin } = await import('@objectstack/plugin-auth');
-    const { DriverPlugin } = await import('@objectstack/runtime');
-
-    let artifactBundle: any = null;
-    try {
-        const raw = await readFile(localArtifactPath, 'utf8');
-        const parsed = JSON.parse(raw);
-        artifactBundle = (parsed?.schemaVersion && parsed?.metadata !== undefined)
-            ? parsed.metadata
-            : parsed;
-    } catch {
-        // Artifact not available yet (e.g. first run before compile) — AppPlugin skipped.
-    }
+    const { DriverPlugin, AppPlugin } = await import('@objectstack/runtime');
 
-    const serverDir = dirname(fileURLToPath(import.meta.url));
     const dbUrl = process.env.OBJECTSTACK_DATABASE_URL?.trim()
         || process.env.TURSO_DATABASE_URL?.trim()
-        || `file:${resolvePath(serverDir, '.objectstack/data/app.db')}`;
+        || `file:${resolvePath(serverDir, '.objectstack/data/standalone.db')}`;
     const dbAuthToken = process.env.OBJECTSTACK_DATABASE_AUTH_TOKEN?.trim()
         || process.env.TURSO_AUTH_TOKEN?.trim();
     const dbDriver = process.env.OBJECTSTACK_DATABASE_DRIVER?.trim()
@@ -128,17 +211,33 @@ async function buildStandalonePlugins() {
         driverPlugin = new DriverPlugin(new MemoryDriver());
     } else if (dbDriver === 'turso' || /^(libsql|https?):\/\//i.test(dbUrl)) {
         const { TursoDriver } = await import('@objectstack/driver-turso');
-        driverPlugin = new DriverPlugin(new TursoDriver({ url: dbUrl, authToken: dbAuthToken }) as any);
+        driverPlugin = new DriverPlugin(
+            new TursoDriver({ url: dbUrl, authToken: dbAuthToken }) as any,
+        );
     } else {
         const { SqlDriver } = await import('@objectstack/driver-sql');
         const filename = dbUrl.replace(/^file:(\/\/)?/, '');
-        const { mkdirSync } = await import('node:fs');
         mkdirSync(resolvePath(filename, '..'), { recursive: true });
         driverPlugin = new DriverPlugin(
-            new SqlDriver({ client: 'better-sqlite3', connection: { filename }, useNullAsDefault: true }),
+            new SqlDriver({
+                client: 'better-sqlite3',
+                connection: { filename },
+                useNullAsDefault: true,
+            }),
         );
     }
 
+    let artifactBundle: any = null;
+    try {
+        const raw = await readFile(localArtifactPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        artifactBundle = (parsed?.schemaVersion != null && parsed?.metadata !== undefined)
+            ? parsed.metadata
+            : parsed;
+    } catch {
+        // No artifact yet — AppPlugin skipped.
+    }
+
     const plugins: any[] = [
         driverPlugin,
         new MetadataPlugin({
@@ -147,32 +246,30 @@ async function buildStandalonePlugins() {
             artifactSource: { mode: 'local-file', path: localArtifactPath },
         }),
         new ObjectQLPlugin({ environmentId: localProjectId }),
-        new AuthPlugin({ secret: authSecret, baseUrl, plugins: { organization: true, twoFactor: true, passkeys: false, magicLink: false, oidcProvider: true, deviceAuthorization: true } }),
-        createSingleProjectPlugin({ projectId: localProjectId }),
     ];
+    if (artifactBundle) plugins.push(new AppPlugin(artifactBundle));
 
-    if (artifactBundle) {
-        plugins.push(new AppPlugin(artifactBundle));
-    }
-
-    return plugins;
-}
-
-// ── Export ────────────────────────────────────────────────────────────────────
-
-const config = isStandaloneMode
-    ? {
-        plugins: await buildStandalonePlugins(),
+    return {
+        plugins,
         api: {
             enableProjectScoping: false,
             projectResolution: 'none' as const,
         },
-    }
-    : await createCloudStack({
-        authSecret,
-        baseUrl,
-        templates: templateRegistry,
-        appBundles: createFsAppBundleResolver(),
-    });
+    };
+}
+
+// ── Export ──────────────────────────────────────────────────────────────────
+
+const config =
+    mode === 'cloud'
+        ? await createCloudStack({
+            authSecret,
+            baseUrl,
+            templates: templateRegistry,
+            appBundles: createFsAppBundleResolver(),
+        })
+    : mode === 'standalone'
+        ? await buildRuntimeOnlyConfig()
+    : await createProjectStack();
 
 export default config;