okengine 0.18.5 → 0.19.0

package/src/cli/ask-seed.ts

@@ -0,0 +1,82 @@
+/**
+ * One-time interactive prompt: run `oke db seed` after first successful push.
+ */
+
+import { confirm, isCancel } from "@clack/prompts";
+import type { ConfigEnv } from "../config/index.ts";
+import { resolveSeedIdentity, seedPromptMessage } from "../elements/store/seed.ts";
+import { formatCliChrome } from "../term.ts";
+import { loadSeedDef, resolveSeedModulePath, runSeed } from "./db-seed.ts";
+import { isProjectSeeded, markProjectSeeded } from "./project-state.ts";
+
+/** @deprecated Use `.oke/state.json` `seededAt` via {@link isProjectSeeded}. */
+export { LEGACY_SEEDED_MARKER as SEEDED_MARKER } from "./project-state.ts";
+
+/** Options for {@link maybeAskSeed}. */
+export interface AskSeedOptions {
+  readonly cwd: string;
+  readonly env: ConfigEnv;
+  readonly write?: (text: string) => void;
+  readonly stdinIsTTY?: boolean;
+  /** Skip prompt (tests / `--yes` / non-interactive). */
+  readonly skip?: boolean;
+  /** Injectable confirm (tests). */
+  readonly confirmFn?: () => Promise<boolean>;
+  /** Injectable seed runner (tests). */
+  readonly seedFn?: (cwd: string, env: ConfigEnv) => Promise<number>;
+}
+
+/**
+ * After a successful `oke db push`, ask once whether to seed this app
+ * (`defineSeed({ name })` or the project folder). Skips when non-TTY,
+ * already seeded for that identity, or no seed module.
+ *
+ * @param options - Project / env / injectables
+ */
+export async function maybeAskSeed(options: AskSeedOptions): Promise<void> {
+  if (options.skip) return;
+  const tty = options.stdinIsTTY ?? Boolean(process.stdin.isTTY);
+  if (!tty) return;
+
+  const cwd = options.cwd;
+  const seedPath = await resolveSeedModulePath(cwd);
+  if (!(await Bun.file(seedPath).exists())) return;
+
+  const def = await loadSeedDef(cwd).catch(() => undefined);
+  const identity = resolveSeedIdentity(def, cwd);
+  if (await isProjectSeeded(cwd, identity.name)) return;
+
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const chromeWrite = (t: string) => write(formatCliChrome(t));
+  const ok =
+    options.confirmFn !== undefined
+      ? await options.confirmFn()
+      : await (async () => {
+          const value = await confirm({
+            message: seedPromptMessage(identity),
+            initialValue: true,
+          });
+          if (isCancel(value)) return false;
+          return Boolean(value);
+        })();
+
+  if (!ok) {
+    chromeWrite("oke db seed: skipped (run `oke db seed` later)\n");
+    return;
+  }
+
+  const seed =
+    options.seedFn ??
+    ((projectCwd, env) =>
+      runSeed({
+        cwd: projectCwd,
+        env,
+        write: chromeWrite,
+        force: true,
+        stdinIsTTY: false,
+      }));
+  const code = await seed(cwd, options.env);
+  if (code === 0) {
+    await markProjectSeeded(cwd, { seed: identity.name });
+  }
+}

package/src/cli/ask-vault-gaps.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Tests for interactive Vault gap fill during `oke dev`.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { maybeAskVaultGaps } from "./ask-vault-gaps.ts";
+
+describe("maybeAskVaultGaps", () => {
+  test("skips when non-TTY", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "ask-vault-"));
+    try {
+      let reads = 0;
+      const code = await maybeAskVaultGaps({
+        cwd: dir,
+        stdinIsTTY: false,
+        gapsFn: async () => [{ name: "OPENROUTER_API_KEY", description: "OpenRouter API key" }],
+        readSecret: async () => {
+          reads += 1;
+          return "sk-test";
+        },
+      });
+      expect(code).toBe(0);
+      expect(reads).toBe(0);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("writes each gap into .env.local and hydrates process.env", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "ask-vault-"));
+    const prev = process.env.OPENROUTER_API_KEY;
+    try {
+      delete process.env.OPENROUTER_API_KEY;
+      const prompts: string[] = [];
+      const code = await maybeAskVaultGaps({
+        cwd: dir,
+        stdinIsTTY: true,
+        gapsFn: async () => [
+          { name: "OPENROUTER_API_KEY", description: "OpenRouter API key" },
+          { name: "OTHER_SECRET" },
+        ],
+        readSecret: async (prompt) => {
+          prompts.push(prompt);
+          return prompt.includes("OPENROUTER") ? "sk-or-v1-test" : "other-value";
+        },
+      });
+      expect(code).toBe(0);
+      expect(prompts).toHaveLength(2);
+      // `delete process.env.OPENROUTER_API_KEY` narrows that property to
+      // `undefined` for the rest of the block — widen before asserting.
+      expect(process.env.OPENROUTER_API_KEY as string | undefined).toBe("sk-or-v1-test");
+      expect(process.env.OTHER_SECRET as string | undefined).toBe("other-value");
+      const env = readFileSync(join(dir, ".env.local"), "utf8");
+      expect(env).toContain("OPENROUTER_API_KEY=sk-or-v1-test");
+      expect(env).toContain("OTHER_SECRET=other-value");
+    } finally {
+      if (prev === undefined) delete process.env.OPENROUTER_API_KEY;
+      else process.env.OPENROUTER_API_KEY = prev;
+      delete process.env.OTHER_SECRET;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("empty value leaves a gap and returns 1", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "ask-vault-"));
+    try {
+      const logs: string[] = [];
+      const code = await maybeAskVaultGaps({
+        cwd: dir,
+        stdinIsTTY: true,
+        write: (t) => logs.push(t),
+        gapsFn: async () => [{ name: "OPENROUTER_API_KEY" }],
+        readSecret: async () => "",
+      });
+      expect(code).toBe(1);
+      expect(logs.some((l) => l.includes("missing secret"))).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/cli/ask-vault-gaps.ts

@@ -0,0 +1,146 @@
+/**
+ * Interactive fill for Vault boot gaps during `oke dev`.
+ *
+ * Probes the same gap set app boot would throw (`allowDevFallbacks` on for
+ * `dev`), then prompts one-by-one and persists into `.env.local`.
+ */
+
+import { resolve } from "node:path";
+import { resolveDriverId } from "../config/index.ts";
+import { VAULT_DEFAULTS } from "../config/driver-defaults.ts";
+import { resolveAppEntryForPluginTables } from "../elements/store/load-plugin-tables.ts";
+import { buildVaultBootChain, normalizeVaultDriverId } from "../elements/vault/boot-chain.ts";
+import { createVaultRuntime, VaultBootError, type VaultGap } from "../elements/vault/runtime.ts";
+import { requiredEnvRegistry, secretRegistry } from "../kernel/element-registries.ts";
+import { formatCliChrome } from "../term.ts";
+import { loadOkeConfig } from "./load-config.ts";
+import { openEnvStore } from "./vault-cmd.ts";
+import { promptHidden } from "./vault-secure-input.ts";
+
+/** Options for {@link maybeAskVaultGaps}. */
+export interface AskVaultGapsOptions {
+  readonly cwd: string;
+  /** App entry override (relative or absolute). */
+  readonly entry?: string;
+  readonly write?: (text: string) => void;
+  readonly stdinIsTTY?: boolean;
+  /** Skip prompt (tests / non-interactive). */
+  readonly skip?: boolean;
+  /**
+   * Injectable gap probe (tests). Default: import entry + vault boot.
+   */
+  readonly gapsFn?: () => Promise<readonly VaultGap[]>;
+  /**
+   * Injectable secret reader (tests). Default: {@link promptHidden}.
+   */
+  readonly readSecret?: (prompt: string) => Promise<string>;
+  /**
+   * Env file relative to cwd (default `.env.local`).
+   */
+  readonly envFile?: string;
+}
+
+/**
+ * Probe Vault contracts declared by the app entry and return boot gaps.
+ *
+ * @param cwd - Project root
+ * @param entry - Optional entry override
+ */
+export async function probeVaultGaps(cwd: string, entry?: string): Promise<readonly VaultGap[]> {
+  const prevSecrets = secretRegistry.slice();
+  const prevRequired = requiredEnvRegistry.slice();
+  secretRegistry.length = 0;
+  requiredEnvRegistry.length = 0;
+  try {
+    const entryAbs = await resolveAppEntryForPluginTables(cwd, entry);
+    if (!entryAbs) return [];
+    await import(entryAbs);
+    const secrets = secretRegistry.slice();
+    const requiredEnv = requiredEnvRegistry.slice();
+    if (secrets.length === 0 && requiredEnv.length === 0) return [];
+
+    const loaded = await loadOkeConfig(cwd).catch(() => null);
+    const configEnv = "dev" as const;
+    const driverId = normalizeVaultDriverId(
+      resolveDriverId(loaded?.config?.drivers?.vault, configEnv, VAULT_DEFAULTS) ?? "env",
+    );
+    const chain = buildVaultBootChain({
+      driverId,
+      env: configEnv,
+      cwd,
+      seed: {},
+    });
+    const vault = createVaultRuntime({
+      secrets,
+      requiredEnv,
+      chain,
+      allowDevFallbacks: true,
+    });
+    try {
+      await vault.boot();
+      return [];
+    } catch (err) {
+      if (err instanceof VaultBootError) return err.gaps;
+      throw err;
+    }
+  } finally {
+    secretRegistry.length = 0;
+    secretRegistry.push(...prevSecrets);
+    requiredEnvRegistry.length = 0;
+    requiredEnvRegistry.push(...prevRequired);
+  }
+}
+
+/**
+ * After compose hydrate (and usually schema push), fill Vault boot gaps
+ * one-by-one into `.env.local`. Skips when non-TTY or no gaps.
+ *
+ * @param options - Project / injectables
+ * @returns `0` when ready to continue, `1` when aborted (still missing)
+ */
+export async function maybeAskVaultGaps(options: AskVaultGapsOptions): Promise<number> {
+  if (options.skip) return 0;
+  const tty = options.stdinIsTTY ?? Boolean(process.stdin.isTTY);
+  if (!tty) return 0;
+
+  const cwd = options.cwd;
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const chromeWrite = (t: string) => write(formatCliChrome(t));
+
+  const gaps = options.gapsFn ? await options.gapsFn() : await probeVaultGaps(cwd, options.entry);
+  if (gaps.length === 0) return 0;
+
+  chromeWrite(
+    gaps.length === 1
+      ? "oke vault: 1 missing secret — enter a value (stored in .env.local)\n"
+      : `oke vault: ${gaps.length} missing secrets — enter each value (stored in .env.local)\n`,
+  );
+
+  const envPath = resolve(cwd, options.envFile ?? ".env.local");
+  const store = await openEnvStore(envPath);
+  const read =
+    options.readSecret ?? ((prompt: string) => promptHidden(prompt, { write: chromeWrite }));
+
+  const remaining: VaultGap[] = [];
+  for (const gap of gaps) {
+    const label = gap.description ? `${gap.name} (${gap.description})` : gap.name;
+    const value = (await read(`Enter value for ${label}: `)).trim();
+    if (value.length === 0) {
+      remaining.push(gap);
+      chromeWrite(`oke vault: skipped ${gap.name} (empty)\n`);
+      continue;
+    }
+    store.set(gap.name, value);
+    process.env[gap.name] = value;
+    chromeWrite(`oke vault: set ${gap.name}\n`);
+  }
+  await store.save?.();
+
+  if (remaining.length > 0) {
+    const err = new VaultBootError(remaining);
+    chromeWrite(`${err.message}\n`);
+    chromeWrite("oke vault: set the missing names, then re-run `oke dev`\n");
+    return 1;
+  }
+  return 0;
+}

package/src/cli/build.ts

@@ -44,7 +44,7 @@ async function defaultSyncAdoptBarrel(rootDir: string): Promise<readonly string[
 }
 
 /**
- * Build a deployable bundle. Edge target aims at the &lt;16 kB kernel budget.
+ * Build a deployable bundle. Edge target aims at the &lt;17 kB kernel budget.
  *
  * @param options - Target / entry
  */
@@ -109,7 +109,7 @@ export async function buildCli(args: readonly string[]): Promise<number> {
     else if (a === "--help" || a === "-h") {
       console.log(`oke build [--target|-t bun|node|edge] [--entry|-e src/app.ts]
 
-Tree-shaken bundle. --target edge aims at the <16 kB kernel budget.
+Tree-shaken bundle. --target edge aims at the <17 kB kernel budget.
 `);
       return 0;
     }

package/src/cli/client-add.test.ts

@@ -35,12 +35,37 @@ describe("oke client add", () => {
     expect(src).toContain("export {}");
   });
 
-  test("writes a compiling .d.ts", async () => {
+  test("emitAmbient includes live/stream stamps", () => {
+    const src = emitAmbient({
+      routes: {
+        orders: {
+          events: {
+            in: "{ orderId: string }",
+            out: "{ status: string }",
+            errors: {},
+            method: "GET",
+            path: "/orders/:orderId/events",
+            live: "order-status",
+            stream: true,
+            matchKey: ["orderId"],
+          },
+        },
+      },
+    });
+    expect(src).toContain('live: "order-status"');
+    expect(src).toContain("stream: true");
+    expect(src).toContain('matchKey: ["orderId"]');
+  });
+
+  test("writes ambient + routes modules and a compiling .d.ts", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-client-add-"));
     const out = join(dir, "oke-client.d.ts");
 
     const result = await clientAdd({ descriptor: fixture, out });
     expect(result.out).toBe(out);
+    expect(result.routesOut).toContain("oke-client.routes.ts");
+    expect(result.routesSource).toContain("export const routes");
+    expect(result.routesSource).toContain('"/bookings"');
     expect(result.source).toContain("FlightFull");
 
     // Ambient-only project — proves the .d.ts itself is valid TypeScript.

package/src/cli/client-add.ts

@@ -1,8 +1,9 @@
 /**
  * `oke client add <url>` — ambient client types for a separate frontend repo.
  *
- * Fetches `GET {url}/_oke/client.json` and writes a compiling `.d.ts` that
- * augments `okengine/client`'s {@link Register} interface.
+ * Fetches `GET {url}/_oke/client.json` and writes:
+ * - `oke-client.d.ts` — Register augmentation
+ * - `oke-client.routes.ts` — value `$routes` for REST / live / stream wire
  */
 
 import type { ClientDescriptor, ClientFetch } from "../client/types.ts";
@@ -11,24 +12,30 @@ import type { ClientDescriptor, ClientFetch } from "../client/types.ts";
 export interface ClientAddOptions {
   /** App base URL (required unless `descriptor` is provided). */
   readonly url?: string;
-  /** Output path (default: `oke-client.d.ts`). */
+  /** Output path for ambient types (default: `oke-client.d.ts`). */
   readonly out?: string;
   /** Override fetch (tests). */
   readonly fetch?: ClientFetch;
   /** Inject a descriptor instead of fetching (tests). */
   readonly descriptor?: ClientDescriptor;
+  /** Skip writing `oke-client.routes.ts` (tests). */
+  readonly skipRoutes?: boolean;
 }
 
 /** Result of a successful {@link clientAdd}. */
 export interface ClientAddResult {
-  /** Absolute or relative path written. */
+  /** Absolute or relative path written for ambient types. */
   readonly out: string;
   /** Emitted TypeScript declaration source. */
   readonly source: string;
+  /** Routes module path when written. */
+  readonly routesOut?: string;
+  /** Routes module source when written. */
+  readonly routesSource?: string;
 }
 
 /**
- * Fetch (or accept) a client descriptor and write an ambient declaration.
+ * Fetch (or accept) a client descriptor and write ambient + routes modules.
  *
  * @param options - URL / out / test overrides
  */
@@ -37,7 +44,14 @@ export async function clientAdd(options: ClientAddOptions): Promise<ClientAddRes
   const descriptor = options.descriptor ?? (await fetchDescriptor(options.url, options.fetch));
   const source = emitAmbient(descriptor);
   await Bun.write(out, source);
-  return { out, source };
+  let routesOut: string | undefined;
+  let routesSource: string | undefined;
+  if (!options.skipRoutes) {
+    routesOut = routesPathFor(out);
+    routesSource = emitRoutes(descriptor);
+    await Bun.write(routesOut, routesSource);
+  }
+  return { out, source, routesOut, routesSource };
 }
 
 /**
@@ -65,6 +79,7 @@ export async function clientAddCli(args: readonly string[]): Promise<number> {
   try {
     const result = await clientAdd({ url, out });
     console.log(`Wrote ${result.out}`);
+    if (result.routesOut) console.log(`Wrote ${result.routesOut}`);
     return 0;
   } catch (err) {
     console.error(err instanceof Error ? err.message : String(err));
@@ -85,27 +100,7 @@ export function emitAmbient(descriptor: ClientDescriptor): string {
       : units
           .map(([unit, flows]) => {
             const flowLines = Object.entries(flows)
-              .map(([flow, c]) => {
-                const errors = c.errors
-                  ? Object.entries(c.errors)
-                      .map(([code, ty]) => `            ${JSON.stringify(code)}: ${ty}`)
-                      .join(";\n")
-                  : "";
-                const errorBlock = errors
-                  ? `          errors: {\n${errors};\n          };`
-                  : "          errors: {};";
-                return [
-                  `        ${JSON.stringify(flow)}: {`,
-                  `          in: ${c.in ?? "unknown"};`,
-                  `          out: ${c.out ?? "unknown"};`,
-                  errorBlock,
-                  c.method ? `          method: ${JSON.stringify(c.method)};` : undefined,
-                  c.path ? `          path: ${JSON.stringify(c.path)};` : undefined,
-                  `        }`,
-                ]
-                  .filter((line): line is string => line !== undefined)
-                  .join("\n");
-              })
+              .map(([flow, c]) => emitFlowContract(flow, c, "ambient"))
               .join(";\n");
             return `      ${JSON.stringify(unit)}: {\n${flowLines};\n      }`;
           })
@@ -115,6 +110,7 @@ export function emitAmbient(descriptor: ClientDescriptor): string {
 /**
  * Generated by \`oke client add\` — do not edit by hand.
  * Ambient types for \`createClient(url)\` without importing App.
+ * Pair with \`oke-client.routes.ts\`: createClient(url, { $routes: routes }).
  */
 declare module "okengine/client" {
   interface Register {
@@ -130,6 +126,89 @@ export {};
 `;
 }
 
+/**
+ * Emit a value `$routes` module for wire REST / live / stream.
+ *
+ * @param descriptor - Client descriptor
+ */
+export function emitRoutes(descriptor: ClientDescriptor): string {
+  const units = Object.entries(descriptor.routes);
+  const body =
+    units.length === 0
+      ? "  // no HTTP flows"
+      : units
+          .map(([unit, flows]) => {
+            const flowLines = Object.entries(flows)
+              .map(([flow, c]) => emitFlowContract(flow, c, "value"))
+              .join(",\n");
+            return `  ${JSON.stringify(unit)}: {\n${flowLines},\n  }`;
+          })
+          .join(",\n");
+
+  return `/* eslint-disable */
+/**
+ * Generated by \`oke client add\` — do not edit by hand.
+ * Runtime route stamps for createClient(url, { $routes: routes }).
+ */
+export const routes = {
+${body},
+} as const;
+
+export default routes;
+`;
+}
+
+function emitFlowContract(
+  flow: string,
+  c: ClientDescriptor["routes"][string][string],
+  mode: "ambient" | "value",
+): string {
+  if (mode === "value") {
+    const fields = [
+      c.method !== undefined ? `    method: ${JSON.stringify(c.method)}` : undefined,
+      c.path !== undefined ? `    path: ${JSON.stringify(c.path)}` : undefined,
+      c.live !== undefined ? `    live: ${JSON.stringify(c.live)}` : undefined,
+      c.stream === true ? `    stream: true as const` : undefined,
+      c.matchKey !== undefined ? `    matchKey: ${JSON.stringify(c.matchKey)} as const` : undefined,
+      c.gates !== undefined && c.gates.length > 0
+        ? `    gates: ${JSON.stringify(c.gates)} as const`
+        : undefined,
+    ].filter((line): line is string => line !== undefined);
+    if (fields.length === 0) return `    ${JSON.stringify(flow)}: {}`;
+    return `    ${JSON.stringify(flow)}: {\n${fields.join(",\n")},\n  }`;
+  }
+
+  const errors = c.errors
+    ? Object.entries(c.errors)
+        .map(([code, ty]) => `            ${JSON.stringify(code)}: ${ty}`)
+        .join(";\n")
+    : "";
+  const errorBlock = errors
+    ? `          errors: {\n${errors};\n          };`
+    : "          errors: {};";
+  return [
+    `        ${JSON.stringify(flow)}: {`,
+    `          in: ${c.in ?? "unknown"};`,
+    `          out: ${c.out ?? "unknown"};`,
+    errorBlock,
+    c.method ? `          method: ${JSON.stringify(c.method)};` : undefined,
+    c.path ? `          path: ${JSON.stringify(c.path)};` : undefined,
+    c.live ? `          live: ${JSON.stringify(c.live)};` : undefined,
+    c.stream === true ? `          stream: true;` : undefined,
+    c.matchKey ? `          matchKey: ${JSON.stringify(c.matchKey)};` : undefined,
+    c.gates && c.gates.length > 0 ? `          gates: ${JSON.stringify(c.gates)};` : undefined,
+    `        }`,
+  ]
+    .filter((line): line is string => line !== undefined)
+    .join("\n");
+}
+
+function routesPathFor(dtsOut: string): string {
+  if (dtsOut.endsWith(".d.ts")) return `${dtsOut.slice(0, -5)}.routes.ts`;
+  if (dtsOut.endsWith(".ts")) return dtsOut.replace(/\.ts$/, ".routes.ts");
+  return `${dtsOut}.routes.ts`;
+}
+
 async function fetchDescriptor(
   url: string | undefined,
   fetchFn: ClientFetch = globalThis.fetch.bind(globalThis),

package/src/cli/db-seed.ts

@@ -329,6 +329,8 @@ export async function runSeed(options: SeedOptions = {}): Promise<number> {
       : await bootSeedFx(cwd, env, options.entry, loaded?.config);
     stop = session.stop;
     await executeSeedDef(def, env, session.fx, write);
+    const { markProjectSeeded } = await import("./project-state.ts");
+    await markProjectSeeded(cwd, { seed: identity.name });
     write("oke db seed: ok\n");
     return finish(EXIT_OK, "oke db seed: ok");
   } catch (err) {