okengine 0.21.1 → 0.23.0

package/src/cli/decide.ts

@@ -0,0 +1,174 @@
+/**
+ * `oke decide promote` — fetch the operator candidate and write the lockfile.
+ * The command does not recompute a certificate.
+ */
+
+import { join, resolve } from "node:path";
+import {
+  DECISION_LOCK_FILENAME,
+  lockFromCandidate,
+  parseDecisionLockfile,
+  type DecisionLockfile,
+} from "../elements/ai/decisions/certificate.ts";
+import { DECISION_EXPORT_WARNING } from "../elements/ai/decisions/export.ts";
+
+/** Options for {@link promoteDecision}. */
+export interface PromoteDecisionOptions {
+  readonly name: string;
+  /** Origin of the running app, including scheme and port. */
+  readonly origin: string;
+  /** Lockfile path. Defaults to `oke-decisions.lock.json` in the app root. */
+  readonly lockPath?: string;
+  /** Operator credential header value (`Authorization`). */
+  readonly authorization?: string;
+  /** Injected fetch. Defaults to the global fetch. */
+  readonly fetcher?: (input: string, init?: RequestInit) => Promise<Response>;
+  /** Existing lockfile body. When omitted, the file is read if it exists. */
+  readonly current?: DecisionLockfile;
+}
+
+/**
+ * Fetch one candidate and write it into the app lockfile.
+ *
+ * @param options - Decision name, origin, and credentials
+ */
+export async function promoteDecision(options: PromoteDecisionOptions): Promise<DecisionLockfile> {
+  const fetcher = options.fetcher ?? fetch;
+  const url = `${options.origin.replace(/\/$/, "")}/_oke/decisions/${encodeURIComponent(options.name)}/candidate`;
+  const headers = new Headers();
+  if (options.authorization) headers.set("authorization", options.authorization);
+  const res = await fetcher(url, { headers });
+  if (!res.ok) {
+    throw new Error(`oke decide promote: ${res.status} from ${url}`);
+  }
+  const candidate: unknown = await res.json();
+  const root = resolve(process.env["OKE_ROOT_DIR"] ?? ".");
+  const path = resolve(options.lockPath ?? join(root, DECISION_LOCK_FILENAME));
+  let current = options.current;
+  if (!current) {
+    const file = Bun.file(path);
+    if (await file.exists()) current = parseDecisionLockfile(await file.json());
+  }
+  const next = lockFromCandidate(options.name, candidate, current);
+  const { persistDecisionDrift } = await import("../elements/ai/decisions/labels.ts");
+  persistDecisionDrift(options.name, false);
+  await Bun.write(path, `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
+
+/** Options for {@link exportDecisionLabelsFile}. */
+export interface ExportDecisionLabelsOptions {
+  readonly name: string;
+  /** Origin of the running app, including scheme and port. */
+  readonly origin: string;
+  /** File the JSONL is written to. */
+  readonly out: string;
+  /** Operator credential header value (`Authorization`). */
+  readonly authorization?: string;
+  /** Tenant the operator is exporting. A mismatch is rejected by the app. */
+  readonly tenant?: string;
+  /** Injected fetch. Defaults to the global fetch. */
+  readonly fetcher?: (input: string, init?: RequestInit) => Promise<Response>;
+  /** Where the production-data warning is printed. Defaults to stdout. */
+  readonly write?: (text: string) => void;
+}
+
+/**
+ * Fetch reviewed labels and write seed JSONL. Prints that the file holds production data.
+ *
+ * @param options - Decision name, origin, and output path
+ */
+export async function exportDecisionLabelsFile(
+  options: ExportDecisionLabelsOptions,
+): Promise<void> {
+  const fetcher = options.fetcher ?? fetch;
+  const url = new URL(
+    `/_oke/decisions/${encodeURIComponent(options.name)}/labels`,
+    options.origin.endsWith("/") ? options.origin : `${options.origin}/`,
+  );
+  if (options.tenant) url.searchParams.set("tenant", options.tenant);
+  const headers = new Headers();
+  if (options.authorization) headers.set("authorization", options.authorization);
+  const res = await fetcher(url.toString(), { headers });
+  if (!res.ok) {
+    throw new Error(`oke decide labels: ${res.status} from ${url}`);
+  }
+  const body = (await res.json()) as { lines?: string; data?: { lines?: string } };
+  const lines = body.data?.lines ?? body.lines ?? "";
+  const write = options.write ?? ((text: string) => process.stdout.write(text));
+  write(`${DECISION_EXPORT_WARNING}\n`);
+  await Bun.write(options.out, lines);
+}
+
+/**
+ * `oke decide labels <name> --export`.
+ *
+ * @param name - Decision name
+ * @param rest - Flags after the name
+ */
+async function exportLabelsCommand(name: string | undefined, rest: string[]): Promise<number> {
+  if (!name || !rest.includes("--export")) {
+    console.error("oke decide: expected `oke decide labels <name> --export`");
+    return 1;
+  }
+  let origin = process.env.OKE_ORIGIN ?? "http://127.0.0.1:6530";
+  let out = `${name}.labels.jsonl`;
+  let authorization = process.env.OKE_OPERATOR_AUTHORIZATION;
+  let tenant: string | undefined;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--origin") origin = rest[++i] ?? origin;
+    else if (arg === "--out") out = rest[++i] ?? out;
+    else if (arg === "--authorization") authorization = rest[++i];
+    else if (arg === "--tenant") tenant = rest[++i];
+  }
+  await exportDecisionLabelsFile({
+    name,
+    origin,
+    out,
+    ...(authorization !== undefined ? { authorization } : {}),
+    ...(tenant !== undefined ? { tenant } : {}),
+  });
+  return 0;
+}
+
+/**
+ * CLI entry for `oke decide`.
+ *
+ * @param args - Remaining argv after `decide`
+ */
+export async function decideCli(args: string[]): Promise<number> {
+  const [sub, name, ...rest] = args;
+  if (sub === "--help" || sub === "-h" || !sub) {
+    console.log(`oke decide promote <name> [--origin URL] [--lock path]
+oke decide labels <name> --export [--out file] [--origin URL]
+
+promote fetches the operator candidate and writes oke-decisions.lock.json.
+labels --export writes reviewed labels as seed JSONL. The file contains production data.
+`);
+    return sub ? 0 : 1;
+  }
+  if (sub === "labels") return exportLabelsCommand(name, rest);
+  if (sub !== "promote" || !name) {
+    console.error(
+      "oke decide: expected `oke decide promote <name>` or `oke decide labels <name> --export`",
+    );
+    return 1;
+  }
+  let origin = process.env.OKE_ORIGIN ?? "http://127.0.0.1:6530";
+  let lockPath: string | undefined;
+  let authorization = process.env.OKE_OPERATOR_AUTHORIZATION;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--origin") origin = rest[++i] ?? origin;
+    else if (arg === "--lock") lockPath = rest[++i];
+    else if (arg === "--authorization") authorization = rest[++i];
+  }
+  await promoteDecision({
+    name,
+    origin,
+    ...(lockPath !== undefined ? { lockPath } : {}),
+    ...(authorization !== undefined ? { authorization } : {}),
+  });
+  return 0;
+}

package/src/cli/decision-lock-watch.test.ts

@@ -0,0 +1,45 @@
+/**
+ * `oke dev` reloads the decision lockfile without a restart.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  DECISION_LOCK_FILENAME,
+  getDecisionLock,
+  resetDecisionCertificates,
+} from "../elements/ai/decisions/certificate.ts";
+import { watchDecisionLockfile } from "./decision-lock-watch.ts";
+
+describe("decision lockfile watch", () => {
+  test("a change calls setDecisionLock without restarting", async () => {
+    resetDecisionCertificates();
+    const root = await mkdtemp(join(tmpdir(), "oke-lock-"));
+    const path = join(root, DECISION_LOCK_FILENAME);
+    await Bun.write(
+      path,
+      `${JSON.stringify({ decisions: { triage: { model: "m", questions: {} } } })}\n`,
+    );
+    let listener: ((event: "rename" | "change", filename: string | null) => void) | undefined;
+    const watch = watchDecisionLockfile(root, (_path, _options, next) => {
+      listener = next;
+      return { close() {} };
+    });
+    listener?.("change", DECISION_LOCK_FILENAME);
+    await watch.flushed();
+    expect(getDecisionLock()?.decisions.triage?.model).toBe("m");
+
+    await Bun.write(
+      path,
+      `${JSON.stringify({ decisions: { route: { model: "n", questions: {} } } })}\n`,
+    );
+    listener?.("change", DECISION_LOCK_FILENAME);
+    await watch.flushed();
+    expect(getDecisionLock()?.decisions.route?.model).toBe("n");
+    expect(getDecisionLock()?.decisions.triage).toBeUndefined();
+    watch.close();
+    resetDecisionCertificates();
+  });
+});

package/src/cli/decision-lock-watch.ts

@@ -0,0 +1,51 @@
+/**
+ * `oke dev` reloads `oke-decisions.lock.json` without restarting.
+ * Production reads the file once, at boot.
+ */
+
+import { watch } from "node:fs";
+import {
+  DECISION_LOCK_FILENAME,
+  loadDecisionLockfile,
+} from "../elements/ai/decisions/certificate.ts";
+
+/** Handle for the lockfile watcher. */
+export interface DecisionLockWatch {
+  close(): void;
+  /** Resolves after the latest reload this watcher started. */
+  flushed(): Promise<void>;
+}
+
+/**
+ * Install `setDecisionLock` whenever the lockfile changes.
+ *
+ * @param root - App root
+ * @param watchFs - Injected watch. The dev server uses `node:fs` on the root.
+ */
+export function watchDecisionLockfile(
+  root: string,
+  watchFs?: (
+    path: string,
+    options: { readonly recursive: true },
+    listener: (event: "rename" | "change", filename: string | null) => void,
+  ) => { close(): void },
+): DecisionLockWatch {
+  let pending: Promise<void> = Promise.resolve();
+  const reload = (): void => {
+    pending = loadDecisionLockfile(root).then(
+      () => undefined,
+      () => undefined,
+    );
+  };
+  if (watchFs) {
+    const handle = watchFs(`${root}/${DECISION_LOCK_FILENAME}`, { recursive: true }, () => {
+      reload();
+    });
+    return { close: () => handle.close(), flushed: () => pending };
+  }
+  const handle = watch(root, (_event, filename) => {
+    if (filename?.toString() !== DECISION_LOCK_FILENAME) return;
+    reload();
+  });
+  return { close: () => handle.close(), flushed: () => pending };
+}

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

@@ -21,6 +21,8 @@
 
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { closeSharedPostgresClients } from "../drivers/postgres.ts";
+import { installDevHotGeneration, takeDevHotGeneration } from "./dev-hot.ts";
 import { installGracefulShutdown, type GracefulShutdownApp } from "../kernel/graceful-shutdown.ts";
 import type { Manifest } from "../manifest/types.ts";
 import { createBunRuntime } from "../runtime/bun.ts";
@@ -67,22 +69,36 @@ if (manifestPath !== undefined && manifestPath.length > 0) {
   }
 }
 
+// Soft reload re-enters this file in the same process. Stop the previous
+// boot's 1s scheduler and close its Bun.SQL pools before opening new ones.
+// Holder `close()` is a no-op on the shared pool, so this has to be explicit.
+const previous = takeDevHotGeneration();
+if (previous) {
+  try {
+    await previous.dispose();
+  } catch (err) {
+    console.error(
+      `oke dev: previous hot generation failed to dispose — ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}
+await closeSharedPostgresClients();
+
 const absoluteEntry = resolve(entry);
 const mod = (await import(pathToFileURL(absoluteEntry).href)) as {
   app?: BootableApp;
 };
+const app = mod.app;
 
-if (
-  mod.app === undefined ||
-  typeof mod.app.boot !== "function" ||
-  typeof mod.app.fetch !== "function"
-) {
+if (app === undefined || typeof app.boot !== "function" || typeof app.fetch !== "function") {
   console.error(`oke dev: ${absoluteEntry} must export app with boot() and fetch()`);
   process.exit(1);
 }
 
 try {
-  await mod.app.boot({
+  await app.boot({
     rootDir: process.env["OKE_ROOT_DIR"],
     ...(manifest !== undefined ? { manifest } : {}),
   });
@@ -94,12 +110,22 @@ try {
   console.error(formatFatalError(err));
   process.exit(1);
 }
-const handle = createBunRuntime().serve(mod.app, {
+const handle = createBunRuntime().serve(app, {
   port,
   hostname,
   id: DEV_APP_SERVE_ID,
 });
-installGracefulShutdown({ app: mod.app, handle });
+const { watchDecisionLockfile } = await import("./decision-lock-watch.ts");
+const decisionLockWatch = watchDecisionLockfile(process.env.OKE_ROOT_DIR ?? process.cwd());
+const removeSignals = installGracefulShutdown({ app, handle });
+installDevHotGeneration({
+  async dispose() {
+    decisionLockWatch.close();
+    removeSignals();
+    await app.stop();
+    await closeSharedPostgresClients();
+  },
+});
 
 const appUrl = `http://${formatHostForUrl(hostname)}:${handle.port}`;
 // Parent board (claim + Docker) stays. Bun `--no-clear-screen` + no child wipe.

package/src/cli/dev-auth-secret.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ensureDevAuthSecret } from "./dev-auth-secret.ts";
+
+describe("ensureDevAuthSecret", () => {
+  const dirs: string[] = [];
+  const prev = process.env.OKE_AUTH_SECRET;
+
+  afterEach(async () => {
+    if (prev === undefined) delete process.env.OKE_AUTH_SECRET;
+    else process.env.OKE_AUTH_SECRET = prev;
+    await Promise.all(dirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+  });
+
+  test("reuses process.env and does not write a file", async () => {
+    process.env.OKE_AUTH_SECRET = "from-env";
+    const dir = await mkdtemp(join(tmpdir(), "oke-auth-secret-"));
+    dirs.push(dir);
+    expect(await ensureDevAuthSecret(dir)).toBe("from-env");
+    expect(await Bun.file(join(dir, ".env.local")).exists()).toBe(false);
+  });
+
+  test("reads .env.local before minting", async () => {
+    delete process.env.OKE_AUTH_SECRET;
+    const dir = await mkdtemp(join(tmpdir(), "oke-auth-secret-"));
+    dirs.push(dir);
+    await Bun.write(
+      join(dir, ".env.local"),
+      "DATABASE_URL=postgres://localhost/oke\nOKE_AUTH_SECRET=from-file\n",
+    );
+    expect(await ensureDevAuthSecret(dir)).toBe("from-file");
+  });
+
+  test("mints once and appends to .env.local", async () => {
+    delete process.env.OKE_AUTH_SECRET;
+    const dir = await mkdtemp(join(tmpdir(), "oke-auth-secret-"));
+    dirs.push(dir);
+    await Bun.write(join(dir, ".env.local"), "DATABASE_URL=postgres://localhost/oke\n");
+    const first = await ensureDevAuthSecret(dir);
+    expect(first.startsWith("oke_dev_")).toBe(true);
+    const text = await readFile(join(dir, ".env.local"), "utf8");
+    expect(text).toContain(`OKE_AUTH_SECRET=${first}`);
+    expect(text.startsWith("DATABASE_URL=")).toBe(true);
+    delete process.env.OKE_AUTH_SECRET;
+    expect(await ensureDevAuthSecret(dir)).toBe(first);
+  });
+});

package/src/cli/dev-auth-secret.ts

@@ -0,0 +1,49 @@
+/**
+ * One HMAC secret for `oke dev`.
+ *
+ * Console boots the app in the parent; the HTTP server is a child. Each
+ * process would otherwise mint its own `gate.auth` secret, and a Bearer API
+ * key hashed in Console would not verify on the app. This stores one
+ * `OKE_AUTH_SECRET` in `.env.local` and returns it for both.
+ */
+
+import { join } from "node:path";
+import { mintDevAuthSecret } from "../auth/config.ts";
+import { escapeDotenvValue, parseDotenv } from "../drivers/vault-dotenv-parse.ts";
+
+/**
+ * Resolve the shared dev auth secret.
+ *
+ * Order: `process.env.OKE_AUTH_SECRET`, then `.env.local`, then a minted
+ * value appended to `.env.local`. Does not write `process.env`.
+ *
+ * @param cwd - Project root
+ */
+export async function ensureDevAuthSecret(cwd: string): Promise<string> {
+  const current = process.env.OKE_AUTH_SECRET?.trim();
+  if (current) return current;
+
+  const envPath = join(cwd, ".env.local");
+  let text = "";
+  const file = Bun.file(envPath);
+  if (await file.exists()) {
+    try {
+      text = await file.text();
+    } catch {
+      text = "";
+    }
+  }
+  const fromFile = parseDotenv(text).get("OKE_AUTH_SECRET")?.trim();
+  if (fromFile) return fromFile;
+
+  const secret = mintDevAuthSecret();
+  const line = `OKE_AUTH_SECRET=${escapeDotenvValue(secret)}`;
+  const next =
+    text.length === 0
+      ? `${line}\n`
+      : text.endsWith("\n")
+        ? `${text}${line}\n`
+        : `${text}\n${line}\n`;
+  await Bun.write(envPath, next);
+  return secret;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Soft-reload slot: one live generation, disposed before the next boot.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { installDevHotGeneration, takeDevHotGeneration } from "./dev-hot.ts";
+
+describe("dev hot generation", () => {
+  test("take returns the installed generation once", async () => {
+    let disposed = 0;
+    installDevHotGeneration({
+      async dispose() {
+        disposed += 1;
+      },
+    });
+    const first = takeDevHotGeneration();
+    expect(first).toBeDefined();
+    await first!.dispose();
+    expect(disposed).toBe(1);
+    expect(takeDevHotGeneration()).toBeUndefined();
+  });
+
+  test("install replaces the previous slot without disposing it", () => {
+    installDevHotGeneration({
+      async dispose() {
+        throw new Error("stale");
+      },
+    });
+    let disposed = 0;
+    installDevHotGeneration({
+      async dispose() {
+        disposed += 1;
+      },
+    });
+    const current = takeDevHotGeneration();
+    expect(current).toBeDefined();
+    return current!.dispose().then(() => {
+      expect(disposed).toBe(1);
+    });
+  });
+});

package/src/cli/dev-hot.ts

@@ -0,0 +1,48 @@
+/**
+ * One live `bun --hot` generation for `oke dev`.
+ *
+ * Soft reload re-runs the app runner in the same process. The previous
+ * boot's scheduler and Postgres pools stay open unless this slot disposes
+ * them before the next `boot()`.
+ */
+
+const DEV_HOT_SLOT = Symbol.for("oke.dev.hot.generation");
+
+/** Work the previous runner evaluation must undo before the next boot. */
+export type DevHotGeneration = {
+  /** Stop schedulers, drop signal handlers, and close this generation's pools. */
+  dispose(): Promise<void>;
+};
+
+type HotBox = { current?: DevHotGeneration };
+
+function hotBox(): HotBox {
+  const g = globalThis as typeof globalThis & { [DEV_HOT_SLOT]?: HotBox };
+  let box = g[DEV_HOT_SLOT];
+  if (!box) {
+    box = {};
+    g[DEV_HOT_SLOT] = box;
+  }
+  return box;
+}
+
+/**
+ * Take the previous generation, if a soft reload left one.
+ *
+ * Clears the slot so a failed dispose cannot be retried against a half-stopped app.
+ */
+export function takeDevHotGeneration(): DevHotGeneration | undefined {
+  const box = hotBox();
+  const prev = box.current;
+  box.current = undefined;
+  return prev;
+}
+
+/**
+ * Remember this evaluation so the next soft reload can dispose it.
+ *
+ * @param generation - Stop handle for the boot that just started
+ */
+export function installDevHotGeneration(generation: DevHotGeneration): void {
+  hotBox().current = generation;
+}

package/src/cli/dev.test.ts

@@ -1191,7 +1191,7 @@ describe("oke dev Console vault config", () => {
   test("writes OKE_MANIFEST_PATH for the app child when a Manifest is available", async () => {
     const runner = await Bun.file(new URL("./dev-app-runner.ts", import.meta.url)).text();
     expect(runner).toContain("OKE_MANIFEST_PATH");
-    expect(runner).toMatch(/mod\.app\.boot\(\{/);
+    expect(runner).toMatch(/\bapp\.boot\(\{/);
 
     const dir = await mkdtemp(join(tmpdir(), "oke-dev-manifest-handoff-"));
     await Bun.write(join(dir, "src/app.ts"), "export {}\n");

package/src/cli/dev.ts

@@ -1036,6 +1036,13 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     setProcessEnv("OKE_KV_DRIVER", stackKvDriver);
   }
 
+  // One secret for Console (this process) and the app child. Must land
+  // before the first import of the app entry.
+  {
+    const { ensureDevAuthSecret } = await import("./dev-auth-secret.ts");
+    setProcessEnv("OKE_AUTH_SECRET", await ensureDevAuthSecret(cwd));
+  }
+
   // One-shot schema sync for the compose (`dev`) profile: emits
   // drizzle/ for the active dialect, then pushes via drizzle-kit.
   let schemaPushOk = options.noDbPush === true;
@@ -1063,12 +1070,20 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
   // Vault gaps before seed / app — missing contracts (e.g. OPENROUTER_API_KEY).
   {
     const { maybeAskVaultGaps } = await import("./ask-vault-gaps.ts");
-    const vaultCode = await maybeAskVaultGaps({
-      cwd,
-      entry,
-      write,
-      stdinIsTTY: options.stdinIsTTY ?? process.stdin.isTTY,
-    });
+    // The secret prompt owns an open cursor line. A board repaint would
+    // move that cursor and split the mask.
+    bootBoard.hold();
+    let vaultCode = 0;
+    try {
+      vaultCode = await maybeAskVaultGaps({
+        cwd,
+        entry,
+        write,
+        stdinIsTTY: options.stdinIsTTY ?? process.stdin.isTTY,
+      });
+    } finally {
+      bootBoard.release();
+    }
     if (vaultCode !== 0) {
       bootBoard.stop();
       restoreProcessEnv();
@@ -1443,6 +1458,8 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
       autoPushRunner.trigger();
     }
   });
+  const { watchDecisionLockfile } = await import("./decision-lock-watch.ts");
+  const decisionLockWatch = watchDecisionLockfile(cwd);
 
   let stopped = false;
   const stop = () => {
@@ -1458,6 +1475,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     clientRegen.cancel();
     manifestRefresh.cancel();
     watcher.close();
+    decisionLockWatch.close();
     const host = attachedHost;
     attachedHost = null;
     void host?.stop();

package/src/cli/docker-cli.test.ts

@@ -72,7 +72,7 @@ describe("oke stack", () => {
     const code = await runStackPreview({
       cwd: dir,
       images: {
-        "channel.email": "axllent/mailpit:v1.31.1",
+        "channel.email": "axllent/mailpit:v1.31.2",
       },
       write: (t) => {
         out += t;