okengine 0.2.5 → 0.2.8

package/src/cli/eval.ts

@@ -3,11 +3,7 @@
  */
 
 import { resolve } from "node:path";
-import {
-  parseEvalJsonl,
-  runPromptEvals,
-  type EvalCase,
-} from "../elements/ai/eval.ts";
+import { parseEvalJsonl, runPromptEvals, type EvalCase } from "../elements/ai/eval.ts";
 import type { Manifest } from "../manifest/types.ts";
 
 /** Options for {@link runOkeEval}. */
@@ -35,9 +31,7 @@ export interface OkeEvalOptions {
  * @param options - Manifest + ask wiring
  * @returns Exit code (1 on any failure)
  */
-export async function runOkeEval(
-  options: OkeEvalOptions = {},
-): Promise<number> {
+export async function runOkeEval(options: OkeEvalOptions = {}): Promise<number> {
   const write = options.write ?? ((t) => process.stdout.write(t));
   let manifest = options.manifest;
   if (!manifest) {
@@ -57,9 +51,7 @@ export async function runOkeEval(
     return 0;
   }
 
-  const load =
-    options.loadEvals ??
-    (async (p: string) => Bun.file(resolve(p)).text());
+  const load = options.loadEvals ?? (async (p: string) => Bun.file(resolve(p)).text());
 
   let failed = 0;
   for (const name of names) {
@@ -69,9 +61,7 @@ export async function runOkeEval(
       continue;
     }
     if (!options.ask) {
-      console.error(
-        `oke eval: ask() not wired — provide a runtime binding for prompt "${name}"`,
-      );
+      console.error(`oke eval: ask() not wired — provide a runtime binding for prompt "${name}"`);
       return 1;
     }
     let cases: EvalCase[];

package/src/cli/gates-list.ts

@@ -3,10 +3,7 @@
  */
 
 import { resolve } from "node:path";
-import {
-  deriveModuleActions,
-  formatGatesList,
-} from "../elements/gate/permissions.ts";
+import { deriveModuleActions, formatGatesList } from "../elements/gate/permissions.ts";
 import type { Manifest } from "../manifest/types.ts";
 import { wantsJson } from "./args.ts";
 import { EXIT_OK, EXIT_RUNTIME } from "./exit.ts";

package/src/cli/hero-meta.test.ts

@@ -15,31 +15,29 @@ import {
 const SAMPLE: OkeConfig = {
   drivers: {
     store: {
-      sql: { dev: "sqlite", stack: "postgres", prod: "postgres" },
-      kv: { dev: "memory", stack: "redis", prod: "redis" },
+      sql: { local: "sqlite", docker: "postgres", prod: "postgres" },
+      kv: { local: "memory", docker: "redis", prod: "redis" },
     },
-    signal: { dev: "memory", stack: "postgres", prod: "postgres" },
-    clock: { dev: "memory", stack: "postgres", prod: "postgres" },
-    vault: { dev: "dotenv", stack: "dotenv", prod: "sops" },
+    signal: { local: "memory", docker: "postgres", prod: "postgres" },
+    clock: { local: "memory", docker: "postgres", prod: "postgres" },
+    vault: { local: "dotenv", docker: "dotenv", prod: "sops" },
     channel: {
-      email: { dev: "console", stack: "smtp", prod: "smtp" },
+      email: { local: "console", docker: "smtp", prod: "smtp" },
     },
-    ai: { dev: "mock", stack: "mock" },
+    ai: { local: "mock", docker: "mock" },
   },
 };
 
 describe("hero-meta", () => {
-  test("resolveDevProfile maps stack and NODE_ENV", () => {
-    expect(resolveDevProfile({ stack: false })).toBe("local");
-    expect(resolveDevProfile({ stack: true })).toBe("local-server");
-    expect(resolveDevProfile({ stack: false, nodeEnv: "test" })).toBe("test");
-    expect(resolveDevProfile({ stack: false, nodeEnv: "production" })).toBe(
-      "production",
-    );
+  test("resolveDevProfile maps docker and NODE_ENV", () => {
+    expect(resolveDevProfile({ docker: false })).toBe("local");
+    expect(resolveDevProfile({ docker: true })).toBe("docker");
+    expect(resolveDevProfile({ docker: false, nodeEnv: "test" })).toBe("test");
+    expect(resolveDevProfile({ docker: false, nodeEnv: "production" })).toBe("production");
   });
 
   test("resolveHeroElements lists eight elements with drivers", () => {
-    const rows = resolveHeroElements(SAMPLE, { stack: false });
+    const rows = resolveHeroElements(SAMPLE, { docker: false });
     expect(rows.map((r) => r.element)).toEqual([
       "flow",
       "signal",
@@ -54,9 +52,9 @@ describe("hero-meta", () => {
     expect(rows.find((r) => r.element === "flow")?.detail).toBe("●");
   });
 
-  test("stack profile applies to every element", () => {
+  test("docker profile applies to every element", () => {
     const rows = resolveHeroElements(SAMPLE, {
-      stack: true,
+      docker: true,
       sqlDriver: "postgres",
       kvDriver: "redis",
     });
@@ -72,13 +70,13 @@ describe("hero-meta", () => {
   test("encode/decode round-trips", () => {
     const snap = buildDevHeroSnapshot({
       config: SAMPLE,
-      stack: true,
+      docker: true,
       sqlDriver: "postgres",
       kvDriver: "redis",
       version: "0.2.4",
       nodeEnv: "development",
     });
-    expect(snap.profile).toBe("local-server");
+    expect(snap.profile).toBe("docker");
     expect(snap.runtimeEnv).toBe("local");
     expect(decodeHeroSnapshot(encodeHeroSnapshot(snap))).toEqual(snap);
   });

package/src/cli/hero-meta.ts

@@ -11,11 +11,7 @@ import {
 } from "../config/index.ts";
 
 /** How the process is running (local laptop → production). */
-export type DevRuntimeProfile =
-  | "local"
-  | "local-server"
-  | "test"
-  | "production";
+export type DevRuntimeProfile = "local" | "docker" | "test" | "production";
 
 /** Data plane: still on a laptop vs real production. */
 export type DevRuntimeEnv = "local" | "production";
@@ -61,16 +57,16 @@ export function formatHeroSystemLine(
 /**
  * Profile for an `oke dev` session.
  *
- * @param options - Stack / NODE_ENV hints
+ * @param options - Docker / NODE_ENV hints
  */
 export function resolveDevProfile(options: {
-  readonly stack: boolean;
+  readonly docker: boolean;
   /** Explicit role — do not infer from ambient `NODE_ENV` (tests set `test`). */
   readonly nodeEnv?: string;
 }): DevRuntimeProfile {
   if (options.nodeEnv === "test") return "test";
   if (options.nodeEnv === "production") return "production";
-  return options.stack ? "local-server" : "local";
+  return options.docker ? "docker" : "local";
 }
 
 /**
@@ -78,9 +74,7 @@ export function resolveDevProfile(options: {
  *
  * @param profile - Runtime profile
  */
-export function resolveDevRuntimeEnv(
-  profile: DevRuntimeProfile,
-): DevRuntimeEnv {
+export function resolveDevRuntimeEnv(profile: DevRuntimeProfile): DevRuntimeEnv {
   return profile === "production" ? "production" : "local";
 }
 
@@ -89,7 +83,7 @@ export function resolveDevRuntimeEnv(
  *
  * @param map - Env driver map
  * @param env - Config env key
- * @param prefer - Override (stack sql/kv)
+ * @param prefer - Override (docker sql/kv)
  */
 function driverOr(
   map: Parameters<typeof resolveDriverId>[0],
@@ -106,10 +100,7 @@ function driverOr(
  * @param channel - Channel driver maps
  * @param env - Config env
  */
-function channelDetail(
-  channel: DriversConfig["channel"],
-  env: ConfigEnv,
-): string {
+function channelDetail(channel: DriversConfig["channel"], env: ConfigEnv): string {
   if (!channel) return "—";
   const parts: string[] = [];
   for (const medium of ["email", "sms", "whatsapp", "push"] as const) {
@@ -120,11 +111,11 @@ function channelDetail(
 }
 
 /**
- * Summarize store facets for the active (or stack-overridden) drivers.
+ * Summarize store facets for the active (or docker-overridden) drivers.
  *
  * @param store - Store driver maps
  * @param env - Config env for non-overridden facets
- * @param overrides - Stack sql/kv ids
+ * @param overrides - Docker sql/kv ids
  */
 function storeDetail(
   store: DriversConfig["store"],
@@ -145,26 +136,25 @@ function storeDetail(
 }
 
 /**
- * Resolve eight-element rows from `oke.config` + stack overrides.
+ * Resolve eight-element rows from `oke.config` + docker overrides.
  *
  * @param config - Loaded config (or null)
- * @param options - Stack driver overrides; config env for maps
+ * @param options - Docker driver overrides; config env for maps
  */
 export function resolveHeroElements(
   config: OkeConfig | null | undefined,
   options: {
-    /** Use prod store ids from stack (`oke dev -s`). */
-    readonly stack: boolean;
+    /** Use docker store ids from stack (`oke dev -d`). */
+    readonly docker: boolean;
     readonly sqlDriver?: string;
     readonly kvDriver?: string;
-    /** Which driver map column to read (default `dev`). */
+    /** Which driver map column to read (default `local`). */
     readonly configEnv?: ConfigEnv;
   },
 ): readonly HeroElementRow[] {
   const drivers = config?.drivers;
-  // `-s` reads the `stack` profile for every element (not a store-only override).
-  const configEnv: ConfigEnv =
-    options.configEnv ?? (options.stack ? "stack" : "dev");
+  // `-d` reads the `docker` profile for every element (not a store-only override).
+  const configEnv: ConfigEnv = options.configEnv ?? (options.docker ? "docker" : "local");
 
   const byName: Record<string, string> = {
     flow: "●",
@@ -189,18 +179,18 @@ export function resolveHeroElements(
 /**
  * Build the full hero snapshot for banner / soft reload.
  *
- * @param options - Config, stack, versions
+ * @param options - Config, docker, versions
  */
 export function buildDevHeroSnapshot(options: {
   readonly config?: OkeConfig | null;
-  readonly stack: boolean;
+  readonly docker: boolean;
   readonly sqlDriver?: string;
   readonly kvDriver?: string;
   readonly version?: string;
   readonly nodeEnv?: string;
 }): DevHeroSnapshot {
   const profile = resolveDevProfile({
-    stack: options.stack,
+    docker: options.docker,
     nodeEnv: options.nodeEnv,
   });
   return {
@@ -208,7 +198,7 @@ export function buildDevHeroSnapshot(options: {
     runtimeEnv: resolveDevRuntimeEnv(profile),
     system: formatHeroSystemLine(),
     elements: resolveHeroElements(options.config, {
-      stack: options.stack,
+      docker: options.docker,
       sqlDriver: options.sqlDriver,
       kvDriver: options.kvDriver,
     }),

package/src/cli/images.ts

@@ -54,9 +54,7 @@ export interface ImagesPinOptions {
  *
  * @param options - Config / images
  */
-export async function runImagesList(
-  options: ImagesListOptions = {},
-): Promise<number> {
+export async function runImagesList(options: ImagesListOptions = {}): Promise<number> {
   const write = options.write ?? ((t) => process.stdout.write(t));
   const writeErr = options.writeErr ?? ((t) => process.stderr.write(t));
   const json = options.json ?? false;
@@ -113,8 +111,7 @@ export function buildImagesListRows(
     } catch {
       // Unknown image — still list the row; recipe stays "-".
     }
-    const digest =
-      lock?.images[role]?.digest ?? digestFromRef ?? "-";
+    const digest = lock?.images[role]?.digest ?? digestFromRef ?? "-";
     return {
       role,
       recipe,
@@ -150,9 +147,7 @@ export function formatImagesList(rows: readonly ImagesListRow[]): string {
  *
  * @param options - Config / resolver
  */
-export async function runImagesPin(
-  options: ImagesPinOptions = {},
-): Promise<number> {
+export async function runImagesPin(options: ImagesPinOptions = {}): Promise<number> {
   const write = options.write ?? ((t) => process.stdout.write(t));
   const cwd = options.cwd ?? process.cwd();
   let images = options.images;

package/src/cli/index.ts

@@ -7,6 +7,7 @@ import { branchCli } from "./branch.ts";
 import { buildCli } from "./build.ts";
 import { clientAddCli } from "./client-add.ts";
 import { completionCli } from "./completion.ts";
+import { dbCli } from "./db.ts";
 import { devCli } from "./dev.ts";
 import { doctorCli } from "./doctor.ts";
 import { dockerCli } from "./docker.ts";
@@ -14,6 +15,7 @@ import { evalCli } from "./eval.ts";
 import { EXIT_CODE_HELP, EXIT_OK, EXIT_USAGE } from "./exit.ts";
 import { gatesListCli } from "./gates-list.ts";
 import { imagesCli } from "./images.ts";
+import { modeCli } from "./mode.ts";
 import { privacyEraseCli } from "./privacy-erase.ts";
 import { formatOkeHelp } from "./registry.ts";
 import { schemaCli } from "./schema.ts";
@@ -29,6 +31,10 @@ if (cmd === "dev") {
   process.exit(await devCli(sub ? [sub, ...rest] : rest));
 }
 
+if (cmd === "mode") {
+  process.exit(await modeCli(sub ? [sub, ...rest] : rest));
+}
+
 if (cmd === "start") {
   process.exit(await startCli(sub ? [sub, ...rest] : rest));
 }
@@ -45,6 +51,10 @@ if (cmd === "schema") {
   process.exit(await schemaCli(sub ? [sub, ...rest] : rest));
 }
 
+if (cmd === "db") {
+  process.exit(await dbCli(sub ? [sub, ...rest] : rest));
+}
+
 if (cmd === "client" && sub === "add") {
   process.exit(await clientAddCli(rest));
 }
@@ -91,8 +101,7 @@ if (cmd === "completion") {
 
 if (cmd === undefined || cmd === "--help" || cmd === "-h" || cmd === "help") {
   // Bare `oke` — commands only. Exit-code table only on explicit --help.
-  const help =
-    cmd === undefined ? formatOkeHelp() : `${formatOkeHelp()}${EXIT_CODE_HELP}`;
+  const help = cmd === undefined ? formatOkeHelp() : `${formatOkeHelp()}${EXIT_CODE_HELP}`;
   console.log(help);
   process.exit(cmd ? EXIT_OK : EXIT_USAGE);
 }

package/src/cli/load-config.images.test.ts

@@ -6,7 +6,7 @@ import { describe, expect, test } from "bun:test";
 import {
   defaultImagesFromConfig,
   resolveImages,
-  stackDevDriverMismatches,
+  dockerDevDriverMismatches,
 } from "./load-config.ts";
 
 describe("defaultImagesFromConfig", () => {
@@ -75,14 +75,14 @@ describe("resolveImages", () => {
   });
 });
 
-describe("stackDevDriverMismatches", () => {
-  test("flags stack/prod sqlite/memory when containers are up", () => {
-    const mismatches = stackDevDriverMismatches(
+describe("dockerDevDriverMismatches", () => {
+  test("flags docker/prod sqlite/memory when containers are up", () => {
+    const mismatches = dockerDevDriverMismatches(
       {
         drivers: {
           store: {
-            sql: { dev: "sqlite", stack: "sqlite", prod: "sqlite" },
-            kv: { dev: "memory", stack: "memory", prod: "memory" },
+            sql: { local: "sqlite", docker: "sqlite", prod: "sqlite" },
+            kv: { local: "memory", docker: "memory", prod: "memory" },
           },
         },
       },
@@ -94,13 +94,13 @@ describe("stackDevDriverMismatches", () => {
     ]);
   });
 
-  test("silent when stack profile matches containers", () => {
-    const mismatches = stackDevDriverMismatches(
+  test("silent when docker profile matches containers", () => {
+    const mismatches = dockerDevDriverMismatches(
       {
         drivers: {
           store: {
-            sql: { dev: "sqlite", stack: "postgres", prod: "postgres" },
-            kv: { dev: "memory", stack: "redis", prod: "redis" },
+            sql: { local: "sqlite", docker: "postgres", prod: "postgres" },
+            kv: { local: "memory", docker: "redis", prod: "redis" },
           },
         },
       },
@@ -109,13 +109,13 @@ describe("stackDevDriverMismatches", () => {
     expect(mismatches).toEqual([]);
   });
 
-  test("silent when only prod is set (stack falls back to prod)", () => {
-    const mismatches = stackDevDriverMismatches(
+  test("silent when only prod is set (docker falls back to prod)", () => {
+    const mismatches = dockerDevDriverMismatches(
       {
         drivers: {
           store: {
-            sql: { dev: "sqlite", prod: "postgres" },
-            kv: { dev: "memory", prod: "redis" },
+            sql: { local: "sqlite", prod: "postgres" },
+            kv: { local: "memory", prod: "redis" },
           },
         },
       },

package/src/cli/load-config.ts

@@ -22,33 +22,31 @@ function driverId(ref: DriverRef | undefined): string | undefined {
 }
 
 /**
- * Prefer `stack` then `prod` for a driver map (local server ≈ production).
+ * Prefer `docker` then `prod` for a driver map (compose infra ≈ production).
  *
  * @param map - Env driver map
  */
-function stackOrProdId(
-  map: { readonly stack?: DriverRef; readonly prod?: DriverRef } | undefined,
+function dockerOrProdId(
+  map: { readonly docker?: DriverRef; readonly prod?: DriverRef } | undefined,
 ): string | undefined {
-  return driverId(map?.stack) ?? driverId(map?.prod);
+  return driverId(map?.docker) ?? driverId(map?.prod);
 }
 
 /**
- * Derive default image pins from stack/prod driver protocols.
+ * Derive default image pins from docker/prod driver protocols.
  *
  * Used when `oke.config.ts` omits `images` but declares postgres/redis (etc.)
- * so `oke dev -s` / `oke stack` / `oke docker` have something to run.
+ * so `oke dev -d` / `oke stack` / `oke docker` have something to run.
  *
  * @param config - Loaded config
  */
-export function defaultImagesFromConfig(
-  config: OkeConfig,
-): Readonly<Record<string, string>> {
+export function defaultImagesFromConfig(config: OkeConfig): Readonly<Record<string, string>> {
   const out: Record<string, string> = {};
-  const sql = stackOrProdId(config.drivers?.store?.sql);
-  const index = stackOrProdId(config.drivers?.store?.index);
-  const kv = stackOrProdId(config.drivers?.store?.kv);
-  const signal = stackOrProdId(config.drivers?.signal);
-  const clock = stackOrProdId(config.drivers?.clock);
+  const sql = dockerOrProdId(config.drivers?.store?.sql);
+  const index = dockerOrProdId(config.drivers?.store?.index);
+  const kv = dockerOrProdId(config.drivers?.store?.kv);
+  const signal = dockerOrProdId(config.drivers?.signal);
+  const clock = dockerOrProdId(config.drivers?.clock);
 
   const needsSql =
     sql === "postgres" ||
@@ -56,19 +54,14 @@ export function defaultImagesFromConfig(
     index === "pgvector" ||
     signal === "postgres" ||
     clock === "postgres" ||
-    (config.drivers?.prod ?? []).some(
-      (p) => p === "postgres" || p === "pgvector",
-    );
+    (config.drivers?.prod ?? []).some((p) => p === "postgres" || p === "pgvector");
 
   if (needsSql) {
     out["store.sql"] =
-      sql === "pgvector" || index === "pgvector"
-        ? DEFAULT_PGVECTOR_IMAGE
-        : DEFAULT_SQL_IMAGE;
+      sql === "pgvector" || index === "pgvector" ? DEFAULT_PGVECTOR_IMAGE : DEFAULT_SQL_IMAGE;
   }
 
-  const needsKv =
-    kv === "redis" || (config.drivers?.prod ?? []).includes("redis");
+  const needsKv = kv === "redis" || (config.drivers?.prod ?? []).includes("redis");
   if (needsKv) {
     out["store.kv"] = DEFAULT_KV_IMAGE;
   }
@@ -109,9 +102,7 @@ export async function loadOkeConfig(
     }
     return { config: mod.default, path };
   }
-  throw new Error(
-    `oke: no oke.config.ts found in ${cwd} — create one with defineConfig()`,
-  );
+  throw new Error(`oke: no oke.config.ts found in ${cwd} — create one with defineConfig()`);
 }
 
 /**
@@ -131,7 +122,7 @@ export async function loadManifest(path: string): Promise<Manifest> {
  * Resolve images map from config or Manifest.
  *
  * When neither declares `images`, derive defaults from prod driver protocols
- * so `oke dev -s` works on scaffolded templates without an explicit pin map.
+ * so `oke dev -d` works on scaffolded templates without an explicit pin map.
  *
  * @param config - Optional config
  * @param manifest - Optional manifest
@@ -150,49 +141,44 @@ export function resolveImages(
 export type StackDriverMismatch = {
   /** Short label (`sql`, `kv`). */
   readonly label: string;
-  /** Active `drivers.*.stack` (→ prod) id. */
+  /** Active `drivers.*.docker` (→ prod) id. */
   readonly using: string;
   /** Driver that would use the container. */
   readonly container: string;
 };
 
 /**
- * Detect when `oke dev -s` containers will not back the app because the
- * `stack` driver profile still points at local/memory backends.
+ * Detect when `oke dev -d` containers will not back the app because the
+ * `docker` driver profile still points at local/memory backends.
  *
  * @param config - Loaded config
  * @param stackRoles - Roles being composed
  */
-export function stackDevDriverMismatches(
+export function dockerDevDriverMismatches(
   config: OkeConfig,
   stackRoles: readonly string[],
 ): readonly StackDriverMismatch[] {
   const roles = new Set(stackRoles);
   const out: StackDriverMismatch[] = [];
-  const sqlStack =
-    driverId(config.drivers?.store?.sql?.stack) ??
-    driverId(config.drivers?.store?.sql?.prod);
-  const kvStack =
-    driverId(config.drivers?.store?.kv?.stack) ??
-    driverId(config.drivers?.store?.kv?.prod);
+  const sqlDocker =
+    driverId(config.drivers?.store?.sql?.docker) ?? driverId(config.drivers?.store?.sql?.prod);
+  const kvDocker =
+    driverId(config.drivers?.store?.kv?.docker) ?? driverId(config.drivers?.store?.kv?.prod);
 
   if (
     roles.has("store.sql") &&
-    (sqlStack === "sqlite" || sqlStack === "memory" || sqlStack === undefined)
+    (sqlDocker === "sqlite" || sqlDocker === "memory" || sqlDocker === undefined)
   ) {
     out.push({
       label: "sql",
-      using: sqlStack ?? "unset",
+      using: sqlDocker ?? "unset",
       container: "postgres",
     });
   }
-  if (
-    roles.has("store.kv") &&
-    (kvStack === "memory" || kvStack === undefined)
-  ) {
+  if (roles.has("store.kv") && (kvDocker === "memory" || kvDocker === undefined)) {
     out.push({
       label: "kv",
-      using: kvStack ?? "memory",
+      using: kvDocker ?? "memory",
       container: "redis",
     });
   }
@@ -200,7 +186,17 @@ export function stackDevDriverMismatches(
 }
 
 /**
- * @deprecated Use {@link stackDevDriverMismatches} — kept for older call sites.
+ * @deprecated Use {@link dockerDevDriverMismatches} — kept for older call sites.
+ */
+export function stackDevDriverMismatches(
+  config: OkeConfig,
+  stackRoles: readonly string[],
+): readonly StackDriverMismatch[] {
+  return dockerDevDriverMismatches(config, stackRoles);
+}
+
+/**
+ * @deprecated Use {@link dockerDevDriverMismatches} — kept for older call sites.
  * @param config - Loaded config
  * @param stackRoles - Roles being composed
  */
@@ -208,7 +204,5 @@ export function stackDevDriverWarnings(
   config: OkeConfig,
   stackRoles: readonly string[],
 ): readonly string[] {
-  return stackDevDriverMismatches(config, stackRoles).map(
-    (m) => `${m.label}: ${m.using}`,
-  );
+  return dockerDevDriverMismatches(config, stackRoles).map((m) => `${m.label}: ${m.using}`);
 }

package/src/cli/mcp-from-console.ts

@@ -4,10 +4,7 @@
  * Used by `oke dev` so port 6535 is not a separate mock context.
  */
 
-import {
-  createFileDiff,
-  emitStructuralDiff,
-} from "../console/server/structural.ts";
+import { createFileDiff, emitStructuralDiff } from "../console/server/structural.ts";
 import type { Manifest } from "../manifest/types.ts";
 import type { WideEvent } from "../runs/types.ts";
 import type { McpContext } from "../mcp/tools.ts";

package/src/cli/mode.ts

@@ -0,0 +1,45 @@
+/**
+ * `oke mode [local|docker]` — read or set the saved `oke dev` preference.
+ */
+
+import { parseDevMode, readDevMode, writeDevMode, type DevMode } from "./dev-mode.ts";
+
+/**
+ * CLI entry for `oke mode`.
+ *
+ * @param args - Args after `mode`
+ */
+export async function modeCli(args: readonly string[]): Promise<number> {
+  const cwd = process.cwd();
+  for (const a of args) {
+    if (a === "--help" || a === "-h") {
+      console.log(`oke mode [local|docker]
+
+Get or set the default infrastructure mode for \`oke dev\`
+(saved in .oke/mode). Session flags \`oke dev --local\` /
+\`oke dev --docker\` never change this preference.
+`);
+      return 0;
+    }
+  }
+
+  const positional = args.filter((a) => !a.startsWith("-"));
+  if (positional.length === 0) {
+    const saved = await readDevMode(cwd);
+    if (saved === null) {
+      console.log("oke mode: unset (default local until chosen)");
+      return 0;
+    }
+    console.log(saved);
+    return 0;
+  }
+
+  const next = parseDevMode(positional[0]);
+  if (next === null) {
+    console.error(`oke mode: expected local|docker, got ${JSON.stringify(positional[0])}`);
+    return 1;
+  }
+  await writeDevMode(cwd, next satisfies DevMode);
+  console.log(`oke mode: saved ${next}`);
+  return 0;
+}