okengine 0.3.6 → 0.5.0

package/src/kernel/plugin-elements.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test, beforeEach } from "bun:test";
+import { clock } from "../elements/clock.ts";
+import { gate } from "../elements/gate.ts";
+import { signal } from "../elements/signal.ts";
+import { vault } from "../elements/vault.ts";
+import { oke } from "./app.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { plugin } from "./plugin.ts";
+import { http } from "./triggers.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+describe("plugin element contributions", () => {
+  test("vault / clock / signal / gate merge into boot options", async () => {
+    const otpSecret = vault.secret("OTP_SIGNING_KEY", {
+      description: "2FA HMAC",
+      dev: "test-otp-signing-key",
+    });
+    const expire = clock("expire-otp", { every: "1m" });
+    const bus = signal("otp.events", { delivery: "once" });
+    const member = gate.policy("plugin-member", ({ auth }) => !!auth.verified);
+
+    const twoFactor = plugin("twoFactor-scaffold", { version: "0.0.1" })
+      .vault(otpSecret)
+      .clock(expire)
+      .signal(bus)
+      .gate(member)
+      .table("otp_codes")
+      .needs("store.sql");
+
+    on(http.get("/ok").gate(gate.public), flow({ name: "ok", do: () => ({ ok: true }) }));
+
+    const app = oke({
+      name: "plugin-elements",
+      gate: { policies: [gate.public] },
+      vault: { allowDevFallbacks: true },
+    }).plug(twoFactor);
+
+    await app.boot({ env: "test", unguardedHttp: "allow" });
+    expect(app.booted).toBe(true);
+    expect(app.elements?.vault).toBeDefined();
+    expect(app.elements?.clock).toBeDefined();
+    expect(app.elements?.signal).toBeDefined();
+    expect(app.elements?.gate).toBeDefined();
+    await app.stop();
+  });
+});

package/src/kernel/plugin-needs.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from "bun:test";
+import { oke } from "./app.ts";
+import { flow } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { plugin } from "./plugin.ts";
+import { assertPluginNeeds, PluginNeedsError, buildAvailableNeedTokens } from "./plugin-needs.ts";
+import { http } from "./triggers.ts";
+import { resetFlowSeq } from "./flow.ts";
+import { gate } from "../elements/gate.ts";
+
+describe("plugin .needs() resolution", () => {
+  test("plugin-name dependency fails when missing", () => {
+    expect(() =>
+      assertPluginNeeds(
+        {
+          twoFactor: {
+            name: "twoFactor",
+            version: "0.0.1",
+            declares: [],
+            intercepts: [],
+            needs: ["auth"],
+          },
+        },
+        { pluginNames: new Set(["twoFactor"]), available: new Set() },
+      ),
+    ).toThrow(PluginNeedsError);
+  });
+
+  test("plugin-name dependency passes when plugged", () => {
+    expect(() =>
+      assertPluginNeeds(
+        {
+          auth: {
+            name: "auth",
+            version: "0.0.1",
+            declares: [],
+            intercepts: [],
+            needs: [],
+          },
+          twoFactor: {
+            name: "twoFactor",
+            version: "0.0.1",
+            declares: [],
+            intercepts: [],
+            needs: ["auth"],
+          },
+        },
+        {
+          pluginNames: new Set(["auth", "twoFactor"]),
+          available: new Set(),
+        },
+      ),
+    ).not.toThrow();
+  });
+
+  test("element token store.sql from available set", () => {
+    const available = buildAvailableNeedTokens({ elements: { storeSql: true } });
+    expect(available.has("store.sql")).toBe(true);
+    expect(() =>
+      assertPluginNeeds(
+        {
+          auth: {
+            name: "auth",
+            version: "0.0.1",
+            declares: ["table:oke_sessions"],
+            intercepts: [],
+            needs: ["store.sql"],
+          },
+        },
+        { pluginNames: new Set(["auth"]), available },
+      ),
+    ).not.toThrow();
+  });
+
+  test("boot fails when plugin needs missing peer plugin", async () => {
+    resetBindings();
+    resetFlowSeq();
+    on(http.get("/x").gate(gate.public), flow({ name: "x", do: () => ({ ok: true }) }));
+    const dependent = plugin("needs-auth", { version: "0.0.1" }).needs("auth");
+    const app = oke({ name: "needs-boot", gate: { policies: [gate.public] } }).plug(dependent);
+    await expect(app.boot({ env: "test" })).rejects.toThrow(PluginNeedsError);
+  });
+});

package/src/kernel/plugin-needs.ts

@@ -0,0 +1,129 @@
+/**
+ * Resolve plugin `.needs(dep)` at boot — fail loud when unmet.
+ *
+ * Tokens are either:
+ * - another plugged plugin name (e.g. `"auth"`)
+ * - an element / driver id (e.g. `"store.sql"`, `"postgres"`)
+ */
+
+import type { PluginCapabilities } from "./plugin.ts";
+
+/** Known element / facet dependency tokens. */
+export const ELEMENT_NEED_TOKENS = [
+  "store.sql",
+  "store.kv",
+  "store.files",
+  "store.index",
+  "signal",
+  "clock",
+  "gate",
+  "vault",
+  "channel",
+  "ai",
+  "flow",
+] as const;
+
+/** One unmet `.needs()` dependency. */
+export interface PluginNeedGap {
+  /** Plugin that declared the need. */
+  readonly plugin: string;
+  /** Unmet dependency token. */
+  readonly need: string;
+}
+
+/**
+ * Thrown when installed plugins declare unmet `.needs()` dependencies.
+ */
+export class PluginNeedsError extends Error {
+  readonly gaps: readonly PluginNeedGap[];
+
+  constructor(gaps: readonly PluginNeedGap[]) {
+    const lines = gaps.map((g) => `  - ${g.plugin} needs "${g.need}"`);
+    super(
+      `plugin boot failed — ${gaps.length} unmet .needs() dependenc${gaps.length === 1 ? "y" : "ies"}:\n${lines.join("\n")}`,
+    );
+    this.name = "PluginNeedsError";
+    this.gaps = gaps;
+  }
+}
+
+/** Context for resolving whether a need token is available. */
+export interface PluginNeedsContext {
+  /** Installed plugin names. */
+  readonly pluginNames: ReadonlySet<string>;
+  /**
+   * Available element / driver tokens (e.g. `store.sql`, `postgres`).
+   * Built from boot options, declared drivers, and element needs.
+   */
+  readonly available: ReadonlySet<string>;
+}
+
+/**
+ * Collect unmet needs across all plugin capabilities.
+ *
+ * @param capabilities - Registry capability map
+ * @param ctx - Available plugins + element/driver tokens
+ */
+export function collectUnmetPluginNeeds(
+  capabilities: Readonly<Record<string, PluginCapabilities>>,
+  ctx: PluginNeedsContext,
+): PluginNeedGap[] {
+  const gaps: PluginNeedGap[] = [];
+  for (const caps of Object.values(capabilities)) {
+    for (const need of caps.needs) {
+      if (ctx.pluginNames.has(need) || ctx.available.has(need)) continue;
+      gaps.push({ plugin: caps.name, need });
+    }
+  }
+  return gaps;
+}
+
+/**
+ * Assert every plugin `.needs()` is satisfied. Throws {@link PluginNeedsError}.
+ *
+ * @param capabilities - Registry capability map
+ * @param ctx - Available plugins + element/driver tokens
+ */
+export function assertPluginNeeds(
+  capabilities: Readonly<Record<string, PluginCapabilities>>,
+  ctx: PluginNeedsContext,
+): void {
+  const gaps = collectUnmetPluginNeeds(capabilities, ctx);
+  if (gaps.length > 0) throw new PluginNeedsError(gaps);
+}
+
+/**
+ * Build the available token set from boot-time signals.
+ *
+ * @param input - Element/driver presence flags and declared driver ids
+ */
+export function buildAvailableNeedTokens(input: {
+  readonly elements?: {
+    readonly storeSql?: boolean;
+    readonly storeKv?: boolean;
+    readonly storeFiles?: boolean;
+    readonly storeIndex?: boolean;
+    readonly signal?: boolean;
+    readonly clock?: boolean;
+    readonly gate?: boolean;
+    readonly vault?: boolean;
+    readonly channel?: boolean;
+    readonly ai?: boolean;
+  };
+  readonly driverIds?: readonly string[];
+}): Set<string> {
+  const available = new Set<string>();
+  const e = input.elements ?? {};
+  if (e.storeSql) available.add("store.sql");
+  if (e.storeKv) available.add("store.kv");
+  if (e.storeFiles) available.add("store.files");
+  if (e.storeIndex) available.add("store.index");
+  if (e.signal) available.add("signal");
+  if (e.clock) available.add("clock");
+  if (e.gate) available.add("gate");
+  if (e.vault) available.add("vault");
+  if (e.channel) available.add("channel");
+  if (e.ai) available.add("ai");
+  for (const id of input.driverIds ?? []) available.add(id);
+  return available;
+}

package/src/kernel/plugin.ts

@@ -14,8 +14,14 @@
  * @see docs/spec/console.md §9.15
  */
 
+import type { ChannelTemplateDecl } from "../elements/channel/declare.ts";
+import type { ClockDecl } from "../elements/clock/declare.ts";
+import type { GateDecl } from "../elements/gate/declare.ts";
+import type { SignalDecl } from "../elements/signal/declare.ts";
+import type { VaultSecretDecl } from "../elements/vault/declare.ts";
 import type { SchemaInput } from "../validation/standard-schema.ts";
 import type { AnyFlowDef, FlowErrorMap } from "./flow.ts";
+import type { Binding } from "./on.ts";
 import type { HookFn, HookStage } from "./hooks.ts";
 
 /** Brand carrying accumulated decoration types through the builder. */
@@ -226,6 +232,13 @@ export interface PluginApi {
     columns?: Readonly<Record<string, unknown>>,
     options?: PluginTableOptions,
   ): PluginApi;
+  /**
+   * Contribute an HTTP (or other) Binding into the app router + adopted set.
+   * Required for auth method plugins — registry `flows[]` alone does not route.
+   *
+   * @param binding - Trigger + flow pair
+   */
+  binding(binding: Binding): PluginApi;
   /**
    * Contribute a flow.
    *
@@ -245,6 +258,36 @@ export interface PluginApi {
    * @param schema - Standard Schema
    */
   config(schema: SchemaInput): PluginApi;
+  /**
+   * Contribute a vault secret/config contract (merged into boot secrets).
+   *
+   * @param secret - Vault contract from `vault.secret(...)` / `vault.config(...)`
+   */
+  vault(secret: VaultSecretDecl): PluginApi;
+  /**
+   * Contribute a named clock schedule (merged into boot clocks).
+   *
+   * @param decl - Clock from `clock(...)`
+   */
+  clock(decl: ClockDecl): PluginApi;
+  /**
+   * Contribute a signal declaration (merged into boot signals).
+   *
+   * @param decl - Signal from `signal(...)`
+   */
+  signal(decl: SignalDecl): PluginApi;
+  /**
+   * Contribute a gate declaration (merged into boot gates).
+   *
+   * @param decl - Gate from `gate.policy` / `gate.scope` / `gate.rate` / `gate.public`
+   */
+  gate(decl: GateDecl): PluginApi;
+  /**
+   * Contribute a channel template (merged into boot channel templates).
+   *
+   * @param decl - Template from `channel.email.template(...)` etc.
+   */
+  channelTemplate(decl: ChannelTemplateDecl): PluginApi;
 }
 
 /** Captured capability lists for the Manifest. */
@@ -276,9 +319,15 @@ export interface PluginRegistration {
   readonly cli: readonly CliContribution[];
   readonly images: readonly ImageRecipeContribution[];
   readonly flows: readonly AnyFlowDef[];
+  readonly bindings: readonly Binding[];
   readonly errors: FlowErrorMap;
   readonly client: readonly ClientExtensionContribution[];
   readonly configSchema: SchemaInput | undefined;
+  readonly vaultSecrets: readonly VaultSecretDecl[];
+  readonly clocks: readonly ClockDecl[];
+  readonly signals: readonly SignalDecl[];
+  readonly gates: readonly GateDecl[];
+  readonly channelTemplates: readonly ChannelTemplateDecl[];
 }
 
 /**
@@ -383,6 +432,12 @@ export interface PluginDef<D extends Record<string, unknown> = {}> {
     columns?: Readonly<Record<string, unknown>>,
     options?: PluginTableOptions,
   ): PluginDef<D>;
+  /**
+   * Queue a Binding contribution (joins router + adopted on app.plug).
+   *
+   * @param binding - Trigger + flow
+   */
+  binding(binding: Binding): PluginDef<D>;
   /**
    * Queue a flow contribution.
    *
@@ -402,6 +457,16 @@ export interface PluginDef<D extends Record<string, unknown> = {}> {
    * @param schema - Standard Schema
    */
   config(schema: SchemaInput): PluginDef<D>;
+  /** Queue a vault secret/config contract. */
+  vault(secret: VaultSecretDecl): PluginDef<D>;
+  /** Queue a clock schedule. */
+  clock(decl: ClockDecl): PluginDef<D>;
+  /** Queue a signal declaration. */
+  signal(decl: SignalDecl): PluginDef<D>;
+  /** Queue a gate declaration. */
+  gate(decl: GateDecl): PluginDef<D>;
+  /** Queue a channel template. */
+  channelTemplate(decl: ChannelTemplateDecl): PluginDef<D>;
 }
 
 /** Extract accumulated decoration types from a {@link PluginDef}. */
@@ -505,6 +570,12 @@ export function plugin(name: string, options: PluginOptions): PluginDef {
       });
       return def;
     },
+    binding(binding) {
+      steps.push((api) => {
+        api.binding(binding);
+      });
+      return def;
+    },
     flow(flowDef) {
       steps.push((api) => {
         api.flow(flowDef);
@@ -523,6 +594,36 @@ export function plugin(name: string, options: PluginOptions): PluginDef {
       });
       return def;
     },
+    vault(secret) {
+      steps.push((api) => {
+        api.vault(secret);
+      });
+      return def;
+    },
+    clock(decl) {
+      steps.push((api) => {
+        api.clock(decl);
+      });
+      return def;
+    },
+    signal(decl) {
+      steps.push((api) => {
+        api.signal(decl);
+      });
+      return def;
+    },
+    gate(decl) {
+      steps.push((api) => {
+        api.gate(decl);
+      });
+      return def;
+    },
+    channelTemplate(decl) {
+      steps.push((api) => {
+        api.channelTemplate(decl);
+      });
+      return def;
+    },
   };
 
   return def;

package/src/kernel/redacted.ts

@@ -0,0 +1,74 @@
+/**
+ * `Redacted<T>` — a plain value wrapper that keeps a secret value out of
+ * logs, traces, and accidental serialization.
+ *
+ * Not an effect type: effect tracking only records which secret *names* a
+ * flow touches. This is value hygiene inside a flow body.
+ */
+
+/** Placeholder used for any representation of a {@link Redacted}. */
+export const REDACTED_PLACEHOLDER = "[redacted]";
+
+/**
+ * Wrap a value so printing / logging / JSON serialization never yields the
+ * real value. The only way to read the wrapped value is {@link reveal}.
+ */
+export class Redacted<T> {
+  readonly #value: T;
+
+  constructor(value: T) {
+    this.#value = value;
+  }
+
+  /** The one explicit way to get the real value. */
+  reveal(): T {
+    return this.#value;
+  }
+
+  toString(): string {
+    return REDACTED_PLACEHOLDER;
+  }
+
+  toJSON(): string {
+    return REDACTED_PLACEHOLDER;
+  }
+
+  [Symbol.toPrimitive](): string {
+    return REDACTED_PLACEHOLDER;
+  }
+
+  /** `util.inspect` / `console.log` — never the real value. */
+  [Symbol.for("nodejs.util.inspect.custom")](): string {
+    return REDACTED_PLACEHOLDER;
+  }
+}
+
+/** Type guard for {@link Redacted}. */
+export function isRedacted(value: unknown): value is Redacted<unknown> {
+  return value instanceof Redacted;
+}
+
+/**
+ * Deep-walk a log/trace payload: replace every {@link Redacted} with the
+ * placeholder (never the wrapped value); leave everything else untouched.
+ *
+ * @param value - Arbitrary structured data
+ */
+export function maskRedactedDeep<T>(value: T): T {
+  return maskRedactedValue(value) as T;
+}
+
+function maskRedactedValue(value: unknown): unknown {
+  if (isRedacted(value)) return REDACTED_PLACEHOLDER;
+  if (value === null || value === undefined) return value;
+  if (Array.isArray(value)) return value.map(maskRedactedValue);
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(obj)) {
+      out[k] = maskRedactedValue(v);
+    }
+    return out;
+  }
+  return value;
+}

package/src/kernel/registry-isolation.test.ts

@@ -22,11 +22,11 @@ afterEach(() => {
 describe("registry isolation", () => {
   test("consume (default): App B does not serve App A routes", async () => {
     on(http.get("/a"), flow({ name: "app-a.ping", do: () => "a" }));
-    const appA = oke({ name: "app-a" });
+    const appA = oke({ autoBoot: false, name: "app-a" });
 
     // No resetBindings() between the apps — the pre-fix leak scenario.
     on(http.get("/b"), flow({ name: "app-b.ping", do: () => "b" }));
-    const appB = oke({ name: "app-b" });
+    const appB = oke({ autoBoot: false, name: "app-b" });
 
     // Pre-fix this was 200: App B adopted App A's leftover binding.
     expect((await appB.fetch(new Request("http://localhost/a"))).status).toBe(404);
@@ -46,10 +46,10 @@ describe("registry isolation", () => {
 
   test("keep: today's behavior — registry survives construction", async () => {
     on(http.get("/a"), flow({ name: "kept.ping", do: () => "a" }));
-    oke({ name: "app-a", registry: "keep" });
+    oke({ autoBoot: false, name: "app-a", registry: "keep" });
     expect(listBindings()).toHaveLength(1);
 
-    const appB = oke({ name: "app-b", registry: "keep" });
+    const appB = oke({ autoBoot: false, name: "app-b", registry: "keep" });
     expect((await appB.fetch(new Request("http://localhost/a"))).status).toBe(200);
   });
 
@@ -60,7 +60,7 @@ describe("registry isolation", () => {
       trigger: http.get("/b"),
       flow: flow({ name: "only-b.ping", do: () => "b" }),
     };
-    const app = oke({ name: "app-b", registry: "ignore", bindings: [onlyB] });
+    const app = oke({ autoBoot: false, name: "app-b", registry: "ignore", bindings: [onlyB] });
 
     expect((await app.fetch(new Request("http://localhost/stray"))).status).toBe(404);