PrismFacet/plugin/core/cross-plugin-api.ts

/**
 * Cross-plugin API: globalThis.__prismFacet
 *
 * PrismFacet is the registration mechanism (routers, rules, the
 * before_prompt_build hook that resolves them); other plugins (notably
 * ClawPrompts) supply the actual content by calling into this API at
 * their own register() time.
 *
 * Installation idempotence: safe to call install() multiple times — the
 * function attaches the same set of methods to globalThis.__prismFacet
 * if not already present. Plugin reload doesn't break consumers.
 *
 * If a consumer plugin (ClawPrompts) loads BEFORE PrismFacet, the
 * `globalThis.__prismFacet` slot will be undefined at the consumer's
 * register() time. To make load-order independence work, this module
 * pre-creates the slot at module-import time too — consumers can call
 * .addRouter / .addRule even if PrismFacet's register() hasn't run yet
 * (the registration still lands in the shared maps).
 */
import { addExternalRouter, type RouterContext } from "./router-loader.js";
import { addExternalRule } from "./rule-store.js";

const _G = globalThis as Record<string, unknown>;

export interface PrismFacetCrossPluginApi {
  /**
   * Register a router programmatically.
   * @param name router name (matches the "router:" prefix of rule keys)
   * @param resolve function returning a key string for the given context
   *                (or empty/null to skip this router for this context)
   */
  addRouter(
    name: string,
    resolve: (ctx: RouterContext) => string | Promise<string>,
  ): void;

  /**
   * Register a rule programmatically (in-memory; persistent rules.json
   * entries set by the prompt-rules tool take precedence on conflict).
   * @param routerName router this rule binds to
   * @param key value the router must resolve to for this rule to fire
   * @param prompt either { file: "/abs/path.md" } or { text: "..." }
   */
  addRule(
    routerName: string,
    key: string,
    prompt: { file?: string; text?: string },
  ): void;
}

type PendingOp =
  | { type: "router"; name: string; resolve: (ctx: RouterContext) => string | Promise<string> }
  | { type: "rule"; routerName: string; key: string; prompt: { file?: string; text?: string } };

/**
 * Idempotent install. Called from PrismFacet's register(). Also runs
 * at module-import time below so consumer plugins loading before
 * PrismFacet still find a usable API.
 *
 * Plugin load order is undefined — if ClawPrompts loads before
 * PrismFacet, the `_G['__prismFacet']` slot stays at the buffering stub
 * created by ClawPrompts (or, if neither has installed yet, missing).
 * To make this race-free, we install the real API on first call from
 * either side AND drain any queued ops a buffering caller may have
 * accumulated via the well-known `__prismFacetPending` array. ClawPrompts
 * (and any future consumer) only needs to: push ops onto the pending
 * array when `__prismFacet?.addRouter` isn't callable; PrismFacet's
 * install() will drain them when it runs.
 */
export function installCrossPluginApi(): PrismFacetCrossPluginApi {
  const existing = _G["__prismFacet"] as PrismFacetCrossPluginApi | undefined;
  if (existing && typeof existing.addRouter === "function" && (existing as any).__real) return existing;

  const api: PrismFacetCrossPluginApi & { __real: true } = {
    addRouter(name, resolve) {
      addExternalRouter(name, resolve);
    },
    addRule(routerName, key, prompt) {
      if (!prompt.file) {
        throw new Error(
          "__prismFacet.addRule: only { file: '/abs/path.md' } is supported today; " +
          "inline { text } pending injector update",
        );
      }
      addExternalRule(routerName, key, prompt.file);
    },
    __real: true,
  };
  _G["__prismFacet"] = api;

  // Drain any ops queued by consumer plugins that ran before us.
  const pending = _G["__prismFacetPending"] as PendingOp[] | undefined;
  if (Array.isArray(pending) && pending.length > 0) {
    for (const op of pending) {
      try {
        if (op.type === "router") api.addRouter(op.name, op.resolve);
        else api.addRule(op.routerName, op.key, op.prompt);
      } catch {
        // Swallow per-op errors so one bad pending entry doesn't block
        // the rest. Consumer plugin logs already fired at queue time.
      }
    }
    _G["__prismFacetPending"] = [];
  }

  return api;
}

// Eager install on module load.
installCrossPluginApi();