okengine 0.2.2 → 0.2.4

package/README.md

@@ -1,3 +1,10 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="site/public/OKE-W.svg" />
+    <img alt="OKE" src="site/public/OKE-B.svg" width="220" />
+  </picture>
+</p>
+
 # okengine
 
 *"Encore's batteries and dashboard, Elysia's speed and DX, Hono's portability — without the Rust lock-in, the cloud gravity, or the source-available license."*
@@ -225,7 +232,7 @@ oke images list                  # recipe · image · tag · digest · size (wri
 3. **Derive Docker / compose**, then pin digests so tags cannot drift:
 
 ```bash
-oke docker                       # Dockerfile + compose.store.sql.yml · compose.store.kv.yml · …
+oke docker                       # writes under docker/ (Dockerfile + compose.<role>.yml · …)
 oke docker --prod                # -p  healthchecks, volumes, limits, secret refs, deploy.replicas
 oke images pin                   # tags → digests in oke.images.lock
 ```
@@ -251,8 +258,8 @@ bun add okengine                 # ONE package
 
 oke dev                          # watch · hot reload · Console :6533 · app :6530 · MCP :6535
                                  #   → also auto-syncs client types on every save
-oke dev --stack                  # -s  also boot the real infra stack (generated compose)
-oke dev -s store.sql,signal      #     partial: only these roles get real backends
+oke dev --stack                  # -s  infra only under docker/ (Postgres/Redis/…); app stays on host Bun
+oke dev -s store.sql,store.kv    #     partial: only these roles get real backends
 
 oke start                        # runs exactly what production runs (this is the Docker CMD)
 oke doctor                       # verify secrets, ports, drivers, tenancy, schema drift
@@ -269,7 +276,7 @@ oke schema generate              # core + plugin tables → schema/oke.ts   (--c
 oke vault set STRIPE_KEY         # also: list · import .env · key rotate
 oke client add <url>             # types for a separate frontend repo
 
-oke docker                       # Dockerfile + compose.store.sql.yml · compose.store.kv.yml · …
+oke docker                       # artefacts under docker/ (Dockerfile + compose.<role>.yml · …)
 oke docker --prod                # -p  healthchecks, volumes, limits, secret refs, deploy.replicas
 oke images list                  # recipe · image · tag · digest · size (--json|-j)
 oke images pin                   # tags → digests in oke.images.lock
@@ -346,6 +353,25 @@ Measured size and latency caps — see [`BUDGETS.md`](BUDGETS.md). Refresh with
 
 ---
 
+## Local framework link (try changes without publishing)
+
+To exercise a local `okengine` checkout inside an app (e.g. `oke-1`) without npm publish:
+
+```bash
+# in the okengine repo
+bun link
+# if you changed the Console SPA:
+bun run build
+
+# in the app repo
+bun link okengine
+# edit okengine → restart `bun dev` in the app
+```
+
+Alternatively set `"okengine": "file:../okengine"` in the app `package.json` and run `bun install`.
+
+---
+
 ## Status
 
 Pre-1.0. Published on [npm](https://www.npmjs.com/package/okengine) and [JSR](https://jsr.io/@omqkhafi/okengine) (`okengine` + `create-oke`, lockstep). Docs at [okengine.vercel.app](https://okengine.vercel.app). MIT. No `CONTRIBUTING` yet — issues and PRs welcome.

package/docs/spec/example.md

@@ -43,7 +43,16 @@ import { defineConfig } from "okengine/config";
 
 export default defineConfig({
   drivers: {
-    store: { sql: { dev: "sqlite", test: "memory", prod: "postgres" } },
+    // `stack` = `oke dev -s` (local server). Omitting it copies `prod`
+    // (defineConfig); vault `sops` becomes stack `dotenv` for `.env.stack`.
+    store: {
+      sql: {
+        dev: "sqlite",
+        stack: "postgres",
+        test: "memory",
+        prod: "postgres",
+      },
+    },
   },
 });
 ```
@@ -1132,7 +1141,7 @@ bun add okengine                 # ONE package
 
 oke dev                          # watch · hot reload · Console :6533 · app :6530 · MCP :6535
                                  #   → also auto-syncs client types on every save
-oke dev --stack                  # -s  also boot the real infra stack (generated compose)
+oke dev --stack                  # -s  infra compose under docker/ (no app container; host Bun)
 oke dev -s store.sql,signal      #     partial: only these roles get real backends
 
 oke start                        # runs exactly what production runs (this is the Docker CMD)
@@ -1143,7 +1152,7 @@ oke schema generate              # core + plugin tables → schema/oke.ts   (--c
 oke vault set STRIPE_KEY         # also: list · import .env · key rotate
 oke client add <url>             # types for a separate frontend repo
 
-oke docker                       # Dockerfile + compose.store.sql.yml · compose.store.kv.yml · …
+oke docker                       # docker/Dockerfile + docker/compose.<role>.yml · …
 oke docker --prod                # healthchecks, volumes, limits, secret refs, deploy.replicas
 oke images pin                   # tags → digests in oke.images.lock
 

package/docs/spec/four-applications.md

@@ -43,7 +43,14 @@ import { defineConfig } from "okengine/config";
 
 export default defineConfig({
   drivers: {
-    store: { sql: { dev: "sqlite", test: "memory", prod: "postgres" } },
+    store: {
+      sql: {
+        dev: "sqlite",
+        stack: "postgres",
+        test: "memory",
+        prod: "postgres",
+      },
+    },
   },
 });
 ```
@@ -1132,7 +1139,7 @@ bun add okengine                 # ONE package
 
 oke dev                          # watch · hot reload · Console :6533 · app :6530 · MCP :6535
                                  #   → also auto-syncs client types on every save
-oke dev --stack                  # -s  also boot the real infra stack (generated compose)
+oke dev --stack                  # -s  infra compose under docker/ (no app container; host Bun)
 oke dev -s store.sql,signal      #     partial: only these roles get real backends
 
 oke start                        # runs exactly what production runs (this is the Docker CMD)
@@ -1143,7 +1150,7 @@ oke schema generate              # core + plugin tables → schema/oke.ts   (--c
 oke vault set STRIPE_KEY         # also: list · import .env · key rotate
 oke client add <url>             # types for a separate frontend repo
 
-oke docker                       # Dockerfile + compose.store.sql.yml · compose.store.kv.yml · …
+oke docker                       # docker/Dockerfile + docker/compose.<role>.yml · …
 oke docker --prod                # healthchecks, volumes, limits, secret refs, deploy.replicas
 oke images pin                   # tags → digests in oke.images.lock
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "type": "module",
@@ -17,51 +17,20 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "bun test --pass-with-no-tests",
-    "test:manifest": "bun test --coverage src/manifest",
-    "test:runtime": "bun test src/runtime",
-    "test:compiler": "bun test src/validation src/compiler/aot src/compiler/differential src/compiler/extract",
-    "test:client": "bun test src/client src/cli/client-add.test.ts",
-    "test:store": "bun test src/elements/store src/drivers",
-    "test:signal": "bun test src/elements/signal",
-    "test:clock": "bun test src/elements/clock",
-    "test:gate": "bun test src/elements/gate",
-    "test:vault": "bun test src/elements/vault",
-    "test:channel": "bun test src/elements/channel",
-    "test:ai": "bun test src/elements/ai",
-    "test:auth": "bun test src/auth",
-    "test:runs": "bun test src/runs",
-    "test:cli": "bun test src/cli src/docker",
-    "test:console": "bun test src/console/server && bun test src/console/ui/flows && bun test src/console/ui/traces && bun test src/console/ui/runs && bun test src/console/ui/signals && bun test src/console/ui/architecture && bun test src/console/xss.gate.test.ts src/console/budget.test.ts",
-    "test:mcp": "bun test src/mcp",
+    "test:coverage": "bun test --coverage --pass-with-no-tests",
     "test:console:smoke": "bunx playwright test tests/console/smoke.spec.ts",
-    "build:console": "bunx vite build --config src/console/ui/vite.config.ts",
-    "prepack": "bun run build:console",
-    "bench:cold-start": "bun test ./src/runtime/cold-start.bench.ts",
-    "bench:client": "bun test src/client/budget.test.ts",
-    "bench:console": "bun test src/console/budget.test.ts",
-    "bench:kernel": "bun test src/kernel/budget.test.ts",
-    "bench:routing": "bun test src/kernel/routing-budget.test.ts",
-    "bench:runs": "bun test src/runs/bench.test.ts",
+    "test:integration": "bun test examples/notes examples/linkly examples/provisions examples/skyport examples/skyport/tests/docker.test.ts && bun run --cwd packages/create-oke typecheck && bun test packages/create-oke/src && CREATE_OKE_INTEGRATION=1 bun test --timeout 180000 packages/create-oke/tests/scaffold.integration.test.ts packages/create-oke/tests/dev.integration.test.ts",
+    "build": "bunx vite build --config src/console/ui/vite.config.ts",
+    "prepack": "bun run build",
+    "bench": "bun test ./src/runtime/cold-start.bench.ts src/client/budget.test.ts src/console/budget.test.ts src/kernel/budget.test.ts src/kernel/routing-budget.test.ts src/runs/bench.test.ts",
     "budgets": "bun src/release/publish.ts",
-    "gate:doctor-diff": "bun src/cli/doctor-diff-examples.ts",
-    "gate:errors": "bun test src/kernel/errors.registry.test.ts",
-    "gate:codemods": "bun test src/upgrade/codemods.test.ts",
-    "test:examples": "bun test examples/notes && bun test examples/linkly && bun test examples/provisions && bun test examples/skyport",
-    "test:create-oke": "bun run --cwd packages/create-oke typecheck && bun test packages/create-oke/src && CREATE_OKE_INTEGRATION=1 bun test --timeout 180000 packages/create-oke/tests/scaffold.integration.test.ts packages/create-oke/tests/dev.integration.test.ts",
-    "test:doc-drift": "bun src/cli/doc-drift.ts",
+    "gate": "bun src/cli/doctor-diff-examples.ts && bun test src/kernel/errors.registry.test.ts src/upgrade/codemods.test.ts scripts/publish.gate.test.ts && bun src/cli/doc-drift.ts",
     "site:sync": "bun run --cwd site sync",
     "site:dev": "bun run --cwd site dev",
     "site:build": "bun run --cwd site build",
-    "test:skyport-docker": "bun test examples/skyport/tests/docker.test.ts",
-    "ci": "bun run bench:cold-start && bun run typecheck && bun run test && bun run budgets && bun run gate:doctor-diff && bun run gate:errors && bun run gate:codemods && bun run test:doc-drift && bun run site:build && bun run test:examples && bun run test:skyport-docker && bun run test:create-oke",
-    "gate:publish": "bun test scripts/publish.gate.test.ts",
+    "ci": "bun run bench && bun run typecheck && bun run test && bun run budgets && bun run gate && bun run site:build && bun run test:integration",
     "bump": "bun run scripts/bump-version.ts",
-    "publish:all": "bun run scripts/publish.ts",
-    "publish:npm": "bun run scripts/publish.ts -- --npm-only",
-    "publish:jsr": "bun run scripts/publish.ts -- --jsr-only",
-    "publish:all:dry": "bun run scripts/publish.ts -- --dry-run",
-    "publish:npm:dry": "bun run scripts/publish.ts -- --dry-run --npm-only",
-    "publish:jsr:dry": "bun run scripts/publish.ts -- --dry-run --jsr-only",
+    "publish": "bun run scripts/publish.ts",
     "g": "gflows"
   },
   "dependencies": {

package/src/cli/dev-app-runner.ts

@@ -11,17 +11,29 @@
  * - `PORT` — listen port (`0` = ephemeral)
  * - `OKE_HOSTNAME` — listen hostname (default `127.0.0.1`)
  * - `OKE_READY_PATH` — when set, write bound port here once listening
+ * - `OKE_DEV_HERO_CONSOLE` / `OKE_DEV_HERO_MCP` — URL lines for soft-reload hero
+ * - `OKE_DEV_HERO_META` — JSON {@link import("./hero-meta.ts").DevHeroSnapshot}
  */
 
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createBunRuntime } from "../runtime/bun.ts";
 import { APP_PORT, type FetchApp } from "../runtime/types.ts";
-import { formatAppReadyLine } from "../term.ts";
+import {
+  clearTerminalScreen,
+  formatAppReadyLine,
+  formatDevHero,
+} from "../term.ts";
+import { decodeHeroSnapshot } from "./hero-meta.ts";
 
 /** Stable Bun.serve id so `--hot` reuses the socket across soft reloads. */
 export const DEV_APP_SERVE_ID = "oke-dev-app";
 
+/** Survives `bun --hot` soft reload — marks second+ evaluation. */
+type DevRunnerGlobals = typeof globalThis & {
+  __okeDevSoftReload?: boolean;
+};
+
 /** App entry shape — FetchApp plus boot before serve. */
 type BootableApp = FetchApp & {
   boot(): Promise<unknown>;
@@ -36,6 +48,9 @@ if (entry === undefined || entry.length === 0) {
 const port = Number(Bun.env["PORT"] ?? APP_PORT);
 const hostname = Bun.env["OKE_HOSTNAME"] ?? "127.0.0.1";
 const readyPath = Bun.env["OKE_READY_PATH"];
+const consoleUrl = Bun.env["OKE_DEV_HERO_CONSOLE"];
+const mcpUrl = Bun.env["OKE_DEV_HERO_MCP"];
+const heroMeta = decodeHeroSnapshot(Bun.env["OKE_DEV_HERO_META"]);
 
 const absoluteEntry = resolve(entry);
 const mod = (await import(pathToFileURL(absoluteEntry).href)) as {
@@ -60,11 +75,35 @@ const handle = createBunRuntime().serve(mod.app, {
   id: DEV_APP_SERVE_ID,
 });
 
-process.stdout.write(
-  formatAppReadyLine(
-    `http://${formatHostForUrl(hostname)}:${handle.port}`,
-  ),
-);
+const appUrl = `http://${formatHostForUrl(hostname)}:${handle.port}`;
+const g = globalThis as DevRunnerGlobals;
+const isSoftReload = g.__okeDevSoftReload === true;
+g.__okeDevSoftReload = true;
+
+if (
+  isSoftReload &&
+  consoleUrl !== undefined &&
+  consoleUrl.length > 0 &&
+  mcpUrl !== undefined &&
+  mcpUrl.length > 0
+) {
+  // Drop request logs; keep the hero (Bun --no-clear-screen + our reprint).
+  process.stdout.write(clearTerminalScreen());
+  process.stdout.write(
+    formatDevHero({
+      appUrl,
+      consoleUrl,
+      mcpUrl,
+      profile: heroMeta?.profile,
+      runtimeEnv: heroMeta?.runtimeEnv,
+      system: heroMeta?.system,
+      elements: heroMeta?.elements,
+      version: heroMeta?.version,
+    }),
+  );
+} else {
+  process.stdout.write(formatAppReadyLine(appUrl));
+}
 
 if (readyPath !== undefined && readyPath.length > 0) {
   await Bun.write(readyPath, `${handle.port}\n`);

package/src/cli/dev.ts

@@ -1,6 +1,6 @@
 /**
  * `oke dev` — watch · hot reload · Console :6533 · MCP :6535 · client types on save.
- * `oke dev --stack` also boots generated compose.
+ * `oke dev --stack` boots infra compose and binds prod store drivers (Postgres/Redis).
  */
 
 import { watch } from "node:fs";
@@ -11,8 +11,12 @@ import type { SessionStore } from "../auth/sessions.ts";
 import type { ConsoleAppHandle } from "../console/server/app.ts";
 import type { ConsoleState } from "../console/server/state.ts";
 import {
+  DEFAULT_DOCKER_DIR,
   deriveInfrastructure,
   formatStackEnv,
+  loadExistingStackCredentials,
+  stackAppSlug,
+  stackInstanceId,
   writeDerivedFiles,
   type DeriveOptions,
 } from "../docker/index.ts";
@@ -25,12 +29,24 @@ import {
 } from "../runtime/types.ts";
 import {
   formatDevBanner,
+  formatDevLogSeparator,
   formatServiceLine,
+  formatStackSummary,
   formatStatusLine,
 } from "../term.ts";
 import { clientAdd } from "./client-add.ts";
-import { loadManifest, loadOkeConfig, resolveImages } from "./load-config.ts";
+import { resolveDriverId } from "../config/index.ts";
+import {
+  buildDevHeroSnapshot,
+  encodeHeroSnapshot,
+} from "./hero-meta.ts";
+import {
+  loadManifest,
+  loadOkeConfig,
+  resolveImages,
+} from "./load-config.ts";
 import { mcpContextFromConsole } from "./mcp-from-console.ts";
+import { resolveDevPorts } from "./ports.ts";
 
 /** Max wait for the `bun --hot` app child to bind a port. */
 const APP_READY_TIMEOUT_MS = 30_000;
@@ -183,9 +199,27 @@ export interface DevResult {
 export async function runDev(options: DevOptions = {}): Promise<DevResult> {
   const write = options.write ?? ((t) => process.stdout.write(t));
   const cwd = options.cwd ?? process.cwd();
-  const appPort = options.appPort ?? Number(Bun.env.PORT ?? APP_PORT);
-  const consolePort = options.consolePort ?? CONSOLE_PORT;
-  const mcpPort = options.mcpPort ?? MCP_PORT;
+  const preferredApp = options.appPort ?? Number(Bun.env.PORT ?? APP_PORT);
+  const preferredConsole = options.consolePort ?? CONSOLE_PORT;
+  const preferredMcp = options.mcpPort ?? MCP_PORT;
+  // Explicit overrides (incl. `0` ephemeral) skip probing; otherwise +1 until free.
+  const ports =
+    options.appPort !== undefined ||
+    options.consolePort !== undefined ||
+    options.mcpPort !== undefined
+      ? {
+          app: preferredApp,
+          console: preferredConsole,
+          mcp: preferredMcp,
+        }
+      : await resolveDevPorts({
+          app: preferredApp,
+          console: preferredConsole,
+          mcp: preferredMcp,
+        });
+  const appPort = ports.app;
+  const consolePort = ports.console;
+  const mcpPort = ports.mcp;
   const keepAlive = options.keepAlive ?? true;
 
   let entry = options.entry;
@@ -205,16 +239,36 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
   let stackRoles: string[] | null = null;
   let composeFiles: string[] | null = null;
   let stackEnv: Record<string, string> | null = null;
+  let stackSqlDriver = "postgres";
+  let stackKvDriver = "redis";
+  let loadedConfig: Awaited<ReturnType<typeof loadOkeConfig>>["config"] | null =
+    null;
+  try {
+    loadedConfig = (await loadOkeConfig(cwd)).config;
+  } catch {
+    loadedConfig = null;
+  }
 
   if (options.stack) {
     let images = options.images;
     if (!images) {
+      if (!loadedConfig) {
+        try {
+          const loaded = await loadOkeConfig(cwd);
+          loadedConfig = loaded.config;
+          images = resolveImages(loaded.config);
+        } catch (err) {
+          console.error(err instanceof Error ? err.message : String(err));
+          return { code: 1 };
+        }
+      } else {
+        images = resolveImages(loadedConfig);
+      }
+    } else if (!loadedConfig) {
       try {
-        const loaded = await loadOkeConfig(cwd);
-        images = resolveImages(loaded.config);
-      } catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return { code: 1 };
+        loadedConfig = (await loadOkeConfig(cwd)).config;
+      } catch {
+        loadedConfig = null;
       }
     }
     if (Array.isArray(options.stack)) {
@@ -227,16 +281,31 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
       stackRoles = Object.keys(images);
     }
 
+    stackSqlDriver =
+      resolveDriverId(loadedConfig?.drivers?.store?.sql, "prod") ?? "postgres";
+    stackKvDriver =
+      resolveDriverId(loadedConfig?.drivers?.store?.kv, "prod") ?? "redis";
+
+    const composeDir = DEFAULT_DOCKER_DIR;
+    const dockerOut = resolve(cwd, composeDir);
+    const instanceId = stackInstanceId(cwd);
+    const appSlug = stackAppSlug(cwd);
+    const reusedCreds =
+      options.credentials ??
+      (await loadExistingStackCredentials(cwd, stackRoles));
     const derived = deriveInfrastructure({
       images,
-      app: "dev",
+      app: appSlug,
       prod: false,
-      ...(options.credentials ? { credentials: options.credentials } : {}),
+      includeApp: false,
+      composeDir,
+      instanceId,
+      ...(reusedCreds ? { credentials: reusedCreds } : {}),
       host: "127.0.0.1",
     });
     // Layer 4 is user-owned — include only if the file already exists.
     const existingOverride = await Bun.file(
-      resolve(cwd, "compose.override.yml"),
+      resolve(dockerOut, "compose.override.yml"),
     ).exists();
     composeFiles = derived.composeFiles.filter(
       (f) => f !== "compose.override.yml" || existingOverride,
@@ -244,8 +313,11 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     stackEnv = { ...derived.stackEnv };
 
     if (!options.dryRun) {
-      await writeDerivedFiles(derived, cwd, { writeStackEnv: true });
-      // Ensure .env.stack is loaded for the app process
+      await writeDerivedFiles(derived, dockerOut, {
+        writeStackEnv: true,
+        stackEnvDir: cwd,
+      });
+      // Ensure .env.stack is at project root for the host Bun app / vault.
       await Bun.write(resolve(cwd, ".env.stack"), formatStackEnv(stackEnv));
       const up =
         options.composeUp ??
@@ -262,8 +334,27 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
             throw new Error(`oke dev --stack: docker compose exited ${code}`);
           }
         });
-      await up(composeFiles, cwd);
-      write(formatStatusLine(`stack up (${stackRoles.join(", ")})`));
+      // Compose files live under docker/; cwd for compose is that directory.
+      await up(composeFiles, dockerOut);
+      const roleLabel = (role: string): string => {
+        if (role === "store.sql") return "postgres";
+        if (role === "store.kv") return "redis";
+        return role;
+      };
+      const appDrivers = [
+        ...(stackRoles.includes("store.sql") ? [stackSqlDriver] : []),
+        ...(stackRoles.includes("store.kv") ? [stackKvDriver] : []),
+      ];
+      write(
+        formatStackSummary({
+          project: `oke-${appSlug}`,
+          services: derived.specs.map((spec) => ({
+            label: roleLabel(spec.role),
+            hostPort: spec.hostPort,
+          })),
+          appDrivers,
+        }),
+      );
     }
   }
 
@@ -277,7 +368,34 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     stackEnv,
   };
 
-  write(formatDevBanner());
+  let okeVersion = "0.0.0";
+  try {
+    const pkg = (await Bun.file(
+      resolve(import.meta.dir, "../../package.json"),
+    ).json()) as { version?: string };
+    if (typeof pkg.version === "string") okeVersion = pkg.version;
+  } catch {
+    // shipped binary may not sit next to package.json
+  }
+
+  const heroSnapshot = buildDevHeroSnapshot({
+    config: loadedConfig,
+    stack: Boolean(options.stack),
+    sqlDriver: options.stack ? stackSqlDriver : undefined,
+    kvDriver: options.stack ? stackKvDriver : undefined,
+    version: okeVersion,
+    nodeEnv: "development",
+  });
+
+  write(
+    formatDevBanner({
+      profile: heroSnapshot.profile,
+      runtimeEnv: heroSnapshot.runtimeEnv,
+      system: heroSnapshot.system,
+      elements: heroSnapshot.elements,
+      version: okeVersion,
+    }),
+  );
 
   if (options.dryRun) return { code: 0, plan };
 
@@ -285,8 +403,21 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     ...(process.env as Record<string, string>),
     NODE_ENV: "development",
     PORT: String(appPort),
+    OKE_DEV_REQUEST_LOG: "1",
+    /** Soft-reload hero reprint (Console / MCP URLs + element snapshot). */
+    OKE_DEV_HERO_CONSOLE: `http://127.0.0.1:${consolePort}`,
+    OKE_DEV_HERO_MCP: `http://127.0.0.1:${mcpPort}`,
+    OKE_DEV_HERO_META: encodeHeroSnapshot(heroSnapshot),
     ...(stackEnv ?? {}),
+    ...(stackEnv
+      ? {
+          OKE_STACK: "1",
+          OKE_SQL_DRIVER: stackSqlDriver,
+          OKE_KV_DRIVER: stackKvDriver,
+        }
+      : {}),
   };
+  process.env.OKE_DEV_REQUEST_LOG = "1";
 
   const startApp =
     options.startApp ??
@@ -297,6 +428,20 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
       ? options.manifest
       : await tryLoadProjectManifest(cwd);
 
+  async function refreshManifestInto(
+    state: ConsoleState | null,
+  ): Promise<void> {
+    if (!state) return;
+    try {
+      const { extractManifest } = await import("../compiler/extract.ts");
+      const { feedManifest } = await import("../console/server/live.ts");
+      const next = await extractManifest({ rootDir: cwd });
+      feedManifest(state, next);
+    } catch {
+      // Source may be mid-edit — keep the last good Manifest.
+    }
+  }
+
   const serveConsole =
     options.serveConsole ??
     (async (port) => {
@@ -396,12 +541,17 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
   const appUrl =
     app.url?.origin ?? `http://127.0.0.1:${boundAppPort}`;
   await regen(appUrl);
+  write(formatDevLogSeparator());
 
   const watcher = watch(
     resolve(cwd, "src"),
     { recursive: true },
     () => {
       void regen(appUrl);
+      // Only live-extract when the host did not pin a Manifest (tests).
+      if (options.manifest === undefined) {
+        void refreshManifestInto(consoleState);
+      }
     },
   );
 
@@ -453,20 +603,45 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
 }
 
 /**
- * Load `oke.manifest.json` / `manifest.oke.json` when present.
+ * True when a Manifest has no declared flows (scaffold / empty extract).
+ *
+ * @param manifest - Candidate
+ */
+function isSparseManifest(manifest: Manifest): boolean {
+  const flows = manifest.flows;
+  if (!flows || typeof flows !== "object") return true;
+  return Object.keys(flows).length === 0;
+}
+
+/**
+ * Load Manifest — prefer AoT extract from `src/` when it has flows;
+ * otherwise on-disk JSON snapshots; otherwise a sparse extract.
  *
  * @param cwd - Project root
  */
 async function tryLoadProjectManifest(
   cwd: string,
 ): Promise<Manifest | null | undefined> {
+  let extracted: Manifest | undefined;
+  try {
+    const { extractManifest } = await import("../compiler/extract.ts");
+    extracted = await extractManifest({ rootDir: cwd });
+  } catch {
+    // Fall through to JSON snapshots.
+  }
+
+  let fromDisk: Manifest | undefined;
   for (const name of ["oke.manifest.json", "manifest.oke.json"]) {
     const path = resolve(cwd, name);
     if (await Bun.file(path).exists()) {
-      return loadManifest(path);
+      fromDisk = await loadManifest(path);
+      break;
     }
   }
-  return undefined;
+
+  if (extracted && !isSparseManifest(extracted)) return extracted;
+  if (fromDisk) return fromDisk;
+  return extracted;
 }
 
 /**
@@ -493,9 +668,13 @@ async function startAppHot(
     OKE_ENTRY: absoluteEntry,
     OKE_HOSTNAME: hostname,
     OKE_READY_PATH: readyPath,
+    OKE_DEV_REQUEST_LOG: "1",
+    OKE_DEV_SURFACE: "App",
   };
 
-  const proc = Bun.spawn(["bun", "--hot", runner], {
+  // `--no-clear-screen`: Bun must not wipe the hero; the runner clears only
+  // request logs on soft reload and reprints App / Console / MCP URLs.
+  const proc = Bun.spawn(["bun", "--hot", "--no-clear-screen", runner], {
     cwd,
     env,
     stdout: "inherit",
@@ -590,7 +769,9 @@ export async function devCli(args: readonly string[]): Promise<number> {
 
 Watch · hot reload · Console :6533 · app :6530 · MCP :6535
 Regenerates client types on every save.
---stack boots generated compose (partial roles: -s store.sql,signal).
+--stack boots infra under docker/ and runs the app on host Bun with prod
+store drivers (Postgres/Redis) so local mimics the server.
+Partial roles: -s store.sql,store.kv.
 `);
       return 0;
     }