@synap-core/workspace-templates 0.12.0 → 0.24.0

package/src/publish-body.d.mts

@@ -0,0 +1,29 @@
+/** Types for `publish-body.mjs` — the official-template publish body builder. */
+import type { PackageDefinitionOutput } from './define';
+
+export interface OfficialPublishBody {
+  slug: string;
+  displayName: string;
+  description?: string;
+  isPublic: boolean;
+  tags: string[];
+  category: 'workspace';
+  requiredTier?: string;
+  vendorId: string;
+  /** `toPackageDefinition()` minus `_meta`, plus `_meta.icon`/`color`/`domain` mirrored on top. */
+  definition: Omit<PackageDefinitionOutput, '_meta'> & {
+    icon?: string;
+    color?: string;
+    domain?: string;
+    /** Which build of this package generated the row — the catalog winner signal. */
+    sourcePackage: { name: string; version: string };
+  };
+}
+
+/** This package's own `{ name, version }` (from its package.json). */
+export declare const OFFICIAL_SOURCE_PACKAGE: Readonly<{ name: string; version: string }>;
+
+export declare function toOfficialPublishBody(
+  pd: PackageDefinitionOutput,
+  vendorId: string,
+): OfficialPublishBody;

package/src/publish-body.mjs

@@ -0,0 +1,74 @@
+import { readFileSync } from 'node:fs';
+
+/**
+ * Provenance every official row carries: WHICH build of this package generated
+ * it. Read from this package's own `package.json`, so a caller can never forget
+ * or misstate it.
+ *
+ * WHY: clients (CLI, browser) merge the catalog with their own frozen bundle
+ * through `mergeCatalog`, where the bundle wins unless the remote row's
+ * `definition.sourcePackage.version` is STRICTLY newer. A row with no
+ * `sourcePackage` therefore lost to every stale client bundle — the CLI then
+ * installed its old copy of content-os (no `primarySurface`) onto a live space.
+ * Bump this package's version whenever template content changes, so a fresh
+ * official row outranks every older bundle (`synap-market` skill).
+ *
+ * The CP excludes `sourcePackage` from the content hash (`templateContentHash`),
+ * so a version bump alone never changes a row's `h-` version.
+ */
+export const OFFICIAL_SOURCE_PACKAGE = Object.freeze(
+  (() => {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    if (!pkg.name || !pkg.version) throw new Error('workspace-templates package.json has no name/version');
+    return { name: pkg.name, version: pkg.version };
+  })(),
+);
+
+/**
+ * The ONE builder of the `POST {CP}/api/packages` body for an official
+ * workspace template. `scripts/publish-official-lib.mjs` (the ONE official-publish
+ * implementation, behind `synap market publish --official` and the CI wrapper
+ * `scripts/publish-official.mjs`) calls it; `publish-body.test.ts` drives it from the REAL `toPackageDefinition`
+ * output so the wire shape is tested, not re-typed.
+ *
+ * WHY icon/color/domain ARE MIRRORED ONTO `definition`
+ * ====================================================
+ * `toPackageDefinition` carries the template's identity (icon, colour, domain)
+ * ONLY in `_meta`, and `_meta` is hoisted to row columns here (slug, name,
+ * tags…), so it does not travel inside `definition`. The CP door reads the
+ * row's `icon`/`domain` columns and the stored `definition.icon`/`.color` from
+ * the definition's TOP-LEVEL fields (`publishPackageCore` +
+ * `normalizePublishedDefinition`); with nothing there it fell back to
+ * `icon: "layers"` / `color: "#6366F1"` and a NULL icon column — which is how
+ * 26/28 official catalog rows lost their own icon and colour. The CLI
+ * (`synap-cli/src/lib/cp-packages.ts`) already mirrors them; this is the same
+ * shape.
+ *
+ * @param {import('./define').PackageDefinitionOutput} pd  `toPackageDefinition()` output
+ * @param {string} vendorId  the `synap-official` vendor id
+ */
+export function toOfficialPublishBody(pd, vendorId) {
+  const { _meta, ...rest } = pd;
+  const definition = {
+    ...rest,
+    ...(_meta.icon !== undefined ? { icon: _meta.icon } : {}),
+    ...(_meta.color !== undefined ? { color: _meta.color } : {}),
+    ...(_meta.domain !== undefined ? { domain: _meta.domain } : {}),
+    sourcePackage: { ...OFFICIAL_SOURCE_PACKAGE },
+  };
+  return {
+    slug: _meta.slug,
+    // The package's own name — an overlay's workspaceName is its TARGET's name
+    // (business-model composes onto Foundation/Strategy and was listed as "Foundation").
+    displayName: _meta.name ?? pd.workspaceName,
+    // Same reason: the catalog lists the PACKAGE's description (meta), not the
+    // overlay target's workspace description ("Adds … to Foundation").
+    description: _meta.description ?? pd.description,
+    isPublic: _meta.isPublic ?? true,
+    tags: _meta.tags ?? [],
+    category: 'workspace',
+    ...(_meta.requiredTier ? { requiredTier: _meta.requiredTier } : {}),
+    vendorId,
+    definition,
+  };
+}

package/src/publish-body.test.ts

@@ -0,0 +1,74 @@
+/**
+ * The official publish body carries each template's OWN identity.
+ *
+ * Defect this guards: `publish-official.mjs` posted `toPackageDefinition()`
+ * minus `_meta` with nothing mirrored, so the CP door found no top-level
+ * `icon`/`color` and stored `icon: "layers"` / `color: "#6366F1"` with a NULL
+ * icon column — 26/28 official catalog rows lost their icon and colour.
+ *
+ * Driven from the REAL corpus (every `src/*.yaml`) through the REAL
+ * `toPackageDefinition` into the REAL body builder the script calls — nothing
+ * hand-built between them. The CP half of the seam (body → publishPackageCore →
+ * stored row) is `synap-control-plane-api/src/seeds/publish-package-core.icon.test.ts`.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { readYamlTemplates } from './generate.mjs';
+import { toOfficialPublishBody } from './publish-body.mjs';
+import { toPackageDefinition } from './define';
+import type { WorkspaceYaml } from './types';
+import { readFileSync } from 'node:fs';
+import { mergeCatalog } from './catalog';
+
+const corpus = readYamlTemplates();
+
+describe('toOfficialPublishBody', () => {
+  it('reads a plausible corpus (non-vacuity)', () => {
+    expect(corpus.length).toBeGreaterThanOrEqual(25);
+  });
+
+  it("mirrors every template's own icon / colour / domain onto the definition", () => {
+    const wrong: string[] = [];
+    let withIcon = 0;
+    for (const t of corpus) {
+      const tpl = t.data as WorkspaceYaml;
+      const body = toOfficialPublishBody(toPackageDefinition(tpl), 'vendor-x');
+      const meta = tpl.meta as { icon?: string; color?: string; domain?: string };
+      if (meta.icon) withIcon++;
+      if (body.definition.icon !== meta.icon) wrong.push(`${t.slug}.icon`);
+      if (body.definition.color !== meta.color) wrong.push(`${t.slug}.color`);
+      if (body.definition.domain !== meta.domain) wrong.push(`${t.slug}.domain`);
+      // `_meta` is hoisted to columns, never sent inside the definition.
+      expect('_meta' in body.definition).toBe(false);
+      expect(body.slug).toBe(tpl.meta.slug);
+      expect(body.vendorId).toBe('vendor-x');
+    }
+    expect(wrong).toEqual([]);
+    // Non-vacuity: the corpus actually declares icons, so the equality above
+    // cannot pass by comparing undefined to undefined everywhere.
+    expect(withIcon).toBe(corpus.length);
+  });
+
+  // Incident 2026-10-06: official rows carried NO `definition.sourcePackage`,
+  // so `mergeCatalog` let every stale client bundle win (the CLI installed its
+  // old content-os — no primarySurface — onto a live space).
+  it("stamps this package's own name + version as definition.sourcePackage", () => {
+    const own = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    expect(own.version).toMatch(/^\d+\.\d+\.\d+/);
+    for (const t of corpus) {
+      const body = toOfficialPublishBody(toPackageDefinition(t.data as WorkspaceYaml), 'vendor-x');
+      expect(body.definition.sourcePackage).toEqual({ name: '@synap-core/workspace-templates', version: own.version });
+    }
+  });
+
+  it('a published row outranks an OLDER client bundle through the real merge door', () => {
+    const tpl = corpus.find((t) => t.slug === 'content-os')!.data as WorkspaceYaml;
+    const body = toOfficialPublishBody(toPackageDefinition(tpl), 'vendor-x');
+    const merged = mergeCatalog({
+      bundled: [tpl],
+      remote: [{ slug: body.slug, name: body.displayName, definition: body.definition }],
+      bundleVersion: '0.0.1',
+    });
+    expect(merged.entries.find((e) => e.slug === 'content-os')?.source).toBe('remote');
+  });
+});

package/src/publish-official-lib.test.ts

@@ -0,0 +1,176 @@
+/**
+ * The ONE official-publish implementation (`scripts/publish-official-lib.mjs`),
+ * driven from the REAL corpus + REAL `toOfficialPublishBody` through an injected
+ * fetch. Nothing between the YAML and the wire is hand-built.
+ *
+ * Pins: the preflight refuses a non-official account BEFORE any write; the plan
+ * is read-only; a failed live read is a refusal, never "new"; the POST carries
+ * the official vendorId and `sourcePackage`; the diff names added/removed
+ * profiles and fields; a stamp the CP did not store is reported.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  OfficialPublishError,
+  diffDefinitions,
+  executeOfficialPublish,
+  planOfficialPublish,
+} from "../scripts/publish-official-lib.mjs";
+import { OFFICIAL_SOURCE_PACKAGE } from "./publish-body.mjs";
+import { cpFetch } from "../scripts/catalog-lib.mjs";
+import { OFFICIAL, fakeCp, isWrite } from "../scripts/__fixtures__/fake-cp.mjs";
+import { readYamlTemplates } from "./generate.mjs";
+
+const CP = "https://cp.test";
+
+describe("planOfficialPublish — preflight", () => {
+  it("refuses an account whose vendor is not synap-official, and writes nothing", async () => {
+    const { calls, fetchImpl } = fakeCp({ vendor: { id: "v-1", slug: "antoine" } });
+    await expect(
+      planOfficialPublish({ cpUrl: CP, token: "t", slugs: ["content-os"], fetchImpl }),
+    ).rejects.toMatchObject({ code: "not-official-publisher" });
+    expect(calls.filter((c) => c.method !== "GET")).toHaveLength(0);
+  });
+
+  it("a failed live read is a refusal — never guessed as a new template", async () => {
+    const { fetchImpl } = fakeCp({ liveStatus: 500 });
+    const err: unknown = await planOfficialPublish({ cpUrl: CP, token: "t", slugs: ["content-os"], fetchImpl }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(OfficialPublishError);
+    expect((err as OfficialPublishError).code).toBe("live-read-failed");
+  });
+
+  it("an unknown slug is refused before any network call", async () => {
+    const { calls, fetchImpl } = fakeCp();
+    await expect(
+      planOfficialPublish({ cpUrl: CP, token: "t", slugs: ["no-such-template"], fetchImpl }),
+    ).rejects.toMatchObject({ code: "unknown-slug" });
+    expect(calls).toHaveLength(0);
+  });
+});
+
+describe("plan → execute — the wire", () => {
+  it("plans read-only, then POSTs the official vendorId + sourcePackage", async () => {
+    const { calls, fetchImpl } = fakeCp({ postStatus: 200 });
+    const plan = await planOfficialPublish({ cpUrl: CP, token: "t", slugs: ["content-os"], fetchImpl });
+    // Read-only: the only non-GET a plan makes is the CP's read-only preview.
+    expect(calls.filter(isWrite)).toHaveLength(0);
+    expect(plan.items).toHaveLength(1);
+    expect(plan.items[0].status).toBe("new");
+
+    const results = await executeOfficialPublish(plan, { token: "t", fetchImpl });
+    const posts = calls.filter(isWrite);
+    expect(posts).toHaveLength(1);
+    expect(posts[0].body.vendorId).toBe(OFFICIAL.id);
+    expect(posts[0].body.definition.sourcePackage).toEqual(OFFICIAL_SOURCE_PACKAGE);
+    // The CP refuses an official publish that does not come through the catalog door.
+    expect(posts[0].headers["x-synap-publish-door"]).toBe("catalog");
+    expect(results[0]).toMatchObject({ slug: "content-os", outcome: "updated", stampStored: true });
+  });
+
+  // The process contract (statusProperty, subjectStatus, onFail, gate, criteria,
+  // activators, relationToSubject, humanOnlyStatuses) is authored in YAML and
+  // must arrive in the POSTed definition UNCHANGED — through the real dist
+  // `toPackageDefinition` and the real body builder. Compared to the YAML parse,
+  // so a converter that drops or rewrites any playbook field fails here.
+  it("POSTs every authored playbook field — the process contract — unchanged", async () => {
+    const yamlPlaybooks = (readYamlTemplates().find((t) => t.slug === "content-os")!.data as any)
+      .playbooks as any[];
+    const produce = yamlPlaybooks.find((p) => p.name === "Produce Content");
+    // Non-vacuity: the YAML really declares the contract fields compared below.
+    expect(produce.subjectProfile.statusProperty).toBe("post-status");
+    expect(produce.activators).toEqual([{ on: "enters_status", status: "Briefed", mode: "propose" }]);
+    expect(produce.stages.find((s: any) => s.key === "review").onFail).toEqual({ toStage: "draft" });
+    expect(
+      produce.stages.find((s: any) => s.key === "draft").expectedOutputs[0].relationToSubject,
+    ).toBe("made_for");
+
+    const { calls, fetchImpl } = fakeCp();
+    const plan = await planOfficialPublish({ cpUrl: CP, token: "t", slugs: ["content-os"], fetchImpl });
+    await executeOfficialPublish(plan, { token: "t", fetchImpl });
+    const posted = calls.find(isWrite)!.body.definition.playbooks;
+    expect(posted).toEqual(yamlPlaybooks);
+    const postedProduce = posted.find((p: any) => p.name === "Produce Content");
+    expect(postedProduce.stages.map((s: any) => s.subjectStatus)).toEqual([
+      "Briefed",
+      "Scripted",
+      "In Draft",
+      "Review",
+      "Scheduled",
+      "Published",
+    ]);
+    expect(postedProduce.humanOnlyStatuses).toEqual(["Idea", "Archived"]);
+  });
+
+  it("reports a stamp the CP did not store", async () => {
+    const { fetchImpl } = fakeCp({ storeStamp: false });
+    const plan = await planOfficialPublish({ cpUrl: CP, token: "t", slugs: ["content-os"], fetchImpl });
+    const [r] = await executeOfficialPublish(plan, { token: "t", fetchImpl });
+    expect(r.stampStored).toBe(false);
+  });
+});
+
+describe("diffDefinitions", () => {
+  it("names added/removed profiles, fields, views, links and dependencies", () => {
+    const live = {
+      profiles: [
+        { slug: "post", properties: [{ slug: "title" }, { slug: "old-field" }] },
+        { slug: "gone" },
+      ],
+      views: [{ slug: "v-old" }],
+      entityLinks: [{ sourceProfileSlug: "post", type: "x", targetProfileSlug: "gone" }],
+      dependencies: [{ slug: "foundation" }],
+      onboarding: { a: 1, b: 2 },
+    };
+    const next = {
+      profiles: [{ slug: "post", properties: [{ slug: "title" }, { slug: "new-field" }] }, { slug: "fresh" }],
+      views: [{ slug: "v-new" }],
+      entityLinks: [],
+      dependencies: [{ slug: "foundation" }, { slug: "brand-library" }],
+      onboarding: { b: 2, a: 1 }, // same content, different key order → NOT a change
+    };
+    const d = diffDefinitions(live, next);
+    expect(d.profiles).toEqual({ added: ["fresh"], removed: ["gone"] });
+    expect(d.fields).toEqual({ added: ["post.new-field"], removed: ["post.old-field"] });
+    expect(d.views).toEqual({ added: ["v-new"], removed: ["v-old"] });
+    expect(d.entityLinks.removed).toEqual(["post —x→ gone"]);
+    expect(d.dependencies).toEqual({ added: ["brand-library"], removed: [] });
+    expect(d.otherKeysChanged).toEqual([]);
+  });
+
+  it("matches a live view (CP-derived slug) to the catalog view that names it", () => {
+    const live = { views: [{ name: "Task Board", slug: "task-board", displayName: "Task Board" }] };
+    const next = { views: [{ name: "Task Board" }] };
+    expect(diffDefinitions(live, next).views).toEqual({ added: [], removed: [] });
+  });
+});
+
+describe("cpFetch — a dropped read is retried once, a write never", () => {
+  const flaky = (failures: number) => {
+    let calls = 0;
+    const impl = (async () => {
+      calls++;
+      if (calls <= failures) throw new TypeError("fetch failed");
+      return new Response("{}", { status: 200 });
+    }) as unknown as typeof fetch;
+    return { impl, calls: () => calls };
+  };
+
+  it("a GET that drops once succeeds on the retry", async () => {
+    const f = flaky(1);
+    const res = await cpFetch(f.impl, "https://cp.test/api/packages", {}, { retryDelayMs: 0 });
+    expect(res.status).toBe(200);
+    expect(f.calls()).toBe(2);
+  });
+
+  it("a GET that drops twice is cp-unreachable", async () => {
+    const f = flaky(2);
+    await expect(cpFetch(f.impl, "https://cp.test/x", {}, { retryDelayMs: 0 })).rejects.toMatchObject({ code: "cp-unreachable" });
+    expect(f.calls()).toBe(2);
+  });
+
+  it("a POST that drops is never re-sent (it may have landed)", async () => {
+    const f = flaky(1);
+    await expect(cpFetch(f.impl, "https://cp.test/api/packages", { method: "POST" }, { retryDelayMs: 0 })).rejects.toMatchObject({ code: "cp-unreachable" });
+    expect(f.calls()).toBe(1);
+  });
+});