zidane-ui 9.1.1 → 9.1.3

package/src/extensions/headless/fixture-host.ts

@@ -1,381 +0,0 @@
-/**
- * An `ExtensionsHost` held in memory, for docs, demos, galleries and tests:
- * items you add and change from outside, scripted callbacks and RPC
- * methods, a dialog queue and an effect channel the "backend" drives,
- * stores, settings, integrations and commands.
- */
-import { writable, type Writable } from '../../chat/headless/store';
-import { createDialogQueue, type DialogQueueShowContext } from './dialog-queue';
-import { createUiEffectChannel, type ExtensionUiEffectResult } from './effect-channel';
-import {
-  ExtensionsHostError,
-  type ExtensionCallbackId,
-  type ExtensionCallbacks,
-  type ExtensionCommandWire,
-  type ExtensionIntegrationConnectionWire,
-  type ExtensionIntegrationWire,
-  type ExtensionItemStores,
-  type ExtensionPanelChange,
-  type ExtensionSettingsWire,
-  type ExtensionStoreRef,
-  type ExtensionsHost,
-  type ExtensionUiEffect,
-  type ExtensionAccessScope,
-  type ExtensionLinkRequest,
-} from './host';
-import {
-  EXTENSION_TOKENS,
-  type DialogRequestWire,
-  type ExtensionItem,
-  type ExtensionTokenName,
-  type ExtensionWireMap,
-} from './wire';
-
-/** A scripted callback: answers like the extension would, or throws. */
-export type FixtureCallback<K extends ExtensionCallbackId> = (
-  args: ExtensionCallbacks[K]['args'],
-) => ExtensionCallbacks[K]['result'] | Promise<ExtensionCallbacks[K]['result']>;
-
-/** An RPC error a scripted method throws: answered as `{ code: 'rpc', … }`. */
-export interface FixtureRpcError {
-  /** The error's type, as the caller reads it. */
-  type: string;
-  /** What went wrong, for a person. */
-  message: string;
-  /** Extra detail for the caller. */
-  data?: unknown;
-}
-
-/** A scripted RPC method. Throw a {@link FixtureRpcError} to answer an error. */
-export type FixtureRpcMethod = (input: unknown, ctx: { extensionId?: string }) => unknown;
-
-/** The optional members a fixture host can leave out. */
-export type FixtureExtensionsCapability =
-  'invoke' | 'dialogs' | 'effects' | 'rpc' | 'storage' | 'settings' | 'integrations' | 'commands' | 'panelChanged';
-
-/** Options of {@link createFixtureExtensionsHost}. */
-export interface FixtureExtensionsOptions {
-  /** The items there at the start. */
-  items?: readonly ExtensionItem[];
-  /** Scripted callbacks. One left out answers `unavailable`. */
-  callbacks?: { [K in ExtensionCallbackId]?: FixtureCallback<K> };
-  /** Scripted RPC methods, by contract then method. */
-  rpc?: Readonly<Record<string, Readonly<Record<string, FixtureRpcMethod>>>>;
-  /** Stored values, by {@link storeKey}. */
-  stores?: Readonly<Record<string, unknown>>;
-  /** The settings. Default: none. */
-  settings?: ExtensionSettingsWire;
-  /** Make settings read-only (no `settings.set`). */
-  settingsReadOnly?: boolean;
-  /** The integrations. Default: none. */
-  integrations?: readonly ExtensionIntegrationWire[];
-  /** The API key `connect` accepts; any other is refused. Default `'good-key'`. */
-  goodKey?: string;
-  /** The commands. Default: none. */
-  commands?: readonly ExtensionCommandWire[];
-  /** Offer only these optional members. Default: all of them. */
-  capabilities?: readonly FixtureExtensionsCapability[];
-  /** The link handlers: whether one opens a link. Absent: no `openLink` (links open the app's way). */
-  openLink?: (request: ExtensionLinkRequest) => boolean | Promise<boolean>;
-  /** The scope the client's token grants. Absent: no `scope` (never limited). */
-  scope?: ExtensionAccessScope | null;
-}
-
-/** Drives a fixture host from outside, as the extensions behind it would. */
-export interface FixtureExtensionsControl {
-  /** Adds or replaces an item (by key). */
-  upsert(entry: ExtensionItem): void;
-  /** Withdraws an item. */
-  remove(key: string): void;
-  /** Asks this client for a dialog; resolves with the answer. */
-  dialog(request: DialogRequestWire, ctx: DialogQueueShowContext): Promise<unknown>;
-  /** Routes a `ctx.ui` / `ctx.composer` call to this client; resolves with what the app settled. */
-  effect(effect: ExtensionUiEffect): Promise<ExtensionUiEffectResult>;
-  /** Another client wrote a store. */
-  writeStore(ref: ExtensionStoreRef, value: unknown): void;
-  /** A store's value now. */
-  readStore(ref: ExtensionStoreRef): unknown;
-  /** The commands run so far. */
-  ran(): readonly { id: string; args?: string; sessionId?: string }[];
-  /** The callbacks invoked so far. */
-  invoked(): readonly { id: ExtensionCallbackId; args: unknown }[];
-  /** Replaces the settings. */
-  setSettings(next: ExtensionSettingsWire): void;
-  /** A live panel would load something new (its `subscribe` emitted): `panelChanged` listeners hear it. */
-  panelChanged(change: ExtensionPanelChange): void;
-  /** The links offered to the link handlers so far. */
-  links(): readonly ExtensionLinkRequest[];
-  /** Changes the token's scope (with `scope` given). */
-  setScope(next: ExtensionAccessScope | null): void;
-}
-
-/** An in-memory {@link ExtensionsHost} and its control. */
-export type FixtureExtensionsHost = ExtensionsHost & { control: FixtureExtensionsControl };
-
-/**
- * The key of a store in {@link FixtureExtensionsOptions.stores}.
- *
- * @param ref - The store.
- */
-export function storeKey(ref: ExtensionStoreRef): string {
-  return [ref.extensionId, ref.scope, ref.sessionId ?? '', ref.name].join('\u0000');
-}
-
-let fixtureSeq = 0;
-
-const EMPTY_SETTINGS: ExtensionSettingsWire = {
-  schema: { categories: [], items: [] },
-  actions: [],
-  values: {},
-  locked: [],
-};
-
-/**
- * Creates an {@link ExtensionsHost} held in memory.
- *
- * @param options - What it holds and which members it offers.
- */
-export function createFixtureExtensionsHost(options: FixtureExtensionsOptions = {}): FixtureExtensionsHost {
-  const has = (c: FixtureExtensionsCapability) => !options.capabilities || options.capabilities.includes(c);
-  const lists = Object.fromEntries(EXTENSION_TOKENS.map((t) => [t, writable<readonly ExtensionItem[]>([])])) as Record<
-    ExtensionTokenName,
-    Writable<readonly ExtensionItem[]>
-  >;
-  const upsert = (entry: ExtensionItem): void => {
-    const list = lists[entry.token];
-    list.set((prev) => {
-      const index = prev.findIndex((e) => e.key === entry.key);
-      if (index < 0) return [...prev, entry];
-      const next = [...prev];
-      next[index] = entry;
-      return next;
-    });
-  };
-  const remove = (key: string): void => {
-    for (const list of Object.values(lists)) {
-      if (list.get().some((e) => e.key === key)) list.set((prev) => prev.filter((e) => e.key !== key));
-    }
-  };
-  for (const entry of options.items ?? []) upsert(entry);
-
-  const invoked: { id: ExtensionCallbackId; args: unknown }[] = [];
-  const queue = createDialogQueue();
-  const channel = createUiEffectChannel();
-
-  const stores = new Map<string, Writable<unknown>>();
-  const storeOf = (ref: ExtensionStoreRef): Writable<unknown> => {
-    const key = storeKey(ref);
-    let store = stores.get(key);
-    if (!store) {
-      store = writable<unknown>(options.stores?.[key]);
-      stores.set(key, store);
-    }
-    return store;
-  };
-
-  const settings = writable<ExtensionSettingsWire>(options.settings ?? EMPTY_SETTINGS);
-  const integrations = writable<readonly ExtensionIntegrationWire[]>(options.integrations ?? []);
-  const commands = writable<readonly ExtensionCommandWire[]>(options.commands ?? []);
-  const ran: { id: string; args?: string; sessionId?: string }[] = [];
-  const goodKey = options.goodKey ?? 'good-key';
-  const panelListeners = new Set<(change: ExtensionPanelChange) => void>();
-  const links: ExtensionLinkRequest[] = [];
-  const scope = writable<ExtensionAccessScope | null>(options.scope ?? null);
-
-  const host: ExtensionsHost = {
-    items: lists as unknown as ExtensionItemStores,
-  };
-  const openLink = options.openLink;
-  if (openLink) {
-    host.openLink = async (request) => {
-      links.push(request);
-      return openLink(request);
-    };
-  }
-  if (options.scope !== undefined) host.scope = scope;
-  if (has('invoke')) {
-    host.invoke = async (id, args) => {
-      invoked.push({ id, args });
-      const fn = options.callbacks?.[id] as FixtureCallback<typeof id> | undefined;
-      if (!fn) throw new ExtensionsHostError({ code: 'unavailable' });
-      try {
-        return await fn(args);
-      } catch (err) {
-        if (err instanceof ExtensionsHostError) throw err;
-        throw new ExtensionsHostError({ code: 'failed', message: err instanceof Error ? err.message : String(err) });
-      }
-    };
-  }
-  if (has('dialogs')) host.dialogs = queue.dialogs;
-  if (has('panelChanged')) {
-    host.panelChanged = (listener) => {
-      panelListeners.add(listener);
-      return () => panelListeners.delete(listener);
-    };
-  }
-  if (has('effects')) host.effects = channel.effects;
-  if (has('rpc')) {
-    host.rpc = async (contract, method, input, opts) => {
-      const fn = options.rpc?.[contract]?.[method];
-      if (!fn)
-        throw new ExtensionsHostError({
-          code: 'rpc',
-          type: 'rpc.unavailable',
-          message: `${contract}.${method} is not registered`,
-        });
-      try {
-        return await fn(input, { ...(opts?.extensionId ? { extensionId: opts.extensionId } : {}) });
-      } catch (err) {
-        const e = err as Partial<FixtureRpcError>;
-        if (e && typeof e.type === 'string' && typeof e.message === 'string')
-          throw new ExtensionsHostError({
-            code: 'rpc',
-            type: e.type,
-            message: e.message,
-            ...(e.data !== undefined ? { data: e.data } : {}),
-          });
-        throw new ExtensionsHostError({
-          code: 'rpc',
-          type: 'rpc.internal',
-          message: err instanceof Error ? err.message : String(err),
-        });
-      }
-    };
-  }
-  if (has('storage')) {
-    host.storage = {
-      store: (ref) => storeOf(ref),
-      set: async (ref, value) => {
-        storeOf(ref).set(value);
-      },
-    };
-  }
-  if (has('settings')) {
-    host.settings = {
-      wire: settings,
-      ...(options.settingsReadOnly
-        ? {}
-        : {
-            set: async (extensionId: string, key: string, value: unknown) => {
-              const now = settings.get();
-              if (now.locked.includes(`${extensionId}:${key}`))
-                throw new ExtensionsHostError({ code: 'refused', reason: 'locked' });
-              const item = now.schema.items.find((i) => i.extension === extensionId && i.key === key);
-              if (!item)
-                throw new ExtensionsHostError({ code: 'refused', reason: 'invalid', message: `no setting ${key}` });
-              const ok =
-                item.type === 'boolean'
-                  ? typeof value === 'boolean'
-                  : item.type === 'number'
-                    ? typeof value === 'number'
-                    : typeof value === 'string';
-              if (!ok) throw new ExtensionsHostError({ code: 'refused', reason: 'invalid' });
-              settings.set({
-                ...now,
-                values: {
-                  ...now.values,
-                  [extensionId]: { ...now.values[extensionId], [key]: value as boolean | number | string },
-                },
-              });
-            },
-          }),
-    };
-  }
-  if (has('integrations')) {
-    const reconnect = (
-      integrationId: string,
-      change: (list: readonly ExtensionIntegrationConnectionWire[]) => ExtensionIntegrationConnectionWire[],
-    ) =>
-      integrations.set((prev) =>
-        prev.map((i) => {
-          if (i.id !== integrationId) return i;
-          const { connection: _c, connections: _cs, ...rest } = i;
-          const next = change(i.connections ?? (i.connection ? [i.connection] : []));
-          // The first is the default: one flag, on it.
-          const marked = next.map(({ isDefault: _d, ...c }, n) => (n === 0 ? { ...c, isDefault: true } : c));
-          return marked.length > 0 ? { ...rest, connection: marked[0], connections: marked } : rest;
-        }),
-      );
-    host.integrations = {
-      list: integrations,
-      connect: async (integrationId, opts) => {
-        const entry = integrations.get().find((i) => i.id === integrationId);
-        const method = entry?.methods.find((m) => m.id === opts.methodId);
-        if (!entry || !method) throw new ExtensionsHostError({ code: 'unavailable' });
-        if (method.type === 'apiKey' && opts.key !== goodKey)
-          throw new ExtensionsHostError({ code: 'refused', reason: 'invalid' });
-        const added = { methodId: method.id, account: 'demo', connectedAt: 1 };
-        reconnect(integrationId, (list) =>
-          list.some((c) => c.account === added.account)
-            ? list.map((c) => (c.account === added.account ? added : c))
-            : [...list, added],
-        );
-      },
-      disconnect: async (integrationId, opts) => {
-        reconnect(integrationId, (list) =>
-          opts?.account === undefined ? [] : list.filter((c) => c.account !== opts.account),
-        );
-      },
-      setDefault: async (integrationId, account) => {
-        const entry = integrations.get().find((i) => i.id === integrationId);
-        const list = entry?.connections ?? (entry?.connection ? [entry.connection] : []);
-        if (!list.some((c) => c.account === account)) throw new ExtensionsHostError({ code: 'unavailable' });
-        reconnect(integrationId, (list) => [
-          ...list.filter((c) => c.account === account),
-          ...list.filter((c) => c.account !== account),
-        ]);
-      },
-    };
-  }
-  if (has('commands')) {
-    host.commands = {
-      list: commands,
-      run: async (id, opts) => {
-        if (!commands.get().some((c) => c.id === id)) return false;
-        ran.push({
-          id,
-          ...(opts?.args !== undefined ? { args: opts.args } : {}),
-          ...(opts?.sessionId ? { sessionId: opts.sessionId } : {}),
-        });
-        return true;
-      },
-    };
-  }
-
-  return {
-    ...host,
-    control: {
-      upsert,
-      remove,
-      dialog: (request, ctx) => queue.show(request, ctx),
-      effect: (effect) => channel.apply(effect),
-      writeStore: (ref, value) => storeOf(ref).set(value),
-      readStore: (ref) => storeOf(ref).get(),
-      ran: () => ran,
-      invoked: () => invoked,
-      setSettings: (next) => settings.set(next),
-      panelChanged: (change) => {
-        for (const listener of [...panelListeners]) listener(change);
-      },
-      links: () => links,
-      setScope: (next) => scope.set(next),
-    },
-  };
-}
-
-/**
- * Builds an item for a fixture: `key` defaults to `<token>:<extension>:<n>`.
- *
- * @param token - The token.
- * @param extension - The contributing extension.
- * @param item - The wire form.
- * @param key - The item's key.
- */
-export function fixtureItem<N extends ExtensionTokenName>(
-  token: N,
-  extension: string,
-  item: ExtensionWireMap[N],
-  key?: string,
-): ExtensionItem<N> {
-  return { key: key ?? `${token}:${extension}:${++fixtureSeq}`, token, extension, item };
-}