okengine 0.2.1 → 0.2.3

package/src/cli/registry.ts

@@ -373,10 +373,6 @@ export function formatOkeHelp(): string {
     }
   }
   lines.push("");
-  lines.push("Flags: long form is canonical; short form is convenience only.");
-  lines.push("JSON:  doctor · stack · images list · gates list accept --json|-j");
-  lines.push("       (stdout = JSON only; hints/progress on stderr).");
-  lines.push("");
   return `${lines.join("\n")}\n`;
 }
 

package/src/cli/safe-defaults.test.ts

@@ -16,7 +16,7 @@ describe("oke safe-default overrides", () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-safe-docker-"));
     await Bun.write(
       join(dir, "oke.config.ts"),
-      `export default { images: { "store.sql": "postgres:16-alpine" } }\n`,
+      `export default { images: { "store.sql": "postgres:18-alpine" } }\n`,
     );
     // Without --prod, derive still runs but prod overlays are not requested.
     // We assert the parser default by calling runDockerDerive via dockerCli
@@ -25,7 +25,7 @@ describe("oke safe-default overrides", () => {
     const off = await runDockerDerive({
       cwd: dir,
       outDir: dir,
-      images: { "store.sql": "postgres:16-alpine" },
+      images: { "store.sql": "postgres:18-alpine" },
       dryRun: true,
       write: () => {},
     });
@@ -35,7 +35,7 @@ describe("oke safe-default overrides", () => {
     const on = await runDockerDerive({
       cwd: dir,
       outDir: dir,
-      images: { "store.sql": "postgres:16-alpine" },
+      images: { "store.sql": "postgres:18-alpine" },
       prod: true,
       dryRun: true,
       write: () => {},

package/src/console/server/app.ts

@@ -49,7 +49,8 @@ export function createConsoleApp(
   options: CreateConsoleAppOptions = {},
 ): ConsoleAppHandle {
   const state = createConsoleState(options);
-  if (!options.silentClaim) {
+  // Spec §2.5 — claim prints only while setup is open (no operators yet).
+  if (!options.silentClaim && !state.setupClosed) {
     printClaimCodeOnce(state.claim);
   }
 

package/src/console/server/claim.test.ts

@@ -52,10 +52,13 @@ describe("claim code", () => {
 
   test("prints to boot log exactly once", () => {
     const state = mintClaimCode(() => 1);
-    const lines: string[] = [];
-    printClaimCodeOnce(state, (l) => lines.push(l));
-    printClaimCodeOnce(state, (l) => lines.push(l));
-    expect(lines.filter((l) => l.includes(state.code)).length).toBe(1);
+    const chunks: string[] = [];
+    printClaimCodeOnce(state, (l) => chunks.push(l));
+    printClaimCodeOnce(state, (l) => chunks.push(l));
+    const joined = chunks.join("");
+    expect(joined).toContain(state.code);
+    expect(joined).toContain("Claim code");
+    expect(chunks.length).toBe(1);
   });
 
   test("constantTimeEqual is length-safe", () => {

package/src/console/server/claim.ts

@@ -5,6 +5,7 @@
  * and rate-limited (console §2.5 · §10.4).
  */
 
+import { formatClaimNote } from "../../term.ts";
 import {
   AUTH_RATE_LIMIT,
   AUTH_RATE_WINDOW_MS,
@@ -67,13 +68,7 @@ export function printClaimCodeOnce(
 ): void {
   if (state.printed) return;
   state.printed = true;
-  write("");
-  write("┌─────────────────────────────────────────────────────────┐");
-  write("│  oke Console — first-admin claim code (expires 30 min)  │");
-  write(`│  ${state.code}  │`);
-  write("│  Whoever can read this log already owns the server.     │");
-  write("└─────────────────────────────────────────────────────────┘");
-  write("");
+  write(formatClaimNote(state.code));
 }
 
 /** Result of {@link verifyClaimCode}. */

package/src/console/server/flows.ts

@@ -1771,6 +1771,7 @@ function createSetupClaim(state: ConsoleState) {
         name: input.name,
         password: input.password,
       });
+      state.persistOperator(op.id);
       const issued = await issueOperatorSession(state, op.id);
       fx.log.info("console.setup.claim", { operatorId: op.id });
       return sessionPayload(op.id, op.email, op.name, issued);

package/src/console/server/index.ts

@@ -71,6 +71,11 @@ export {
   type ClaimCodeState,
   type ClaimVerifyResult,
 } from "./claim.ts";
+export {
+  openConsolePersistence,
+  resolveConsoleSecret,
+  type ConsolePersistence,
+} from "./operator-db.ts";
 export {
   createConsoleBindings,
 } from "./flows.ts";

package/src/console/server/operator-db.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Durable Console operators under `.oke/console.sqlite`.
+ */
+
+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 { createOperator } from "../../auth/operator.ts";
+import { createConsoleApp } from "./app.ts";
+import {
+  openConsolePersistence,
+  resolveConsoleSecret,
+} from "./operator-db.ts";
+
+describe("console operator persistence", () => {
+  const dirs: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(
+      dirs.splice(0).map((d) => rm(d, { recursive: true, force: true })),
+    );
+  });
+
+  test("secret is stable across resolveConsoleSecret calls", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "oke-console-secret-"));
+    dirs.push(cwd);
+    const a = await resolveConsoleSecret(cwd);
+    const b = await resolveConsoleSecret(cwd);
+    expect(a).toBe(b);
+    expect(a.length).toBeGreaterThan(16);
+  });
+
+  test("claim persists and second boot skips claim print", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "oke-console-ops-"));
+    dirs.push(cwd);
+
+    const first = await openConsolePersistence(cwd);
+    expect(first.operators.operators.size).toBe(0);
+    const op = await createOperator(first.operators, {
+      email: "ops@example.com",
+      name: "Ops",
+      password: "password123",
+    });
+    first.persistOperator(op.id);
+    first.close();
+
+    const second = await openConsolePersistence(cwd);
+    expect(second.operators.operators.size).toBe(1);
+    expect(second.operators.operators.get(op.id)?.email).toBe(
+      "ops@example.com",
+    );
+    expect(second.operators.credentials.has(op.id)).toBe(true);
+
+    const printed: string[] = [];
+    const origLog = console.log;
+    console.log = (line?: unknown) => {
+      printed.push(String(line ?? ""));
+    };
+    try {
+      const app = createConsoleApp({
+        cwd,
+        secret: second.secret,
+        operators: second.operators,
+        persistOperator: second.persistOperator,
+        silentClaim: false,
+      });
+      expect(app.state.setupClosed).toBe(true);
+      expect(printed.join("\n")).not.toContain("Claim code");
+    } finally {
+      console.log = origLog;
+      second.close();
+    }
+  });
+});

package/src/console/server/operator-db.ts

@@ -0,0 +1,324 @@
+/**
+ * Durable operator plane for Console — `.oke/console.sqlite` + secret file.
+ *
+ * Spec: wizard closes permanently once the first operator exists (console §2.5).
+ * Claim codes stay ephemeral; operators and the signing secret must survive restarts.
+ */
+
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { Database } from "bun:sqlite";
+import {
+  createOperatorStore,
+  type OperatorStore,
+} from "../../auth/operator.ts";
+import type {
+  OperatorCredentialRow,
+  OperatorRow,
+  OperatorSsoLinkRow,
+} from "../../auth/tables.ts";
+import { AUTH_TABLES } from "../../auth/tables.ts";
+
+/** Relative paths under project cwd. */
+export const CONSOLE_OKE_DIR = ".oke";
+export const CONSOLE_SQLITE_NAME = "console.sqlite";
+export const CONSOLE_SECRET_NAME = "console.secret";
+
+/** Opened Console persistence handle. */
+export interface ConsolePersistence {
+  /** Stable signing secret. */
+  readonly secret: string;
+  /** Hydrated operator Maps. */
+  readonly operators: OperatorStore;
+  /** Persist (or update) one operator + credential + roles/sso. */
+  readonly persistOperator: (operatorId: string) => void;
+  /** Close the SQLite connection. */
+  readonly close: () => void;
+}
+
+/**
+ * Ensure `.oke/` exists and return absolute paths.
+ *
+ * @param cwd - Project root
+ */
+export function consoleOkePaths(cwd: string): {
+  readonly dir: string;
+  readonly sqlite: string;
+  readonly secret: string;
+} {
+  const dir = join(cwd, CONSOLE_OKE_DIR);
+  mkdirSync(dir, { recursive: true });
+  return {
+    dir,
+    sqlite: join(dir, CONSOLE_SQLITE_NAME),
+    secret: join(dir, CONSOLE_SECRET_NAME),
+  };
+}
+
+/**
+ * Load or create a stable Console signing secret under `.oke/console.secret`.
+ *
+ * @param cwd - Project root
+ * @param envSecret - Optional `OKE_CONSOLE_SECRET` override
+ */
+export async function resolveConsoleSecret(
+  cwd: string,
+  envSecret?: string,
+): Promise<string> {
+  if (envSecret !== undefined && envSecret.length > 0) return envSecret;
+  const paths = consoleOkePaths(cwd);
+  const file = Bun.file(paths.secret);
+  if (await file.exists()) {
+    const existing = (await file.text()).trim();
+    if (existing.length > 0) return existing;
+  }
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  const secret = [...bytes]
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+  await Bun.write(paths.secret, `${secret}\n`);
+  return secret;
+}
+
+/**
+ * Open Console operator DB, migrate schema, hydrate Maps.
+ *
+ * @param cwd - Project root
+ * @param options - Optional env secret override
+ */
+export async function openConsolePersistence(
+  cwd: string,
+  options: { readonly envSecret?: string } = {},
+): Promise<ConsolePersistence> {
+  const paths = consoleOkePaths(cwd);
+  const secret = await resolveConsoleSecret(cwd, options.envSecret);
+  const db = new Database(paths.sqlite, { create: true });
+  db.exec("PRAGMA journal_mode = WAL;");
+  migrateOperatorSchema(db);
+  const operators = loadOperatorStore(db);
+
+  return {
+    secret,
+    operators,
+    persistOperator(operatorId: string) {
+      persistOperator(db, operators, operatorId);
+    },
+    close() {
+      db.close();
+    },
+  };
+}
+
+/**
+ * Create operator tables if missing.
+ *
+ * @param db - bun:sqlite database
+ */
+export function migrateOperatorSchema(db: Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS ${AUTH_TABLES.operators} (
+      id TEXT PRIMARY KEY NOT NULL,
+      email TEXT NOT NULL UNIQUE,
+      name TEXT NOT NULL,
+      status TEXT NOT NULL,
+      mfa_enabled INTEGER NOT NULL DEFAULT 0,
+      invited_by TEXT,
+      last_seen_at INTEGER
+    );
+    CREATE TABLE IF NOT EXISTS ${AUTH_TABLES.operatorCredentials} (
+      operator_id TEXT PRIMARY KEY NOT NULL,
+      password_hash TEXT NOT NULL,
+      login_enabled INTEGER NOT NULL DEFAULT 1,
+      FOREIGN KEY (operator_id) REFERENCES ${AUTH_TABLES.operators}(id)
+    );
+    CREATE TABLE IF NOT EXISTS ${AUTH_TABLES.operatorSsoLinks} (
+      operator_id TEXT NOT NULL,
+      provider TEXT NOT NULL,
+      subject TEXT NOT NULL,
+      PRIMARY KEY (operator_id, provider, subject),
+      FOREIGN KEY (operator_id) REFERENCES ${AUTH_TABLES.operators}(id)
+    );
+    CREATE TABLE IF NOT EXISTS ${AUTH_TABLES.operatorRoles} (
+      operator_id TEXT NOT NULL,
+      role TEXT NOT NULL,
+      PRIMARY KEY (operator_id, role),
+      FOREIGN KEY (operator_id) REFERENCES ${AUTH_TABLES.operators}(id)
+    );
+  `);
+}
+
+/**
+ * Hydrate an {@link OperatorStore} from SQLite.
+ *
+ * @param db - Open database
+ */
+export function loadOperatorStore(db: Database): OperatorStore {
+  const store = createOperatorStore();
+
+  const opRows = db
+    .query(
+      `SELECT id, email, name, status, mfa_enabled, invited_by, last_seen_at
+       FROM ${AUTH_TABLES.operators}`,
+    )
+    .all() as Array<{
+    id: string;
+    email: string;
+    name: string;
+    status: OperatorRow["status"];
+    mfa_enabled: number;
+    invited_by: string | null;
+    last_seen_at: number | null;
+  }>;
+
+  for (const row of opRows) {
+    store.operators.set(row.id, {
+      id: row.id,
+      email: row.email,
+      name: row.name,
+      status: row.status,
+      mfaEnabled: row.mfa_enabled === 1,
+      invitedBy: row.invited_by,
+      lastSeenAt: row.last_seen_at,
+    });
+  }
+
+  const credRows = db
+    .query(
+      `SELECT operator_id, password_hash, login_enabled
+       FROM ${AUTH_TABLES.operatorCredentials}`,
+    )
+    .all() as Array<{
+    operator_id: string;
+    password_hash: string;
+    login_enabled: number;
+  }>;
+
+  for (const row of credRows) {
+    const cred: OperatorCredentialRow = {
+      operatorId: row.operator_id,
+      passwordHash: row.password_hash,
+      loginEnabled: row.login_enabled === 1,
+    };
+    store.credentials.set(row.operator_id, cred);
+  }
+
+  const ssoRows = db
+    .query(
+      `SELECT operator_id, provider, subject FROM ${AUTH_TABLES.operatorSsoLinks}`,
+    )
+    .all() as Array<{
+    operator_id: string;
+    provider: string;
+    subject: string;
+  }>;
+
+  for (const row of ssoRows) {
+    const link: OperatorSsoLinkRow = {
+      operatorId: row.operator_id,
+      provider: row.provider,
+      subject: row.subject,
+    };
+    const list = store.ssoLinks.get(row.operator_id) ?? [];
+    list.push(link);
+    store.ssoLinks.set(row.operator_id, list);
+  }
+
+  const roleRows = db
+    .query(
+      `SELECT operator_id, role FROM ${AUTH_TABLES.operatorRoles}`,
+    )
+    .all() as Array<{ operator_id: string; role: string }>;
+
+  for (const row of roleRows) {
+    const list = store.roles.get(row.operator_id) ?? [];
+    list.push(row.role);
+    store.roles.set(row.operator_id, list);
+  }
+
+  return store;
+}
+
+/**
+ * Upsert one operator (and related rows) from the in-memory store.
+ *
+ * @param db - Open database
+ * @param store - In-memory store
+ * @param operatorId - Operator id
+ */
+export function persistOperator(
+  db: Database,
+  store: OperatorStore,
+  operatorId: string,
+): void {
+  const op = store.operators.get(operatorId);
+  if (!op) {
+    throw new Error(`oke console: unknown operator ${operatorId}`);
+  }
+  const cred = store.credentials.get(operatorId);
+  if (!cred) {
+    throw new Error(`oke console: missing credential for ${operatorId}`);
+  }
+
+  const upsertOp = db.query(
+    `INSERT INTO ${AUTH_TABLES.operators}
+      (id, email, name, status, mfa_enabled, invited_by, last_seen_at)
+     VALUES ($id, $email, $name, $status, $mfa, $invited, $seen)
+     ON CONFLICT(id) DO UPDATE SET
+       email = excluded.email,
+       name = excluded.name,
+       status = excluded.status,
+       mfa_enabled = excluded.mfa_enabled,
+       invited_by = excluded.invited_by,
+       last_seen_at = excluded.last_seen_at`,
+  );
+  upsertOp.run({
+    $id: op.id,
+    $email: op.email,
+    $name: op.name,
+    $status: op.status,
+    $mfa: op.mfaEnabled ? 1 : 0,
+    $invited: op.invitedBy,
+    $seen: op.lastSeenAt,
+  });
+
+  const upsertCred = db.query(
+    `INSERT INTO ${AUTH_TABLES.operatorCredentials}
+      (operator_id, password_hash, login_enabled)
+     VALUES ($id, $hash, $enabled)
+     ON CONFLICT(operator_id) DO UPDATE SET
+       password_hash = excluded.password_hash,
+       login_enabled = excluded.login_enabled`,
+  );
+  upsertCred.run({
+    $id: cred.operatorId,
+    $hash: cred.passwordHash,
+    $enabled: cred.loginEnabled ? 1 : 0,
+  });
+
+  db.query(
+    `DELETE FROM ${AUTH_TABLES.operatorSsoLinks} WHERE operator_id = $id`,
+  ).run({ $id: operatorId });
+  const insertSso = db.query(
+    `INSERT INTO ${AUTH_TABLES.operatorSsoLinks} (operator_id, provider, subject)
+     VALUES ($id, $provider, $subject)`,
+  );
+  for (const link of store.ssoLinks.get(operatorId) ?? []) {
+    insertSso.run({
+      $id: link.operatorId,
+      $provider: link.provider,
+      $subject: link.subject,
+    });
+  }
+
+  db.query(
+    `DELETE FROM ${AUTH_TABLES.operatorRoles} WHERE operator_id = $id`,
+  ).run({ $id: operatorId });
+  const insertRole = db.query(
+    `INSERT INTO ${AUTH_TABLES.operatorRoles} (operator_id, role)
+     VALUES ($id, $role)`,
+  );
+  for (const role of store.roles.get(operatorId) ?? []) {
+    insertRole.run({ $id: operatorId, $role: role });
+  }
+}

package/src/console/server/serve.ts

@@ -22,6 +22,7 @@ import {
   type CreateConsoleAppOptions,
 } from "./app.ts";
 import { createLiveWebsocket, type ConsoleLiveData } from "./live.ts";
+import { openConsolePersistence } from "./operator-db.ts";
 import {
   CONSOLE_COOKIES,
   consoleSessionCookie,
@@ -37,6 +38,11 @@ export interface ServeConsoleOptions extends CreateConsoleAppOptions {
   readonly staticDir?: string;
   /** Boot environment — use `"dev"` / `"prod"` so Bearer auth is production-like. */
   readonly env?: "dev" | "prod" | "test";
+  /**
+   * Persist operators + secret under `.oke/` (default true).
+   * Set false for ephemeral test servers.
+   */
+  readonly persist?: boolean;
 }
 
 /** Running Console server handle. */
@@ -54,9 +60,24 @@ export async function serveConsole(
 ): Promise<ConsoleServerHandle> {
   const hostname = options.hostname ?? "127.0.0.1";
   const port = options.port ?? CONSOLE_PORT;
+  const cwd = options.cwd ?? process.cwd();
+  const wantPersist = options.persist !== false && options.operators === undefined;
+  const persistence = wantPersist
+    ? await openConsolePersistence(cwd, {
+        envSecret: options.secret ?? process.env.OKE_CONSOLE_SECRET,
+      })
+    : null;
   const handle = createConsoleApp({
     ...options,
+    cwd,
     silentClaim: options.silentClaim ?? false,
+    ...(persistence
+      ? {
+          secret: options.secret ?? persistence.secret,
+          operators: persistence.operators,
+          persistOperator: persistence.persistOperator,
+        }
+      : {}),
   });
 
   const env = options.env ?? "dev";
@@ -160,6 +181,7 @@ export async function serveConsole(
     stop(closeActive = false) {
       server.stop(closeActive);
       void handle.app.stop();
+      persistence?.close();
     },
   };
 }
@@ -172,11 +194,28 @@ export async function serveConsole(
 export async function startConsoleApp(
   options: CreateConsoleAppOptions & {
     readonly env?: "dev" | "prod" | "test";
+    /** Opt-in durable operators under `.oke/` (default false for unit tests). */
+    readonly persist?: boolean;
   } = {},
 ): Promise<ConsoleAppHandle> {
+  const cwd = options.cwd ?? process.cwd();
+  const persistence =
+    options.persist === true && options.operators === undefined
+      ? await openConsolePersistence(cwd, {
+          envSecret: options.secret ?? process.env.OKE_CONSOLE_SECRET,
+        })
+      : null;
   const handle = createConsoleApp({
     ...options,
+    cwd,
     silentClaim: options.silentClaim ?? true,
+    ...(persistence
+      ? {
+          secret: options.secret ?? persistence.secret,
+          operators: persistence.operators,
+          persistOperator: persistence.persistOperator,
+        }
+      : {}),
   });
   await bootConsoleApp(handle);
   return handle;

package/src/console/server/state.ts

@@ -345,6 +345,11 @@ export interface ConsoleState {
   }>;
   /** Whether first operator exists (wizard permanently closed). */
   get setupClosed(): boolean;
+  /**
+   * Persist an operator after claim/create (SQLite under `.oke/`).
+   * No-op when persistence is disabled (tests / memory-only).
+   */
+  persistOperator: (operatorId: string) => void;
   /**
    * Per-email login attempt timestamps for credential-check rate limiting
    * (console §10.4 — same 5/60s strategy as setup-claim).
@@ -398,6 +403,10 @@ export interface CreateConsoleStateOptions {
   readonly okeConfig?: OkeConfig | null;
   /** Host plugin registry for scopes / capabilities. */
   readonly pluginRegistry?: PluginRegistry | null;
+  /** Pre-hydrated operator store (from `.oke/console.sqlite`). */
+  readonly operators?: OperatorStore;
+  /** Persist hook after claim/create. */
+  readonly persistOperator?: (operatorId: string) => void;
 }
 
 /**
@@ -413,10 +422,12 @@ export function createConsoleState(
     process.env.OKE_CONSOLE_SECRET ??
     `oke-console-dev-${crypto.randomUUID()}`;
   const now = options.now ?? (() => Date.now());
+  const operators = options.operators ?? createOperatorStore();
   const claim = mintClaimCode(now);
-  const operators = createOperatorStore();
   const sessions = createSessionStore();
   const liveSubscribers = new Set<(msg: ConsoleLiveMessage) => void>();
+  const persistOperator =
+    options.persistOperator ?? ((_operatorId: string) => {});
 
   const signalConfig = createMemorySignalConfigStore();
   const gateAuth = createDefaultGateAuthStores();
@@ -843,6 +854,7 @@ export function createConsoleState(
     get setupClosed() {
       return operators.operators.size > 0;
     },
+    persistOperator,
   };
 
   return state;