feat: refactor project mode handling and introduce boot orchestration

- Moved single-project plugin implementation to @objectstack/service-cloud.
- Enhanced CLI serve command to support booting with library based on OBJECTSTACK_MODE.
- Added utility functions for boot environment resolution and mode handling.
- Introduced boot stack orchestration to manage project, cloud, and standalone modes.
- Implemented local identity seeding for project mode with SQLite databases.
- Created file-system app bundle resolver for project artifacts.
- Established project and standalone stack factories for better modularity.
- Updated package dependencies to include zod for schema validation.

Author: hotlong

apps/server/objectstack.config.ts

@@ -13,257 +13,43 @@
  *                            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.
+ *                            single project's business data).
+ *                            Aliases: `local`, `single-project`.
+ *   - `cloud`              — multi-project, control-plane connected.
  *                            Alias: `multi-project`.
+ *   - `standalone`         — runtime-only (ObjectQL + REST + Driver).
  *
- *   - `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.
- *
- * ### Common env vars
- *
- *   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)
- *
- * ### Project / Standalone DB
- *
- *   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
+ * All boot orchestration now lives in @objectstack/service-cloud.
+ * This file only supplies the apps/server-specific knobs (templates,
+ * app bundle resolution).
  */
 
 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 { createCloudStack } from '@objectstack/service-cloud';
-import { createSingleProjectPlugin } from './server/single-project-plugin.js';
-import { templateRegistry } from './server/templates/registry.js';
+import { createBootStack } from '@objectstack/service-cloud';
 import { createFsAppBundleResolver } from './server/fs-app-bundle-resolver.js';
-
-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(): Mode {
-    const raw = process.env.OBJECTSTACK_MODE?.trim().toLowerCase();
-    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 "project".`);
-    }
-    if (envFlag('OBJECTSTACK_MULTI_PROJECT')) {
-        // eslint-disable-next-line no-console
-        console.warn(
-            '[objectstack] OBJECTSTACK_MULTI_PROJECT is deprecated. Use `OBJECTSTACK_MODE=cloud` instead.',
-        );
-        return 'cloud';
-    }
-    return 'project';
-}
-
-const mode = resolveMode();
-
-const authSecret = process.env.AUTH_SECRET
-    ?? 'dev-secret-please-change-in-production-min-32-chars';
-const baseUrl = process.env.NEXT_PUBLIC_BASE_URL
-    ?? (process.env.VERCEL_PROJECT_PRODUCTION_URL
-        ? `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`
-        : undefined)
-    ?? (process.env.VERCEL_URL
-        ? `https://${process.env.VERCEL_URL}`
-        : undefined)
-    ?? `http://localhost:${process.env.PORT ?? 3000}`;
+import { templateRegistry } from './server/templates/registry.js';
 
 const serverDir = dirname(fileURLToPath(import.meta.url));
-const localProjectId = process.env.OBJECTSTACK_PROJECT_ID ?? 'proj_local';
+const dataDir = resolvePath(serverDir, '.objectstack/data');
 const localArtifactPath = process.env.OBJECTSTACK_ARTIFACT_PATH
     ?? 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,
+const config = await createBootStack({
+    project: {
+        dataDir,
+        artifactPath: localArtifactPath,
         appBundles: createFsAppBundleResolver(),
-        // Project-mode per-project plugins. The control plane (created by
-        // `createCloudStack`'s preset) is the sole owner of identity,
-        // authentication, security, audit, tenant catalogs, and packages —
-        // their tables live in `control.db`. Each per-project kernel only
-        // registers the engines needed to materialize that project's
-        // **business data** schemas + records.
-        basePlugins: async ({ projectId }: { projectId: string }) => {
-            const { ObjectQLPlugin } = await import('@objectstack/objectql');
-            const { MetadataPlugin } = await import('@objectstack/metadata');
-            const { AppPlugin } = await import('@objectstack/runtime');
-
-            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 },
-                }),
-            ];
-            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 { DriverPlugin, AppPlugin } = await import('@objectstack/runtime');
-
-    const dbUrl = process.env.OBJECTSTACK_DATABASE_URL?.trim()
-        || process.env.TURSO_DATABASE_URL?.trim()
-        || `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()
-        || (/^(libsql|https?):\/\//i.test(dbUrl) ? 'turso' : 'sqlite');
-
-    let driverPlugin: any;
-    if (dbDriver === 'memory' || dbUrl.startsWith('memory://')) {
-        const { InMemoryDriver: MemoryDriver } = await import('@objectstack/driver-memory');
-        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,
-        );
-    } else {
-        const { SqlDriver } = await import('@objectstack/driver-sql');
-        const filename = dbUrl.replace(/^file:(\/\/)?/, '');
-        mkdirSync(resolvePath(filename, '..'), { recursive: true });
-        driverPlugin = new DriverPlugin(
-            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({
-            watch: false,
-            environmentId: localProjectId,
-            artifactSource: { mode: 'local-file', path: localArtifactPath },
-        }),
-        new ObjectQLPlugin({ environmentId: localProjectId }),
-    ];
-    if (artifactBundle) plugins.push(new AppPlugin(artifactBundle));
-
-    return {
-        plugins,
-        api: {
-            enableProjectScoping: false,
-            projectResolution: 'none' as const,
-        },
-    };
-}
-
-// ── Export ──────────────────────────────────────────────────────────────────
-
-const config =
-    mode === 'cloud'
-        ? await createCloudStack({
-            authSecret,
-            baseUrl,
-            templates: templateRegistry,
-            appBundles: createFsAppBundleResolver(),
-        })
-    : mode === 'standalone'
-        ? await buildRuntimeOnlyConfig()
-    : await createProjectStack();
+    },
+    cloud: {
+        templates: templateRegistry,
+        appBundles: createFsAppBundleResolver(),
+    },
+    standalone: {
+        artifactPath: localArtifactPath,
+        databaseUrl: process.env.OBJECTSTACK_DATABASE_URL
+            ?? `file:${resolvePath(dataDir, 'standalone.db')}`,
+    },
+});
 
 export default config;

apps/server/server/ensure-local-identity.ts

@@ -1,107 +1,11 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * Idempotent control-plane seed for **project** mode.
- *
- * In project mode we reuse the cloud (multi-project) plugin stack but back it
- * with two local SQLite files:
- *
- *   - `control.db`     — control plane (sys_organization, sys_project, …)
- *   - `proj_local.db`  — the single project's business database
- *
- * For `KernelManager` (cloud factory) to resolve `proj_local`, the control
- * plane must contain a real `sys_project` row whose `database_url` points at
- * `proj_local.db`. This helper performs that seed idempotently on every
- * boot, so the project-mode code path is identical to cloud after the first
- * request — no synthetic project rows, no special branches in the dispatcher.
+ * Re-export shim. Implementation lives in `@objectstack/service-cloud`.
  */
-
-export const LOCAL_ORG_ID = 'org_local';
-export const LOCAL_PROJECT_ID = 'proj_local';
-
-export interface LocalIdentityOptions {
-    /** ObjectQL service handle bound to the control-plane DB. */
-    objectql: any;
-    /** Override the default `org_local` identifier. */
-    orgId?: string;
-    /** Override the default `proj_local` identifier. */
-    projectId?: string;
-    /** Display name for the seeded organization. */
-    orgName?: string;
-    /** Project DB URL written to `sys_project.database_url`. */
-    projectDatabaseUrl: string;
-    /** Project DB driver name (e.g. `sqlite`, `turso`). */
-    projectDatabaseDriver: string;
-}
-
-/**
- * Insert the local org + project rows if they don't yet exist. Safe to call
- * on every boot — uses `find` with an exact-id filter for the existence
- * check.
- */
-export async function ensureLocalIdentity(opts: LocalIdentityOptions): Promise<void> {
-    const {
-        objectql,
-        orgId = LOCAL_ORG_ID,
-        projectId = LOCAL_PROJECT_ID,
-        orgName = 'Local',
-        projectDatabaseUrl,
-        projectDatabaseDriver,
-    } = opts;
-
-    if (!objectql) return;
-    const now = new Date().toISOString();
-
-    // ── Organization ─────────────────────────────────────────────────────
-    let existingOrg = await safeFind(objectql, 'sys_organization', orgId);
-    if (!existingOrg?.length) {
-        await safeInsert(objectql, 'sys_organization', {
-            id: orgId,
-            name: orgName,
-            slug: orgId,
-            created_at: now,
-            updated_at: now,
-        });
-    }
-
-    // ── Project ──────────────────────────────────────────────────────────
-    let existingProject = await safeFind(objectql, 'sys_project', projectId);
-    if (!existingProject?.length) {
-        await safeInsert(objectql, 'sys_project', {
-            id: projectId,
-            organization_id: orgId,
-            display_name: orgName,
-            is_default: true,
-            is_system: false,
-            plan: 'free',
-            status: 'active',
-            created_by: 'system',
-            database_url: projectDatabaseUrl,
-            database_driver: projectDatabaseDriver,
-            created_at: now,
-            updated_at: now,
-        });
-    }
-}
-
-async function safeFind(objectql: any, name: string, id: string): Promise<any[] | null> {
-    try {
-        const result = await objectql.find(name, { filters: [['id', '=', id]], top: 1 });
-        // Some ObjectQL implementations wrap results in `{ value }`.
-        const rows = (result && (result as any).value) ?? result;
-        return Array.isArray(rows) ? rows : [];
-    } catch (err: any) {
-        // eslint-disable-next-line no-console
-        console.warn(`[ensureLocalIdentity] find ${name} failed:`, err?.message ?? err);
-        return null;
-    }
-}
-
-async function safeInsert(objectql: any, name: string, doc: Record<string, unknown>): Promise<void> {
-    try {
-        await objectql.insert(name, doc);
-    } catch (err: any) {
-        // eslint-disable-next-line no-console
-        console.warn(`[ensureLocalIdentity] insert ${name} failed:`, err?.message ?? err);
-    }
-}
+export {
+    ensureLocalIdentity,
+    LOCAL_ORG_ID,
+    LOCAL_PROJECT_ID,
+} from '@objectstack/service-cloud';
+export type { LocalIdentityOptions } from '@objectstack/service-cloud';