feat: add empty-boot mode and OS_HOME to objectstack start

os-zhuang · os-zhuang · commit 7d0802b3b45a · 2026-05-26T09:26:08.000+08:00
diff --git a/packages/cli/src/commands/serve.ts b/packages/cli/src/commands/serve.ts
@@ -241,21 +241,33 @@ export default class Serve extends Command {
     // `dist/objectstack.json`.
     const configMissing = !fs.existsSync(absolutePath);
     let useArtifactFallback = false;
+    let useEmptyBoot = false;
     if (configMissing) {
       const { resolveDefaultArtifactPath } = await import('@objectstack/runtime');
       const artifactSource = resolveDefaultArtifactPath();
       if (!artifactSource) {
-        printError(`Configuration file not found: ${absolutePath}`);
-        console.log(chalk.dim('  Hint: Run `objectstack init` to create a new project,'));
-        console.log(chalk.dim('        or run `objectstack build` first, or set OS_ARTIFACT_PATH.'));
-        this.exit(1);
+        // Quick-start mode: `objectstack start` lets the user boot an
+        // empty kernel with no config and no artifact, then install apps
+        // from the marketplace via Studio. The CLI signals this by
+        // setting OS_BOOT_EMPTY=1 in the child env.
+        if (process.env.OS_BOOT_EMPTY === '1') {
+          useEmptyBoot = true;
+        } else {
+          printError(`Configuration file not found: ${absolutePath}`);
+          console.log(chalk.dim('  Hint: Run `objectstack init` to create a new project,'));
+          console.log(chalk.dim('        `objectstack start` to boot an empty kernel against your marketplace,'));
+          console.log(chalk.dim('        or run `objectstack build` first / set OS_ARTIFACT_PATH.'));
+          this.exit(1);
+        }
       }
       useArtifactFallback = true;
     }
 
     // Quiet loading — only show a single spinner line
     console.log('');
-    if (useArtifactFallback) {
+    if (useEmptyBoot) {
+      console.log(chalk.dim('  No objectstack.config.ts or artifact found — booting empty kernel...'));
+    } else if (useArtifactFallback) {
       console.log(chalk.dim('  No objectstack.config.ts found — booting from artifact (default host)...'));
     } else {
       console.log(chalk.dim(`  Loading ${relativeConfig}...`));
@@ -360,8 +372,13 @@ export default class Serve extends Command {
           // Artifact-only boot — no objectstack.config.ts authored.
           // Always use the default-host helper which is standalone-only
           // and never depends on @objectstack/service-cloud.
+          //
+          // When `useEmptyBoot` is set the user asked for a quick-start
+          // ("objectstack start" with nothing to load); skip the
+          // "missing artifact" error and assemble a bare kernel that
+          // can later install marketplace apps at runtime.
           const { createDefaultHostConfig } = await import('@objectstack/runtime');
-          const bootResult = await createDefaultHostConfig();
+          const bootResult = await createDefaultHostConfig({ requireArtifact: !useEmptyBoot });
           config = { ...originalConfig, ...bootResult } as any;
         } else if (resolvedMode === 'standalone') {
           const { createStandaloneStack } = await import('@objectstack/runtime');
diff --git a/packages/cli/src/commands/start.ts b/packages/cli/src/commands/start.ts
@@ -3,45 +3,75 @@
 import { Command, Flags } from '@oclif/core';
 import { spawn } from 'child_process';
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import { printHeader, printKV, printStep, printError } from '../utils/format.js';
 
+/**
+ * `objectstack start` — zero-config quick boot.
+ *
+ * Three escalating modes, picked automatically:
+ *
+ *   1. **Empty boot** (no artifact, no config in cwd)
+ *      Boots a bare kernel with Studio mounted at `/_studio/`. The user
+ *      can then browse the marketplace and install apps into the home
+ *      directory at runtime. Perfect for "I just want to try it".
+ *
+ *   2. **Artifact boot** (an `objectstack.json` is reachable)
+ *      Boots from the compiled artifact, same as today.
+ *
+ *   3. **Explicit overrides** (`--artifact`, `--database`, ...)
+ *      Highest precedence — the user is in control.
+ *
+ * The HOME directory (default `~/.objectstack`) is where the default
+ * sqlite database, downloaded marketplace apps and plugin cache all live
+ * — independent of the current working directory, so the same `os start`
+ * gives you the same instance no matter where you run it.
+ */
 export default class Start extends Command {
-  static override description = 'Serve the pre-compiled artifact in production mode (no objectstack.config.ts required)';
+  static override description = 'Quick-start an ObjectStack server (auto-falls back to an empty kernel with Studio + marketplace when no artifact is present)';
 
   static override examples = [
     '<%= config.bin %> start',
+    '<%= config.bin %> start --home ~/my-objectstack',
     '<%= config.bin %> start --artifact ./build/myapp.json',
     '<%= config.bin %> start --artifact https://cdn.example.com/app.json --port 8080',
     '<%= config.bin %> start --database file:./data/prod.db',
     '<%= config.bin %> start --database postgres://user:pass@host:5432/mydb',
     '<%= config.bin %> start --database libsql://my-db.turso.io --database-auth-token $TURSO_TOKEN',
-    '<%= config.bin %> start --auth-secret $(openssl rand -hex 32) --ui',
+    '<%= config.bin %> start --no-ui',
   ];
 
   static override flags = {
     // Server
     port: Flags.integer({ char: 'p', description: 'Port to listen on (overrides $PORT, default 3000)' }),
     ui: Flags.boolean({
-      description: 'Mount Studio / Account / Console portals at /_studio/, /_account/, /_console/ (off by default in production)',
+      description: 'Mount Studio / Account / Console portals at /_studio/, /_account/, /_console/ (default: true so you can install marketplace apps)',
+      default: true,
+      allowNo: true,
     }),
     verbose: Flags.boolean({ char: 'v', description: 'Verbose output' }),
 
+    // Home directory — where persistent runtime state lives.
+    home: Flags.string({
+      description: 'Home directory for persistent state (default ~/.objectstack; overrides $OS_HOME)',
+    }),
+
     // Artifact source
     artifact: Flags.string({
       char: 'a',
-      description: 'Path or http(s):// URL to the compiled objectstack.json (overrides $OS_ARTIFACT_PATH; defaults to ./dist/objectstack.json)',
+      description: 'Path or http(s):// URL to the compiled objectstack.json (overrides $OS_ARTIFACT_PATH; auto-detected from ./dist/objectstack.json or <home>/dist/objectstack.json)',
     }),
 
     // Project identity
-    'project-id': Flags.string({
-      description: 'Project identifier (overrides $OS_ENVIRONMENT_ID, default proj_local)',
+    'environment-id': Flags.string({
+      description: 'Environment identifier (overrides $OS_ENVIRONMENT_ID, default env_local)',
     }),
 
     // Storage
     database: Flags.string({
       char: 'd',
-      description: 'Database URL: file:./db.sqlite | libsql://... | postgres://... | mongodb://... | memory:// (overrides $OS_DATABASE_URL)',
+      description: 'Database URL: file:./db.sqlite | libsql://... | postgres://... | mongodb://... | memory:// (overrides $OS_DATABASE_URL; defaults to file:<home>/data/objectstack.db)',
     }),
     'database-driver': Flags.string({
       description: 'Force driver kind when URL is ambiguous: sqlite | turso | postgres | mongodb | memory (overrides $OS_DATABASE_DRIVER)',
@@ -60,69 +90,132 @@ export default class Start extends Command {
   async run(): Promise<void> {
     const { flags } = await this.parse(Start);
 
-    printHeader('Production Mode');
+    printHeader('ObjectStack');
 
-    // ── Artifact resolution ────────────────────────────────────────
-    // Priority: --artifact flag > $OS_ARTIFACT_PATH > ./dist/objectstack.json
-    const artifactPathInput = flags.artifact
-      ?? process.env.OS_ARTIFACT_PATH
-      ?? path.resolve(process.cwd(), 'dist/objectstack.json');
-
-    // `--artifact` / `OS_ARTIFACT_PATH` is allowed to be an
-    // `http(s)://` URL — the runtime's loadArtifactBundle() can fetch
-    // JSON over the network. Skip the existence check for URLs
-    // (validated lazily by the loader).
-    const isUrl = /^https?:\/\//i.test(artifactPathInput);
-    const artifactPath = isUrl ? artifactPathInput : path.resolve(process.cwd(), artifactPathInput);
-
-    if (!isUrl && !fs.existsSync(artifactPath)) {
-      printError(`Artifact not found: ${path.relative(process.cwd(), artifactPath)}`);
-      console.error('  Run \x1b[33mobjectstack build\x1b[0m to compile your configuration first,');
-      console.error('  pass \x1b[33m--artifact <path|url>\x1b[0m, or set \x1b[33mOS_ARTIFACT_PATH\x1b[0m.');
+    // ── Home directory ──────────────────────────────────────────────
+    // Priority: --home > $OS_HOME > ~/.objectstack
+    const homeDir = resolveHome(flags.home);
+    try {
+      fs.mkdirSync(path.join(homeDir, 'data'), { recursive: true });
+    } catch (err: any) {
+      printError(`Cannot create home directory at ${homeDir}: ${err?.message ?? err}`);
       process.exit(1);
     }
 
-    const displayPath = isUrl ? artifactPath : path.relative(process.cwd(), artifactPath);
-    printKV('Artifact', displayPath, '📦');
-    printStep('Starting server (production mode)...');
+    // ── Artifact resolution ────────────────────────────────────────
+    // Priority: --artifact > $OS_ARTIFACT_PATH > ./dist/objectstack.json
+    //         > <home>/dist/objectstack.json > none (empty boot)
+    const artifactSource = resolveArtifactSource(flags.artifact, homeDir);
+
+    // ── Database resolution ─────────────────────────────────────────
+    // Priority: --database > $OS_DATABASE_URL > file:<home>/data/objectstack.db
+    const databaseUrl = flags.database
+      ?? process.env.OS_DATABASE_URL
+      ?? `file:${path.join(homeDir, 'data', 'objectstack.db')}`;
+
+    const environmentId = flags['environment-id']
+      ?? process.env.OS_ENVIRONMENT_ID
+      ?? 'env_local';
+
+    // ── Banner ──────────────────────────────────────────────────────
+    printKV('Home', homeDir, '🏠');
+    if (artifactSource) {
+      printKV('Artifact', artifactSource.display, '📦');
+    } else {
+      printKV('Artifact', 'none (empty kernel — install apps via Studio marketplace)', '📦');
+    }
+    printKV('Database', redactDbUrl(databaseUrl), '🗄️');
+    printKV('Environment', environmentId, '🎯');
+    if (flags.ui) printKV('Studio', `http://localhost:${flags.port ?? 3000}/_studio/`, '🎨');
 
-    const environmentId = flags['project-id'] ?? process.env.OS_ENVIRONMENT_ID ?? 'proj_local';
+    printStep('Starting server...');
 
-    // Build the env handed to `serve`. Flags win over inherited env so
-    // `--database file:foo.db` overrides any pre-existing OS_DATABASE_URL.
+    // ── Child env ───────────────────────────────────────────────────
+    // Flags win over inherited env. When no artifact was located, signal
+    // serve.ts to boot an empty kernel via OS_BOOT_EMPTY=1.
     const localEnv: NodeJS.ProcessEnv = {
       ...process.env,
-      NODE_ENV: 'production',
+      OS_HOME: homeDir,
       OS_ENVIRONMENT_ID: environmentId,
-      OS_ARTIFACT_PATH: artifactPath,
+      OS_DATABASE_URL: databaseUrl,
       ...(flags.port ? { PORT: String(flags.port) } : {}),
-      ...(flags.database ? { OS_DATABASE_URL: flags.database } : {}),
       ...(flags['database-driver'] ? { OS_DATABASE_DRIVER: flags['database-driver'] } : {}),
       ...(flags['database-auth-token'] ? { OS_DATABASE_AUTH_TOKEN: flags['database-auth-token'] } : {}),
       ...(flags['auth-secret'] ? { AUTH_SECRET: flags['auth-secret'] } : {}),
+      ...(artifactSource ? { OS_ARTIFACT_PATH: artifactSource.path } : { OS_BOOT_EMPTY: '1' }),
     };
-
-    printKV('Project ID', environmentId, '🎯');
-    if (flags.database) printKV('Database', redactDbUrl(flags.database), '🗄️');
+    // NODE_ENV is only forced to production when the user has not set it.
+    // Allows `NODE_ENV=development objectstack start` to work for debugging.
+    if (!localEnv.NODE_ENV) localEnv.NODE_ENV = 'production';
 
     const binPath = process.argv[1];
-    spawn(
+    const child = spawn(
       process.execPath,
       [
         binPath,
         'serve',
-        // Production runtime: Studio is opt-in. The `serve` command
-        // defaults `--ui` to true (because it's also driven by `os dev`
-        // where Studio is the expected DX), so we have to explicitly
-        // pass `--no-ui` when the user hasn't asked for `--ui`.
-        ...(flags.ui ? ['--ui'] : ['--no-ui']),
+        flags.ui ? '--ui' : '--no-ui',
         ...(flags.verbose ? ['--verbose'] : []),
       ],
       { stdio: 'inherit', env: localEnv },
     );
+    child.on('exit', (code) => process.exit(code ?? 0));
   }
 }
 
+function resolveHome(flagValue?: string): string {
+  const raw = flagValue ?? process.env.OS_HOME;
+  if (raw && raw.trim().length > 0) {
+    const v = raw.trim();
+    if (v.startsWith('~')) return path.resolve(os.homedir(), v.slice(1).replace(/^[/\\]/, ''));
+    return path.resolve(v);
+  }
+  return path.resolve(os.homedir(), '.objectstack');
+}
+
+interface ResolvedArtifact {
+  /** Absolute path or URL passed to OS_ARTIFACT_PATH. */
+  path: string;
+  /** Human-friendly form for the banner. */
+  display: string;
+}
+
+function resolveArtifactSource(flagValue: string | undefined, homeDir: string): ResolvedArtifact | undefined {
+  const cwd = process.cwd();
+
+  // Explicit flag wins, including URLs.
+  if (flagValue) {
+    if (/^https?:\/\//i.test(flagValue)) return { path: flagValue, display: flagValue };
+    const abs = path.resolve(cwd, flagValue);
+    if (!fs.existsSync(abs)) {
+      // We don't exit here — the user asked for this file. Defer to
+      // serve.ts which already prints a precise error.
+      return { path: abs, display: path.relative(cwd, abs) };
+    }
+    return { path: abs, display: path.relative(cwd, abs) };
+  }
+
+  // Explicit env var wins next.
+  const envPath = process.env.OS_ARTIFACT_PATH;
+  if (envPath) {
+    if (/^https?:\/\//i.test(envPath)) return { path: envPath, display: envPath };
+    const abs = path.resolve(cwd, envPath);
+    return { path: abs, display: path.relative(cwd, abs) };
+  }
+
+  // Auto-detect — cwd first, then home.
+  const cwdCandidate = path.resolve(cwd, 'dist/objectstack.json');
+  if (fs.existsSync(cwdCandidate)) {
+    return { path: cwdCandidate, display: path.relative(cwd, cwdCandidate) };
+  }
+  const homeCandidate = path.resolve(homeDir, 'dist/objectstack.json');
+  if (fs.existsSync(homeCandidate)) {
+    return { path: homeCandidate, display: homeCandidate };
+  }
+
+  return undefined;
+}
+
 function redactDbUrl(url: string): string {
   try {
     return url.replace(/(\/\/[^/@:]+):[^/@]+@/, '$1:****@');
diff --git a/packages/runtime/src/default-host.ts b/packages/runtime/src/default-host.ts
@@ -26,8 +26,8 @@
  */
 
 import { resolve as resolvePath } from 'node:path';
-import { existsSync } from 'node:fs';
-import { createStandaloneStack, type StandaloneStackConfig, type StandaloneStackResult } from './standalone-stack.js';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { createStandaloneStack, resolveObjectStackHome, type StandaloneStackConfig, type StandaloneStackResult } from './standalone-stack.js';
 import { isHttpUrl } from './load-artifact-bundle.js';
 
 export interface DefaultHostConfigOptions extends StandaloneStackConfig {
@@ -82,7 +82,7 @@ export async function createDefaultHostConfig(
 ): Promise<DefaultHostConfigResult> {
     const { requireArtifact = true, ...standaloneOpts } = options;
 
-    const resolvedArtifact = resolveDefaultArtifactPath(standaloneOpts.artifactPath);
+    let resolvedArtifact = resolveDefaultArtifactPath(standaloneOpts.artifactPath);
     if (!resolvedArtifact && requireArtifact) {
         throw new Error(
             '[createDefaultHostConfig] No artifact source available. ' +
@@ -93,6 +93,40 @@ export async function createDefaultHostConfig(
         );
     }
 
+    // Empty-boot path: synthesize a minimal artifact stub inside the
+    // ObjectStack home directory so MetadataPlugin has a real file to
+    // read (and to watch for marketplace installs that land later).
+    if (!resolvedArtifact && !requireArtifact) {
+        const home = resolveObjectStackHome();
+        const stubPath = resolvePath(home, 'dist/objectstack.json');
+        if (!existsSync(stubPath)) {
+            mkdirSync(resolvePath(stubPath, '..'), { recursive: true });
+            writeFileSync(
+                stubPath,
+                JSON.stringify(
+                    {
+                        manifest: {
+                            id: 'com.objectstack.empty',
+                            name: 'empty',
+                            version: '0.0.0',
+                            type: 'app',
+                            description: 'Empty starter kernel — install apps via the Studio marketplace.',
+                        },
+                        objects: [],
+                        views: [],
+                        apps: [],
+                        flows: [],
+                        requires: [],
+                    },
+                    null,
+                    2,
+                ),
+                'utf8',
+            );
+        }
+        resolvedArtifact = stubPath;
+    }
+
     return createStandaloneStack({
         ...standaloneOpts,
         artifactPath: resolvedArtifact,
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
@@ -8,7 +8,7 @@ export { Runtime } from './runtime.js';
 export type { RuntimeConfig } from './runtime.js';
 
 // Export Standalone Stack
-export { createStandaloneStack } from './standalone-stack.js';
+export { createStandaloneStack, resolveObjectStackHome } from './standalone-stack.js';
 export type { StandaloneStackConfig, StandaloneStackResult } from './standalone-stack.js';
 
 // Export Default Host (artifact-first, no objectstack.config.ts required)
diff --git a/packages/runtime/src/standalone-stack.ts b/packages/runtime/src/standalone-stack.ts
