okengine 0.10.3 → 0.11.0

package/src/cli/registry.ts

@@ -84,6 +84,27 @@ const HELP: CliFlag = {
   summary: "Show help",
 };
 
+const VAULT_KEY: CliFlag = {
+  long: "--key",
+  takesValue: true,
+  valueName: "base64|-",
+  summary: "Master key (`-` = stdin; else env / interactive prompt)",
+};
+
+const VAULT_NEW_KEY: CliFlag = {
+  long: "--new-key",
+  takesValue: true,
+  valueName: "base64|-",
+  summary: "New master key for resume (`-` = stdin)",
+};
+
+const VAULT_URL: CliFlag = {
+  long: "--url",
+  takesValue: true,
+  valueName: "url",
+  summary: "SQL URL (else DATABASE_URL)",
+};
+
 /**
  * Canonical `oke` command catalogue.
  *
@@ -93,24 +114,19 @@ const HELP: CliFlag = {
 export const OKE_COMMANDS: readonly CliCommand[] = [
   {
     name: "dev",
-    summary: "watch · hot reload · Console · client types",
+    summary: "watch · hot reload · Console · client types (Docker Compose)",
     leaf: true,
     flags: [
-      {
-        long: "--local",
-        short: "-l",
-        summary: "Session-only local mode (in-memory; no compose)",
-      },
       {
         long: "--docker",
         short: "-d",
         takesValue: true,
         valueName: "roles",
-        summary: "Session-only docker compose (optional role list)",
+        summary: "Optional compose role filter (default: all roles)",
       },
       {
         long: "--no-db-push",
-        summary: "Disable auto `oke db push` on schema change (local)",
+        summary: "Disable auto `oke db push` on schema change",
       },
       ENTRY,
       HELP,
@@ -118,7 +134,13 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
   },
   {
     name: "mode",
-    summary: "get/set default oke dev mode (local|docker)",
+    summary: "deprecated — oke dev always uses Docker Compose",
+    leaf: true,
+    flags: [HELP],
+  },
+  {
+    name: "test",
+    summary: "run bun test with PGLite test posture",
     leaf: true,
     flags: [HELP],
   },
@@ -182,11 +204,11 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
   },
   {
     name: "schema",
-    summary: "core + plugin tables → schema/oke.ts",
+    summary: "core + plugin tables → .oke/schema/oke.ts",
     subcommands: [
       {
         name: "generate",
-        summary: "Emit schema/oke.ts",
+        summary: "Emit .oke/schema/oke.ts",
         flags: [
           {
             long: "--check",
@@ -202,7 +224,7 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
   },
   {
     name: "db",
-    summary: "domain schema — push · generate · migrate · seed",
+    summary: "domain schema — push · generate · migrate · seed · studio",
     subcommands: [
       {
         name: "push",
@@ -219,7 +241,7 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
             long: "--env",
             takesValue: true,
             valueName: "name",
-            summary: "Config env (local|docker|test|prod)",
+            summary: "Config env (dev|test|prod)",
           },
           HELP,
         ],
@@ -239,7 +261,7 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
             long: "--env",
             takesValue: true,
             valueName: "name",
-            summary: "Config env (local|docker|test|prod)",
+            summary: "Config env (dev|test|prod)",
           },
           HELP,
         ],
@@ -259,7 +281,7 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
             long: "--env",
             takesValue: true,
             valueName: "name",
-            summary: "Config env (local|docker|test|prod)",
+            summary: "Config env (dev|test|prod)",
           },
           HELP,
         ],
@@ -272,7 +294,7 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
             long: "--env",
             takesValue: true,
             valueName: "name",
-            summary: "Config env (local|docker|test|prod)",
+            summary: "Config env (dev|test|prod)",
           },
           {
             long: "--force",
@@ -282,6 +304,26 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
           HELP,
         ],
       },
+      {
+        name: "studio",
+        summary: "Open drizzle-kit Studio (long-running)",
+        flags: [
+          {
+            long: "--config",
+            short: "-c",
+            takesValue: true,
+            valueName: "path",
+            summary: "drizzle.config.ts path",
+          },
+          {
+            long: "--env",
+            takesValue: true,
+            valueName: "name",
+            summary: "Config env (dev|test|prod)",
+          },
+          HELP,
+        ],
+      },
     ],
   },
   {
@@ -298,7 +340,7 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
   },
   {
     name: "vault",
-    summary: "set · list · import · key rotate",
+    summary: "secrets — set · list · seal/unseal · rotate · audit · backup",
     subcommands: [
       {
         name: "set",
@@ -319,6 +361,96 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
         positionals: "rotate",
         flags: [HELP],
       },
+      {
+        name: "init",
+        summary: "Create the builtin vault; print the master key once",
+        flags: [VAULT_URL, HELP],
+      },
+      {
+        name: "status",
+        summary: "Seal state · KEK generation · secret count",
+        flags: [VAULT_KEY, VAULT_URL, JSON_FLAG, HELP],
+      },
+      {
+        name: "seal",
+        summary: "Drop the master key; reads fail until unsealed",
+        flags: [VAULT_URL, HELP],
+      },
+      {
+        name: "unseal",
+        summary: "Verify the master key and clear the sealed flag",
+        flags: [VAULT_KEY, VAULT_URL, HELP],
+      },
+      {
+        name: "rotate",
+        summary: "New version of a secret under a fresh data key",
+        positionals: "<path> [value]",
+        flags: [VAULT_KEY, VAULT_URL, HELP],
+      },
+      {
+        name: "rotate-master",
+        summary: "New master key; re-wrap every data key",
+        flags: [VAULT_KEY, VAULT_NEW_KEY, VAULT_URL, HELP],
+      },
+      {
+        name: "audit",
+        summary: "Read · verify · purge the tamper-evident chain",
+        positionals: "[verify|purge]",
+        flags: [
+          {
+            long: "--limit",
+            takesValue: true,
+            valueName: "n",
+            summary: "Rows to show (default 50)",
+          },
+          {
+            long: "--path",
+            takesValue: true,
+            valueName: "path",
+            summary: "Restrict to one secret path",
+          },
+          {
+            long: "--before",
+            takesValue: true,
+            valueName: "iso",
+            summary: "Purge rows older than this instant",
+          },
+          VAULT_URL,
+          JSON_FLAG,
+          HELP,
+        ],
+      },
+      {
+        name: "purge-expired",
+        summary: "Hard-delete secret rows past expires_at",
+        flags: [
+          VAULT_KEY,
+          VAULT_URL,
+          {
+            long: "--dry-run",
+            summary: "Count expired rows without deleting",
+          },
+          {
+            long: "--before",
+            takesValue: true,
+            valueName: "iso",
+            summary: "Exclusive upper bound (default: now)",
+          },
+          HELP,
+        ],
+      },
+      {
+        name: "backup",
+        summary: "Write every live secret as one encrypted bundle",
+        positionals: "<file>",
+        flags: [VAULT_KEY, VAULT_URL, HELP],
+      },
+      {
+        name: "restore",
+        summary: "Replay a bundle as new versions",
+        positionals: "<file>",
+        flags: [VAULT_KEY, VAULT_URL, HELP],
+      },
     ],
   },
   {
@@ -549,7 +681,15 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
  * @returns Help text (no trailing exit-code block)
  */
 export function formatOkeHelp(): string {
-  const lines = ["oke — okengine CLI", "", "Commands:"];
+  const lines = [
+    "oke — okengine CLI",
+    "",
+    "  oke              Interactive TUI (TTY). Non-TTY prints this help.",
+    "  oke --tui        Force the interactive TUI",
+    "  oke --help       This command list",
+    "",
+    "Commands:",
+  ];
   for (const cmd of OKE_COMMANDS) {
     const usage = formatCommandUsage(cmd);
     lines.push(`  ${pad(usage, 34)} ${cmd.summary}`);
@@ -608,7 +748,7 @@ function formatCommandUsage(cmd: CliCommand): string {
     return `oke ${cmd.name} ${sub.name}${pos}${flagHint ? ` ${flagHint}` : ""}`;
   }
   if (cmd.subcommands && cmd.subcommands.length > 1) {
-    const subs = cmd.subcommands.map((s) => s.name).join("|");
+    const subs = summarizeSubcommands(cmd.subcommands);
     // Prefer shared JSON flag hint when every list-like sub supports it.
     const jsonHint = cmd.subcommands.some((s) => s.flags?.some((f) => f.long === "--json"))
       ? " [--json|-j]"
@@ -624,6 +764,22 @@ function formatCommandUsage(cmd: CliCommand): string {
   return `oke ${cmd.name}${pos}${flagHint ? ` ${flagHint}` : ""}`;
 }
 
+/** Longest `a|b|c` sub list the one-line help layout can carry. */
+const MAX_SUBCOMMAND_HINTS = 4;
+
+/**
+ * Join subcommand names for the one-line usage, eliding a long tail.
+ *
+ * Commands with a large surface (`vault`) would otherwise push the summary
+ * column off screen; the full list still reaches completion and `--help`.
+ *
+ * @param subs - Subcommands in registry order
+ */
+function summarizeSubcommands(subs: readonly CliSubcommand[]): string {
+  const shown = subs.slice(0, MAX_SUBCOMMAND_HINTS).map((s) => s.name);
+  return subs.length > MAX_SUBCOMMAND_HINTS ? `${shown.join("|")}|…` : shown.join("|");
+}
+
 function formatFlagHint(f: CliFlag): string {
   const name = f.short ? `${f.long}|${f.short}` : f.long;
   if (f.takesValue) {

package/src/cli/resolve-dev-sql-env.test.ts

@@ -1,12 +1,11 @@
 /**
- * Active SQL env resolution from `.oke/mode` / session overrides.
+ * Active SQL env resolution — Docker-first (`dev` default).
  */
 
 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 { writeDevMode } from "./dev-mode.ts";
 import { resolveDevSqlEnv } from "./resolve-dev-sql-env.ts";
 
 const dirs: string[] = [];
@@ -22,27 +21,20 @@ async function tempDir(): Promise<string> {
 }
 
 describe("resolveDevSqlEnv", () => {
-  test("defaults to local when nothing set", async () => {
+  test("defaults to dev (Docker-first)", async () => {
     const dir = await tempDir();
-    expect(await resolveDevSqlEnv(dir)).toBe("local");
+    expect(await resolveDevSqlEnv(dir)).toBe("dev");
   });
 
   test("explicit env override wins", async () => {
     const dir = await tempDir();
-    await writeDevMode(dir, "local");
-    expect(await resolveDevSqlEnv(dir, { env: "docker" })).toBe("docker");
+    expect(await resolveDevSqlEnv(dir, { env: "test" })).toBe("test");
+    expect(await resolveDevSqlEnv(dir, { env: "dev" })).toBe("dev");
   });
 
-  test("session docker flag wins over saved mode", async () => {
+  test("docker flag is ignored (always dev unless env set)", async () => {
     const dir = await tempDir();
-    await writeDevMode(dir, "local");
-    expect(await resolveDevSqlEnv(dir, { docker: true })).toBe("docker");
-    expect(await resolveDevSqlEnv(dir, { docker: false })).toBe("local");
-  });
-
-  test("reads saved .oke/mode", async () => {
-    const dir = await tempDir();
-    await writeDevMode(dir, "docker");
-    expect(await resolveDevSqlEnv(dir)).toBe("docker");
+    expect(await resolveDevSqlEnv(dir, { docker: true })).toBe("dev");
+    expect(await resolveDevSqlEnv(dir, { docker: false })).toBe("dev");
   });
 });

package/src/cli/resolve-dev-sql-env.ts

@@ -1,42 +1,40 @@
 /**
- * Resolve the active SQL env for schema tooling (`oke db`, `oke mode`,
- * `oke dev` one-shot sync) from session overrides and the saved dev mode.
+ * Resolve the active SQL env for schema tooling (`oke db`, `oke dev`
+ * one-shot sync). Docker-first: `oke dev` always uses `dev`.
  */
 
 import type { ConfigEnv } from "../config/index.ts";
-import { readDevMode } from "./dev-mode.ts";
 
 /** Options for {@link resolveDevSqlEnv}. */
 export interface ResolveDevSqlEnvOptions {
   /**
-   * Session override — `true` means docker (e.g. `OKE_DOCKER=1` or
-   * `oke dev --docker`). `false` means local. `undefined` → auto-resolve.
+   * Session override — `true` means compose infra is up. Ignored for env
+   * selection (always `dev` unless `options.env` is set); kept for call-site
+   * compatibility.
    */
   readonly docker?: boolean;
   /**
-   * Explicit env override (e.g. `oke db --env docker`). Wins over `.oke/mode`.
+   * Explicit env override (e.g. `oke db --env test`). Wins over the default.
    */
   readonly env?: ConfigEnv;
 }
 
 /**
- * Resolve the SQL env (`local` | `docker` for dev tooling) without prompting.
+ * Resolve the SQL {@link ConfigEnv} for tooling without prompting.
  *
  * Order:
  * 1. Explicit `options.env` (CLI flag)
- * 2. Session docker flag (`options.docker`)
- * 3. `.oke/mode` persisted preference
- * 4. Default `local`
+ * 2. Default `dev` (Docker-first local development)
  *
- * @param cwd - Project root
+ * @param _cwd - Project root (unused; kept for call-site compatibility)
  * @param options - Session / CLI overrides
  */
 export async function resolveDevSqlEnv(
-  cwd: string,
+  _cwd: string,
   options: ResolveDevSqlEnvOptions = {},
 ): Promise<ConfigEnv> {
+  void _cwd;
+  void options.docker;
   if (options.env !== undefined) return options.env;
-  if (options.docker !== undefined) return options.docker ? "docker" : "local";
-  const saved = await readDevMode(cwd);
-  return saved ?? "local";
+  return "dev";
 }

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

@@ -12,36 +12,54 @@ import { runImagesPin } from "./images.ts";
 import { upgradeCli } from "./upgrade.ts";
 
 describe("oke safe-default overrides", () => {
-  test("docker --prod is off unless --prod|-p is passed", async () => {
+  test("docker prod overlays are on by default; --no-prod opts out", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-safe-docker-"));
     await Bun.write(
       join(dir, "oke.config.ts"),
       `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
-    // with a dry path: inspect that -p flips prod on.
     const { runDockerDerive } = await import("./docker.ts");
-    const off = await runDockerDerive({
+
+    // Default layout is single: prod readiness/deploy folds into docker-compose.yml
+    // (no separate compose.prod.yml). Assert production-grade content is present.
+    const defaults = await runDockerDerive({
+      cwd: dir,
+      outDir: dir,
+      images: { "store.sql": "postgres:18-alpine" },
+      dryRun: true,
+      write: () => {},
+    });
+    expect(defaults.code).toBe(0);
+    const defaultCompose = defaults.result?.files.find((f) => f.path === "docker-compose.yml");
+    expect(defaultCompose).toBeDefined();
+    expect(defaultCompose!.content).toContain("/_/ready");
+    expect(defaults.result?.files.some((f) => f.path.includes("prod"))).toBe(false);
+
+    const noProd = await runDockerDerive({
       cwd: dir,
       outDir: dir,
       images: { "store.sql": "postgres:18-alpine" },
+      prod: false,
       dryRun: true,
       write: () => {},
     });
-    expect(off.code).toBe(0);
-    expect(off.result?.files.some((f) => f.path.includes("prod"))).toBe(false);
+    expect(noProd.code).toBe(0);
+    const noProdCompose = noProd.result?.files.find((f) => f.path === "docker-compose.yml");
+    expect(noProdCompose).toBeDefined();
+    expect(noProdCompose!.content).not.toContain("/_/ready");
 
-    const on = await runDockerDerive({
+    // Split layout still emits a separate compose.prod.yml when prod is on.
+    const splitProd = await runDockerDerive({
       cwd: dir,
       outDir: dir,
       images: { "store.sql": "postgres:18-alpine" },
       prod: true,
+      layout: "split",
       dryRun: true,
       write: () => {},
     });
-    expect(on.code).toBe(0);
-    expect(on.result?.files.some((f) => f.path.includes("prod"))).toBe(true);
+    expect(splitProd.code).toBe(0);
+    expect(splitProd.result?.files.some((f) => f.path === "compose.prod.yml")).toBe(true);
 
     expect(await dockerCli(["--help"])).toBe(0);
   });

package/src/cli/schema.ts

@@ -1,5 +1,9 @@
 /**
- * `oke schema generate` — core + auth + plugin tables → `schema/oke.ts`.
+ * `oke schema generate` — core + auth + plugin tables → `.oke/schema/oke.ts`.
+ *
+ * Domain Drizzle lives under `src/db/` (`oke db …`). This file is the
+ * generated system/stub catalogue — kept under `.oke/` so it never lands
+ * at the project root next to app source.
  */
 
 import { createHash } from "node:crypto";
@@ -15,10 +19,16 @@ import type { Manifest } from "../manifest/types.ts";
 import { loadManifest } from "./load-config.ts";
 
 /** Fingerprint file written beside generated schema. */
-export const SCHEMA_FINGERPRINT_FILE = "schema/.oke-schema.sha256";
+export const SCHEMA_FINGERPRINT_FILE = ".oke/schema/.oke-schema.sha256";
+
+/** Default generated system schema path (under `.oke/`, not project root). */
+export const SCHEMA_OUT = ".oke/schema/oke.ts";
 
-/** Default generated schema path. */
-export const SCHEMA_OUT = "schema/oke.ts";
+/** Pre-0.10.4 path — still read for doctor / --check soft-compat. */
+export const LEGACY_SCHEMA_OUT = "schema/oke.ts";
+
+/** Pre-0.10.4 fingerprint path. */
+export const LEGACY_SCHEMA_FINGERPRINT_FILE = "schema/.oke-schema.sha256";
 
 /** Options for {@link runSchemaGenerate}. */
 export interface SchemaGenerateOptions {
@@ -36,7 +46,7 @@ export interface SchemaGenerateOptions {
 }
 
 /**
- * Generate `schema/oke.ts` from Manifest store tables + core auth columns.
+ * Generate `.oke/schema/oke.ts` from Manifest store tables + core auth columns.
  *
  * @param options - Manifest / check flag
  */
@@ -60,6 +70,11 @@ export async function runSchemaGenerate(options: SchemaGenerateOptions = {}): Pr
     "oke_crons",
     "oke_signal_config",
     "oke_console_prefs",
+    "oke_vault_secrets",
+    "oke_vault_keys",
+    "oke_vault_audit",
+    "oke_vault_master",
+    "oke_vault_status",
     ...(options.extraTables ?? []),
   ]);
   if (authSchema) {
@@ -85,13 +100,31 @@ export async function runSchemaGenerate(options: SchemaGenerateOptions = {}): Pr
   }
 
   const source = emitSchemaSource([...tables].sort(), authSchema);
-  const out = resolve(cwd, options.out ?? SCHEMA_OUT);
+  const outRel = options.out ?? SCHEMA_OUT;
+  const out = resolve(cwd, outRel);
   const fp = hashSource(source);
+  const fpRel = options.out
+    ? `${dirname(outRel)}/.oke-schema.sha256`.replace(/^\.\//, "")
+    : SCHEMA_FINGERPRINT_FILE;
 
   if (options.check) {
     const existing = Bun.file(out);
     if (!(await existing.exists())) {
-      write("oke schema generate --check: schema/oke.ts missing\n");
+      // Soft-compat: accept a correct legacy root `schema/oke.ts` during migrate.
+      if (!options.out) {
+        const legacy = Bun.file(resolve(cwd, LEGACY_SCHEMA_OUT));
+        if (await legacy.exists()) {
+          if (hashSource(await legacy.text()) === fp) {
+            write(
+              "oke schema generate --check: ok (legacy schema/oke.ts — re-run without --check to move under .oke/schema/)\n",
+            );
+            return 0;
+          }
+          write("oke schema generate --check: schema drift\n");
+          return 1;
+        }
+      }
+      write(`oke schema generate --check: ${outRel} missing\n`);
       return 1;
     }
     const current = await existing.text();
@@ -105,7 +138,7 @@ export async function runSchemaGenerate(options: SchemaGenerateOptions = {}): Pr
 
   await mkdir(dirname(out), { recursive: true });
   await Bun.write(out, source);
-  await Bun.write(resolve(cwd, SCHEMA_FINGERPRINT_FILE), `${fp}\n`);
+  await Bun.write(resolve(cwd, fpRel), `${fp}\n`);
   write(`oke schema generate: wrote ${out} (${tables.size} table(s))\n`);
   return 0;
 }
@@ -128,6 +161,11 @@ export async function schemaFingerprint(cwd: string, manifest?: Manifest): Promi
     "oke_crons",
     "oke_signal_config",
     "oke_console_prefs",
+    "oke_vault_secrets",
+    "oke_vault_keys",
+    "oke_vault_audit",
+    "oke_vault_master",
+    "oke_vault_status",
     ...authSchema.tableNames,
   ]);
   if (m?.stores) {
@@ -141,16 +179,24 @@ export async function schemaFingerprint(cwd: string, manifest?: Manifest): Promi
 /**
  * Read the on-disk schema fingerprint, if any.
  *
+ * Prefers `.oke/schema/`, then legacy root `schema/`.
+ *
  * @param cwd - Project root
  */
 export async function readSchemaFingerprint(cwd: string): Promise<string | null> {
-  const fpFile = Bun.file(resolve(cwd, SCHEMA_FINGERPRINT_FILE));
-  if (await fpFile.exists()) {
-    return (await fpFile.text()).trim();
+  for (const rel of [SCHEMA_FINGERPRINT_FILE, LEGACY_SCHEMA_FINGERPRINT_FILE] as const) {
+    const fpFile = Bun.file(resolve(cwd, rel));
+    if (await fpFile.exists()) {
+      return (await fpFile.text()).trim();
+    }
+  }
+  for (const rel of [SCHEMA_OUT, LEGACY_SCHEMA_OUT] as const) {
+    const schema = Bun.file(resolve(cwd, rel));
+    if (await schema.exists()) {
+      return hashSource(await schema.text());
+    }
   }
-  const schema = Bun.file(resolve(cwd, SCHEMA_OUT));
-  if (!(await schema.exists())) return null;
-  return hashSource(await schema.text());
+  return null;
 }
 
 /**
@@ -173,9 +219,11 @@ export async function schemaCli(args: readonly string[]): Promise<number> {
     else if (a === "--manifest" || a === "-m") manifestPath = rest[++i];
     else if (a === "--out" || a === "-o") out = rest[++i];
     else if (a === "--help" || a === "-h") {
-      console.log(`oke schema generate [--check|-c] [--out|-o schema/oke.ts]
+      console.log(`oke schema generate [--check|-c] [--out|-o .oke/schema/oke.ts]
 
-Emit core auth columns + Manifest store tables. Use --check in CI to fail on drift.
+Emit core auth columns + Manifest store tables into \`.oke/schema/oke.ts\`
+(system stubs — not domain Drizzle under src/db/). Use --check in CI to fail on drift.
+Re-run after adding plugins / auth tables so the stub catalogue stays current.
 `);
       return 0;
     }
@@ -211,6 +259,7 @@ export function emitSchemaSource(
   return `/**
  * Generated by \`oke schema generate\` — do not edit.
  * Core Gate auth tables + Manifest store tables.
+ * Path: \`.oke/schema/oke.ts\` (system stubs; domain schema lives under \`src/db/\`).
  */
 
 ${decls}