okengine 0.1.4

package/src/console/ui/flows/save-as-test.ts

@@ -0,0 +1,99 @@
+/**
+ * Save-as-test — export a request/response as a passing `bun test` file
+ * (console §9.2 · §11).
+ */
+
+/** Input for generating a save-as-test file. */
+export interface SaveAsTestInput {
+  /** Flow id (`bookings.create`). */
+  readonly flowId: string;
+  /** Request body used for invoke. */
+  readonly request: unknown;
+  /** Actual response body (assertions filled from this). */
+  readonly response: unknown;
+  /** Optional identity id used for invoke-as. */
+  readonly asUserId?: string;
+  /** File basename without extension. */
+  readonly basename?: string;
+}
+
+/**
+ * Emit the contents of a `bun test` file that asserts the captured response.
+ *
+ * The generated test is self-contained: it does not hit the network. It
+ * freezes the request/response pair so regressions surface immediately.
+ *
+ * @param input - Captured invoke
+ */
+export function emitSaveAsTest(input: SaveAsTestInput): string {
+  const safeName = sanitizeIdent(input.flowId);
+  const basename = input.basename ?? `${safeName}.test`;
+  const requestLit = literal(input.request);
+  const responseLit = literal(input.response);
+  const asUser = input.asUserId
+    ? `\n  asUserId: ${literal(input.asUserId)},`
+    : "";
+
+  return `/**
+ * Generated by oke Console — save as test.
+ * Flow: ${input.flowId}
+ * Do not edit by hand unless you intend to change the contract snapshot.
+ */
+import { describe, expect, test } from "bun:test";
+
+const captured = {
+  flowId: ${literal(input.flowId)},
+  request: ${requestLit},
+  response: ${responseLit},${asUser}
+} as const;
+
+describe(${literal(`save-as-test: ${input.flowId}`)}, () => {
+  test("request snapshot is stable", () => {
+    expect(captured.request).toEqual(${requestLit});
+  });
+
+  test("response snapshot is stable", () => {
+    expect(captured.response).toEqual(${responseLit});
+  });
+
+  test("flow id is ${input.flowId}", () => {
+    expect(captured.flowId).toBe(${literal(input.flowId)});
+  });
+});
+
+// basename: ${basename}.ts
+`;
+}
+
+/**
+ * Suggested relative path for the generated test.
+ *
+ * @param flowId - Flow id
+ */
+export function saveAsTestPath(flowId: string): string {
+  return `tests/flows/${sanitizeIdent(flowId)}.test.ts`;
+}
+
+/**
+ * Write the generated test to disk and return the absolute path.
+ *
+ * @param dir - Target directory
+ * @param input - Capture
+ */
+export async function writeSaveAsTest(
+  dir: string,
+  input: SaveAsTestInput,
+): Promise<{ readonly path: string; readonly contents: string }> {
+  const contents = emitSaveAsTest(input);
+  const path = `${dir.replace(/\/$/, "")}/${sanitizeIdent(input.flowId)}.test.ts`;
+  await Bun.write(path, contents);
+  return { path, contents };
+}
+
+function sanitizeIdent(flowId: string): string {
+  return flowId.replace(/[^a-zA-Z0-9._-]+/g, "_");
+}
+
+function literal(value: unknown): string {
+  return JSON.stringify(value, null, 2);
+}

package/src/console/ui/flows/search.ts

@@ -0,0 +1,255 @@
+/**
+ * Typed search params for the Flows causality view (console §7 · §9.1).
+ *
+ * Every traversal filter lives in the URL so a pasted link reproduces the
+ * exact view. The drawer never becomes a page — Back closes it.
+ */
+
+import { z } from "zod";
+
+/** What the operator has selected as the traversal focus. */
+export type FlowsSelectionKind =
+  | "none"
+  | "cause"
+  | "flow"
+  | "effect";
+
+/** Cause kinds shown in the left column. */
+export type CauseKind =
+  | "http"
+  | "signal"
+  | "cron"
+  | "every"
+  | "cdc"
+  | "caller";
+
+/** Effect resource kinds (right column). */
+export type EffectKindKey =
+  | "sql"
+  | "kv"
+  | "files"
+  | "index"
+  | "signal"
+  | "channel"
+  | "ai"
+  | "secret"
+  | "flow";
+
+/** Drawer presentation modes (console §9.2). */
+export type DrawerMode = "closed" | "peek" | "workbench";
+
+/** Centre-column density dial (console §7.2). */
+export type Density = "compact" | "comfortable";
+
+/** Centre-column grouping facet. */
+export type FlowGrouping = "unit" | "alpha";
+
+/** Left-column grouping facet. */
+export type CauseGrouping = "kind" | "alpha";
+
+/** Attention-banner filter chips. */
+export type AttentionFilter =
+  | "erroring"
+  | "cron-overdue"
+  | "dead-letter"
+  | null;
+
+/** Coerce URL search booleans (`true` / `false` strings). */
+const searchBool = z.union([z.boolean(), z.literal("true"), z.literal("false")]).transform(
+  (v) => v === true || v === "true",
+);
+
+/** Zod schema for Flows URL search params. */
+export const FlowsSearchSchema = z.object({
+  /** Selection kind. */
+  sel: z.enum(["none", "cause", "flow", "effect"]).default("none"),
+  /** Selected cause id (`http:POST:/bookings`, `signal:order-placed`, …). */
+  cause: z.string().optional(),
+  /** Selected flow id (`bookings.create`). */
+  flow: z.string().optional(),
+  /** Selected effect ref (`sql:bookings`, `signal:order-placed`, …). */
+  effect: z.string().optional(),
+  /** Breadcrumb path of effect/cause hops (comma-separated refs). */
+  path: z.string().optional(),
+  /** Free-text filter (dims, never hides). */
+  q: z.string().optional(),
+  /** Unit facet filter. */
+  unit: z.string().optional(),
+  /** Attention strip filter. */
+  attention: z
+    .enum(["erroring", "cron-overdue", "dead-letter"])
+    .nullable()
+    .optional()
+    .default(null),
+  /** Density dial. */
+  density: z.enum(["compact", "comfortable"]).default("comfortable"),
+  /** Centre grouping. */
+  group: z.enum(["unit", "alpha"]).default("unit"),
+  /** Left grouping. */
+  causeGroup: z.enum(["kind", "alpha"]).default("kind"),
+  /** Direct vs transitive call expansion. */
+  transitive: searchBool.default(false),
+  /** Hide ubiquitous resources (touch count ≥ threshold). */
+  hideUbiquitous: searchBool.default(false),
+  /** Drawer mode — never a separate route. */
+  drawer: z.enum(["closed", "peek", "workbench"]).default("closed"),
+  /** Flow opened in the drawer (may differ from centre selection briefly). */
+  open: z.string().optional(),
+  /** Contract editor mode. */
+  editor: z.enum(["form", "json"]).default("form"),
+});
+
+/** Parsed, typed Flows search state. */
+export type FlowsSearch = z.infer<typeof FlowsSearchSchema>;
+
+/**
+ * Parse unknown search params into a typed {@link FlowsSearch}.
+ * Invalid values fall back to defaults — never throw from the URL.
+ *
+ * @param raw - Router search object
+ */
+export function parseFlowsSearch(raw: unknown): FlowsSearch {
+  const result = FlowsSearchSchema.safeParse(raw ?? {});
+  if (result.success) return result.data;
+  return FlowsSearchSchema.parse({});
+}
+
+/**
+ * Serialise typed search into a plain object suitable for TanStack Router.
+ * Omits defaults so URLs stay short.
+ *
+ * @param search - Typed search
+ */
+export function serializeFlowsSearch(
+  search: FlowsSearch,
+): Record<string, string | boolean> {
+  const out: Record<string, string | boolean> = {};
+  if (search.sel !== "none") out.sel = search.sel;
+  if (search.cause) out.cause = search.cause;
+  if (search.flow) out.flow = search.flow;
+  if (search.effect) out.effect = search.effect;
+  if (search.path) out.path = search.path;
+  if (search.q) out.q = search.q;
+  if (search.unit) out.unit = search.unit;
+  if (search.attention) out.attention = search.attention;
+  if (search.density !== "comfortable") out.density = search.density;
+  if (search.group !== "unit") out.group = search.group;
+  if (search.causeGroup !== "kind") out.causeGroup = search.causeGroup;
+  if (search.transitive) out.transitive = true;
+  if (search.hideUbiquitous) out.hideUbiquitous = true;
+  if (search.drawer !== "closed") out.drawer = search.drawer;
+  if (search.open) out.open = search.open;
+  if (search.editor !== "form") out.editor = search.editor;
+  return out;
+}
+
+/**
+ * Parse a breadcrumb path string into ordered refs.
+ *
+ * @param path - Comma-separated refs
+ */
+export function parsePath(path: string | undefined): string[] {
+  if (!path) return [];
+  return path
+    .split(",")
+    .map((p) => p.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Join breadcrumb refs for the URL.
+ *
+ * @param refs - Ordered hop refs
+ */
+export function joinPath(refs: readonly string[]): string | undefined {
+  if (refs.length === 0) return undefined;
+  return refs.join(",");
+}
+
+/**
+ * Build the next search state when the operator selects a cause.
+ *
+ * @param prev - Current search
+ * @param causeId - Cause id
+ */
+export function selectCause(prev: FlowsSearch, causeId: string): FlowsSearch {
+  return {
+    ...prev,
+    sel: "cause",
+    cause: causeId,
+    flow: undefined,
+    effect: undefined,
+  };
+}
+
+/**
+ * Build the next search state when the operator selects a flow.
+ *
+ * @param prev - Current search
+ * @param flowId - Flow id
+ */
+export function selectFlow(prev: FlowsSearch, flowId: string): FlowsSearch {
+  return {
+    ...prev,
+    sel: "flow",
+    flow: flowId,
+    cause: undefined,
+    effect: undefined,
+  };
+}
+
+/**
+ * Build the next search state when the operator selects an effect
+ * (re-centres the graph one hop; appends to breadcrumb path).
+ *
+ * @param prev - Current search
+ * @param effectRef - Effect resource ref
+ */
+export function selectEffect(prev: FlowsSearch, effectRef: string): FlowsSearch {
+  const path = parsePath(prev.path);
+  const last = path[path.length - 1];
+  const nextPath =
+    last === effectRef ? path : [...path, effectRef].slice(-12);
+  return {
+    ...prev,
+    sel: "effect",
+    effect: effectRef,
+    flow: undefined,
+    cause: undefined,
+    path: joinPath(nextPath),
+  };
+}
+
+/**
+ * Open the drawer over a flow without leaving the panel route.
+ *
+ * @param prev - Current search
+ * @param flowId - Flow to open
+ * @param mode - Peek (default) or workbench
+ */
+export function openDrawer(
+  prev: FlowsSearch,
+  flowId: string,
+  mode: Exclude<DrawerMode, "closed"> = "peek",
+): FlowsSearch {
+  return {
+    ...prev,
+    open: flowId,
+    drawer: mode,
+    flow: flowId,
+    sel: "flow",
+  };
+}
+
+/**
+ * Close the drawer; URL stays on the Flows panel.
+ *
+ * @param prev - Current search
+ */
+export function closeDrawer(prev: FlowsSearch): FlowsSearch {
+  return {
+    ...prev,
+    drawer: "closed",
+    open: undefined,
+  };
+}

package/src/console/ui/flows/tiers.ts

@@ -0,0 +1,140 @@
+/**
+ * Effect-tier presentation for the Flows causality view (console §9.1).
+ *
+ * Effect tier is the only accent colour. Colour alone is never enough —
+ * irreversible effects also carry an outward arrow.
+ */
+
+import type { Effects } from "../../../manifest/types.ts";
+import {
+  reversibilityOf,
+  type EffectKind,
+  type ReversibilityTier,
+} from "../../../kernel/effects.ts";
+
+/** UI column tiers, ranked by reversibility (console §9.1 right column). */
+export type UiEffectTier =
+  | "reads"
+  | "writes"
+  | "emits"
+  | "external"
+  | "capabilities";
+
+/** One resource/effect row in the right column. */
+export interface TieredEffect {
+  /** Display tier. */
+  readonly tier: UiEffectTier;
+  /** Kernel effect kind. */
+  readonly kind: EffectKind;
+  /** Resource / signal / template / prompt / secret / flow ref. */
+  readonly ref: string;
+  /** Reversibility taxonomy. */
+  readonly reversibility: ReversibilityTier;
+  /** How many flows touch this resource (idle inventory). */
+  readonly touchCount: number;
+  /** Fan-out count for emits (consumers). */
+  readonly fanOut?: number;
+  /** True when this is a transitive (callee) effect. */
+  readonly transitive?: boolean;
+}
+
+/** CSS variable used for the irreversible accent — the panel's only accent. */
+export const EXTERNAL_ACCENT_VAR = "var(--oke-external)";
+
+/**
+ * Map a Manifest {@link Effects} block into ranked tier rows.
+ *
+ * @param effects - Flow effects (or undefined)
+ * @param options - Touch counts and emit fan-out
+ */
+export function tierEffects(
+  effects: Effects | undefined,
+  options: {
+    readonly touchCounts?: ReadonlyMap<string, number>;
+    readonly emitFanOut?: ReadonlyMap<string, number>;
+    readonly transitive?: boolean;
+  } = {},
+): TieredEffect[] {
+  if (!effects) return [];
+  const touch = options.touchCounts;
+  const fan = options.emitFanOut;
+  const rows: TieredEffect[] = [];
+
+  const push = (
+    tier: UiEffectTier,
+    kind: EffectKind,
+    refs: readonly string[] | undefined,
+  ): void => {
+    for (const ref of refs ?? []) {
+      rows.push({
+        tier,
+        kind,
+        ref,
+        reversibility: reversibilityOf(kind),
+        touchCount: touch?.get(ref) ?? 1,
+        fanOut: kind === "emit" ? (fan?.get(ref) ?? 0) : undefined,
+        transitive: options.transitive,
+      });
+    }
+  };
+
+  push("reads", "read", effects.reads);
+  push("writes", "write", effects.writes);
+  push("emits", "emit", effects.emits);
+  push("external", "send", effects.sends);
+  push("external", "ask", effects.asks);
+  push("capabilities", "secret", effects.secrets);
+
+  return rows;
+}
+
+/**
+ * Highest (most severe) effect tier on a flow — drives centre-column flags
+ * and invoke confirmation.
+ *
+ * @param effects - Flow effects
+ */
+export function peakEffectTier(
+  effects: Effects | undefined,
+): UiEffectTier | "none" {
+  if (!effects) return "none";
+  if ((effects.sends?.length ?? 0) > 0 || (effects.asks?.length ?? 0) > 0) {
+    return "external";
+  }
+  if ((effects.secrets?.length ?? 0) > 0) return "capabilities";
+  if ((effects.emits?.length ?? 0) > 0) return "emits";
+  if ((effects.writes?.length ?? 0) > 0) return "writes";
+  if ((effects.reads?.length ?? 0) > 0) return "reads";
+  return "none";
+}
+
+/**
+ * Whether a flow has any irreversible (external) effect.
+ *
+ * @param effects - Flow effects
+ */
+export function hasExternalEffect(effects: Effects | undefined): boolean {
+  return peakEffectTierHasExternal(peakEffectTier(effects));
+}
+
+function peakEffectTierHasExternal(tier: UiEffectTier | "none"): boolean {
+  return tier === "external";
+}
+
+/** Display order for right-column sections. */
+export const TIER_ORDER: readonly UiEffectTier[] = [
+  "reads",
+  "writes",
+  "emits",
+  "external",
+  "capabilities",
+] as const;
+
+/** Human labels for tiers. */
+export const TIER_LABEL: Readonly<Record<UiEffectTier, string>> = {
+  reads: "Reads",
+  writes: "Writes",
+  emits: "Emits",
+  external: "External",
+  capabilities: "Capabilities",
+};

package/src/console/ui/gates/GatesA11yView.tsx

@@ -0,0 +1,192 @@
+/**
+ * Static Gates markup for the axe gate — same landmarks as the live panel.
+ */
+
+import { auditLines, formatViolation } from "./audit.ts";
+import { formatDenial, formatEvaluationStep } from "./denial.ts";
+import {
+  GATES_LIST_FIXTURE,
+  SIMULATE_RATE_FIXTURE,
+} from "./fixture.ts";
+import { groupFlows, groupPrincipals } from "./group.ts";
+
+/** Props for {@link GatesA11yView}. */
+export interface GatesA11yViewProps {
+  /** Inquiry direction. */
+  readonly from?: "principal" | "flow";
+  /** Open principal encoded id. */
+  readonly openPrincipal?: string;
+  /** Open flow id. */
+  readonly openFlow?: string;
+}
+
+/**
+ * Accessible Gates list + simulator for CI.
+ *
+ * @param props - Open selection
+ */
+export function GatesA11yView(props: GatesA11yViewProps) {
+  const from = props.from ?? "flow";
+  const groups =
+    from === "principal"
+      ? groupPrincipals(GATES_LIST_FIXTURE.principals)
+      : groupFlows(GATES_LIST_FIXTURE.flows);
+  const openFlowId = props.openFlow ?? "bookings.create";
+  const openFlow = GATES_LIST_FIXTURE.flows.find(
+    (f) => f.flowId === openFlowId,
+  );
+  const openPrincipalId = props.openPrincipal ?? "role:role_member";
+  const openPrincipal = GATES_LIST_FIXTURE.principals.find(
+    (p) => `${p.kind}:${p.id}` === openPrincipalId,
+  );
+  const lines = auditLines(GATES_LIST_FIXTURE.audit);
+  const sim = SIMULATE_RATE_FIXTURE;
+
+  return (
+    <div className="gates-a11y">
+      <a href="#gates-main">Skip to main content</a>
+      <header>
+        <h1>Gates</h1>
+        <p>Two inquiries — principal or flow — simulator at the centre</p>
+        <div role="group" aria-label="Inquiry direction">
+          <button type="button" aria-pressed={from === "principal"}>
+            From principal
+          </button>
+          <button type="button" aria-pressed={from === "flow"}>
+            From flow
+          </button>
+        </div>
+        <label>
+          Filter gates
+          <input aria-label="Filter gates" defaultValue="" />
+        </label>
+      </header>
+
+      {lines.length > 0 ? (
+        <section aria-label="Continuous security audit" role="status">
+          <h2>Standing audit</h2>
+          <ul>
+            {lines.map((line) => (
+              <li key={line.code}>{line.message}</li>
+            ))}
+          </ul>
+        </section>
+      ) : null}
+
+      {GATES_LIST_FIXTURE.violations.length > 0 ? (
+        <section aria-label="Plane violations" role="alert">
+          <h2>Two-plane violations</h2>
+          <ul>
+            {GATES_LIST_FIXTURE.violations.map((v) => (
+              <li key={v.operatorId}>{formatViolation(v)}</li>
+            ))}
+          </ul>
+        </section>
+      ) : null}
+
+      <main id="gates-main">
+        <section aria-label={from === "principal" ? "Principal list" : "Flow list"}>
+          <h2>{from === "principal" ? "Principals" : "Flows"}</h2>
+          {groups.map((group) => (
+            <section key={group.id} aria-label={group.label}>
+              <h3>{group.label}</h3>
+              <ul>
+                {group.items.map((item) => (
+                  <li key={item.id}>
+                    <button
+                      type="button"
+                      aria-pressed={
+                        from === "flow"
+                          ? item.id === openFlowId
+                          : item.id === openPrincipalId
+                      }
+                      style={{ minHeight: 32, width: "100%" }}
+                    >
+                      <span>{item.label}</span>
+                      {item.meta ? <span> {item.meta}</span> : null}
+                      {item.flag ? (
+                        <span role="status"> {item.flag}</span>
+                      ) : null}
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            </section>
+          ))}
+        </section>
+
+        <section aria-label="Gates detail" aria-live="polite">
+          {from === "flow" && openFlow ? (
+            <>
+              <h2>{openFlow.flowId}</h2>
+              <p>Gate chain in registration order</p>
+              <ol aria-label="Gate chain">
+                {openFlow.gates.map((g) => (
+                  <li key={g}>
+                    <code>{g}</code>
+                  </li>
+                ))}
+              </ol>
+              {openFlow.unguarded ? (
+                <p role="status">Unguarded — public on the user plane</p>
+              ) : null}
+            </>
+          ) : null}
+
+          {from === "principal" && openPrincipal ? (
+            <>
+              <h2>{openPrincipal.name}</h2>
+              <p>
+                {openPrincipal.kind} · {openPrincipal.plane} plane
+              </p>
+              <h3>Scopes</h3>
+              <ul aria-label="Scopes">
+                {openPrincipal.scopes.map((s) => (
+                  <li key={s}>
+                    <code>{s}</code>
+                  </li>
+                ))}
+              </ul>
+            </>
+          ) : null}
+
+          <section aria-label="Simulator">
+            <h3>Simulator</h3>
+            <p>Evaluates the gate chain only — never runs the handler</p>
+            <label>
+              Companion selection
+              <select aria-label="Companion selection" defaultValue="user_demo">
+                <option value="user_demo">Demo User</option>
+                <option value="role_member">member role</option>
+              </select>
+            </label>
+            <button type="button">Simulate</button>
+            <ol aria-label="Evaluation order">
+              {sim.evaluations.map((e, i) => (
+                <li key={e.name}>{formatEvaluationStep(e, i)}</li>
+              ))}
+            </ol>
+            {sim.denial ? (
+              <p role="status" data-denial={sim.denial.code}>
+                {formatDenial(sim.denial)}
+              </p>
+            ) : (
+              <p role="status">Allowed</p>
+            )}
+          </section>
+
+          {GATES_LIST_FIXTURE.widenings.length > 0 ? (
+            <section aria-label="Permission widenings">
+              <h3>Deploy widenings</h3>
+              <ul>
+                {GATES_LIST_FIXTURE.widenings.map((w) => (
+                  <li key={w.path}>{w.summary}</li>
+                ))}
+              </ul>
+            </section>
+          ) : null}
+        </section>
+      </main>
+    </div>
+  );
+}