@synap-core/workspace-templates 0.6.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synap-core/workspace-templates",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "type": "module",
   "packageManager": "pnpm@9.15.4",
   "description": "Canonical workspace definitions — YAML source + typed exports for browser, backend, CLI, and marketplace",
@@ -18,10 +18,11 @@
   "scripts": {
     "type-check": "tsc --noEmit",
     "build:yaml": "node build.mjs",
-    "build": "node build.mjs && tsup",
+    "check:converters": "node scripts/check-converters.mjs",
+    "build": "node build.mjs && tsup && node scripts/check-converters.mjs",
     "provision": "node scripts/provision.mjs",
     "eval": "node scripts/eval-standard.mjs",
-    "prepublishOnly": "node build.mjs && tsup"
+    "prepublishOnly": "node build.mjs && tsup && node scripts/check-converters.mjs"
   },
   "dependencies": {
     "zod": "^3.0.0",

package/src/agent-fleet.yaml

@@ -895,28 +895,36 @@ displayTemplates:
 bento:
   viewName: "Agent Fleet Home"
   blocks:
-    - widgetType: welcome-header
+    - kind: widget
+      widgetType: welcome-header
       pos: { x: 0, y: 0, w: 12, h: 2 }
       config: { title: "Agent Fleet", subtitle: "Your sovereign control plane for the agent fleet." }
-    - widgetType: entity-count
+    - kind: widget
+      widgetType: entity-count
       pos: { x: 0, y: 2, w: 3, h: 2 }
       config: { profileSlug: agent, label: Agents, icon: bot }
-    - widgetType: entity-count
+    - kind: widget
+      widgetType: entity-count
       pos: { x: 3, y: 2, w: 3, h: 2 }
       config: { profileSlug: task, label: Tasks, icon: check-square }
-    - widgetType: entity-count
+    - kind: widget
+      widgetType: entity-count
       pos: { x: 6, y: 2, w: 3, h: 2 }
       config: { profileSlug: skill, label: Skills, icon: zap }
-    - widgetType: entity-count
+    - kind: widget
+      widgetType: entity-count
       pos: { x: 9, y: 2, w: 3, h: 2 }
       config: { profileSlug: provider, label: Providers, icon: database }
-    - widgetType: entity-spotlight
+    - kind: widget
+      widgetType: entity-spotlight
       pos: { x: 0, y: 4, w: 4, h: 4 }
       config: { profileSlug: agent, seed: random, layout: detail, subtitleField: status, color: "#1A3A5C" }
-    - widgetType: entity-list
+    - kind: widget
+      widgetType: entity-list
       pos: { x: 4, y: 4, w: 4, h: 4 }
       config: { profileSlug: task, title: "Active Tasks", limit: 6, variant: compact }
-    - widgetType: entity-list
+    - kind: widget
+      widgetType: entity-list
       pos: { x: 8, y: 4, w: 4, h: 4 }
       config: { profileSlug: skill, title: "Top Skills", limit: 6, variant: compact }
     - kind: view

package/src/catalog.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Unit tests for the mergeCatalog door. Run: `npx tsx --test src/catalog.test.ts`
+ *
+ * These test the SOURCE (`./catalog.js` → catalog.ts), never `dist/`, so no build
+ * is required and there is no stale-generated-output trap.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mergeCatalog, type RemoteEntry } from "./catalog.js";
+import type { WorkspaceYaml } from "./types.js";
+
+const BUNDLE_VERSION = "0.6.0";
+
+/** Minimal bundled template — only the fields the door reads. */
+function bundled(slug: string, extra?: Partial<WorkspaceYaml["meta"]>): WorkspaceYaml {
+  return {
+    meta: { slug, name: slug, description: `${slug} desc`, icon: "layers", color: "#fff", ...extra },
+    workspace: { name: slug, description: "" },
+    profiles: [],
+  } as WorkspaceYaml;
+}
+
+/** Minimal CP row. `version` (when given) lands at definition.sourcePackage.version. */
+function remote(slug: string, opts?: { version?: string; isPrivate?: boolean }): RemoteEntry {
+  return {
+    slug,
+    name: slug,
+    description: `${slug} remote`,
+    category: "workspace",
+    tags: [],
+    isPrivate: opts?.isPrivate,
+    definition:
+      opts?.version !== undefined
+        ? { sourcePackage: { name: "@synap-core/workspace-templates", version: opts.version } }
+        : undefined,
+  };
+}
+
+// ── Dedupe by slug ──────────────────────────────────────────────────────────
+// MUTATION PROOF: change the dedupe key to `slug@version` and this count goes to
+// 2 (bundled "1.0.0"-implied vs remote) → RED.
+test("dedupes a slug present in both sources into ONE entry", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm"), bundled("legal")],
+    remote: [remote("crm", { version: "0.5.0" }), remote("legal", { version: "0.5.0" })],
+    bundleVersion: BUNDLE_VERSION,
+  });
+  assert.equal(entries.length, 2, "two slugs, deduped");
+  assert.equal(entries.filter((e) => e.slug === "crm").length, 1);
+});
+
+// ── Winner rule ─────────────────────────────────────────────────────────────
+test("bundle wins when remote version EQUALS the bundle", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [remote("crm", { version: BUNDLE_VERSION })],
+    bundleVersion: BUNDLE_VERSION,
+  });
+  assert.equal(entries[0].source, "bundled");
+});
+
+test("bundle wins when remote version is OLDER", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [remote("crm", { version: "0.5.0" })],
+    bundleVersion: BUNDLE_VERSION,
+  });
+  assert.equal(entries[0].source, "bundled");
+});
+
+// MUTATION PROOF: flip `remoteIsStrictlyNewer`'s comparison (`>` → `<`, or return
+// false) and this assertion (source === "remote") goes RED.
+test("remote wins when it is STRICTLY newer (this client is stale)", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [remote("crm", { version: "0.7.0" })],
+    bundleVersion: BUNDLE_VERSION,
+  });
+  assert.equal(entries[0].source, "remote");
+});
+
+// ── Third-party & squatting ─────────────────────────────────────────────────
+test("a non-colliding remote slug is kept as a DISTINCT entry", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [remote("acme-widget")], // no sourcePackage, no bundled twin
+    bundleVersion: BUNDLE_VERSION,
+  });
+  assert.equal(entries.length, 2);
+  const acme = entries.find((e) => e.slug === "acme-widget");
+  assert.equal(acme?.source, "remote");
+  assert.equal(acme?.isPrivate, false, "browse rows default public");
+});
+
+test("a third-party row SQUATTING an official slug (no sourcePackage) loses to the bundle", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [remote("crm")], // slug collision, NO sourcePackage → squatting
+    bundleVersion: BUNDLE_VERSION,
+  });
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0].source, "bundled");
+});
+
+// ── sources degradation (load-bearing) ──────────────────────────────────────
+test("remote unreachable → returns bundled only + honest source status", () => {
+  const { entries, sources } = mergeCatalog({
+    bundled: [bundled("crm"), bundled("legal")],
+    remote: [], // fetch failed → empty
+    bundleVersion: BUNDLE_VERSION,
+    remoteStatus: "unreachable",
+  });
+  assert.equal(entries.length, 2, "still shows all bundled");
+  assert.equal(sources.bundled, "ok");
+  assert.equal(sources.remote, "unreachable");
+});
+
+test("remote unauthenticated → status surfaced; any stray remote rows are ignored", () => {
+  const { entries, sources } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [remote("private-pack", { isPrivate: true })], // must NOT be merged
+    bundleVersion: BUNDLE_VERSION,
+    remoteStatus: "unauthenticated",
+  });
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0].slug, "crm");
+  assert.equal(sources.remote, "unauthenticated");
+});
+
+test("private remote packages merge when reachable and carry isPrivate", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [remote("private-pack", { isPrivate: true })],
+    bundleVersion: BUNDLE_VERSION,
+    remoteStatus: "ok",
+  });
+  const priv = entries.find((e) => e.slug === "private-pack");
+  assert.equal(priv?.source, "remote");
+  assert.equal(priv?.isPrivate, true);
+});
+
+// ── Real bundled data shape (integration-ish) ───────────────────────────────
+test("maps a bundled template's meta fields onto the entry", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm", { icon: "handshake", tags: ["crm", "sales"], isPublic: false })],
+    remote: [],
+    bundleVersion: BUNDLE_VERSION,
+  });
+  const e = entries[0];
+  assert.equal(e.source, "bundled");
+  assert.equal(e.icon, "handshake");
+  assert.deepEqual(e.tags, ["crm", "sales"]);
+  assert.equal(e.category, "workspace");
+  assert.equal(e.isPrivate, true, "isPublic:false ⇒ isPrivate");
+});

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 },
+  };
+}

package/src/communication.yaml

@@ -28,8 +28,35 @@ workspace:
     - brand.templates
     - brand.components
     - narrative.positioning
+  # Communication CONSUMES brand and PROVIDES narrative.
+  #
+  # `brand: provider` here was a LIVE bug, not dead metadata. brand-library.yaml
+  # also declares `brand: provider`, and the IS reads this to pick which
+  # workspace supplies brand for EVERY agent's system prompt
+  # (`resolveWorkspaceForCapability` in agents/utils/context-manager.ts): it
+  # filters candidates by the `brand.library` capability, then takes the FIRST
+  # workspace whose sourceRoles.brand is a provider. With both installed, "first"
+  # is whatever order listWorkspaces returned — an arbitrary, non-deterministic
+  # brand voice across turns. brand-library is the canonical brand source (this
+  # file's brand profiles are, by its own admission below, verbatim from it);
+  # Communication is the narrative/voice layer that reads from it.
+  #
+  # Every other domain in this template set has exactly ONE provider and names
+  # its consumers (content-studio: `brand: consumer`; marketing: `brand: consumer`).
+  # `brand` was the only domain with two. This restores that invariant.
+  #
+  # Expressed as a source ROLE, not `defaultSources.brand`, because a
+  # TemplateDefaultSource requires a concrete `workspaceId` (types.ts) that does
+  # not exist until provisioning — a template cannot know it. finance.yaml makes
+  # the same call for `strategy` and says so. `defaultSources` remains the
+  # correct RUNTIME override (`synap_declare_workspace_source`).
+  #
+  # The `brand.library` capability above is deliberately KEPT: it is what the
+  # resolver filters candidates on, and it makes this workspace a graceful
+  # fallback (step 3) when brand-library is not installed — in which case the
+  # local brand profiles below are exactly what the agent should read.
   sourceRoles:
-    brand: provider
+    brand: consumer
     narrative: provider
 
 profiles: