@gogitcms/editor 0.23.0

package/app/vendor/plugin-sdk/src/loader.ts

@@ -0,0 +1,45 @@
+// loadPlugins is the shared async loader both hosts use: the SPA feeds it the
+// virtual:cms-plugins entries the build generated; the desktop feeds it
+// entries whose load() imports from the plugin file server. Failures are
+// per-plugin — one broken plugin never takes down the rest of the app.
+
+import type { PluginLoadEntry, PluginSetup } from "./types";
+import type { PluginRegistry } from "./registry";
+
+/**
+ * Load every entry in parallel and run each plugin's setup function against a
+ * registry-scoped API. Resolves once every plugin is ready or failed; hosts
+ * normally fire-and-forget and re-render from registry subscriptions instead
+ * of awaiting.
+ */
+export async function loadPlugins(entries: PluginLoadEntry[], registry: PluginRegistry): Promise<void> {
+  const seen = new Set<string>();
+  const jobs: Promise<void>[] = [];
+  for (const entry of entries) {
+    if (!entry.id || seen.has(entry.id)) {
+      console.error(`[plugins] duplicate or empty plugin id ${JSON.stringify(entry.id)} skipped`);
+      continue;
+    }
+    seen.add(entry.id);
+    registry.markPending(entry.id);
+    jobs.push(loadOne(entry, registry));
+  }
+  await Promise.all(jobs);
+}
+
+async function loadOne(entry: PluginLoadEntry, registry: PluginRegistry): Promise<void> {
+  try {
+    const mod = (await entry.load()) as { default?: unknown } | null;
+    const setup = mod?.default;
+    if (typeof setup !== "function") {
+      throw new Error(`plugin "${entry.id}" has no default-exported setup function`);
+    }
+    await (setup as PluginSetup)(registry.api(entry.id), entry.options);
+    registry.markReady(entry.id);
+  } catch (err) {
+    // The failure is surfaced in the registry (settings UI, fallback panels);
+    // log it too so a broken plugin is loud during development.
+    console.error(`[plugins] "${entry.id}" failed to load:`, err);
+    registry.markFailed(entry.id, err);
+  }
+}

package/app/vendor/plugin-sdk/src/navkeys.ts

@@ -0,0 +1,17 @@
+// Sidebar nav keys for plugin links. A plugin id is a package name and may
+// contain "/" (@acme/analytics), so the id is percent-encoded into the key and
+// the first literal "/" separates it from the route path.
+
+const PREFIX = "plugin:";
+
+export function pluginNavKey(pluginId: string, path: string): string {
+  return PREFIX + encodeURIComponent(pluginId) + (path ? "/" + path : "");
+}
+
+export function parsePluginNavKey(key: string): { id: string; path: string } | null {
+  if (!key.startsWith(PREFIX)) return null;
+  const rest = key.slice(PREFIX.length);
+  const slash = rest.indexOf("/");
+  if (slash === -1) return { id: decodeURIComponent(rest), path: "" };
+  return { id: decodeURIComponent(rest.slice(0, slash)), path: rest.slice(slash + 1) };
+}

package/app/vendor/plugin-sdk/src/react.tsx

@@ -0,0 +1,155 @@
+// React-facing helpers for the hosts: registry subscription, memoized lazy
+// resolution of plugin component loaders, and the renderField chain that puts
+// plugin field components into the editor.
+
+import React, { Suspense, useSyncExternalStore, type ComponentType, type LazyExoticComponent } from "react";
+import { Text, type RenderField } from "@gogitcms/design-system";
+import { PLUGIN_COMPONENT_PREFIX, PluginRegistry } from "./registry";
+import type { PluginComponentLoader, PluginScreenProps, PluginTabContext } from "./types";
+
+/**
+ * Re-render the calling component whenever the registry changes (a plugin
+ * finished loading, a registration landed). Hosts call this once near the
+ * root, which is what re-evaluates every sync decision made from registry
+ * state — including createPluginRenderField's fallbacks below.
+ */
+export function usePluginRegistry(registry: PluginRegistry): number {
+  return useSyncExternalStore(registry.subscribe, registry.getVersion, registry.getVersion);
+}
+
+// One React.lazy per loader function, so repeated renders reuse the same
+// component identity (and the same in-flight import) instead of remounting.
+const lazyCache = new WeakMap<PluginComponentLoader<any>, LazyExoticComponent<ComponentType<any>>>();
+
+export function getLazyComponent<P>(loader: PluginComponentLoader<P>): ComponentType<P> {
+  let lazy = lazyCache.get(loader);
+  if (!lazy) {
+    lazy = React.lazy(loader as PluginComponentLoader<any>);
+    lazyCache.set(loader, lazy);
+  }
+  return lazy as unknown as ComponentType<P>;
+}
+
+// A resolution problem is worth exactly one console line, not one per render.
+const warned = new Set<string>();
+function warnOnce(key: string, message: string) {
+  if (warned.has(key)) return;
+  warned.add(key);
+  console.warn(message);
+}
+
+/**
+ * Renders a plugin's screen for the current plugins/{id}/{path} route. Owns
+ * the degraded states so a deep link into a missing/broken plugin lands on a
+ * polite panel instead of a crash:
+ *  - plugin still loading → nothing (the host shell is already on screen)
+ *  - plugin failed / unknown / no matching route → explanatory text
+ *  - matched → the route's lazy component with PluginScreenProps
+ */
+export function PluginScreenHost({
+  registry,
+  pluginId,
+  path,
+  workspaceId,
+  repositoryId,
+  branchId,
+  gitRef,
+  apiUrl,
+  navigate,
+  params,
+  tab,
+}: {
+  registry: PluginRegistry;
+  pluginId: string;
+  path: string;
+  workspaceId: string;
+  repositoryId: string;
+  branchId?: string;
+  /** Git ref name of the branch. Named `gitRef` because `ref` is reserved on
+   *  a React element's props. */
+  gitRef?: string;
+  apiUrl: string;
+  navigate: (to: string) => void;
+  /** Extra params merged over the route's matched `:segment` params. */
+  params?: Record<string, string>;
+  /** Present when this route is being rendered as a column tab, not a screen. */
+  tab?: PluginTabContext;
+}) {
+  usePluginRegistry(registry);
+  const status = registry.status(pluginId);
+  if (status === "pending") return null;
+  const match = status === "ready" ? registry.matchRoute(pluginId, path) : null;
+  if (!match) {
+    const what = tab ? "tab" : "screen";
+    return (
+      <Text variant="body" color="tertiary" style={{ padding: 24 }} testID="plugin-screen-unavailable">
+        {status === "ready"
+          ? `The plugin "${pluginId}" has no ${what} at "${path || "/"}".`
+          : `This ${what} comes from the plugin "${pluginId}", which isn't available.`}
+      </Text>
+    );
+  }
+  const Lazy = getLazyComponent(match.record.component);
+  const props: PluginScreenProps = {
+    workspaceId,
+    repositoryId,
+    branchId,
+    ref: gitRef,
+    params: { ...match.params, ...params },
+    navigate,
+    apiUrl,
+    tab,
+  };
+  return (
+    <Suspense fallback={<React.Fragment />}>
+      <Lazy {...props} />
+    </Suspense>
+  );
+}
+
+/**
+ * Build the host's renderField: fields whose `display.component` is
+ * `plugin:<name>` render the registered plugin component; everything else is
+ * delegated to `next` (the markdown render field) and, beneath that, the
+ * design-system's built-in controls (by returning undefined).
+ *
+ * Fallbacks keep documents editable when a plugin is absent:
+ *  - unknown component after all plugins settled → default control for the type
+ *  - component registered but wrong field type   → default control for the type
+ *  - plugins still loading                       → empty placeholder (no
+ *    default-control flash that would swap out from under the user's cursor)
+ */
+export function createPluginRenderField(registry: PluginRegistry, next?: RenderField): RenderField {
+  return (args) => {
+    const component = args.field.component;
+    if (!component || !component.startsWith(PLUGIN_COMPONENT_PREFIX)) {
+      return next ? next(args) : undefined;
+    }
+    const record = registry.fieldComponent(component);
+    if (!record) {
+      if (!registry.settled()) return <React.Fragment />;
+      warnOnce(component, `[plugins] no plugin provides field component "${component}"; rendering the default control`);
+      return undefined;
+    }
+    if (!record.types.includes(args.field.type as any)) {
+      warnOnce(
+        `${component}:${args.field.type}`,
+        `[plugins] field component "${component}" (plugin ${record.pluginId}) does not accept type "${args.field.type}"; rendering the default control`
+      );
+      return undefined;
+    }
+    const Lazy = getLazyComponent(record.component);
+    return (
+      <Suspense fallback={<React.Fragment />}>
+        <Lazy
+          field={args.field}
+          value={args.value}
+          onChange={args.onChange}
+          readOnly={args.readOnly}
+          collab={args.collab}
+          path={args.path}
+        />
+      </Suspense>
+    );
+  };
+}

package/app/vendor/plugin-sdk/src/registry.ts

@@ -0,0 +1,337 @@
+// PluginRegistry collects every registration plugins make and is what the
+// hosts read contributions from. Mutations happen through per-plugin scoped
+// API instances (api()), so each record carries the plugin id that made it —
+// contributions are attributable and a plugin can never overwrite another's.
+//
+// The registry is host-agnostic and React-free; subscribe()/getVersion() fit
+// React's useSyncExternalStore so hosts re-render as plugins finish loading.
+
+import type {
+  CmsPluginApi,
+  PluginDocument,
+  PluginDocumentAction,
+  PluginFieldComponent,
+  PluginRoute,
+  PluginSidebarLink,
+  PluginStatus,
+  PluginUserMenuLink,
+} from "./types";
+
+// The schema prefix under which plugin field components are addressed
+// (display.component: "plugin:<name>"), whitelisted by the schema parser.
+export const PLUGIN_COMPONENT_PREFIX = "plugin:";
+
+// Bare field-component names: something a human can type after `plugin:` in a
+// hand-written schema without quoting surprises.
+const FIELD_NAME_RE = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
+export type PluginRouteRecord = PluginRoute & { pluginId: string };
+export type PluginSidebarLinkRecord = Required<Pick<PluginSidebarLink, "section">> &
+  PluginSidebarLink & { pluginId: string };
+export type PluginUserMenuLinkRecord = PluginUserMenuLink & { pluginId: string };
+export type PluginFieldComponentRecord = PluginFieldComponent & {
+  pluginId: string;
+  /** The schema-facing key: `plugin:<name>`. */
+  key: string;
+};
+export type PluginDocumentActionRecord = PluginDocumentAction & {
+  pluginId: string;
+  /** Host-facing key, unique across plugins: `<pluginId>:<action id>`. */
+  key: string;
+};
+
+export type PluginInfo = { id: string; status: PluginStatus; error?: string };
+
+export type RouteMatch = { record: PluginRouteRecord; params: Record<string, string> };
+
+// normalizePath trims slashes so "dashboard", "/dashboard" and "dashboard/"
+// all name the same route.
+const normalizePath = (p: string) => p.split("/").filter(Boolean).join("/");
+
+// A misbehaving plugin is worth exactly one console line, not one per render.
+// documentActionsFor runs on every toolbar render, so an `available` that
+// throws would otherwise flood the console.
+const warned = new Set<string>();
+function warnOnce(key: string, message: string) {
+  if (warned.has(key)) return;
+  warned.add(key);
+  console.warn(message);
+}
+
+/**
+ * Capabilities only the host can provide, injected at construction.
+ *
+ * Everything else on CmsPluginApi is bookkeeping the registry does itself. These
+ * are the calls that need the host's own session — so they are supplied rather
+ * than reached for, and a host that does not implement one gets a clear error
+ * instead of a plugin quietly reading a global.
+ */
+export type PluginHost = {
+  /**
+   * Mint a short-lived, repository-scoped preview token (see the CMS's
+   * POST /git/repositories/{id}/preview-token).
+   *
+   * Deliberately not "give me the user's access token": the credential a plugin
+   * holds should be the narrowest one that does its job, and this one is refused
+   * by every other CMS endpoint.
+   */
+  getPreviewToken?: (repositoryId: string) => Promise<string>;
+};
+
+export class PluginRegistry {
+  private host: PluginHost;
+  private routes: PluginRouteRecord[] = [];
+  private sidebarLinks: PluginSidebarLinkRecord[] = [];
+  private userMenuLinks: PluginUserMenuLinkRecord[] = [];
+  private fieldComponents = new Map<string, PluginFieldComponentRecord>();
+  private documentActions: PluginDocumentActionRecord[] = [];
+  private statuses = new Map<string, { status: PluginStatus; error?: string }>();
+  private listeners = new Set<() => void>();
+  private version = 0;
+
+  constructor(host: PluginHost = {}) {
+    this.host = host;
+  }
+
+  // --- change notification (useSyncExternalStore-shaped) --------------------
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  /** Monotonic version, bumped on every mutation — the store snapshot. */
+  getVersion = (): number => this.version;
+
+  private bump() {
+    this.version++;
+    for (const l of this.listeners) l();
+  }
+
+  // --- load state -----------------------------------------------------------
+
+  markPending(pluginId: string) {
+    this.statuses.set(pluginId, { status: "pending" });
+    this.bump();
+  }
+
+  markReady(pluginId: string) {
+    this.statuses.set(pluginId, { status: "ready" });
+    this.bump();
+  }
+
+  markFailed(pluginId: string, error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    this.statuses.set(pluginId, { status: "failed", error: message });
+    this.bump();
+  }
+
+  status(pluginId: string): PluginStatus | undefined {
+    return this.statuses.get(pluginId)?.status;
+  }
+
+  plugins(): PluginInfo[] {
+    return [...this.statuses.entries()].map(([id, s]) => ({ id, status: s.status, error: s.error }));
+  }
+
+  /** True once no plugin is still pending (vacuously true with none loaded). */
+  settled(): boolean {
+    return [...this.statuses.values()].every((s) => s.status !== "pending");
+  }
+
+  // --- scoped registration API ----------------------------------------------
+
+  /** The per-plugin CmsPluginApi handed to a plugin's setup function. */
+  api(pluginId: string): CmsPluginApi {
+    // Registrations funnel through one guard so a bad call from a plugin
+    // reports the offender and skips the record instead of throwing into the
+    // loader (which would fail the whole plugin over one bad link).
+    const registry = this;
+    return {
+      id: pluginId,
+      async getPreviewToken(repositoryId: string): Promise<string> {
+        const mint = registry.host.getPreviewToken;
+        if (!mint) {
+          // A plugin asking for one in a host that cannot mint them is a
+          // configuration problem, and the plugin's own error message ("the
+          // preview service refused the session") would hide it.
+          throw new Error(
+            `[plugin ${pluginId}] getPreviewToken: this host does not provide preview tokens`,
+          );
+        }
+        if (!repositoryId) {
+          throw new Error(`[plugin ${pluginId}] getPreviewToken: repositoryId is required`);
+        }
+        return mint(repositoryId);
+      },
+      addRoute(route: PluginRoute) {
+        const path = normalizePath(route.path ?? "");
+        if (typeof route.component !== "function") {
+          console.error(`[plugin ${pluginId}] addRoute("${route.path}"): component must be a loader function`);
+          return;
+        }
+        if (registry.routes.some((r) => r.pluginId === pluginId && r.path === path)) {
+          console.error(`[plugin ${pluginId}] addRoute: duplicate route path "${path}" ignored`);
+          return;
+        }
+        registry.routes.push({ ...route, path, pluginId });
+        registry.bump();
+      },
+      addSidebarLink(link: PluginSidebarLink) {
+        if (!link.label || !link.to) {
+          console.error(`[plugin ${pluginId}] addSidebarLink: label and to are required`);
+          return;
+        }
+        registry.sidebarLinks.push({
+          ...link,
+          to: normalizePath(link.to),
+          section: link.section || "Plugins",
+          pluginId,
+        });
+        registry.bump();
+      },
+      addUserMenuLink(link: PluginUserMenuLink) {
+        const forms = [link.to, link.onSelect].filter((x) => x != null).length;
+        if (!link.label || forms !== 1) {
+          console.error(`[plugin ${pluginId}] addUserMenuLink: label plus exactly one of to/onSelect required`);
+          return;
+        }
+        registry.userMenuLinks.push({
+          ...link,
+          to: link.to != null ? normalizePath(link.to) : undefined,
+          pluginId,
+        });
+        registry.bump();
+      },
+      registerFieldComponent(reg: PluginFieldComponent) {
+        if (!FIELD_NAME_RE.test(reg.name ?? "")) {
+          console.error(
+            `[plugin ${pluginId}] registerFieldComponent: invalid name ${JSON.stringify(reg.name)} (want ${FIELD_NAME_RE})`
+          );
+          return;
+        }
+        if (typeof reg.component !== "function") {
+          console.error(`[plugin ${pluginId}] registerFieldComponent("${reg.name}"): component must be a loader function`);
+          return;
+        }
+        const key = PLUGIN_COMPONENT_PREFIX + reg.name;
+        const existing = registry.fieldComponents.get(key);
+        if (existing) {
+          // One global namespace: first registration wins so an installed,
+          // working schema doesn't change meaning when a second plugin lands.
+          console.error(
+            `[plugin ${pluginId}] registerFieldComponent: "${key}" already registered by plugin ${existing.pluginId}; ignored`
+          );
+          return;
+        }
+        registry.fieldComponents.set(key, { ...reg, types: [...reg.types], pluginId, key });
+        registry.bump();
+      },
+      addDocumentAction(action: PluginDocumentAction) {
+        if (!FIELD_NAME_RE.test(action.id ?? "")) {
+          console.error(
+            `[plugin ${pluginId}] addDocumentAction: invalid id ${JSON.stringify(action.id)} (want ${FIELD_NAME_RE})`
+          );
+          return;
+        }
+        if (!action.label) {
+          console.error(`[plugin ${pluginId}] addDocumentAction("${action.id}"): label is required`);
+          return;
+        }
+        if (typeof action.onSelect !== "function") {
+          console.error(`[plugin ${pluginId}] addDocumentAction("${action.id}"): onSelect must be a function`);
+          return;
+        }
+        const key = `${pluginId}:${action.id}`;
+        if (registry.documentActions.some((a) => a.key === key)) {
+          console.error(`[plugin ${pluginId}] addDocumentAction: duplicate id "${action.id}" ignored`);
+          return;
+        }
+        registry.documentActions.push({
+          ...action,
+          collections: action.collections ? [...action.collections] : undefined,
+          pluginId,
+          key,
+        });
+        registry.bump();
+      },
+    };
+  }
+
+  // --- queries the hosts render from ----------------------------------------
+
+  /** Field component for a schema `display.component` key ("plugin:<name>"). */
+  fieldComponent(key: string): PluginFieldComponentRecord | undefined {
+    return this.fieldComponents.get(key);
+  }
+
+  sidebar(): PluginSidebarLinkRecord[] {
+    return [...this.sidebarLinks];
+  }
+
+  /**
+   * Toolbar actions that apply to one document, in registration order.
+   *
+   * Both filters are applied here rather than in each host: `collections`
+   * (cheap, declarative) and then the action's own `available` predicate. An
+   * `available` that throws is treated as "not available" and reported once —
+   * a plugin bug should cost its own button, not the whole toolbar.
+   */
+  documentActionsFor(doc: PluginDocument): PluginDocumentActionRecord[] {
+    return this.documentActions.filter((a) => {
+      if (a.collections && !a.collections.includes(doc.collection)) return false;
+      if (!a.available) return true;
+      try {
+        return a.available(doc);
+      } catch (err) {
+        warnOnce(
+          `available:${a.key}`,
+          `[plugin ${a.pluginId}] document action "${a.id}" available() threw; hiding the button: ${String(err)}`
+        );
+        return false;
+      }
+    });
+  }
+
+  userMenu(): PluginUserMenuLinkRecord[] {
+    return [...this.userMenuLinks];
+  }
+
+  routesFor(pluginId: string): PluginRouteRecord[] {
+    return this.routes.filter((r) => r.pluginId === pluginId);
+  }
+
+  /**
+   * Match a subpath against a plugin's registered routes. `:segment` patterns
+   * capture into params; among routes that match, the one with the most static
+   * segments wins (so "reports/summary" beats "reports/:kind").
+   */
+  matchRoute(pluginId: string, subpath: string): RouteMatch | null {
+    const segs = normalizePath(subpath).split("/").filter(Boolean);
+    let best: RouteMatch | null = null;
+    let bestStatic = -1;
+    for (const record of this.routes) {
+      if (record.pluginId !== pluginId) continue;
+      const patSegs = record.path.split("/").filter(Boolean);
+      if (patSegs.length !== segs.length) continue;
+      const params: Record<string, string> = {};
+      let staticCount = 0;
+      let ok = true;
+      for (let i = 0; i < patSegs.length; i++) {
+        if (patSegs[i].startsWith(":")) {
+          params[patSegs[i].slice(1)] = segs[i];
+        } else if (patSegs[i] === segs[i]) {
+          staticCount++;
+        } else {
+          ok = false;
+          break;
+        }
+      }
+      if (ok && staticCount > bestStatic) {
+        best = { record, params };
+        bestStatic = staticCount;
+      }
+    }
+    return best;
+  }
+}