okengine 0.6.1 → 0.8.0

package/src/elements/store/sql-session.test.ts

@@ -56,6 +56,7 @@ describe("SqlStoreHandle — no relational query surface (path b)", () => {
         "findById",
         "delete",
         "exists",
+        "upsert",
         "increment",
         "raw",
         "count",
@@ -133,3 +134,41 @@ describe("SqlStoreHandle — orderBy / limit select chain", () => {
     await conn.close();
   });
 });
+
+describe("SqlStoreHandle — upsert", () => {
+  test("default inserts once then already-existed without touching the row", async () => {
+    const { handle, conn } = await openHandle();
+    const first = await handle.upsert(
+      posts,
+      { id: "welcome" },
+      { id: "welcome", title: "Hello", createdAt: 1 },
+    );
+    expect(first.status).toBe("upserted");
+
+    const second = await handle.upsert(
+      posts,
+      { id: "welcome" },
+      { id: "welcome", title: "Changed", createdAt: 2 },
+    );
+    expect(second.status).toBe("already-existed");
+
+    const row = await handle.findById(posts, "welcome");
+    expect(row).toEqual({ id: "welcome", title: "Hello", createdAt: 1 });
+    await conn.close();
+  });
+
+  test("onExisting update changes matched columns", async () => {
+    const { handle, conn } = await openHandle();
+    await handle.upsert(posts, { id: "n1" }, { id: "n1", title: "one", createdAt: 10 });
+    const updated = await handle.upsert(
+      posts,
+      { id: "n1" },
+      { id: "n1", title: "two", createdAt: 20 },
+      { onExisting: "update" },
+    );
+    expect(updated.status).toBe("changed");
+    const row = await handle.findById(posts, "n1");
+    expect(row).toEqual({ id: "n1", title: "two", createdAt: 20 });
+    await conn.close();
+  });
+});

package/src/elements/store/sql-session.ts

@@ -237,6 +237,21 @@ export interface SqlStoreHandle {
    * @param idOrWhere - Primary key string, or column equality map
    */
   exists(table: TableHandle | unknown, idOrWhere: string | WhereMap): Promise<boolean>;
+  /**
+   * Insert when no row matches `matchOn`; never touches an existing match
+   * unless `options.onExisting` is `"update"`.
+   *
+   * @param table - Table
+   * @param matchOn - Equality map or Drizzle condition identifying the row
+   * @param values - Row values for insert (and optional update)
+   * @param options - Per-call opt-in to update an existing match
+   */
+  upsert(
+    table: TableHandle | unknown,
+    matchOn: WhereMap | unknown,
+    values: SqlRow,
+    options?: { readonly onExisting?: "update" },
+  ): Promise<UpsertResult>;
   /**
    * Atomically add `by` to `column` on the PK row.
    *
@@ -276,6 +291,14 @@ export interface SqlStoreHandle {
   ensureTable(table: TableHandle): Promise<void>;
 }
 
+/** Outcome of {@link SqlStoreHandle.upsert}. */
+export type UpsertStatus = "upserted" | "changed" | "already-existed";
+
+/** Result envelope for {@link SqlStoreHandle.upsert}. */
+export interface UpsertResult {
+  readonly status: UpsertStatus;
+}
+
 /** Options for {@link SqlStoreHandle.page}. */
 export interface SqlPageOptions {
   /** Filter condition (equality map or Drizzle SQL). */
@@ -617,6 +640,38 @@ export function createSqlStoreHandle(
       return rows.length > 0;
     },
 
+    async upsert(table, matchOn, values, upsertOptions) {
+      await ensureFromMeta(table);
+      const name = resolveTableName(table);
+      const compiled = compileTableWhere(table, matchOn);
+      if (!compiled.clause) {
+        throw new Error("upsert() requires at least one matchOn predicate");
+      }
+      const found = await query(
+        `SELECT 1 AS "ok" FROM ${quoteIdent(name)} WHERE ${compiled.clause} LIMIT 1`,
+        compiled.params,
+      );
+      if (found.length === 0) {
+        const prepared = prepareInsertRow(table, values);
+        const cols = Object.keys(prepared);
+        const placeholders = cols.map(() => "?").join(", ");
+        const colList = cols.map(quoteIdent).join(", ");
+        const params = cols.map((c) => prepared[c]);
+        await exec(`INSERT INTO ${quoteIdent(name)} (${colList}) VALUES (${placeholders})`, params);
+        return { status: "upserted" as const };
+      }
+      if (upsertOptions?.onExisting !== "update") {
+        return { status: "already-existed" as const };
+      }
+      const prepared = prepareUpdateRow(table, values);
+      const setEntries = Object.entries(prepared);
+      if (setEntries.length === 0) return { status: "changed" as const };
+      const setSql = setEntries.map(([col]) => `${quoteIdent(col)} = ?`).join(", ");
+      const params = [...setEntries.map(([, v]) => v), ...compiled.params];
+      await exec(`UPDATE ${quoteIdent(name)} SET ${setSql} WHERE ${compiled.clause}`, params);
+      return { status: "changed" as const };
+    },
+
     async increment(table, idValue, column, by = 1) {
       await ensureFromMeta(table);
       const name = resolveTableName(table);

package/src/elements/store/upsert-app.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Real app-boot path for fx.store(db).upsert — must work through
+ * oke() → createTestApp → app.fetch(), not only the isolated SqlStoreHandle.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { gate } from "../gate.ts";
+import { oke } from "../../kernel/app.ts";
+import { createFx } from "../../kernel/fx.ts";
+import { flow, resetFlowSeq } from "../../kernel/flow.ts";
+import { on, resetBindings } from "../../kernel/on.ts";
+import { http } from "../../kernel/triggers.ts";
+import { createTestApp } from "../../test/create-test-app.ts";
+import { field, id, now, store } from "../store.ts";
+
+afterEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+const notes = store.schema.table("notes", {
+  id: field.text().primaryKey().defaultFn(id),
+  title: field.text().notNull(),
+  body: field.text().notNull(),
+  createdAt: field.integer().notNull().defaultFn(now),
+});
+
+const UpsertIn = z.object({
+  id: z.string(),
+  title: z.string(),
+  body: z.string(),
+  onExisting: z.enum(["update"]).optional(),
+});
+
+const UpsertOut = z.object({
+  status: z.enum(["upserted", "changed", "already-existed"]),
+});
+
+describe("fx.store(db).upsert via app.fetch (real boot)", () => {
+  test("abstract schema table: upserted → already-existed → changed", async () => {
+    resetBindings();
+    resetFlowSeq();
+
+    const db = store.sql("app", { schema: { notes } });
+
+    const seed = on(
+      http.post("/seed").gate(gate.public),
+      flow({
+        name: "notes.seed",
+        in: UpsertIn,
+        out: UpsertOut,
+        effects: { writes: ["sql:app"], reads: ["sql:app"] },
+        do: async (input, fx) =>
+          fx
+            .store(db)
+            .upsert(
+              notes,
+              { id: input.id },
+              { id: input.id, title: input.title, body: input.body, createdAt: 1 },
+              input.onExisting ? { onExisting: input.onExisting } : undefined,
+            ),
+      }),
+    );
+
+    const app = oke({
+      name: "upsert-app-boot",
+      gate: { policies: [gate.public] },
+    }).adopt({ seed });
+    Object.assign(app.$options, { env: "test", stores: [db], unguardedHttp: "allow" });
+    await createTestApp(app);
+
+    async function post(body: unknown) {
+      const res = await app.fetch(
+        new Request("http://localhost/seed", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(body),
+        }),
+      );
+      expect(res.status).toBe(200);
+      const json = (await res.json()) as { data: { status: string } };
+      return json.data.status;
+    }
+
+    expect(await post({ id: "welcome", title: "Hello", body: "one" })).toBe("upserted");
+    expect(await post({ id: "welcome", title: "Changed", body: "two" })).toBe("already-existed");
+    expect(
+      await post({
+        id: "welcome",
+        title: "Updated",
+        body: "three",
+        onExisting: "update",
+      }),
+    ).toBe("changed");
+  });
+
+  test("SQL StoreDecl without store runtime fails loudly (not stub upsert-missing)", async () => {
+    const db = store.sql("app", { schema: { notes } });
+    const fx = createFx({ flow: "orphan" });
+    expect(() => fx.store(db)).toThrow(/no store runtime/);
+  });
+});

package/src/elements/store.ts

@@ -91,6 +91,9 @@ export type {
   ResolvedListConfig,
 } from "./store/resource.ts";
 
+export { defineSeed, normalizeSeedFns, resolveSeedCategory } from "./store/seed.ts";
+export type { SeedCategory, SeedDef, SeedFn, SeedFns } from "./store/seed.ts";
+
 export { createSqlStoreHandle, resolvePkColumn } from "./store/sql-session.ts";
 export type {
   SqlStoreHandle,
@@ -102,6 +105,8 @@ export type {
   InsertValuesBuilder,
   SqlSessionOptions,
   SqlPageOptions,
+  UpsertResult,
+  UpsertStatus,
   WhereMap,
 } from "./store/sql-session.ts";
 
@@ -122,3 +127,27 @@ export type {
 
 export { fileKeyWarnings, contentAddressedKey, projectFileKeys } from "./store/files-policy.ts";
 export type { FileKeyWarning } from "./store/files-policy.ts";
+
+export {
+  createFilesImagePipeline,
+  putImageToBucket,
+  variantObjectKey,
+  resolveFilesImageCtorOptions,
+  DEFAULT_FILES_IMAGE_MAX_PIXELS,
+} from "./store/files-image.ts";
+export type {
+  FilesImageMeta,
+  FilesImageOptions,
+  FilesImageResizeOptions,
+  FilesImageModulateOptions,
+  FilesImageJpegOptions,
+  FilesImagePngOptions,
+  FilesImageWebpOptions,
+  FilesImageQualityOptions,
+  FilesImageFormat,
+  FilesImagePipeline,
+  FilesImageBucketAccess,
+  ImageVariantSpec,
+  PutImageOptions,
+  PutImageResult,
+} from "./store/files-image.ts";

package/src/elements/vault/boot-chain.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared Vault resolution-chain assembly for app boot and Console.
+ *
+ * Order (first hit wins): process.env → .env.local → compose .env.docker →
+ * backend layer (`env` seed / openbao / memory / managed).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ConfigEnv } from "../../config/index.ts";
+import {
+  envVaultDriver,
+  managedVaultDriver,
+  memoryVaultDriver,
+  openbaoVaultDriver,
+} from "../../drivers/index.ts";
+import { parseDotenv } from "../../drivers/vault-dotenv-parse.ts";
+import type { VaultDriverId } from "../../drivers/vault-types.ts";
+import { resolveComposeEnvPath } from "./chain.ts";
+import type { VaultChainLayer } from "./runtime.ts";
+
+/** Options for {@link buildVaultBootChain}. */
+export interface BuildVaultBootChainOptions {
+  /** Project root (defaults to `process.cwd()`). */
+  readonly cwd?: string;
+  /** Resolved `drivers.vault` id for the active env. */
+  readonly driverId: VaultDriverId;
+  /** Active config env — controls fail-loud vs soft fallback for openbao. */
+  readonly env?: ConfigEnv;
+  /** Seed secrets for the terminal memory / managed layer. */
+  readonly seed?: Readonly<Record<string, string>>;
+  /**
+   * When `openbao` is selected but credentials are missing:
+   * - `"throw"` — fail loud (default for `prod` / `docker`)
+   * - `"memory"` — soft-fallback to a seeded memory bag (Console / local)
+   */
+  readonly missingOpenbao?: "throw" | "memory";
+}
+
+/**
+ * Normalize a config label to a {@link VaultDriverId}.
+ *
+ * Accepts legacy `"dotenv"` as an alias for `"env"`.
+ *
+ * @param raw - Config string
+ */
+export function normalizeVaultDriverId(raw: string): VaultDriverId {
+  if (raw === "dotenv") return "env";
+  if (raw === "env" || raw === "openbao" || raw === "memory" || raw === "managed") {
+    return raw;
+  }
+  throw new Error(
+    `oke boot: unknown vault driver "${raw}" (expected env · openbao · memory · managed)`,
+  );
+}
+
+/**
+ * Build the standard Vault resolution chain for app boot / Console.
+ *
+ * @param options - Driver id + cwd + seed
+ */
+export function buildVaultBootChain(options: BuildVaultBootChainOptions): VaultChainLayer[] {
+  const cwd = options.cwd ?? process.cwd();
+  const seed = options.seed ?? {};
+  const composeEnv = resolveComposeEnvPath(cwd);
+
+  let composeText = "";
+  if (existsSync(composeEnv.path)) {
+    composeText = readFileSync(composeEnv.path, "utf8").toString();
+  }
+  const envMap = parseDotenv(composeText);
+  const openbaoUrl = process.env.OKE_VAULT_URL ?? envMap.get("OKE_VAULT_URL");
+  const openbaoToken = process.env.OKE_VAULT_TOKEN ?? envMap.get("OKE_VAULT_TOKEN");
+  const openbaoMount = process.env.OKE_VAULT_MOUNT ?? envMap.get("OKE_VAULT_MOUNT") ?? "secret";
+
+  const envLayers: VaultChainLayer[] = [
+    { driver: envVaultDriver, source: "process.env" },
+    {
+      driver: envVaultDriver,
+      source: ".env.local",
+      options: { path: resolve(cwd, ".env.local") },
+    },
+    {
+      driver: envVaultDriver,
+      source: composeEnv.source,
+      options: { path: composeEnv.path },
+    },
+  ];
+
+  switch (options.driverId) {
+    case "memory":
+      return [
+        {
+          driver: memoryVaultDriver,
+          source: "driver",
+          options: { secrets: seed },
+        },
+      ];
+    case "managed":
+      return [
+        {
+          driver: managedVaultDriver,
+          source: "driver",
+          options: { secrets: seed },
+        },
+      ];
+    case "env":
+      return [
+        ...envLayers,
+        {
+          driver: memoryVaultDriver,
+          source: "driver",
+          options: { secrets: seed },
+        },
+      ];
+    case "openbao": {
+      if (openbaoUrl && openbaoToken) {
+        return [
+          ...envLayers,
+          {
+            driver: openbaoVaultDriver,
+            source: "driver",
+            options: { url: openbaoUrl, token: openbaoToken, mount: openbaoMount },
+          },
+        ];
+      }
+      const env = options.env ?? "local";
+      const missing =
+        options.missingOpenbao ?? (env === "prod" || env === "docker" ? "throw" : "memory");
+      if (missing === "throw") {
+        throw new Error(
+          'oke boot: vault driver "openbao" needs OKE_VAULT_URL and OKE_VAULT_TOKEN ' +
+            "(did `oke dev -d` bootstrap OpenBao / write docker/.env.docker?)",
+        );
+      }
+      return [
+        ...envLayers,
+        {
+          driver: memoryVaultDriver,
+          source: "driver",
+          options: { secrets: seed },
+        },
+      ];
+    }
+    default: {
+      const _exhaustive: never = options.driverId;
+      throw new Error(`oke boot: unhandled vault driver ${String(_exhaustive)}`);
+    }
+  }
+}

package/src/elements/vault/runtime.ts

@@ -87,6 +87,11 @@ export interface CreateVaultRuntimeOptions {
 export interface VaultRuntime {
   /** Declared contracts by name. */
   readonly contracts: ReadonlyMap<string, VaultSecretDecl>;
+  /**
+   * Driver ids of each chain layer in order (`env` · `openbao` · `memory` · `managed`).
+   * Available before {@link boot}.
+   */
+  readonly chainDriverIds: readonly string[];
   /**
    * Open every chain layer, merge (first wins), validate all contracts,
    * register redaction. Throws {@link VaultBootError} listing every gap.
@@ -245,8 +250,11 @@ export function createVaultRuntime(options: CreateVaultRuntimeOptions = {}): Vau
     booted = true;
   }
 
+  const chainDriverIds = (options.chain ?? []).map((layer) => layer.driver.id);
+
   return {
     contracts,
+    chainDriverIds,
     get booted() {
       return booted;
     },

package/src/index.ts

@@ -65,6 +65,9 @@ export {
   now,
   defineTable,
   field,
+  defineSeed,
+  normalizeSeedFns,
+  resolveSeedCategory,
   createStoreRuntime,
   type StoreDecl,
   type StoreRuntime,
@@ -72,6 +75,12 @@ export {
   type TableHandle,
   type SchemaTableDecl,
   type SchemaColumnDecl,
+  type SeedDef,
+  type SeedFn,
+  type SeedFns,
+  type SeedCategory,
+  type UpsertResult,
+  type UpsertStatus,
 } from "./elements/store.ts";
 
 export {
@@ -152,7 +161,13 @@ export {
   createJournal,
   createMemoryJournalStore,
   createFileJournalStore,
+  hasJournalLease,
+  isJournalLeaseBusy,
+  JournalLeaseBusy,
+  JOURNAL_DEFAULT_LEASE_MS,
   type Journal,
+  type JournalLeaseOptions,
+  type JournalLeaseStore,
   type JournalStore,
   type JournalRun,
 } from "./kernel/journal.ts";