@ekanos/harness 0.1.0

package/dist/registry.d.ts

@@ -0,0 +1,418 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { ActivationFormProps, IntegrationComponentProps, IntegrationFetch, MarketplaceTileProps } from '@ekanos/sdk';
+import type { StorageSchemas } from '@ekanos/sdk';
+import type { IntegrationDefinition } from '@ekanos/sdk/integration';
+import type { MockFetchHandler } from '@ekanos/sdk/testing';
+/**
+ * The fixture variants the dev toolbar can switch between. Every widget should
+ * supply at least `default`; the others are optional and fall back to
+ * "nothing seeded", which surfaces as the widget's own error state.
+ */
+export declare const FIXTURE_VARIANTS: readonly ["default", "empty", "error"];
+export type FixtureVariant = (typeof FIXTURE_VARIANTS)[number];
+/**
+ * One programmed outcome for one react-query key.
+ *
+ * `data` seeds the cache so the widget renders populated on first paint with
+ * zero network traffic. `error` programs a rejection instead, so you can
+ * exercise a widget's error branch without unplugging anything.
+ *
+ * Exactly one of `data` / `error` should be set. If both are, `error` wins.
+ */
+export interface FixtureSeed {
+    queryKey: readonly unknown[];
+    data?: unknown;
+    error?: unknown;
+}
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ *  ONE RECORDED HTTP EXCHANGE — the default way to give the harness data
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * Fixtures describe what your VENDOR returns, not what your widget's cache
+ * holds. That one change is why this format exists:
+ *
+ *  - it is authored ONCE and feeds both seams. The same fixture answers a
+ *    widget's request and a webhook handler's `ctx.fetch`, where before the
+ *    same vendor data had to be written twice in two different shapes with
+ *    nothing relating them;
+ *  - it does not care how you fetch. Query-key seeding could only be expressed
+ *    through `@tanstack/react-query`, so a partner using SWR, RSC `fetch` or a
+ *    plain `useEffect` had no working fixture surface at all;
+ *  - the `error` variant stops being a special case. `status: 403` is an
+ *    ordinary recorded response, where before "seed an error" meant "skip
+ *    seeding and hope something throws", which is precisely the path that let
+ *    fixtures mode reach the real internet.
+ *
+ * Nothing here is computed at author time, so a captured exchange is the same
+ * object as a hand-written one — which is what leaves record/replay reachable.
+ */
+export interface HttpFixture {
+    /**
+     * `'<METHOD> <url-or-path>'`.
+     *
+     * Absolute — `'GET https://api.acme.com/v1/payouts'` — or path-only —
+     * `'GET /v1/payouts'` — which resolves against the integration's declared
+     * `egress` and is allowed only when exactly one origin is declared.
+     *
+     * `:param` matches one path segment, `*` matches the rest. A `?query` means
+     * those params must all be present with those values (a subset match, so you
+     * can pin the two that matter); no `?` ignores query entirely.
+     *
+     * First declaration wins, so write a specific fixture above a general one.
+     */
+    request: string;
+    /** Body. Sent as JSON unless it is already a string. */
+    response?: unknown;
+    /** Defaults to 200 when `response` is set, 204 when it is not. */
+    status?: number;
+    headers?: Record<string, string>;
+}
+export interface HarnessWidget {
+    /** Stable id. Also the URL segment on /[slug]/widgets/[widgetId]. */
+    id: string;
+    /** Title rendered in the widget header chrome. */
+    title: string;
+    component: ComponentType<IntegrationComponentProps>;
+    /**
+     * Column span in the dashboard grid. `full` gets its own row; runs of
+     * `half` widgets are balanced across two columns. Defaults to `half`.
+     */
+    width?: 'half' | 'full';
+    isCollapsible?: boolean;
+    isPinnable?: boolean;
+    /** Renders the "Ask about this" AI footer bar. */
+    aiFooterEnabled?: boolean;
+    /**
+     * Query-key seeds per variant — the zero-flicker FAST PATH, not the default.
+     *
+     * Writes straight into the react-query cache, so a widget paints populated
+     * with no request at all. That makes it the fastest thing available and the
+     * narrowest: it only works if your data layer is `@tanstack/react-query`,
+     * and it addresses data by query key rather than by what the vendor returns.
+     *
+     * Prefer `HarnessIntegration.fixtures`. Reach for this when you want a
+     * specific widget to skip the request entirely.
+     *
+     * (Named `fixtures` before HTTP fixtures existed. Renamed so the two are not
+     * the same word one level apart.)
+     */
+    seeds?: Partial<Record<FixtureVariant, FixtureSeed[]>>;
+}
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ *  LIVE MODE — opting your integration into real third-party requests
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * The harness mocks Fusion, not your vendor. Declare this and the toolbar grows
+ * a fixtures ⇄ live switch for your integration: in live mode the harness stops
+ * seeding your data keys, your widgets' own query functions run, and the
+ * requests they make reach the real API.
+ *
+ * Fusion stays mocked either way. There is still no Supabase, no auth and no
+ * server action — which is what `seeds` below is for.
+ *
+ * What you write is three fields:
+ *
+ * ```ts
+ * live: {
+ *   egress: MY_INTEGRATION_EGRESS,          // the same array you pass to defineIntegration
+ *   FetchProvider: MyIntegrationFetchProvider,
+ *   seeds: [{ queryKey: settingsKey, data: MY_SETTINGS }],
+ * }
+ * ```
+ *
+ * An integration with no `live` block behaves exactly as before; the toolbar
+ * control is disabled for it and says why.
+ */
+export interface HarnessLiveMode {
+    /**
+     * The integration's egress allowlist.
+     *
+     * OPTIONAL, and you almost certainly should NOT set it. When the harness
+     * entry carries a `definition`, the harness reads egress off the validated
+     * definition (`resolveEgress`) — and setting it in both places is a hard
+     * error, deliberately, because two copies are how they drift apart and the
+     * definition is the one a reviewer reads and production enforces.
+     *
+     * This field exists only for an entry with NO `definition`, where there is
+     * nothing to read it from. Requiring it here used to contradict the runtime
+     * outright: the type demanded a field `resolveEgress` refused to accept.
+     *
+     * When it is the source, the harness builds its allowlisted fetch from this
+     * array using the SDK's own `isEgressAllowed`, so a request to an origin
+     * missing from it throws `EgressDeniedError` locally exactly as it would in
+     * production.
+     */
+    egress?: readonly string[];
+    /**
+     * OPTIONAL, and no longer needed for the harness to work.
+     *
+     * The harness patches `globalThis.fetch`, so it reaches your requests
+     * whether or not you supply this — which is the point: an interception a
+     * partner can decline to wire is not really an interception. It used to be
+     * the only seam through which live mode could hand you an allowlisted fetch,
+     * and omitting it was an unintentional escape hatch.
+     *
+     * It is still worth having in YOUR code, for a reason that has nothing to do
+     * with the harness: it lets one code path serve `ctx.fetch` on the server and
+     * a browser fetch on the client, instead of a query function reaching for a
+     * global and behaving differently in each. If you supply it, the harness
+     * hands it the same fetch it would have used anyway.
+     *
+     * The pattern is a ~20-line React context whose default is the browser's
+     * `fetch`:
+     *
+     * ```tsx
+     * 'use client';
+     *
+     * import { type ReactNode, createContext, use } from 'react';
+     *
+     * import type { IntegrationFetch } from '@ekanos/sdk';
+     *
+     * const browserFetch: IntegrationFetch = (input, init) =>
+     *   globalThis.fetch(input as RequestInfo, init);
+     *
+     * const AcmeFetchContext = createContext<IntegrationFetch>(browserFetch);
+     *
+     * export function AcmeFetchProvider({
+     *   fetch,
+     *   children,
+     * }: {
+     *   fetch: IntegrationFetch;
+     *   children: ReactNode;
+     * }) {
+     *   return <AcmeFetchContext value={fetch}>{children}</AcmeFetchContext>;
+     * }
+     *
+     * export const useAcmeFetch = () => use(AcmeFetchContext);
+     * ```
+     *
+     * Then have your query functions take an `IntegrationFetch` as an argument
+     * rather than reaching for a global. The README's "Live mode" section has
+     * the full worked example.
+     *
+     * (This used to say to omit it if your widgets only call your own host
+     * routes, because the harness could not serve those. It can: a fixture
+     * whose request is under `/api/` is answered like any other, which is how
+     * the Acme example's widgets work.)
+     */
+    FetchProvider?: ComponentType<{
+        fetch: IntegrationFetch;
+        children: ReactNode;
+    }>;
+    /**
+     * Keys that stay MOCKED in live mode: Fusion-side state your widgets read
+     * before they can call anything — a saved location, an account preference,
+     * whatever your own host route would have returned. Seeded exactly like a
+     * fixture, and for exactly the same reason: the harness has no Supabase.
+     *
+     * Everything NOT listed here runs its real query function.
+     */
+    seeds?: FixtureSeed[];
+}
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ *  TRIGGERS — the local transport's seeds for the mock context
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * The Triggers surface executes the definition's declared webhooks and
+ * schedules against ONE `createMockContext()` per visit (state accumulates
+ * across invocations, like a real account). The context is derived from the
+ * definition itself — slug, storage schemas, egress — and these seeds are the
+ * only extra input: whatever Fusion-side state your handlers need to run a
+ * happy path (a stored config row, a seeded API key, a programmed response
+ * for `ctx.fetch`). There is no Supabase and no network in here either way.
+ */
+export interface HarnessTriggerMocks {
+    /** Secrets seeded into the mock context, by tier. */
+    secrets?: {
+        account?: Record<string, string>;
+        admin?: Record<string, string>;
+    };
+    /** Storage rows seeded per scope — validated against the declared schemas. */
+    storage?: {
+        account?: Record<string, unknown>;
+        user?: Record<string, unknown>;
+    };
+    /** Programmed responses for the handlers' `ctx.fetch` calls. */
+    fetchHandlers?: MockFetchHandler[];
+}
+/**
+ * The harness-only half of a widget entry — everything
+ * `harnessWidgetsFromDefinition` cannot derive, plus any chrome flag you want
+ * to override for the harness alone.
+ */
+export type HarnessWidgetOverride = Partial<Omit<HarnessWidget, 'id'>>;
+export interface HarnessIntegration {
+    /** URL segment and the id a partner would ship as their product slug. */
+    slug: string;
+    name: string;
+    description: string;
+    widgets: HarnessWidget[];
+    /**
+     * Recorded HTTP exchanges per variant — the documented default.
+     *
+     * Declared on the INTEGRATION rather than a widget because a URL is not
+     * owned by one: the same `GET /v1/payouts` may answer a widget, a second
+     * widget, and a webhook handler, and it should be written once.
+     */
+    fixtures?: Partial<Record<FixtureVariant, HttpFixture[]>>;
+    /** The marketplace tile. Optional — most real integrations don't ship one. */
+    tile?: ComponentType<MarketplaceTileProps>;
+    /** The activation form. Rendered with `inline` so it doesn't open a dialog. */
+    activationForm?: ComponentType<ActivationFormProps>;
+    /** Opt in to real third-party requests. Omit for fixtures-only. */
+    live?: HarnessLiveMode;
+    /**
+     * The validated `defineIntegration()` output — import it from your package
+     * (`import { integration } from '@you/your-integration/integration'`).
+     * Powers the Triggers surface: declared webhooks (payload editor seeded
+     * from `examplePayload`), schedules ("Run now"), and the OAuth declaration
+     * readout. Omit it and the Triggers surface explains what to add.
+     */
+    definition?: IntegrationDefinition;
+    /** Seeds for the Triggers surface's mock context. */
+    triggerMocks?: HarnessTriggerMocks;
+}
+/** The two data sources a surface can render from. */
+export declare const DATA_MODES: readonly ["fixtures", "live"];
+export type DataMode = (typeof DATA_MODES)[number];
+/**
+ * The account/product identifiers every surface is rendered with. These are
+ * plausible UUIDs rather than sentinels like `'preview-mode'`, so any widget
+ * that validates the shape of its `accountId` is happy. Nothing reads them —
+ * there is no database.
+ */
+export declare const HARNESS_ACCOUNT_ID = "00000000-0000-4000-8000-000000000001";
+export declare const HARNESS_SOURCE_ID = "00000000-0000-4000-8000-000000000002";
+export declare const HARNESS_ACCOUNT_SLUG = "harness-team";
+/**
+ * Erases a definition's storage generic so it can sit in the heterogeneous
+ * registry array — the same erasure the host performs inside
+ * `registerPartnerIntegration()`. Nothing rests on the generic surviving:
+ * the Triggers surface builds its mock context FROM the definition's own
+ * `storage` schemas, and every read/write is validated against them at
+ * runtime regardless of the static parameter.
+ */
+export declare function asHarnessDefinition<Schemas extends StorageSchemas>(definition: IntegrationDefinition<Schemas>): IntegrationDefinition;
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ *  DERIVE THE WIDGET LIST FROM THE DEFINITION YOU ALREADY WROTE
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * `HarnessWidget` restates `id`, `title`, `component`, `isCollapsible`,
+ * `isPinnable` and `aiFooterEnabled` — every one of which is already in
+ * `defineIntegration({ components: { widgets } })`. Writing both by hand means
+ * two declarations of the same thing with nothing detecting drift, and it is
+ * how `isCollapsible` came to be declared in one place and read from the
+ * other.
+ *
+ * This derives the harness entry from the definition, so the definition stays
+ * the single source and the harness entry adds only what is genuinely
+ * harness-only: `width`, and per-widget `seeds`.
+ *
+ *     widgets: harnessWidgetsFromDefinition(integration, {
+ *       'acme-payouts': { width: 'full' },
+ *     }),
+ *
+ * HTTP fixtures are NOT in here — they live on the integration
+ * (`HarnessIntegration.fixtures`), because a URL is not owned by one widget.
+ *
+ * ── The cast, and why it lives here rather than in your config ──
+ *
+ * `defineIntegration` is dependency-pure — zod only, no React — so it types a
+ * widget's `component` structurally as `ComponentReference`
+ * (`(...args: never[]) => unknown`, or anything with a `$$typeof`). That is
+ * deliberate and correct for validation, but it is not assignable to
+ * `ComponentType<IntegrationComponentProps>`, so SOMETHING has to assert the
+ * type back.
+ *
+ * Without this helper that assertion happens in every partner's config file,
+ * once per widget, unreviewed. Here it happens once, in code we own and test.
+ * The runtime risk is unchanged either way: the definition was already
+ * validated by `defineIntegration`, which checked that each `component` is a
+ * component reference — this only recovers the parameter type that validation
+ * could not carry.
+ *
+ * If the SDK ever preserves component types through validation, delete the
+ * cast and nothing else changes.
+ */
+export declare function harnessWidgetsFromDefinition(definition: IntegrationDefinition, overrides?: Record<string, HarnessWidgetOverride>): HarnessWidget[];
+export declare function findIntegration(integrations: HarnessIntegration[], slug: string): HarnessIntegration | null;
+export declare function findWidget(integration: HarnessIntegration, widgetId: string): HarnessWidget | null;
+/** Every seed a given integration declares for the active fixture variant. */
+export declare function collectSeeds(integration: HarnessIntegration, variant: FixtureVariant): FixtureSeed[];
+/**
+ * The seeds for one integration in one mode.
+ *
+ * Fixtures mode seeds everything the widgets declare. Live mode seeds ONLY the
+ * Fusion-side keys, so every other query function runs for real — that one
+ * difference is the whole fixtures ⇄ live switch.
+ */
+export declare function seedsForMode(integration: HarnessIntegration, variant: FixtureVariant, mode: DataMode): FixtureSeed[];
+/**
+ * A `live.egress` that does not match the integration's own
+ * `defineIntegration({ egress })` declaration.
+ */
+export interface EgressMismatch {
+    /** Origins the validated definition declares. */
+    declared: readonly string[];
+    /** Origins live mode would actually allow. */
+    live: readonly string[];
+    /** In `live.egress` but NOT declared — the ones that matter. */
+    undeclared: readonly string[];
+}
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ *  THE TWO EGRESS LISTS MUST AGREE
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * `HarnessLiveMode.egress` is documented as the definition's array passed
+ * through VERBATIM, and until now nothing enforced that. A partner could
+ * declare a modest `egress` in `defineIntegration` — the list a reviewer
+ * actually reads — and independently set `live.egress` to something wider, or
+ * to `http://127.0.0.1:8080`. The harness would happily use the second list,
+ * so a green local run would prove nothing about the declaration we review.
+ * That defeats the entire purpose of live mode.
+ *
+ * Only origins present in `live` but absent from the definition are a fault. A
+ * definition may legitimately declare more than live mode exercises; the
+ * reverse is the harness permitting what production would refuse.
+ *
+ * Returns null when there is nothing to compare — no `live` block, or no
+ * `definition` linked. An unlinked definition is already surfaced by the
+ * Triggers surface, and inventing a second complaint here would not help.
+ */
+export declare function findEgressMismatch(integration: HarnessIntegration): EgressMismatch | null;
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ *  ONE EGRESS LIST, AND IT IS THE ONE A REVIEWER READS
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * `live.egress` used to be the harness's own copy of the allowlist, documented
+ * as "the definition's array, verbatim" and enforced by nothing. A partner
+ * could declare a modest list in `defineIntegration` — the list a reviewer
+ * actually reads — and quietly widen the harness's. `findEgressMismatch`
+ * detected that; reading the definition directly makes it impossible, which is
+ * better than detecting it.
+ *
+ * So when a definition is linked, its `egress` is THE list. Supplying
+ * `live.egress` as well is a hard error rather than a silent preference,
+ * because a silent preference is how the divergence became possible in the
+ * first place.
+ *
+ * Without a definition there is nothing to read, so `live.egress` remains the
+ * only source — which is the one case `findEgressMismatch` still has work to
+ * do in. That is why it looks narrower than the story around it; it is not a
+ * leftover to be generalised back.
+ */
+export declare function resolveEgress(integration: HarnessIntegration): readonly string[];
+/**
+ * Whether live mode is actually available here. The toolbar reads this to
+ * disable the control (and say why) rather than offering a switch that would
+ * silently render empty widgets.
+ */
+export declare function supportsLiveMode(integration: HarnessIntegration | null): integration is HarnessIntegration & {
+    live: HarnessLiveMode;
+};

package/dist/registry.js

@@ -0,0 +1,82 @@
+const FIXTURE_VARIANTS = ["default", "empty", "error"];
+const DATA_MODES = ["fixtures", "live"];
+const HARNESS_ACCOUNT_ID = "00000000-0000-4000-8000-000000000001";
+const HARNESS_SOURCE_ID = "00000000-0000-4000-8000-000000000002";
+const HARNESS_ACCOUNT_SLUG = "harness-team";
+function asHarnessDefinition(definition) {
+  return definition;
+}
+function harnessWidgetsFromDefinition(definition, overrides = {}) {
+  const declared = definition.components?.widgets ?? [];
+  for (const id of Object.keys(overrides)) {
+    if (!declared.some((widget) => widget.id === id)) {
+      throw new Error(
+        `harnessWidgetsFromDefinition(): "${id}" is not a widget in "${definition.slug}". Declared: ${declared.map((w) => w.id).join(", ") || "(none)"}. An override keyed to a widget that does not exist is silently ignored otherwise, which reads as the override not working.`
+      );
+    }
+  }
+  return declared.map((widget) => {
+    const override = overrides[widget.id] ?? {};
+    return {
+      id: widget.id,
+      title: widget.name,
+      component: widget.component,
+      // Chrome flags come from the definition and are passed through ONLY when
+      // it declares them, so an undeclared flag still lands on the host's
+      // default rather than one invented here.
+      ...widget.isCollapsible === void 0 ? {} : { isCollapsible: widget.isCollapsible },
+      ...widget.isPinnable === void 0 ? {} : { isPinnable: widget.isPinnable },
+      ...widget.aiFooterEnabled === void 0 ? {} : { aiFooterEnabled: widget.aiFooterEnabled },
+      ...override
+    };
+  });
+}
+function findIntegration(integrations, slug) {
+  return integrations.find((integration) => integration.slug === slug) ?? null;
+}
+function findWidget(integration, widgetId) {
+  return integration.widgets.find((widget) => widget.id === widgetId) ?? null;
+}
+function collectSeeds(integration, variant) {
+  return integration.widgets.flatMap((widget) => widget.seeds?.[variant] ?? []);
+}
+function seedsForMode(integration, variant, mode) {
+  return mode === "live" ? integration.live?.seeds ?? [] : collectSeeds(integration, variant);
+}
+function findEgressMismatch(integration) {
+  const live = integration.live?.egress;
+  const declared = integration.definition?.egress;
+  if (!live || !declared) return null;
+  const declaredSet = new Set(declared);
+  const undeclared = live.filter((origin) => !declaredSet.has(origin));
+  return undeclared.length > 0 ? { declared, live, undeclared } : null;
+}
+function resolveEgress(integration) {
+  const declared = integration.definition?.egress;
+  const live = integration.live?.egress;
+  if (declared && live) {
+    throw new Error(
+      `"${integration.slug}" declares egress in BOTH defineIntegration() and its harness entry's \`live.egress\`. The harness reads it from your definition now, so remove \`live.egress\` \u2014 keeping two copies is how they drift apart, and the definition is the one a reviewer reads and production enforces.`
+    );
+  }
+  return declared ?? live ?? [];
+}
+function supportsLiveMode(integration) {
+  return integration?.live !== void 0;
+}
+export {
+  DATA_MODES,
+  FIXTURE_VARIANTS,
+  HARNESS_ACCOUNT_ID,
+  HARNESS_ACCOUNT_SLUG,
+  HARNESS_SOURCE_ID,
+  asHarnessDefinition,
+  collectSeeds,
+  findEgressMismatch,
+  findIntegration,
+  findWidget,
+  harnessWidgetsFromDefinition,
+  resolveEgress,
+  seedsForMode,
+  supportsLiveMode
+};

package/dist/routes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The five `[slug]` surfaces plus their shared layout.
+ *
+ * Every one is a `'use client'` module: the registry holds live React component
+ * references, which cannot cross the server/client boundary as props, so each
+ * route reads the injected registry out of context instead. That makes this
+ * whole entry a client entry — see the directive note in tsup.config.ts.
+ *
+ * The shell's route files are one-line re-exports of these:
+ *
+ *     export { WidgetsPage as default } from '@ekanos/harness/routes';
+ *
+ * The directive sits on the BARREL as well as on each module it re-exports.
+ * Every export here is a client component, so it is simply true — and it makes
+ * the boundary legible at the one file a reader is likely to open. It does cost
+ * the six route modules being bundled together rather than per route; for a
+ * local dev tool that is not a real cost.
+ */
+export { IntegrationLayout } from './internal/routes/integration-layout.js';
+export { WidgetsPage } from './internal/routes/widgets-page.js';
+export { SingleWidgetPage } from './internal/routes/single-widget-page.js';
+export { TilePage } from './internal/routes/tile-page.js';
+export { ActivationPage } from './internal/routes/activation-page.js';
+export { TriggersPage } from './internal/routes/triggers-page.js';

package/dist/routes.js

@@ -0,0 +1,15 @@
+"use client";
+import { IntegrationLayout } from "./internal/routes/integration-layout.js";
+import { WidgetsPage } from "./internal/routes/widgets-page.js";
+import { SingleWidgetPage } from "./internal/routes/single-widget-page.js";
+import { TilePage } from "./internal/routes/tile-page.js";
+import { ActivationPage } from "./internal/routes/activation-page.js";
+import { TriggersPage } from "./internal/routes/triggers-page.js";
+export {
+  ActivationPage,
+  IntegrationLayout,
+  SingleWidgetPage,
+  TilePage,
+  TriggersPage,
+  WidgetsPage
+};