okengine 0.10.2 → 0.11.0

package/site/content/docs/console/privacy.mdx

@@ -1,32 +0,0 @@
----
-title: "Privacy"
-description: "Where PII lives, who touches it, export/erase (conditional)."
-icon: "EyeOff"
-source: "docs/spec/console.md"
----
-
-Answers: **where PII lives, who touches it, export/erase**
-
-<Callout title="Governing rule">
-  Conditional panel — appears when the privacy plugin is plugged. Catalog row is the durable
-  reference.
-</Callout>
-
-## What this panel shows
-
-<Cards>
-  <Card title="PII map" description="Where personal data lives and who touches it." />
-  <Card title="Export / erase" description="`oke privacy export|erase --subject` across stores." />
-</Cards>
-
-## Catalog
-
-<Cards>
-  <Card title="Dev" description="✓" />
-  <Card title="Prod" description="✓" />
-</Cards>
-
-<Callout title="Conditional">
-  This panel appears when the optional core plugin is plugged. There is no separate detailed
-  subsection beyond the catalog row.
-</Callout>

package/site/content/docs/console/runs.mdx

@@ -1,50 +0,0 @@
----
-title: "Runs"
-description: "Wide events — one record per flow execution."
-icon: "Play"
-source: "docs/spec/console.md"
----
-
-Answers: **wide events — one record per flow execution, queried by dimension**
-
-<Callout title="Governing rule">
-  One flow execution = one wide event = one span. Analysis by dimension, not a text search box.
-</Callout>
-
-## What this panel shows
-
-<Cards>
-  <Card
-    title="Wide events"
-    description="Dimensions from effects — no manual instrumentation tax."
-  />
-  <Card
-    title="Error patterns"
-    description="Failed runs in the lookback window, grouped by error code."
-  />
-  <Card
-    title="Outlier explanation"
-    description="Compare all dimensions between slow and baseline populations."
-  />
-  <Card
-    title="Storage tiers"
-    description="Default Parquet + DuckDB; optional postgres / clickhouse."
-  />
-  <Card
-    title="Lifecycle"
-    description="Retain by default; redaction and crypto-shredding for compliance."
-  />
-</Cards>
-
-Use **Since** (`5m` · `1h` · `24h` · all time) to bound the population. Error patterns count
-`error_code` occurrences in that window — the same store Traces and Overview read.
-
-Local replay: `oke replay --request-id <runId>` re-invokes from the stored input snapshot
-(dry-run when the ledger has `send` / `ask`).
-
-## Catalog
-
-<Cards>
-  <Card title="Dev" description="✓" />
-  <Card title="Prod" description="✓" />
-</Cards>

package/site/content/docs/console/signals.mdx

@@ -1,40 +0,0 @@
----
-title: "Signals"
-description: "Queue depth, in-flight, DLQ, live monitors, orphaned config."
-icon: "Radio"
-source: "docs/spec/console.md"
----
-
-Answers: **queue depth, in-flight, DLQ, live monitors, orphaned config**
-
-<Callout title="Governing rule">
-  One list grouped by delivery physics — not three tabs that re-split the element.
-</Callout>
-
-## What this panel shows
-
-<Cards>
-  <Card title="once" description="Pending, in-flight (leased), DLQ, retry policy." />
-  <Card title="broadcast" description="Per-subscriber lag and targeted replay." />
-  <Card
-    title="live"
-    description="Connection count, throughput, newest-50 payload monitor (full history still retained)."
-  />
-  <Card
-    title="DLQ repair"
-    description="Schema form, typed errors, causal chain, dry-run bulk replay."
-  />
-  <Card
-    title="Orphaned"
-    description="Config still listed after the declaration left code — messages kept; dry-run refused."
-  />
-</Cards>
-
-Dry-run is refused for orphaned signals and for signals with no Manifest consumer — unknown handler shapes are not invoked unsafely. Restore the `signal(…)` declaration (and a consumer) before replaying DLQ rows. Lease / at-least-once physics live on [Signal](/docs/elements/signal).
-
-## Catalog
-
-<Cards>
-  <Card title="Dev" description="full" />
-  <Card title="Prod" description="replay/purge per gates" />
-</Cards>

package/site/content/docs/console/store.mdx

@@ -1,32 +0,0 @@
----
-title: "Store"
-description: "Browse sql/kv/files/index; cache keys; replica lag."
-icon: "Database"
-source: "docs/spec/console.md"
----
-
-Answers: **browse sql/kv/files/index; cache keys; replica lag**
-
-<Callout title="Governing rule">
-  The most dangerous panel in production — gates, tenant isolation, PII masking, and audit on the
-  data path.
-</Callout>
-
-## What this panel shows
-
-<Cards>
-  <Card title="Four facets" description="sql · kv · files · index with adaptive detail." />
-  <Card title="PII masking" description="Follows schema classification, including raw SQL." />
-  <Card title="Cache keys" description="Which read produced a key; which write invalidates it." />
-  <Card
-    title="Direct edit warning"
-    description="Names what will not happen — not a silent row patch."
-  />
-</Cards>
-
-## Catalog
-
-<Cards>
-  <Card title="Dev" description="full + Studio link" />
-  <Card title="Prod" description="masked, gated, audited" />
-</Cards>

package/site/content/docs/console/tenancy.mdx

@@ -1,32 +0,0 @@
----
-title: "Tenancy"
-description: "Per-tenant usage, limits, isolation checks (conditional)."
-icon: "Building2"
-source: "docs/spec/console.md"
----
-
-Answers: **per-tenant usage, limits, isolation checks**
-
-<Callout title="Governing rule">
-  Conditional panel — appears when the tenancy plugin is plugged. Catalog row is the durable
-  reference.
-</Callout>
-
-## What this panel shows
-
-<Cards>
-  <Card title="Usage &amp; limits" description="Per-tenant usage and configured limits." />
-  <Card title="Isolation" description="Checks that tenant boundaries hold." />
-</Cards>
-
-## Catalog
-
-<Cards>
-  <Card title="Dev" description="✓" />
-  <Card title="Prod" description="✓" />
-</Cards>
-
-<Callout title="Conditional">
-  This panel appears when the optional core plugin is plugged. There is no separate detailed
-  subsection beyond the catalog row.
-</Callout>

package/site/content/docs/console/traces.mdx

@@ -1,38 +0,0 @@
----
-title: "Traces"
-description: "One timeline across http → store → signal → durable steps."
-icon: "Route"
-source: "docs/spec/console.md"
----
-
-Answers: **one timeline across http → store → signal → durable steps**
-
-<Callout title="Governing rule">
-  Folded time across async boundaries — a seven-day sleep is not 99.99% empty waterfall.
-</Callout>
-
-## What this panel shows
-
-<Cards>
-  <Card title="Causal chain" description="Join parent/child across emit boundaries." />
-  <Card title="Effect tiers" description="Spans coloured by the same vocabulary as Flows." />
-  <Card
-    title="Filter by effect"
-    description="Everything that wrote a table, sent mail, or cost more than X."
-  />
-  <Card
-    title="Why slow / why fail"
-    description="Critical path highlight; open on the failing span."
-  />
-</Cards>
-
-Chains use `WideEvent.parentId`: producers stamp it on `fx.emit` / `fx.call`;
-consumers record it on their run. Per-effect timing comes from the ledger
-(`timestamp` + `duration`) — not a second instrumentation API.
-
-## Catalog
-
-<Cards>
-  <Card title="Dev" description="✓" />
-  <Card title="Prod" description="✓" />
-</Cards>

package/site/content/docs/console/vault.mdx

@@ -1,41 +0,0 @@
----
-title: "Vault"
-description: "Secret contracts, who can read each, rotation due."
-icon: "KeyRound"
-source: "docs/spec/console.md"
----
-
-Answers: **secret contracts, who can read each, rotation due**
-
-<Callout title="Governing rule">
-  Secrets are write-only — the panel can set and rotate; it can never reveal.
-</Callout>
-
-## What this panel shows
-
-<Cards>
-  <Card
-    title="Contracts"
-    description="Optional description as the human title; technical key stays visible."
-  />
-  <Card
-    title="Fingerprints"
-    description="Salted hash per environment — rotation and drift without exposure."
-  />
-  <Card
-    title="Resolution chain"
-    description="Which source won: env, files, vault driver, or fallback."
-  />
-  <Card title="Who can read" description="Derived from effects that declare `fx.vault`." />
-  <Card
-    title="Rotation blast radius"
-    description="In-flight durable runs that wake with a new key."
-  />
-</Cards>
-
-## Catalog
-
-<Cards>
-  <Card title="Dev" description="full" />
-  <Card title="Prod" description="set/rotate only, never reveal" />
-</Cards>

package/site/content/docs/recipes/openbao.mdx

@@ -1,141 +0,0 @@
----
-title: "OpenBao"
-description: "Durable single-node vault — Raft under /openbao/file, OKE_VAULT_URL / OKE_VAULT_TOKEN, host unseal key SPOF."
-icon: "KeyRound"
-source: "docs/spec/unified-theory.md"
----
-
-OpenBao is the docker/prod Vault driver target — a real secrets service with Raft
-storage, **not** an in-memory `-dev` server. Templates pin
-`vault: "openbao/openbao:2.6.1"` and `drivers.vault.docker/prod: "openbao"`.
-
-<Callout title="The one rule">
-  Never run OpenBao `-dev` in docker/prod. Data belongs on the Raft volume; init + unseal stay on
-  the host under `.oke/openbao/`.
-</Callout>
-
-## Quick start
-
-<Steps>
-
-<Step>
-### Pin driver + image
-
-```typescript title="oke.config.ts"
-drivers: {
-  vault: { local: "env", docker: "openbao", test: "memory", prod: "openbao" },
-},
-images: {
-  vault: "openbao/openbao:2.6.1",
-},
-```
-
-</Step>
-
-<Step>
-### First boot is automatic
-
-`oke dev --docker` initializes OpenBao (Shamir 1-of-1), unseals it, writes a
-least-privilege policy for **declared** secrets only, and mints an app token. You do not
-run raw `bao` commands.
-
-</Step>
-
-<Step>
-### App sees only the least-privilege token
-
-```bash title="docker/.env.docker"
-OKE_VAULT_URL=http://127.0.0.1:8200
-OKE_VAULT_TOKEN=…        # app token — not the root token
-OKE_VAULT_MOUNT=secret   # KV v2 mount (default)
-```
-
-</Step>
-
-</Steps>
-
-## Required env
-
-| Variable           | Who holds it        | Meaning                                  |
-| ------------------ | ------------------- | ---------------------------------------- |
-| `OKE_VAULT_URL`    | App / stack         | OpenBao base URL                         |
-| `OKE_VAULT_TOKEN`  | App (`.env.docker`) | Least-privilege app token                |
-| `OKE_VAULT_MOUNT`  | Optional            | KV v2 mount path (default `"secret"`)    |
-| `BAO_LOCAL_CONFIG` | Container (recipe)  | Listener + Raft JSON — set by the recipe |
-
-Host-only material (mode `0600`, gitignored) — **not** in compose YAML:
-
-| File                      | Holds                                    |
-| ------------------------- | ---------------------------------------- |
-| `.oke/openbao/unseal.key` | Single unseal share                      |
-| `.oke/openbao/root.token` | Root token (CLI policy sync / mint only) |
-| `.oke/openbao/app.token`  | Same least-privilege token the app uses  |
-
-## Data and backup
-
-| Volume       | Path            | What it stores               |
-| ------------ | --------------- | ---------------------------- |
-| `vault-data` | `/openbao/file` | Raft storage (node id `oke`) |
-
-Recipe note: Raft path is `/openbao/file` (the stock entrypoint chowns that directory).
-Healthcheck hits `/v1/sys/init` — **200 even while sealed**; bootstrap owns unseal.
-
-**Backup means two things:**
-
-1. The Raft volume (`/openbao/file`) — encrypted secret store
-2. `.oke/openbao/unseal.key` on the host — without it the volume is unrecoverable
-
-## Production note
-
-<Callout title="Single point of failure — read this once" type="warn">
-  Back up `.oke/openbao/unseal.key` to a separate safe location. Losing it means losing every secret
-  permanently, with no recovery. Restated from [Vault ·
-  OpenBao](/docs/elements/vault#openbao-in-docker-and-prod).
-</Callout>
-
-Self-hosted single-node, Shamir 1-of-1, no cloud KMS — by design. If OpenBao is
-initialized but the key is gone, boot fails with an explicit permanent-loss error; it
-never silently starts empty.
-
-## What the recipe configures
-
-| Field          | Value                                                                                  |
-| -------------- | -------------------------------------------------------------------------------------- |
-| Container port | `8200`                                                                                 |
-| Command        | `server` (with `BAO_LOCAL_CONFIG`)                                                     |
-| TLS            | Disabled on the listener for compose (`tls_disable: true`) — rely on network isolation |
-| Healthcheck    | `wget` `/v1/sys/init`, every 5s, 12 retries                                            |
-
-## Troubleshooting
-
-<Accordions>
-<Accordion title="openbao vault: GET … failed (… ) — sealed or unauthorized?">
-
-`OpenBaoUnavailableError` — vault sealed, wrong token, or unreachable. Re-run
-`oke dev --docker` so bootstrap unseals with the host key. If the vault is initialized
-but `.oke/openbao/unseal.key` is missing, restore the key from backup.
-
-</Accordion>
-<Accordion title="Permanent-loss / initialized but key missing">
-
-Starting empty would look like “no secrets.” The CLI refuses that path. Restore
-`unseal.key` or treat the Raft volume as destroyed and re-init only if you accept wiping
-secrets.
-
-</Accordion>
-</Accordions>
-
-## Learn more
-
-- [Vault · OpenBao in docker and prod](/docs/elements/vault#openbao-in-docker-and-prod) —
-  full bootstrap, key table, SPOF callout
-- [Errors](/docs/reference/errors) — `OpenBaoUnavailableError`, `OpenBaoBootstrapError`
-- [CLI · oke vault](/docs/reference/cli) — `set` / `list` / `import`
-
-## Next
-
-<Cards>
-  <Card title="Vault" description="Resolution chain and rotation." href="/docs/elements/vault" />
-  <Card title="Mailpit" description="Local email catcher." href="/docs/recipes/mailpit" />
-  <Card title="RustFS" description="S3-compatible files." href="/docs/recipes/rustfs" />
-</Cards>

package/src/cli/ask-dev-mode.ts

@@ -1,40 +0,0 @@
-/**
- * One-time interactive `oke dev` mode choice via `@clack/prompts`.
- */
-
-import { isCancel, select } from "@clack/prompts";
-import type { DevMode } from "./dev-mode.ts";
-
-/**
- * Injectable ask step — production uses {@link askDevMode}.
- *
- * @returns Chosen mode, or `null` if the user cancelled
- */
-export type AskDevModeFn = () => Promise<DevMode | null>;
-
-/**
- * Prompt once: local vs docker.
- *
- * @returns Chosen mode, or `null` on cancel
- */
-export async function askDevMode(): Promise<DevMode | null> {
-  const value = await select({
-    message: "Run against",
-    options: [
-      {
-        value: "local",
-        label: "local",
-        hint: "sqlite file, instant, no Docker needed",
-      },
-      {
-        value: "docker",
-        label: "docker",
-        hint: "real Postgres/Redis via compose, closer to production",
-      },
-    ],
-    initialValue: "local",
-  });
-  if (isCancel(value)) return null;
-  if (value === "local" || value === "docker") return value;
-  return null;
-}

package/src/cli/dev-mode.test.ts

@@ -1,45 +0,0 @@
-/**
- * `.oke/mode` persistence and prompt gating.
- */
-
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdtemp, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { parseDevMode, readDevMode, shouldAskDevMode, writeDevMode } from "./dev-mode.ts";
-
-const dirs: string[] = [];
-
-afterEach(async () => {
-  await Promise.all(dirs.splice(0).map((d) => rm(d, { recursive: true, force: true })));
-});
-
-async function tempDir(): Promise<string> {
-  const dir = await mkdtemp(join(tmpdir(), "oke-mode-"));
-  dirs.push(dir);
-  return dir;
-}
-
-describe("dev-mode", () => {
-  test("parseDevMode accepts local|docker only", () => {
-    expect(parseDevMode("local")).toBe("local");
-    expect(parseDevMode(" docker \n")).toBe("docker");
-    expect(parseDevMode("stack")).toBeNull();
-    expect(parseDevMode(undefined)).toBeNull();
-  });
-
-  test("read/write round-trip", async () => {
-    const dir = await tempDir();
-    expect(await readDevMode(dir)).toBeNull();
-    await writeDevMode(dir, "docker");
-    expect(await readDevMode(dir)).toBe("docker");
-  });
-
-  test("shouldAskDevMode: TTY + unset → ask; non-TTY → never", () => {
-    expect(shouldAskDevMode({ saved: null, explicit: false, stdinIsTTY: true })).toBe(true);
-    expect(shouldAskDevMode({ saved: null, explicit: false, stdinIsTTY: false })).toBe(false);
-    expect(shouldAskDevMode({ saved: null, explicit: false, stdinIsTTY: undefined })).toBe(false);
-    expect(shouldAskDevMode({ saved: "local", explicit: false, stdinIsTTY: true })).toBe(false);
-    expect(shouldAskDevMode({ saved: null, explicit: true, stdinIsTTY: true })).toBe(false);
-  });
-});

package/src/cli/dev-mode.ts

@@ -1,78 +0,0 @@
-/**
- * Persisted `oke dev` run mode — `local` vs `docker`.
- */
-
-import { mkdir } from "node:fs/promises";
-import { join, resolve } from "node:path";
-
-/** Saved / selectable `oke dev` infrastructure mode. */
-export type DevMode = "local" | "docker";
-
-/** Relative path under the project root. */
-export const DEV_MODE_RELATIVE_PATH = ".oke/mode";
-
-/**
- * Absolute path to the mode preference file.
- *
- * @param cwd - Project root
- */
-export function devModePath(cwd: string): string {
-  return resolve(cwd, DEV_MODE_RELATIVE_PATH);
-}
-
-/**
- * Parse a raw mode string.
- *
- * @param raw - File contents or CLI arg
- */
-export function parseDevMode(raw: string | undefined | null): DevMode | null {
-  if (raw === undefined || raw === null) return null;
-  const value = raw.trim().toLowerCase();
-  if (value === "local" || value === "docker") return value;
-  return null;
-}
-
-/**
- * Read the saved mode from `.oke/mode`, or `null` when unset / invalid.
- *
- * @param cwd - Project root
- */
-export async function readDevMode(cwd: string): Promise<DevMode | null> {
-  const path = devModePath(cwd);
-  const file = Bun.file(path);
-  if (!(await file.exists())) return null;
-  try {
-    return parseDevMode(await file.text());
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Persist the preferred mode for future `oke dev` invocations.
- *
- * @param cwd - Project root
- * @param mode - Mode to save
- */
-export async function writeDevMode(cwd: string, mode: DevMode): Promise<void> {
-  const path = devModePath(cwd);
-  await mkdir(join(cwd, ".oke"), { recursive: true });
-  await Bun.write(path, `${mode}\n`);
-}
-
-/**
- * Whether `oke dev` should open the one-time mode prompt.
- *
- * Mirrors create-oke: never prompt when stdin is not a TTY.
- *
- * @param options - Preference + TTY + explicit flag
- */
-export function shouldAskDevMode(options: {
-  readonly saved: DevMode | null;
-  readonly explicit: boolean;
-  readonly stdinIsTTY: boolean | undefined;
-}): boolean {
-  if (options.explicit) return false;
-  if (options.saved !== null) return false;
-  return Boolean(options.stdinIsTTY);
-}