okengine 0.10.3 → 0.11.0

package/src/upgrade/codemods.ts

@@ -4,6 +4,10 @@
  * `oke upgrade` runs every applicable transform and prints a diff.
  * Adding a breaking change without a codemod is a process defect; the
  * registry is the checklist.
+ *
+ * Environment-model migrations (`local`/`docker` → `dev`, sqlite removal)
+ * are documented only — see site docs `reference/migrating-environments`.
+ * No soft-compat rewriter for those.
  */
 
 import { readdir } from "node:fs/promises";
@@ -38,49 +42,7 @@ export interface Codemod {
 }
 
 /**
- * Rewrite driver-map keys `dev:` → `local:` and `stack:` → `docker:`.
- *
- * Vault `dev:` fallbacks are intentionally excluded — callers pass only
- * `oke.config.*` paths into this rewriter.
- *
- * @param source - File contents
- */
-export function rewriteConfigEnvKeys(source: string): string {
-  return source
-    .replace(/(^|[^\w.])dev(\s*:)/gm, "$1local$2")
-    .replace(/(^|[^\w.])stack(\s*:)/gm, "$1docker$2");
-}
-
-/**
- * Rewrite removed vault stack markers to docker equivalents.
- *
- * @param source - File contents
- */
-export function rewriteFromStackMarkers(source: string): string {
-  return source
-    .replace(/\bfromStack\b/g, "fromDocker")
-    .replace(/\bFROM_STACK_PREFIX\b/g, "FROM_DOCKER_PREFIX")
-    .replace(/\bisFromStack\b/g, "isFromDocker")
-    .replace(/\bfromStackRole\b/g, "fromDockerRole")
-    .replace(/__oke_from_stack__/g, "__oke_from_docker__");
-}
-
-/**
- * Collect `oke.config.*` files under a project root.
- *
- * @param cwd - Project root
- */
-async function collectConfigCandidates(cwd: string): Promise<string[]> {
-  const out: string[] = [];
-  for (const name of ["oke.config.ts", "oke.config.mts", "oke.config.js"]) {
-    const path = resolve(cwd, name);
-    if (await Bun.file(path).exists()) out.push(path);
-  }
-  return out;
-}
-
-/**
- * Collect TypeScript sources that may reference `fromStack`.
+ * Collect TypeScript sources under `src` / `app`.
  *
  * @param cwd - Project root
  */
@@ -116,30 +78,101 @@ async function walkTs(dir: string, out: string[]): Promise<void> {
 }
 
 /**
- * Built-in transforms.
+ * Rewrite deep `okengine` imports that left the thin root to subpaths.
+ *
+ * @param source - File contents
  */
+export function rewriteThinRootImports(source: string): string {
+  const movers: readonly { readonly names: readonly string[]; readonly from: string }[] = [
+    {
+      names: [
+        "createRunsRuntime",
+        "collectWideEvent",
+        "createRunTelemetry",
+        "explainOutliers",
+        "filesRunsDriver",
+        "memoryRunsDriver",
+        "postgresRunsDriver",
+        "clickhouseRunsDriver",
+        "openDuckDB",
+        "duckQuery",
+      ],
+      from: "okengine/runs",
+    },
+    {
+      names: [
+        "createJournal",
+        "createMemoryJournalStore",
+        "createFileJournalStore",
+        "hasJournalLease",
+        "JOURNAL_DEFAULT_LEASE_MS",
+      ],
+      from: "okengine/journal",
+    },
+    {
+      names: ["compileAot", "compileDynamic", "compileRoute", "sucrose", "extractManifest"],
+      from: "okengine/compiler",
+    },
+    {
+      names: ["formatMessage", "clearMessageFormatCache", "resolveFailureMessage"],
+      from: "okengine/i18n",
+    },
+    {
+      names: [
+        "bootApplication",
+        "mintCapabilities",
+        "createFx",
+        "createRouter",
+        "CONSOLE_PORT",
+        "MCP_PORT",
+      ],
+      from: "okengine/full",
+    },
+  ];
+
+  let text = source;
+  for (const mover of movers) {
+    const re = new RegExp(`import\\s*\\{([^}]*)\\}\\s*from\\s*(["'])okengine\\2`, "g");
+    text = text.replace(re, (full, body: string, quote: string) => {
+      const parts = body
+        .split(",")
+        .map((p) => p.trim())
+        .filter(Boolean);
+      const keep: string[] = [];
+      const move: string[] = [];
+      for (const part of parts) {
+        const base =
+          part
+            .replace(/^type\s+/, "")
+            .split(/\s+as\s+/)[0]
+            ?.trim() ?? part;
+        if (mover.names.includes(base)) move.push(part);
+        else keep.push(part);
+      }
+      if (move.length === 0) return full;
+      const lines: string[] = [];
+      if (keep.length > 0) {
+        lines.push(`import { ${keep.join(", ")} } from ${quote}okengine${quote}`);
+      }
+      lines.push(`import { ${move.join(", ")} } from ${quote}${mover.from}${quote}`);
+      return lines.join(";\n");
+    });
+  }
+  return text;
+}
+
 export const CODEMODS: readonly Codemod[] = [
   {
-    id: "0.2.7-config-env-local-docker",
-    from: "0.2.6",
-    to: "0.2.7",
-    description: "Rename driver-map keys dev→local, stack→docker; fromStack→fromDocker",
+    id: "0.10.3-thin-root-subpaths",
+    from: "0.10.2",
+    to: "0.10.3",
+    description:
+      "Move deep okengine imports (runs/journal/compiler/i18n/boot helpers) to okengine/* subpaths after thin root",
     async apply(cwd) {
       const changes: CodemodChange[] = [];
-      for (const path of await collectConfigCandidates(cwd)) {
-        const before = await Bun.file(path).text();
-        const after = rewriteConfigEnvKeys(before);
-        if (after !== before) {
-          changes.push({
-            path: relative(cwd, path) || path,
-            before,
-            after,
-          });
-        }
-      }
       for (const path of await collectVaultCandidates(cwd)) {
         const before = await Bun.file(path).text();
-        const after = rewriteFromStackMarkers(before);
+        const after = rewriteThinRootImports(before);
         if (after !== before) {
           changes.push({
             path: relative(cwd, path) || path,

package/site/content/docs/recipes/openbao.mdx

@@ -1,141 +0,0 @@
----
-title: "OpenBao"
-description: "Durable single-node vault — Raft under /openbao/file, OKE_VAULT_URL / OKE_VAULT_TOKEN, host unseal key SPOF."
-icon: "KeyRound"
-source: "docs/spec/unified-theory.md"
----
-
-OpenBao is the docker/prod Vault driver target — a real secrets service with Raft
-storage, **not** an in-memory `-dev` server. Templates pin
-`vault: "openbao/openbao:2.6.1"` and `drivers.vault.docker/prod: "openbao"`.
-
-<Callout title="The one rule">
-  Never run OpenBao `-dev` in docker/prod. Data belongs on the Raft volume; init + unseal stay on
-  the host under `.oke/openbao/`.
-</Callout>
-
-## Quick start
-
-<Steps>
-
-<Step>
-### Pin driver + image
-
-```typescript title="oke.config.ts"
-drivers: {
-  vault: { local: "env", docker: "openbao", test: "memory", prod: "openbao" },
-},
-images: {
-  vault: "openbao/openbao:2.6.1",
-},
-```
-
-</Step>
-
-<Step>
-### First boot is automatic
-
-`oke dev --docker` initializes OpenBao (Shamir 1-of-1), unseals it, writes a
-least-privilege policy for **declared** secrets only, and mints an app token. You do not
-run raw `bao` commands.
-
-</Step>
-
-<Step>
-### App sees only the least-privilege token
-
-```bash title="docker/.env.docker"
-OKE_VAULT_URL=http://127.0.0.1:8200
-OKE_VAULT_TOKEN=…        # app token — not the root token
-OKE_VAULT_MOUNT=secret   # KV v2 mount (default)
-```
-
-</Step>
-
-</Steps>
-
-## Required env
-
-| Variable           | Who holds it        | Meaning                                  |
-| ------------------ | ------------------- | ---------------------------------------- |
-| `OKE_VAULT_URL`    | App / stack         | OpenBao base URL                         |
-| `OKE_VAULT_TOKEN`  | App (`.env.docker`) | Least-privilege app token                |
-| `OKE_VAULT_MOUNT`  | Optional            | KV v2 mount path (default `"secret"`)    |
-| `BAO_LOCAL_CONFIG` | Container (recipe)  | Listener + Raft JSON — set by the recipe |
-
-Host-only material (mode `0600`, gitignored) — **not** in compose YAML:
-
-| File                      | Holds                                    |
-| ------------------------- | ---------------------------------------- |
-| `.oke/openbao/unseal.key` | Single unseal share                      |
-| `.oke/openbao/root.token` | Root token (CLI policy sync / mint only) |
-| `.oke/openbao/app.token`  | Same least-privilege token the app uses  |
-
-## Data and backup
-
-| Volume       | Path            | What it stores               |
-| ------------ | --------------- | ---------------------------- |
-| `vault-data` | `/openbao/file` | Raft storage (node id `oke`) |
-
-Recipe note: Raft path is `/openbao/file` (the stock entrypoint chowns that directory).
-Healthcheck hits `/v1/sys/init` — **200 even while sealed**; bootstrap owns unseal.
-
-**Backup means two things:**
-
-1. The Raft volume (`/openbao/file`) — encrypted secret store
-2. `.oke/openbao/unseal.key` on the host — without it the volume is unrecoverable
-
-## Production note
-
-<Callout title="Single point of failure — read this once" type="warn">
-  Back up `.oke/openbao/unseal.key` to a separate safe location. Losing it means losing every secret
-  permanently, with no recovery. Restated from [Vault ·
-  OpenBao](/docs/elements/vault#openbao-in-docker-and-prod).
-</Callout>
-
-Self-hosted single-node, Shamir 1-of-1, no cloud KMS — by design. If OpenBao is
-initialized but the key is gone, boot fails with an explicit permanent-loss error; it
-never silently starts empty.
-
-## What the recipe configures
-
-| Field          | Value                                                                                  |
-| -------------- | -------------------------------------------------------------------------------------- |
-| Container port | `8200`                                                                                 |
-| Command        | `server` (with `BAO_LOCAL_CONFIG`)                                                     |
-| TLS            | Disabled on the listener for compose (`tls_disable: true`) — rely on network isolation |
-| Healthcheck    | `wget` `/v1/sys/init`, every 5s, 12 retries                                            |
-
-## Troubleshooting
-
-<Accordions>
-<Accordion title="openbao vault: GET … failed (… ) — sealed or unauthorized?">
-
-`OpenBaoUnavailableError` — vault sealed, wrong token, or unreachable. Re-run
-`oke dev --docker` so bootstrap unseals with the host key. If the vault is initialized
-but `.oke/openbao/unseal.key` is missing, restore the key from backup.
-
-</Accordion>
-<Accordion title="Permanent-loss / initialized but key missing">
-
-Starting empty would look like “no secrets.” The CLI refuses that path. Restore
-`unseal.key` or treat the Raft volume as destroyed and re-init only if you accept wiping
-secrets.
-
-</Accordion>
-</Accordions>
-
-## Learn more
-
-- [Vault · OpenBao in docker and prod](/docs/elements/vault#openbao-in-docker-and-prod) —
-  full bootstrap, key table, SPOF callout
-- [Errors](/docs/reference/errors) — `OpenBaoUnavailableError`, `OpenBaoBootstrapError`
-- [CLI · oke vault](/docs/reference/cli) — `set` / `list` / `import`
-
-## Next
-
-<Cards>
-  <Card title="Vault" description="Resolution chain and rotation." href="/docs/elements/vault" />
-  <Card title="Mailpit" description="Local email catcher." href="/docs/recipes/mailpit" />
-  <Card title="RustFS" description="S3-compatible files." href="/docs/recipes/rustfs" />
-</Cards>

package/src/cli/ask-dev-mode.ts

@@ -1,40 +0,0 @@
-/**
- * One-time interactive `oke dev` mode choice via `@clack/prompts`.
- */
-
-import { isCancel, select } from "@clack/prompts";
-import type { DevMode } from "./dev-mode.ts";
-
-/**
- * Injectable ask step — production uses {@link askDevMode}.
- *
- * @returns Chosen mode, or `null` if the user cancelled
- */
-export type AskDevModeFn = () => Promise<DevMode | null>;
-
-/**
- * Prompt once: local vs docker.
- *
- * @returns Chosen mode, or `null` on cancel
- */
-export async function askDevMode(): Promise<DevMode | null> {
-  const value = await select({
-    message: "Run against",
-    options: [
-      {
-        value: "local",
-        label: "local",
-        hint: "sqlite file, instant, no Docker needed",
-      },
-      {
-        value: "docker",
-        label: "docker",
-        hint: "real Postgres/Redis via compose, closer to production",
-      },
-    ],
-    initialValue: "local",
-  });
-  if (isCancel(value)) return null;
-  if (value === "local" || value === "docker") return value;
-  return null;
-}

package/src/cli/dev-mode.test.ts

@@ -1,45 +0,0 @@
-/**
- * `.oke/mode` persistence and prompt gating.
- */
-
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdtemp, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { parseDevMode, readDevMode, shouldAskDevMode, writeDevMode } from "./dev-mode.ts";
-
-const dirs: string[] = [];
-
-afterEach(async () => {
-  await Promise.all(dirs.splice(0).map((d) => rm(d, { recursive: true, force: true })));
-});
-
-async function tempDir(): Promise<string> {
-  const dir = await mkdtemp(join(tmpdir(), "oke-mode-"));
-  dirs.push(dir);
-  return dir;
-}
-
-describe("dev-mode", () => {
-  test("parseDevMode accepts local|docker only", () => {
-    expect(parseDevMode("local")).toBe("local");
-    expect(parseDevMode(" docker \n")).toBe("docker");
-    expect(parseDevMode("stack")).toBeNull();
-    expect(parseDevMode(undefined)).toBeNull();
-  });
-
-  test("read/write round-trip", async () => {
-    const dir = await tempDir();
-    expect(await readDevMode(dir)).toBeNull();
-    await writeDevMode(dir, "docker");
-    expect(await readDevMode(dir)).toBe("docker");
-  });
-
-  test("shouldAskDevMode: TTY + unset → ask; non-TTY → never", () => {
-    expect(shouldAskDevMode({ saved: null, explicit: false, stdinIsTTY: true })).toBe(true);
-    expect(shouldAskDevMode({ saved: null, explicit: false, stdinIsTTY: false })).toBe(false);
-    expect(shouldAskDevMode({ saved: null, explicit: false, stdinIsTTY: undefined })).toBe(false);
-    expect(shouldAskDevMode({ saved: "local", explicit: false, stdinIsTTY: true })).toBe(false);
-    expect(shouldAskDevMode({ saved: null, explicit: true, stdinIsTTY: true })).toBe(false);
-  });
-});

package/src/cli/dev-mode.ts

@@ -1,78 +0,0 @@
-/**
- * Persisted `oke dev` run mode — `local` vs `docker`.
- */
-
-import { mkdir } from "node:fs/promises";
-import { join, resolve } from "node:path";
-
-/** Saved / selectable `oke dev` infrastructure mode. */
-export type DevMode = "local" | "docker";
-
-/** Relative path under the project root. */
-export const DEV_MODE_RELATIVE_PATH = ".oke/mode";
-
-/**
- * Absolute path to the mode preference file.
- *
- * @param cwd - Project root
- */
-export function devModePath(cwd: string): string {
-  return resolve(cwd, DEV_MODE_RELATIVE_PATH);
-}
-
-/**
- * Parse a raw mode string.
- *
- * @param raw - File contents or CLI arg
- */
-export function parseDevMode(raw: string | undefined | null): DevMode | null {
-  if (raw === undefined || raw === null) return null;
-  const value = raw.trim().toLowerCase();
-  if (value === "local" || value === "docker") return value;
-  return null;
-}
-
-/**
- * Read the saved mode from `.oke/mode`, or `null` when unset / invalid.
- *
- * @param cwd - Project root
- */
-export async function readDevMode(cwd: string): Promise<DevMode | null> {
-  const path = devModePath(cwd);
-  const file = Bun.file(path);
-  if (!(await file.exists())) return null;
-  try {
-    return parseDevMode(await file.text());
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Persist the preferred mode for future `oke dev` invocations.
- *
- * @param cwd - Project root
- * @param mode - Mode to save
- */
-export async function writeDevMode(cwd: string, mode: DevMode): Promise<void> {
-  const path = devModePath(cwd);
-  await mkdir(join(cwd, ".oke"), { recursive: true });
-  await Bun.write(path, `${mode}\n`);
-}
-
-/**
- * Whether `oke dev` should open the one-time mode prompt.
- *
- * Mirrors create-oke: never prompt when stdin is not a TTY.
- *
- * @param options - Preference + TTY + explicit flag
- */
-export function shouldAskDevMode(options: {
-  readonly saved: DevMode | null;
-  readonly explicit: boolean;
-  readonly stdinIsTTY: boolean | undefined;
-}): boolean {
-  if (options.explicit) return false;
-  if (options.saved !== null) return false;
-  return Boolean(options.stdinIsTTY);
-}

package/src/cli/openbao-bootstrap.test.ts

@@ -1,150 +0,0 @@
-/**
- * OpenBao bootstrap — material durability gates (`.oke/` ignore + real
- * `0600`, init-then-write-fail must not report success, initialized-without-
- * key fails loud).
- */
-
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdtemp, rm } from "node:fs/promises";
-import { statSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import {
-  assertMode,
-  ensureOpenBao,
-  OpenBaoBootstrapError,
-  OPENBAO_STATE_DIR_REL,
-} from "./openbao-bootstrap.ts";
-
-let dirs: string[] = [];
-
-async function tempDir(): Promise<string> {
-  const dir = await mkdtemp(join(tmpdir(), "oke-openbao-boot-"));
-  dirs.push(dir);
-  return dir;
-}
-
-afterEach(async () => {
-  for (const dir of dirs) await rm(dir, { recursive: true, force: true });
-  dirs = [];
-});
-
-/** Scripted fake OpenBao (seal-status → init → unseal → policy → token). */
-function fakeOpenBao(calls: { url: string; method: string; body?: string }[]) {
-  const routes: Record<string, () => Response> = {
-    "GET /v1/sys/seal-status": () =>
-      Response.json({ sealed: false, initialized: false, t: 1, n: 1, progress: 0 }),
-    "GET /v1/sys/health": () =>
-      Response.json({ initialized: true, sealed: false, standby: false }, { status: 200 }),
-    "POST /v1/sys/init": () =>
-      Response.json({ keys: ["unseal-key-1"], keys_base64: ["dW5zZWFs"], root_token: "root-tok" }),
-    "POST /v1/sys/unseal": () => Response.json({ sealed: false, t: 1, n: 1, progress: 0 }),
-    "POST /v1/sys/mounts/secret": () => Response.json({}),
-    "POST /v1/sys/policy/oke-app": () => new Response(null, { status: 204 }),
-    "POST /v1/auth/token/create": () =>
-      Response.json({ auth: { client_token: "app-tok", policies: ["oke-app"] } }),
-  };
-  const fetchFn = (async (input: string | URL | Request, init?: RequestInit) => {
-    const url = String(input);
-    const method = init?.method ?? "GET";
-    calls.push({ url, method, body: typeof init?.body === "string" ? init.body : undefined });
-    const path = new URL(url).pathname;
-    const handler = routes[`${method} ${path}`];
-    if (!handler) return new Response("not found", { status: 404 });
-    return handler();
-  }) as typeof globalThis.fetch;
-  return fetchFn;
-}
-
-describe("openbao bootstrap material gates", () => {
-  test("`.oke/` is gitignored (check-ignore, not inference)", () => {
-    const root = join(import.meta.dir, "../..");
-    for (const p of [
-      `${OPENBAO_STATE_DIR_REL}/unseal.key`,
-      `${OPENBAO_STATE_DIR_REL}/root.token`,
-    ]) {
-      const proc = Bun.spawnSync(["git", "check-ignore", "-v", p], {
-        cwd: root,
-        stdout: "pipe",
-        stderr: "pipe",
-      });
-      expect(proc.exitCode).toBe(0);
-      expect(proc.stdout.toString()).toContain(".gitignore");
-    }
-  });
-
-  test("init writes 0600 files + 0700 dir (real mode) before success", async () => {
-    const cwd = await tempDir();
-    const calls: { url: string; method: string; body?: string }[] = [];
-    const result = await ensureOpenBao({
-      cwd,
-      url: "http://127.0.0.1:8200",
-      names: ["STRIPE_KEY", "DATABASE_URL"],
-      fetch: fakeOpenBao(calls),
-    });
-    expect(result.initializedNow).toBe(true);
-    expect(result.appToken).toBe("app-tok");
-
-    const stateDir = join(cwd, OPENBAO_STATE_DIR_REL);
-    expect(statSync(stateDir).mode & 0o777).toBe(0o700);
-    expect(statSync(join(stateDir, "unseal.key")).mode & 0o777).toBe(0o600);
-    expect(statSync(join(stateDir, "root.token")).mode & 0o777).toBe(0o600);
-    expect(statSync(join(stateDir, "app.token")).mode & 0o777).toBe(0o600);
-    assertMode(join(stateDir, "unseal.key"), 0o600);
-
-    // Policy is scoped to the two declared paths only.
-    const policyCall = calls.find((c) => c.url.endsWith("/v1/sys/policy/oke-app"));
-    expect(policyCall?.body).toContain("secret/data/STRIPE_KEY");
-    expect(policyCall?.body).toContain("secret/data/DATABASE_URL");
-    expect(policyCall?.body).not.toContain("secret/data/*");
-  });
-
-  test("post-init material write failure does NOT report success", async () => {
-    const cwd = await tempDir();
-    // Block the state dir with a *file* so mkdir/write fails after init.
-    const blocker = join(cwd, ".oke");
-    await Bun.write(blocker, "not-a-dir");
-
-    const calls: { url: string; method: string; body?: string }[] = [];
-    let failed: unknown;
-    try {
-      await ensureOpenBao({
-        cwd,
-        url: "http://127.0.0.1:8200",
-        names: ["STRIPE_KEY"],
-        fetch: fakeOpenBao(calls),
-      });
-    } catch (err) {
-      failed = err;
-    }
-    expect(failed).toBeDefined();
-    // init happened (vault now initialized server-side) but we never returned
-    // success without durable material.
-    expect(calls.some((c) => c.url.endsWith("/v1/sys/init"))).toBe(true);
-    expect(calls.some((c) => c.url.endsWith("/v1/auth/token/create"))).toBe(false);
-  });
-
-  test("initialized but host unseal.key missing → loud permanent-loss error", async () => {
-    const cwd = await tempDir();
-    const calls: { url: string; method: string; body?: string }[] = [];
-    const fetchFn = fakeOpenBao(calls);
-    // Seal-status says initialized (data exists) but the host has no material.
-    const initialized = (async (input: string | URL | Request, init?: RequestInit) => {
-      const url = String(input);
-      if (url.endsWith("/v1/sys/seal-status")) {
-        return Response.json({ sealed: true, initialized: true });
-      }
-      return fetchFn(input as string, init);
-    }) as typeof globalThis.fetch;
-
-    let failed: unknown;
-    try {
-      await ensureOpenBao({ cwd, url: "http://127.0.0.1:8200", fetch: initialized });
-    } catch (err) {
-      failed = err;
-    }
-    expect(failed).toBeInstanceOf(OpenBaoBootstrapError);
-    expect(String(failed)).toContain("unrecoverable");
-    expect(String(failed)).toContain("compose.vault.yml down -v");
-  });
-});