okengine 0.11.2 → 0.12.0

package/src/cli/project-state.test.ts

@@ -19,10 +19,12 @@ describe("project-state", () => {
     const dir = mkdtempSync(join(tmpdir(), "oke-state-"));
     try {
       expect(await isProjectSeeded(dir)).toBe(false);
-      await markProjectSeeded(dir, "2026-01-02T03:04:05.000Z");
-      expect(await isProjectSeeded(dir)).toBe(true);
+      await markProjectSeeded(dir, { seed: "keel", at: "2026-01-02T03:04:05.000Z" });
+      expect(await isProjectSeeded(dir, "keel")).toBe(true);
+      expect(await isProjectSeeded(dir, "notes")).toBe(false);
       const state = await readProjectState(dir);
       expect(state.seededAt).toBe("2026-01-02T03:04:05.000Z");
+      expect(state.seed).toBe("keel");
       expect(existsSync(join(dir, PROJECT_STATE_REL))).toBe(true);
       expect(existsSync(join(dir, LEGACY_SEEDED_MARKER))).toBe(false);
     } finally {
@@ -43,6 +45,8 @@ describe("project-state", () => {
         seededAt?: string;
       };
       expect(raw.seededAt).toBe("2025-12-01T00:00:00.000Z");
+      expect(await isProjectSeeded(dir)).toBe(true);
+      expect(await isProjectSeeded(dir, "keel")).toBe(false);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }

package/src/cli/project-state.ts

@@ -20,6 +20,11 @@ export const LEGACY_SEEDED_MARKER = ".oke/seeded";
 export type ProjectState = {
   /** ISO timestamp when prompted `oke db seed` last succeeded. */
   readonly seededAt?: string;
+  /**
+   * Seed identity (`defineSeed({ name })` or project folder).
+   * A different name re-prompts — not a global "already seeded" flag.
+   */
+  readonly seed?: string;
 };
 
 /**
@@ -40,10 +45,13 @@ export function parseProjectState(raw: unknown): ProjectState {
   if (raw === null || typeof raw !== "object") return {};
   const o = raw as Record<string, unknown>;
   const seededAt = o["seededAt"];
-  if (typeof seededAt === "string" && seededAt.trim().length > 0) {
-    return { seededAt: seededAt.trim() };
-  }
-  return {};
+  const seed = o["seed"];
+  return {
+    ...(typeof seededAt === "string" && seededAt.trim().length > 0
+      ? { seededAt: seededAt.trim() }
+      : {}),
+    ...(typeof seed === "string" && seed.trim().length > 0 ? { seed: seed.trim() } : {}),
+  };
 }
 
 /**
@@ -95,29 +103,37 @@ export async function writeProjectState(cwd: string, state: ProjectState): Promi
   await mkdir(dirname(path), { recursive: true });
   const body: Record<string, string> = {};
   if (state.seededAt) body.seededAt = state.seededAt;
+  if (state.seed) body.seed = state.seed;
   await Bun.write(path, `${JSON.stringify(body, null, 2)}\n`);
 }
 
 /**
- * Whether prompted seed already completed for this project.
+ * Whether prompted seed already completed for this seed identity.
  *
  * @param cwd - Project root
+ * @param seed - Current {@link SeedDef.name} / folder id; a mismatch re-asks
  */
-export async function isProjectSeeded(cwd: string): Promise<boolean> {
+export async function isProjectSeeded(cwd: string, seed?: string): Promise<boolean> {
   const state = await readProjectState(cwd);
-  return typeof state.seededAt === "string" && state.seededAt.length > 0;
+  if (typeof state.seededAt !== "string" || state.seededAt.length === 0) return false;
+  if (seed === undefined) return true;
+  return state.seed === seed;
 }
 
 /**
- * Record a successful prompted seed (ISO timestamp).
+ * Record a successful prompted seed (ISO timestamp + identity).
  *
  * @param cwd - Project root
- * @param at - Optional timestamp (defaults to now)
+ * @param options - Seed id and optional timestamp
  */
 export async function markProjectSeeded(
   cwd: string,
-  at: string = new Date().toISOString(),
+  options: { readonly seed?: string; readonly at?: string } = {},
 ): Promise<void> {
   const prev = await readProjectState(cwd);
-  await writeProjectState(cwd, { ...prev, seededAt: at });
+  await writeProjectState(cwd, {
+    ...prev,
+    seededAt: options.at ?? new Date().toISOString(),
+    ...(options.seed !== undefined ? { seed: options.seed } : {}),
+  });
 }

package/src/cli/registry.ts

@@ -655,6 +655,17 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
       HELP,
     ],
   },
+  {
+    name: "console",
+    summary: "Console helpers — claim-code",
+    subcommands: [
+      {
+        name: "claim-code",
+        summary: "Print the local setup claim code from .oke/claim-code",
+        flags: [JSON_FLAG, HELP],
+      },
+    ],
+  },
   {
     name: "gates",
     summary: "gate catalogue from Manifest",

package/src/cli/replay.ts

@@ -6,7 +6,12 @@ import { resolve } from "node:path";
 import { withDryRun } from "../kernel/dry-run.ts";
 import type { AnyFlowDef } from "../kernel/flow.ts";
 import type { InternalTrigger } from "../kernel/triggers.ts";
-import { createRunsRuntime, type RunsRuntime, type WideEvent } from "../runs/index.ts";
+import {
+  createRunsRuntime,
+  DEFAULT_RUNS_LOCAL_ROOT,
+  type RunsRuntime,
+  type WideEvent,
+} from "../runs/index.ts";
 import { resolveStartEntry } from "./start.ts";
 import { flagValue, hasFlag } from "./args.ts";
 import { EXIT_OK, EXIT_USAGE } from "./exit.ts";
@@ -134,7 +139,7 @@ export async function runReplay(options: ReplayOptions): Promise<number> {
       options.runs ??
       createRunsRuntime({
         driver: "files",
-        localRoot: resolve(cwd, ".oke/runs"),
+        localRoot: resolve(cwd, DEFAULT_RUNS_LOCAL_ROOT),
       });
     if (!runs.store) await runs.open();
 

package/src/cli/vault-cmd.test.ts

@@ -74,6 +74,8 @@ async function harness(options: HarnessOptions = {}): Promise<Harness> {
         sql,
         // Never inherit a real OKE_VAULT_MASTER_KEY from the developer's shell.
         env: {},
+        // `bun test` from a TTY must not block on the hidden master-key prompt.
+        stdinIsTTY: false,
         ...(cwd === undefined ? {} : { cwd }),
         write: (text) => {
           captured += text;

package/src/cli/vault-cmd.ts

@@ -59,6 +59,11 @@ export interface VaultCmdOptions {
    * `process.env`.
    */
   readonly env?: Readonly<Record<string, string | undefined>>;
+  /**
+   * Override stdin TTY detection (tests). Default: `process.stdin.isTTY`.
+   * Non-interactive runs must not block on a hidden master-key prompt.
+   */
+  readonly stdinIsTTY?: boolean;
   /**
    * Pre-opened SQL connection for the builtin loop. Injected by tests so a
    * sequence of subcommands shares one in-memory database; the CLI never
@@ -368,7 +373,7 @@ async function resolveMasterKey(
     return prompted.length > 0 ? prompted : null;
   }
   // Never block a non-interactive pipe waiting for a hidden prompt.
-  if (!process.stdin.isTTY) return null;
+  if (!(options.stdinIsTTY ?? Boolean(process.stdin.isTTY))) return null;
   const prompted = (
     await promptHidden("Enter current master key: ", { write: options.write })
   ).trim();
@@ -405,7 +410,7 @@ async function resolveNewMasterKey(
     const prompted = (await options.readSecret("Enter new master key: ")).trim();
     return prompted.length > 0 ? prompted : undefined;
   }
-  if (!process.stdin.isTTY) return undefined;
+  if (!(options.stdinIsTTY ?? Boolean(process.stdin.isTTY))) return undefined;
   const prompted = (await promptHidden("Enter new master key: ", { write: options.write })).trim();
   return prompted.length > 0 ? prompted : undefined;
 }

package/src/client/create.test.ts

@@ -5,7 +5,7 @@
 import { describe, expect, test } from "bun:test";
 import { createClient } from "./create.ts";
 import { isErrorCode, isOk, isTransportError } from "./errors.ts";
-import type { AppOf, ClientError, ClientResult } from "./types.ts";
+import type { AppOf, ClientEnvelope, ClientError } from "./types.ts";
 
 /** Fixture App matching Notes / bookings (`FlightFull`). */
 type BookingsApp = AppOf<{
@@ -118,6 +118,42 @@ describe("createClient — same-repo <App>", () => {
     expect(method).toBe("GET");
     expect(url).toBe("http://app.test/notes/n_1");
   });
+
+  test("REST QUERY always sends a JSON body and Content-Type", async () => {
+    type SearchApp = AppOf<{
+      search: {
+        run: {
+          in: { id: string; q?: string };
+          out: { n: number };
+          errors: Record<string, never>;
+        };
+      };
+    }>;
+    let method = "";
+    let url = "";
+    let body: string | undefined;
+    let contentType: string | null = null;
+    const api = createClient<SearchApp>("http://app.test", {
+      routes: {
+        "search.run": { method: "QUERY", path: "/search/:id" },
+      },
+      fetch: async (input, init) => {
+        url = String(input);
+        method = String(init?.method ?? "");
+        body = typeof init?.body === "string" ? init.body : undefined;
+        contentType = new Headers(init?.headers).get("content-type");
+        return Response.json({ data: { n: 1 }, error: null });
+      },
+    });
+    await api.search.run({ id: "x" });
+    expect(method).toBe("QUERY");
+    expect(url).toBe("http://app.test/search/x");
+    expect(body).toBe("{}");
+    expect(contentType ?? "").toContain("application/json");
+
+    await api.search.run({ id: "x", q: "ali" });
+    expect(body).toBe('{"q":"ali"}');
+  });
 });
 
 describe("createClient — type helpers", () => {
@@ -130,7 +166,7 @@ describe("createClient — type helpers", () => {
     const ok: _Codes = true;
     expect(ok).toBe(true);
 
-    const sample: ClientResult<{ id: string }, { FlightFull: { seatsLeft: number } }> = {
+    const sample: ClientEnvelope<{ id: string }, { FlightFull: { seatsLeft: number } }> = {
       data: null,
       error: { code: "FlightFull", data: { seatsLeft: 0 } },
     };

package/src/client/create.ts

@@ -13,6 +13,7 @@
  */
 
 import { createTransport, type Transport } from "./transport.ts";
+import { asThenableIterable, attachPager } from "./pager.ts";
 import type { Client, ClientOptions, ClientRouteMap, ResolveApp } from "./types.ts";
 
 /** App-shaped value that carries a runtime `$routes` table from typed adopt. */
@@ -115,30 +116,34 @@ export function flattenRoutes(
  * @param path - Accumulated property path
  */
 function proxy(transport: Transport, path: readonly string[]): unknown {
-  const call = (input?: unknown) => {
+  const invoke = async (input?: unknown) => {
     if (path.length < 2) {
-      return Promise.resolve({
-        data: null,
-        error: {
-          code: "TransportError" as const,
-          data: {
-            message: `Incomplete path: api.${path.join(".") || "?"}(…)`,
+      return attachPager(
+        {
+          data: null,
+          error: {
+            code: "TransportError" as const,
+            data: {
+              message: `Incomplete path: api.${path.join(".") || "?"}(…)`,
+            },
           },
         },
-      });
+        invoke,
+        input,
+      );
     }
-    // `api.bookings.create` → unit `bookings`, flow `create`
     const unit = path[0]!;
     const flow = path.slice(1).join(".");
-    return transport.call(`${unit}/${flow}`, input);
+    const result = await transport.call(`${unit}/${flow}`, input);
+    return attachPager(result, invoke, input);
   };
+  const call = (input?: unknown) => asThenableIterable(invoke, input);
 
   return new Proxy(call, {
     get(_target, prop, receiver) {
       if (typeof prop === "symbol") {
         return Reflect.get(_target, prop, receiver);
       }
-      // Prevent `await api.notes` from treating the proxy as a Thenable.
       if (prop === "then") return undefined;
       return proxy(transport, [...path, prop]);
     },

package/src/client/index.ts

@@ -8,6 +8,8 @@
 export { createClient, flattenRoutes } from "./create.ts";
 export type { AppWithRoutes } from "./create.ts";
 export { isErrorCode, isFail, isOk, isTransportError } from "./errors.ts";
+export { isPagerMeta, pagerLink } from "./pager.ts";
+export type { ClientPager, PagerLink } from "./pager.ts";
 export { createTransport } from "./transport.ts";
 export type { Transport } from "./transport.ts";
 export type {
@@ -21,7 +23,11 @@ export type {
   ClientFromRoutes,
   ClientHeaders,
   ClientOptions,
+  ClientEnvelope,
+  ClientListMeta,
+  ClientPagerLink,
   ClientResult,
+  ClientThenableIterable,
   ClientRouteMap,
   FlowContract,
   Register,

package/src/client/pager.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+import { createClient } from "./create.ts";
+import type { AppOf, ClientListMeta } from "./types.ts";
+
+type NotesApp = AppOf<{
+  notes: {
+    list: {
+      in: { limit?: number; cursor?: string };
+      out: Array<{ id: string }>;
+      errors: Record<string, never>;
+    };
+  };
+}>;
+
+describe("client list pager", () => {
+  test("page.next() and for-await walk without checking mode", async () => {
+    const pages = [
+      {
+        data: [{ id: "n_1" }],
+        error: null,
+        meta: { next: { cursor: "p2" }, prev: null, limit: 1 },
+      },
+      {
+        data: [{ id: "n_2" }],
+        error: null,
+        meta: { next: null, prev: { cursor: "p1" }, limit: 1 },
+      },
+    ];
+    const seen: unknown[] = [];
+    const api = createClient<NotesApp>("http://app.test", {
+      fetch: async (_url, init) => {
+        const raw = init && "body" in init && typeof init.body === "string" ? init.body : "{}";
+        seen.push(raw);
+        const input = JSON.parse(raw) as { cursor?: string };
+        const body = input.cursor === "p2" ? pages[1]! : pages[0]!;
+        return Response.json(body);
+      },
+    });
+
+    const first = await api.notes.list({ limit: 1 });
+    expect(first.error).toBeNull();
+    expect(first.data).toEqual([{ id: "n_1" }]);
+    const meta: ClientListMeta | undefined = first.error === null ? first.meta : undefined;
+    expect(meta?.next).toEqual({ cursor: "p2" });
+    expect(meta?.prev).toBeNull();
+    const second = await first.next();
+    expect(second.data).toEqual([{ id: "n_2" }]);
+    const empty = await second.next();
+    expect(empty.data).toEqual([]);
+    expect(empty.error).toBeNull();
+    const back = await second.prev();
+    expect(back.data).toEqual([{ id: "n_1" }]);
+
+    const collected: string[] = [];
+    for await (const page of api.notes.list({ limit: 1 })) {
+      for (const row of page.data ?? []) collected.push(row.id);
+    }
+    expect(collected).toEqual(["n_1", "n_2"]);
+
+    const fromPage: string[] = [];
+    for await (const page of await api.notes.list({ limit: 1 })) {
+      for (const row of page.data ?? []) fromPage.push(row.id);
+    }
+    expect(fromPage).toEqual(["n_1", "n_2"]);
+  });
+});

package/src/client/pager.ts

@@ -0,0 +1,138 @@
+/**
+ * List pager — `page.next()` / `page.prev()` and `for await` of the call.
+ *
+ * `meta.next` / `meta.prev` are the next request (`{ cursor }`), not flags.
+ * Methods always exist; a missing link returns an empty page (no request).
+ * `for await` stops when `meta.next` is null — it does not yield the empty
+ * terminal page. `page.next()` at the end still returns `[]`.
+ */
+
+import type { ClientEnvelope, ClientResult } from "./types.ts";
+
+/** Next / previous list request — spread into the same list call. */
+export type PagerLink = {
+  readonly cursor: string;
+};
+
+/** Walk helpers attached to every {@link ClientResult}. */
+export type ClientPager<
+  O = unknown,
+  E extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  /** Next page, or an empty success when `meta.next` is null. */
+  readonly next: () => Promise<ClientResult<O, E>>;
+  /** Previous page, or an empty success when `meta.prev` is null. */
+  readonly prev: () => Promise<ClientResult<O, E>>;
+};
+
+type Invoke = (input?: unknown) => Promise<ClientResult>;
+
+/**
+ * True when `meta` carries list pager links.
+ *
+ * @param meta - Result meta
+ */
+export function isPagerMeta(
+  meta: unknown,
+): meta is { readonly next: PagerLink | null; readonly prev: PagerLink | null } {
+  return meta !== null && typeof meta === "object" && "next" in meta && "prev" in meta;
+}
+
+/**
+ * Read a pager link from meta.
+ *
+ * @param meta - Result meta
+ * @param side - Direction
+ */
+export function pagerLink(meta: unknown, side: "next" | "prev"): PagerLink | null {
+  if (!isPagerMeta(meta)) return null;
+  const link = meta[side];
+  if (link === null || typeof link !== "object") return null;
+  return typeof link.cursor === "string" && link.cursor.length > 0 ? { cursor: link.cursor } : null;
+}
+
+/**
+ * Attach always-callable `next` / `prev` and an async iterator from this page.
+ *
+ * @param result - Transport result
+ * @param invoke - Same flow call
+ * @param input - Last list input (filters, limit, …)
+ */
+export function attachPager(result: ClientEnvelope, invoke: Invoke, input: unknown): ClientResult {
+  const walk = (side: "next" | "prev"): (() => Promise<ClientResult>) => {
+    return async () => {
+      if (result.error !== null) return attachPager(result, invoke, input);
+      const link = pagerLink(result.meta, side);
+      if (link === null) return attachPager(terminalPage(result, side), invoke, input);
+      return invoke(mergeInput(input, link));
+    };
+  };
+  const page = { ...result, next: walk("next"), prev: walk("prev") } as ClientResult;
+  return Object.assign(page, {
+    [Symbol.asyncIterator]: () => iterateFrom(page),
+  });
+}
+
+/**
+ * Yield this page, then `next()`, until `meta.next` is null.
+ *
+ * @param page - Starting page
+ */
+export async function* iterateFrom(page: ClientResult): AsyncGenerator<ClientResult, void, void> {
+  yield page;
+  while (page.error === null && pagerLink(page.meta, "next") !== null) {
+    page = await page.next();
+    yield page;
+  }
+}
+
+/**
+ * Yield each page until `meta.next` is null.
+ *
+ * @param invoke - List call
+ * @param input - First-page input
+ */
+export async function* iteratePages(
+  invoke: Invoke,
+  input?: unknown,
+): AsyncGenerator<ClientResult, void, void> {
+  const page = await invoke(input);
+  yield* iterateFrom(page);
+}
+
+/**
+ * Thenable (one page) + async-iterable (walk) for `list()`.
+ *
+ * @param invoke - List call
+ * @param input - First-page input
+ */
+export function asThenableIterable(
+  invoke: Invoke,
+  input?: unknown,
+): Promise<ClientResult> & AsyncIterable<ClientResult> {
+  const promise = invoke(input);
+  return Object.assign(promise, {
+    [Symbol.asyncIterator]: () => iteratePages(invoke, input),
+  });
+}
+
+function mergeInput(input: unknown, link: PagerLink): unknown {
+  const base = input !== null && typeof input === "object" ? input : {};
+  return { ...base, ...link };
+}
+
+function terminalPage(
+  result: Extract<ClientEnvelope, { readonly error: null }>,
+  side: "next" | "prev",
+): ClientEnvelope {
+  const data = Array.isArray(result.data) ? [] : result.data;
+  const meta =
+    result.meta !== undefined && typeof result.meta === "object"
+      ? {
+          ...result.meta,
+          next: side === "next" ? null : result.meta.next,
+          prev: side === "prev" ? null : result.meta.prev,
+        }
+      : result.meta;
+  return { data, error: null, meta };
+}

package/src/client/transport.ts

@@ -5,7 +5,7 @@
  * Optional `routes` map switches to REST (`method` + path template).
  */
 
-import type { ClientFetch, ClientOptions, ClientResult } from "./types.ts";
+import type { ClientEnvelope, ClientFetch, ClientOptions } from "./types.ts";
 
 /** Internal transport handle. */
 export interface Transport {
@@ -15,7 +15,7 @@ export interface Transport {
    * @param key - `unit/flow`
    * @param input - JSON body / path-param source
    */
-  call(key: string, input: unknown): Promise<ClientResult>;
+  call(key: string, input: unknown): Promise<ClientEnvelope>;
 }
 
 /**
@@ -132,7 +132,7 @@ async function once(
  *
  * @param res - HTTP response (body consumed)
  */
-async function decodeIfEnvelope(res: Response): Promise<ClientResult | null> {
+async function decodeIfEnvelope(res: Response): Promise<ClientEnvelope | null> {
   const text = await res.text();
   if (!text) return null;
   let json: unknown;
@@ -142,7 +142,7 @@ async function decodeIfEnvelope(res: Response): Promise<ClientResult | null> {
     return null;
   }
   if (json !== null && typeof json === "object" && "data" in json && "error" in json) {
-    return json as ClientResult;
+    return json as ClientEnvelope;
   }
   return null;
 }
@@ -186,6 +186,9 @@ function restRequest(
         query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
       }
     }
+  } else if (upper === "QUERY") {
+    // RFC 10008 QUERY always carries JSON content (empty object when only path params).
+    body = JSON.stringify(Object.keys(rest).length > 0 ? rest : {});
   } else if (Object.keys(rest).length > 0 || path === pathOut) {
     body = JSON.stringify(Object.keys(rest).length > 0 ? rest : (input ?? {}));
   }
@@ -194,7 +197,7 @@ function restRequest(
   return { url: `${base}${pathOut}${qs}`, method: upper, body };
 }
 
-async function decode(res: Response): Promise<ClientResult> {
+async function decode(res: Response): Promise<ClientEnvelope> {
   if (res.status === 204) {
     return { data: undefined, error: null };
   }
@@ -228,7 +231,7 @@ async function decode(res: Response): Promise<ClientResult> {
   }
 
   if (json !== null && typeof json === "object" && "data" in json && "error" in json) {
-    return json as ClientResult;
+    return json as ClientEnvelope;
   }
 
   if (res.ok) {