@synap-core/workspace-templates 0.5.0 → 0.6.1

package/src/catalog.ts

@@ -0,0 +1,285 @@
+/**
+ * mergeCatalog — the ONE merge door for the workspace-template catalog.
+ * ====================================================================
+ *
+ * Both marketplace entry points (browser + CLI) and the pod need to show ONE
+ * list of installable workspace templates drawn from TWO sources:
+ *
+ *   1. BUNDLED — the canonical `@synap-core/workspace-templates` package that
+ *      ships inside every client (this package). Always present, zero network.
+ *   2. REMOTE  — rows in the control-plane package registry (`GET /api/packages`),
+ *      which includes both the official templates re-published by
+ *      `seed-templates.ts` AND private / third-party packages that never shipped
+ *      in the bundle.
+ *
+ * The two overlap: every official template exists in BOTH sources (once bundled,
+ * once seeded to the CP). Naively concatenating them shows 21 duplicate cards.
+ * `mergeCatalog` de-dupes them into ONE catalog with a deterministic winner.
+ *
+ * WHY THIS LIVES HERE (and is PURE):
+ *   This is the ONLY module the root `pnpm-workspace.yaml` lets `synap-cli`,
+ *   `browser`, `synap-control-plane-api`, AND `synap-backend/packages/api` all
+ *   resolve. `@synap-core/marketplace` pulls React and is `private: true`, so the
+ *   Node CLI cannot import it. Keep this file pure data — no fetch, no auth, no
+ *   React, no Node-only APIs. Each entry point has a DIFFERENT transport (browser
+ *   cookie/`cpFetch`, CLI Bearer, pod anonymous); a door that fetched would force
+ *   ONE auth model on all three and become the next lossy seam. Transport lives
+ *   in the consumers; this door only merges arrays they already fetched.
+ */
+
+import type { WorkspaceYaml } from "./types.js";
+
+// ============================================================================
+// Inputs
+// ============================================================================
+
+/**
+ * A bundled template — the canonical `WorkspaceYaml` this package ships. Callers
+ * pass `listPublicTemplates()` (18) or `listWorkspaceTemplates()` (21); the door
+ * merges whatever it is given and does NOT filter (see the publicity note below).
+ */
+export type BundledEntry = WorkspaceYaml;
+
+/**
+ * A control-plane registry row, mapped into the minimal shape the door needs.
+ * Consumers build this from a `MarketplacePackage` (browser) / the CP
+ * `GET /api/packages` JSON (CLI) — a thin, transport-specific projection.
+ *
+ * `definition` is carried OPAQUE: it is both (a) the install payload the consumer
+ * feeds back to the pod, and (b) the home of the ONE comparable version signal,
+ * `definition.sourcePackage.version` — the real npm semver of the published
+ * `@synap-core/workspace-templates` build that generated an official row
+ * (`seed-templates.ts` stamps it). The door only reads that one nested field; the
+ * rest of `definition` is passed through untouched.
+ */
+export interface RemoteEntry {
+  slug: string;
+  name: string;
+  description?: string;
+  /** CP package category / type (e.g. `"workspace"`, `"view"`). */
+  category?: string;
+  tags?: string[];
+  icon?: string | null;
+  /**
+   * `true` when the CP row is not publicly listed (`isPublic === false`). Browse
+   * rows leave this `undefined` BY CONSTRUCTION — the browse route hard-filters
+   * `WHERE is_public = true`, so every browse row is public; `undefined` ⇒ public,
+   * never "unknown-so-hide".
+   */
+  isPrivate?: boolean;
+  /**
+   * The CP `definition` jsonb — opaque install payload. The door reads only
+   * `definition.sourcePackage.version` (the winner signal). Absent on browse rows
+   * (the list route strips `definition`), which is fine: absence ⇒ bundle wins.
+   */
+  definition?: {
+    sourcePackage?: { name?: string; version?: string };
+    [k: string]: unknown;
+  };
+}
+
+/** Whether the caller could reach / authenticate against the remote source. */
+export type RemoteSourceStatus = "ok" | "unauthenticated" | "unreachable";
+
+export interface MergeCatalogInput {
+  /** Bundled templates (this package). Always "ok" — it is in-process data. */
+  bundled: BundledEntry[];
+  /** Already-fetched CP rows. Empty/omitted when the fetch failed. */
+  remote?: RemoteEntry[];
+  /**
+   * This client's bundled-package version (`package.json` `version`, live `0.6.0`).
+   * Compared against each remote row's `sourcePackage.version` to decide whether
+   * THIS client's bundle is stale. Callers pass the compiled-in package version.
+   */
+  bundleVersion: string;
+  /**
+   * The transport's verdict on the remote fetch. `"ok"` (default) ⇒ merge the
+   * `remote` array. `"unauthenticated"` / `"unreachable"` ⇒ ignore `remote` and
+   * surface the degradation in `sources.remote`, so the consumer can render
+   * "18 available — private ones need login" instead of FAILING OPEN EMPTY.
+   */
+  remoteStatus?: RemoteSourceStatus;
+}
+
+// ============================================================================
+// Output
+// ============================================================================
+
+interface CatalogEntryBase {
+  slug: string;
+  name: string;
+  description?: string;
+  /** Package category / type. Bundled templates are always `"workspace"`. */
+  category?: string;
+  tags: string[];
+  icon?: string | null;
+  /** `true` ⇒ not publicly listed (internal bundled template, or private CP row). */
+  isPrivate: boolean;
+}
+
+/** A catalog entry backed by a bundled template. Install via `toWorkspaceDefinition()` / `toPackageDefinition()` on `template`. */
+export interface BundledCatalogEntry extends CatalogEntryBase {
+  source: "bundled";
+  template: WorkspaceYaml;
+}
+
+/** A catalog entry backed by a CP registry row. Install from `remote.definition`. */
+export interface RemoteCatalogEntry extends CatalogEntryBase {
+  source: "remote";
+  remote: RemoteEntry;
+}
+
+/** One merged card. `source` discriminates the install path; common fields feed a picker. */
+export type CatalogEntry = BundledCatalogEntry | RemoteCatalogEntry;
+
+export interface MergeCatalogResult {
+  entries: CatalogEntry[];
+  /**
+   * Per-source health. LOAD-BEARING, not decoration: it is what lets a consumer
+   * distinguish "remote returned nothing" from "remote unreachable" and avoid the
+   * FAILS-OPEN-EMPTY trap (agent sees empty catalog → thinks pod is empty → dupes).
+   */
+  sources: { bundled: "ok"; remote: RemoteSourceStatus };
+}
+
+// ============================================================================
+// Winner signal
+// ============================================================================
+
+function parseSemver(v: string | undefined): [number, number, number] | null {
+  if (!v) return null;
+  const m = /^\s*v?(\d+)\.(\d+)\.(\d+)/.exec(v);
+  if (!m) return null; // e.g. a range string ("range:>=0.6.0 <1.0.0") — not a version
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * Is the remote row STRICTLY newer than this client's bundle? Only then does the
+ * remote win a slug conflict — it means THIS client is stale and the CP has a
+ * fresher official build. Every other case (equal, older, unparseable, or no
+ * `sourcePackage` at all) ⇒ `false` ⇒ BUNDLE WINS. That default is correct four
+ * ways, strongest last: (1) the CP is provably staler in the common case; (2) the
+ * CP row is a lossy re-encode of the bundle; (3) zero network; (4) the pod's boot
+ * reconcile already converges every workspace to the BUNDLED shape — bundle-wins
+ * agrees with the reconciler; CP-wins would fight it every boot.
+ */
+function remoteIsStrictlyNewer(
+  remoteVersion: string | undefined,
+  bundleVersion: string,
+): boolean {
+  const r = parseSemver(remoteVersion);
+  const b = parseSemver(bundleVersion);
+  if (!r || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (r[i] > b[i]) return true;
+    if (r[i] < b[i]) return false;
+  }
+  return false; // equal ⇒ not strictly newer ⇒ bundle wins
+}
+
+// ============================================================================
+// Mapping
+// ============================================================================
+
+function bundledToEntry(tpl: WorkspaceYaml): BundledCatalogEntry {
+  return {
+    source: "bundled",
+    slug: tpl.meta.slug,
+    name: tpl.meta.name,
+    description: tpl.meta.description,
+    // Every bundled template is a full workspace — the CP calls this category
+    // "workspace" (PACKAGE_TYPES). Finer display grouping is derived from `tags`
+    // by the consumer (browser `categoryFor`), not baked in here.
+    category: "workspace",
+    tags: tpl.meta.tags ?? [],
+    icon: tpl.meta.icon,
+    isPrivate: tpl.meta.isPublic === false,
+    template: tpl,
+  };
+}
+
+function remoteToEntry(row: RemoteEntry): RemoteCatalogEntry {
+  return {
+    source: "remote",
+    slug: row.slug,
+    name: row.name,
+    description: row.description,
+    category: row.category,
+    tags: row.tags ?? [],
+    icon: row.icon ?? null,
+    isPrivate: row.isPrivate ?? false,
+    remote: row,
+  };
+}
+
+// ============================================================================
+// The door
+// ============================================================================
+
+/**
+ * Merge bundled + remote template catalogs into ONE de-duplicated list.
+ *
+ * DEDUPE KEY = `slug` — NOT `slug@version`. This is forced by the live data, not
+ * a preference: every CP flagship row is hardcoded `version: "1.0.0"`
+ * (`seed-templates.ts`) and `TemplateMeta` carries NO version field at all, so a
+ * `slug@version` key would collide on nothing → 21 duplicate cards. The real
+ * per-build version lives only in `definition.sourcePackage.version`, which is
+ * the WINNER signal, never the identity key.
+ *
+ * CONFLICT RESOLUTION (remote slug already claimed by a bundled template):
+ *   • remote `sourcePackage.version` strictly > `bundleVersion` → remote wins
+ *     (this client is stale — the CP has a fresher official build).
+ *   • otherwise (equal / older / no `sourcePackage`) → BUNDLE wins. The
+ *     no-`sourcePackage` case is a third-party package SQUATTING an official slug;
+ *     the bundle wins unconditionally (squatting defense).
+ *
+ * A remote slug that does NOT collide with any bundled template is a DISTINCT
+ * entry (a private or third-party package) and is always kept.
+ */
+export function mergeCatalog(input: MergeCatalogInput): MergeCatalogResult {
+  const { bundled, bundleVersion } = input;
+  const remoteStatus: RemoteSourceStatus = input.remoteStatus ?? "ok";
+  const remote = input.remote ?? [];
+
+  // Insertion-ordered map keyed by slug. Bundled entries seed it first, so they
+  // are the default winner; a qualifying remote row overwrites in place.
+  const bySlug = new Map<string, CatalogEntry>();
+
+  for (const tpl of bundled) {
+    bySlug.set(tpl.meta.slug, bundledToEntry(tpl));
+  }
+
+  // Only fold in remote rows when the transport actually reached the source.
+  // A failed fetch must NOT silently look like "the CP has no templates".
+  if (remoteStatus === "ok") {
+    for (const row of remote) {
+      const existing = bySlug.get(row.slug);
+
+      if (!existing) {
+        // No bundled template owns this slug → distinct (private / third-party).
+        bySlug.set(row.slug, remoteToEntry(row));
+        continue;
+      }
+
+      if (existing.source !== "bundled") {
+        // Two remote rows with the same slug (shouldn't happen — CP slugs are
+        // unique) — keep the first, defensively.
+        continue;
+      }
+
+      // Slug conflict with an official bundled template. Remote wins ONLY if it
+      // is a strictly-newer official build; else the bundle stays (older, equal,
+      // or a squatting third-party with no sourcePackage).
+      const remoteVersion = row.definition?.sourcePackage?.version;
+      if (remoteIsStrictlyNewer(remoteVersion, bundleVersion)) {
+        bySlug.set(row.slug, remoteToEntry(row));
+      }
+      // else: no-op — bundled entry already in place wins.
+    }
+  }
+
+  return {
+    entries: [...bySlug.values()],
+    sources: { bundled: "ok", remote: remoteStatus },
+  };
+}