@ekanos/harness 0.1.0

package/dist/internal/lib/harness-live-fetch.d.ts

@@ -0,0 +1,66 @@
+import type { IntegrationFetch } from '@ekanos/sdk';
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ *  THE HARNESS'S `ctx.fetch`
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * The harness mocks Fusion. It does NOT mock your vendor's API — and in live
+ * mode it stops standing between you and it. What it does instead is enforce
+ * the one rule that matters: an integration may only reach the origins it
+ * DECLARED in `defineIntegration({ egress })`.
+ *
+ * The check is not a harness-local imitation. `isEgressAllowed` is imported
+ * from `@ekanos/sdk/context` — the same pure matcher used by
+ * `createMockContext()` in your unit tests and by the production `ctx.fetch`
+ * wrapper. Three enforcement points, one implementation, so a call that works
+ * here works after promotion, and a call that is denied here would have been
+ * denied in production too.
+ *
+ * That is the entire point of live mode: **it proves the egress declaration is
+ * correct before the integration is ever submitted.** An origin you forgot to
+ * declare fails on your laptop, with the same `EgressDeniedError` and the same
+ * remediation message, rather than in a reviewer's queue or a customer's tenant.
+ */
+export interface HarnessFetchCall {
+    url: string;
+    method: string;
+    denied: boolean;
+    at: string;
+}
+export interface AllowlistedFetchOptions {
+    /**
+     * Notified for every call, allowed or denied — the harness console logger
+     * hangs off this. Never throws into the caller.
+     */
+    onCall?: (call: HarnessFetchCall) => void;
+}
+/**
+ * Builds an `IntegrationFetch` bound to one integration's declared egress list.
+ *
+ * Denial is SYNCHRONOUS, before any I/O, and throws `EgressDeniedError` rather
+ * than resolving a synthetic 403 — matching the production wrapper exactly. A
+ * fake response would get retried, parsed, and blamed on the remote API.
+ */
+export declare function createAllowlistedFetch(egress: readonly string[], options?: AllowlistedFetchOptions): IntegrationFetch;
+/**
+ * The default observer: one console line per live request, prefixed so it is
+ * obvious in a busy devtools console which calls left the building.
+ *
+ * `call.url` arrives already redacted — see `redactUrl`.
+ */
+export declare function logHarnessFetch(slug: string): (call: HarnessFetchCall) => void;
+/**
+ * The fetch fixtures mode installs — it refuses everything.
+ *
+ * The third of the three mechanisms closing fixtures mode, and the only one
+ * that survives a widget doing something the harness did not anticipate. The
+ * partner's own fetch context defaults to the browser's real `fetch`, so a
+ * widget whose `queryFn` runs would reach the internet through that default.
+ * That is not hypothetical: it is exactly how the `error` fixture variant came
+ * to fire four live requests at api.github.com, because the query-client guard
+ * that was supposed to prevent the `queryFn` running had never worked.
+ *
+ * Throws synchronously, like the live guard, so nothing reaches the microtask
+ * queue first.
+ */
+export declare function createFixturesFetch(): IntegrationFetch;

package/dist/internal/lib/harness-live-fetch.js

@@ -0,0 +1,121 @@
+import { EgressDeniedError, isEgressAllowed } from "@ekanos/sdk/context";
+const BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set(["localhost"]);
+function isNonPublicIpv4(hostname) {
+  const octets = hostname.split(".");
+  if (octets.length !== 4) return false;
+  const parts = octets.map((octet) => Number(octet));
+  if (parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+    return false;
+  }
+  const [a, b] = parts;
+  return a === 0 || // "this network"
+  a === 127 || // loopback
+  a === 10 || // RFC1918
+  a === 172 && b >= 16 && b <= 31 || // RFC1918
+  a === 192 && b === 168 || // RFC1918
+  a === 169 && b === 254 || // link-local, incl. cloud metadata
+  a === 100 && b >= 64 && b <= 127 || // CGNAT
+  a >= 224;
+}
+function isNonPublicIpv6(hostname) {
+  const address = hostname.slice(1, -1).toLowerCase();
+  const mapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(address);
+  if (mapped) {
+    const high = Number.parseInt(mapped[1], 16);
+    const low = Number.parseInt(mapped[2], 16);
+    return isNonPublicIpv4(
+      [high >> 8, high & 255, low >> 8, low & 255].join(".")
+    );
+  }
+  return address === "::1" || // loopback
+  address === "::" || // unspecified
+  /^fe[89ab]/.test(address) || // fe80::/10 link-local
+  /^f[cd]/.test(address) || // fc00::/7 unique local
+  /^ff/.test(address);
+}
+function assertPublicDestination(url) {
+  const hostname = url.hostname.toLowerCase();
+  const nonPublic = BLOCKED_HOSTNAMES.has(hostname) || hostname.endsWith(".localhost") || (hostname.startsWith("[") ? isNonPublicIpv6(hostname) : isNonPublicIpv4(hostname));
+  if (nonPublic) {
+    throw new EgressDeniedError(url.origin);
+  }
+}
+function redactUrl(url) {
+  const redacted = new URL(url.toString());
+  redacted.username = "";
+  redacted.password = "";
+  const hadQuery = redacted.search !== "";
+  redacted.search = "";
+  return `${redacted.toString()}${hadQuery ? "?\u2026" : ""}`;
+}
+function createAllowlistedFetch(egress, options = {}) {
+  const record = (url, method, denied) => {
+    try {
+      options.onCall?.({
+        url,
+        method,
+        denied,
+        at: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    } catch {
+    }
+  };
+  return (input, init) => {
+    const parsed = new URL(input);
+    const url = parsed.toString();
+    const method = init?.method ?? "GET";
+    const allowed = isEgressAllowed(url, egress);
+    record(redactUrl(parsed), method, !allowed);
+    if (!allowed) {
+      throw new EgressDeniedError(parsed.origin);
+    }
+    assertPublicDestination(parsed);
+    return globalThis.fetch(url, {
+      ...init,
+      /**
+       * The allowlist is a promise about ONE url. Following a redirect would
+       * silently turn it into a promise about wherever that url points next —
+       * an attacker origin, a LAN service, link-local metadata — and a 307/308
+       * carries the method and body along for the ride.
+       *
+       * Production re-vets every hop and rejects cross-origin redirects
+       * outright. A browser cannot do that: `redirect: 'manual'` yields an
+       * opaque response whose `Location` header is unreadable, so there is no
+       * way to check the next hop and continue. `'error'` is therefore the
+       * only sound choice here — the request fails loudly instead of following
+       * an unchecked redirect.
+       *
+       * A partner whose API legitimately redirects should call the final URL
+       * directly, which is the same advice production's hop-limit error gives.
+       */
+      redirect: "error"
+    });
+  };
+}
+function logHarnessFetch(slug) {
+  return (call) => {
+    if (call.denied) {
+      console.error(
+        `[harness:live:${slug}] DENIED ${call.method} ${call.url} \u2014 origin not in the integration's declared egress list.`
+      );
+      return;
+    }
+    console.info(`[harness:live:${slug}] ${call.method} ${call.url}`);
+  };
+}
+function createFixturesFetch() {
+  return (input) => {
+    throw new Error(
+      `[harness] fixtures mode refused a request to ${redactUrl(new URL(input))}.
+
+A widget called the network directly instead of reading a seeded query. Fixtures mode answers every query from your registry entry and never leaves the machine, so this call was refused.
+
+Seed the query key this widget uses, or switch the toolbar to Live API if the integration declares an \`egress\` list.`
+    );
+  };
+}
+export {
+  createAllowlistedFetch,
+  createFixturesFetch,
+  logHarnessFetch
+};

package/dist/internal/lib/harness-query-client.d.ts

@@ -0,0 +1,43 @@
+import { QueryClient } from '@tanstack/react-query';
+import type { DataMode, FixtureSeed } from '../../registry.js';
+/**
+ * Thrown when a widget fires a query the harness has no fixture for.
+ *
+ * This is the harness's single most important error message: it is what a
+ * partner sees the first time they wire up a widget, and it has to tell them
+ * exactly what to paste into their registry entry.
+ */
+export declare class MissingFixtureError extends Error {
+    readonly queryKey: readonly unknown[];
+    constructor(queryKey: readonly unknown[]);
+}
+/**
+ * Build a QueryClient for one mode.
+ *
+ * FIXTURES mode is closed by two independent mechanisms, and it needs both:
+ *
+ *  1. Every declared key is programmed into the cache up front — `data` seeds
+ *     as data, `error` seeds as an error state — so widgets paint populated (or
+ *     paint their error branch) on the very first render with no loading flash
+ *     and no fetch.
+ *  2. `defaultQueryOptions` puts the seed table AHEAD of whatever the widget
+ *     supplied, so a seeded key never fetches. An unseeded key now falls
+ *     through to the widget's own fetcher rather than throwing — safe because
+ *     `globalThis.fetch` is patched, and necessary because otherwise a
+ *     recorded HTTP response could never be reached by a react-query widget.
+ *
+ * The layout closes it a third time, outside this file, by handing fixtures
+ * mode a fetch seam that throws (`harness-providers.tsx`). Belt, braces, and a
+ * second pair of braces, because "the harness makes no network requests" is a
+ * promise a partner relies on when they point it at a production API key.
+ *
+ * LIVE mode installs no override at all, so react-query falls through to each
+ * widget's own `queryFn` — the real one, reaching the real vendor API through
+ * the allowlisted fetch. Fusion-side keys are still pre-seeded, so a widget
+ * that needs an account setting before it can call anything still gets one.
+ *
+ * `retry: false` matters as much as the rest: the default three retries with
+ * backoff would turn one missing fixture into several seconds of confusing
+ * pending state before the error surfaced.
+ */
+export declare function createHarnessQueryClient(seeds: FixtureSeed[], mode?: DataMode): QueryClient;

package/dist/internal/lib/harness-query-client.js

@@ -0,0 +1,103 @@
+import { QueryClient, hashKey } from "@tanstack/react-query";
+class MissingFixtureError extends Error {
+  constructor(queryKey) {
+    const serialized = JSON.stringify(queryKey);
+    super(
+      [
+        `No fixture seeded for query key ${serialized}.`,
+        "",
+        "This query has no seed AND no `queryFn` of its own, so nothing can",
+        "answer it \u2014 not even an HTTP fixture, because no request is made.",
+        "Seed the key on the widget in your harness registry entry:",
+        "",
+        "  seeds: {",
+        `    default: [{ queryKey: ${serialized}, data: /* your fixture */ }],`,
+        "  }",
+        "",
+        "To exercise the error branch instead, seed `error` rather than `data`.",
+        "If this key looks unfamiliar, log it from the widget's own hook \u2014 the",
+        "key must match exactly, including every argument the hook interpolates."
+      ].join("\n")
+    );
+    this.queryKey = queryKey;
+    this.name = "MissingFixtureError";
+  }
+}
+function isErrorSeed(seed) {
+  return "error" in seed && seed.error !== void 0;
+}
+function forceFixturesQueryFn(client, seedsByKey) {
+  const base = client.defaultQueryOptions.bind(client);
+  client.defaultQueryOptions = ((options) => {
+    const merged = base(options);
+    const own = merged.queryFn;
+    return {
+      ...merged,
+      queryFn: (context) => {
+        const seed = seedsByKey.get(hashKey(context.queryKey));
+        if (seed) {
+          if (isErrorSeed(seed)) throw seed.error;
+          return seed.data;
+        }
+        if (typeof own === "function") {
+          return own(context);
+        }
+        throw new MissingFixtureError(context.queryKey);
+      }
+    };
+  });
+}
+function createHarnessQueryClient(seeds, mode = "fixtures") {
+  const seedsByKey = /* @__PURE__ */ new Map();
+  for (const seed of seeds) {
+    seedsByKey.set(hashKey(seed.queryKey), seed);
+  }
+  const live = mode === "live";
+  const defaultOptions = {
+    queries: {
+      retry: false,
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: false,
+      // Fixtures never go stale — nothing can refresh them. In live mode the
+      // widget's own `staleTime` is the one that should apply, so the default
+      // gets out of the way.
+      ...live ? {} : {
+        staleTime: Infinity,
+        gcTime: Infinity,
+        // An error state has no `dataUpdatedAt`, so `staleTime` cannot
+        // hold it and react-query would refetch it on mount. Harmless now
+        // that the queryFn is forced, but it would turn every seeded error
+        // into a pointless extra round through the seed table.
+        refetchOnMount: false
+      }
+    },
+    mutations: {
+      retry: false
+    }
+  };
+  const client = new QueryClient({ defaultOptions });
+  if (!live) {
+    forceFixturesQueryFn(client, seedsByKey);
+  }
+  for (const seed of seeds) {
+    if (isErrorSeed(seed)) {
+      if (!live) {
+        const query = client.getQueryCache().build(client, { queryKey: seed.queryKey });
+        query.setState({
+          status: "error",
+          error: seed.error,
+          errorUpdateCount: 1,
+          errorUpdatedAt: Date.now(),
+          fetchStatus: "idle"
+        });
+      }
+      continue;
+    }
+    client.setQueryData(seed.queryKey, seed.data);
+  }
+  return client;
+}
+export {
+  MissingFixtureError,
+  createHarnessQueryClient
+};

package/dist/internal/lib/http-fixtures.d.ts

@@ -0,0 +1,145 @@
+import type { MockFetchHandler } from '@ekanos/sdk/testing';
+import type { HttpFixture } from '../../registry.js';
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ *  MATCHING A REQUEST TO A RECORDED RESPONSE
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * Pure, and deliberately so: `(request, fixtures) -> fixture | null` with no
+ * React, no network and no clock. That keeps it exhaustively testable, and it
+ * is the seam record/replay will need later — a captured exchange has to be the
+ * same object a hand-written one is, so nothing here may depend on how the
+ * fixture was produced.
+ *
+ * The rules, all of which exist because a real API forced them:
+ *
+ *  ORIGIN     `'GET https://api.acme.com/v1/payouts'` is unambiguous. The
+ *             path-only `'GET /v1/payouts'` resolves against the integration's
+ *             declared `egress` — reusing the declaration instead of adding a
+ *             second `baseUrl` to keep in step — and is allowed ONLY when
+ *             exactly one origin is declared. With two, there is no defensible
+ *             guess, so it throws and names them.
+ *
+ *             EXCEPT under `/api/`, which resolves against the harness's OWN
+ *             origin. That is the host-route namespace: a first-party
+ *             integration's widgets call `/api/integrations/<slug>/…` rather
+ *             than the vendor directly, and the vendor call happens server-side
+ *             where the credential lives. Our own Acme example is shaped that
+ *             way, so without this the format could not express the request the
+ *             most realistic widget in the repo actually makes.
+ *
+ *  PATH       `:param` matches one segment, `*` matches the rest. Segment
+ *             counts must otherwise agree, so `/v1/payouts` does not match
+ *             `/v1/payouts/42`.
+ *
+ *  QUERY      If the fixture's request has a `?`, every param in it must be
+ *             present on the request with the same value — a SUBSET match, so
+ *             a fixture can pin the two params that matter and ignore the
+ *             other nine. If it has no `?`, query is ignored entirely.
+ *             Open-Meteo settles this: its whole request is query params, and
+ *             requiring an exact match would mean restating a 200-character
+ *             string that changes whenever a widget adds a field.
+ *
+ * First declaration wins, so a specific fixture can shadow a general one by
+ * being written above it.
+ */
+/** A fixture with its request line parsed once, ready to match against. */
+export interface CompiledFixture {
+    method: string;
+    origin: string;
+    segments: readonly string[];
+    /** Params that must be present with these values, or null to ignore query. */
+    query: readonly (readonly [string, string])[] | null;
+    fixture: HttpFixture;
+}
+export declare class FixtureRequestError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse one `'<METHOD> <url-or-path>'` request line.
+ *
+ * Throws rather than skipping: a fixture the harness cannot understand is a
+ * fixture the partner believes is live, and silently ignoring it produces the
+ * "no recorded response" error for a request they can see they recorded.
+ */
+export declare function compileFixture(fixture: HttpFixture, egress: readonly string[], selfOrigin?: string): CompiledFixture;
+/**
+ * Does compiling this fixture require the harness's OWN origin?
+ *
+ * Only the host-route shape does. An absolute request line carries its origin;
+ * a path-only one resolves against the declared `egress`. `/api/…` is the one
+ * branch above that has nothing to resolve against but `selfOrigin`.
+ *
+ * This exists so a caller with no origin — a server render — can compile the
+ * fixtures that do not need one instead of compiling nothing. Duplicating the
+ * request-line parse at that call site is how the two would drift, which is
+ * the failure this whole module is written to avoid, so the question is
+ * answered here next to the code that answers it for real.
+ *
+ * A malformed request line is reported as NOT needing an origin, deliberately:
+ * `compileFixture` already has a precise error for every way a line can be
+ * wrong, and filtering it out early would replace that error with silence.
+ */
+export declare function needsSelfOrigin(fixture: HttpFixture): boolean;
+export declare function compileFixtures(fixtures: readonly HttpFixture[], egress: readonly string[], selfOrigin?: string): CompiledFixture[];
+/**
+ * The first fixture that matches, or null.
+ *
+ * Null is not an error here — the caller decides what an unmatched request
+ * means, because it differs by mode: refuse in fixtures, go to the network in
+ * live.
+ */
+export declare function matchHttpFixture(method: string, requestUrl: string, compiled: readonly CompiledFixture[]): HttpFixture | null;
+/**
+ * Build the `Response` a matched fixture stands for.
+ *
+ * `status` defaults to 200 when a body is present and 204 when it is not, so
+ * `{ request: 'DELETE /v1/thing/:id' }` is a complete fixture. A string body is
+ * sent as-is; anything else is JSON, which is what makes `{ response: {...} }`
+ * the common case rather than a special one.
+ */
+export declare function fixtureResponse(fixture: HttpFixture): Response;
+export declare class NoRecordedResponseError extends Error {
+    readonly method: string;
+    readonly url: string;
+    /**
+     * Set when this refusal is a host-route request during a server render —
+     * the one shape not compiled for that pass.
+     */
+    readonly deferredToClientRender: boolean;
+    constructor(method: string, url: string, 
+    /**
+     * Set when this refusal is a host-route request during a server render —
+     * the one shape not compiled for that pass.
+     */
+    deferredToClientRender?: boolean);
+}
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ *  THE SAME FIXTURES, ANSWERING THE TRIGGERS SURFACE
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * This is the half that kills the double-authoring. A partner used to write
+ * their vendor's payloads twice — once as query-key seeds for widgets, once as
+ * wire-shaped `fetchHandlers` for webhook and schedule handlers — in two
+ * different shapes, with nothing relating them. Our own Acme example
+ * demonstrates it. Now both seams read one list.
+ *
+ * Returned as a single CATCH-ALL handler rather than one per fixture, and that
+ * matters twice over:
+ *
+ *  - matching stays in `matchHttpFixture`, so a request resolves identically
+ *    whether a widget or a schedule made it. Two matchers would drift, and the
+ *    drift would be invisible until a handler and a widget disagreed about the
+ *    same URL.
+ *  - `createMockContext()`'s own fallback, when no handler matches, is
+ *    `new Response('{}', { status: 200 })` — a plausible empty success. That is
+ *    the trigger-side twin of the silent fixture miss: a handler calling an
+ *    endpoint nobody recorded gets a 200 and carries on. Taking every request
+ *    replaces it with the same named refusal a widget gets.
+ *
+ * Explicit `triggerMocks.fetchHandlers` still win, because they are placed
+ * ahead of this one — a partner needing a dynamic or stateful response should
+ * not have to abandon fixtures for the rest.
+ */
+export declare function fixturesToMockHandlers(compiled: readonly CompiledFixture[]): MockFetchHandler[];