@synap-core/workspace-templates 0.6.3 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synap-core/workspace-templates",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "type": "module",
   "packageManager": "pnpm@9.15.4",
   "description": "Canonical workspace definitions — YAML source + typed exports for browser, backend, CLI, and marketplace",

package/src/catalog.test.ts

@@ -7,7 +7,7 @@
 
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mergeCatalog, type RemoteEntry } from "./catalog.js";
+import { mergeCatalog, computeTemplateUpdates, type RemoteEntry } from "./catalog.js";
 import type { WorkspaceYaml } from "./types.js";
 
 const BUNDLE_VERSION = "0.6.0";
@@ -154,3 +154,101 @@ test("maps a bundled template's meta fields onto the entry", () => {
   assert.equal(e.category, "workspace");
   assert.equal(e.isPrivate, true, "isPublic:false ⇒ isPrivate");
 });
+
+// ── computeTemplateUpdates ───────────────────────────────────────────────────
+
+test("computeTemplateUpdates: no update when installed equals catalog latest (semver)", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [remote("crm", { version: "0.7.0" })],
+    bundleVersion: BUNDLE_VERSION, // remote strictly newer → remote wins, carries "0.7.0"
+  });
+  const [check] = computeTemplateUpdates([{ slug: "crm", version: "0.7.0" }], entries);
+  assert.equal(check.latestVersion, "0.7.0");
+  assert.equal(check.updateAvailable, false);
+});
+
+test("computeTemplateUpdates: update available when installed is older (semver)", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [remote("crm", { version: "0.7.0" })],
+    bundleVersion: BUNDLE_VERSION,
+  });
+  const [check] = computeTemplateUpdates([{ slug: "crm", version: "0.5.0" }], entries);
+  assert.equal(check.latestVersion, "0.7.0");
+  assert.equal(check.updateAvailable, true);
+});
+
+// NOTE: uses a non-colliding slug so the remote row is kept as a DISTINCT entry
+// regardless of version — a hash string never parses as semver, so on a slug
+// COLLISION `remoteIsStrictlyNewer` would (correctly, per mergeCatalog's existing
+// squatting-defense semantics) keep the bundle winning and never surface the hash.
+test("computeTemplateUpdates: hash-vs-semver — any mismatch with a hash version signals an update", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [remote("hash-template", { version: "h-abc123" })],
+    bundleVersion: BUNDLE_VERSION,
+  });
+  const [staleSemver] = computeTemplateUpdates(
+    [{ slug: "hash-template", version: "0.5.0" }],
+    entries,
+  );
+  assert.equal(staleSemver.latestVersion, "h-abc123");
+  assert.equal(staleSemver.updateAvailable, true, "semver installed vs hash latest ⇒ differ ⇒ update");
+
+  const [sameHash] = computeTemplateUpdates(
+    [{ slug: "hash-template", version: "h-abc123" }],
+    entries,
+  );
+  assert.equal(sameHash.updateAvailable, false, "identical hash ⇒ no update");
+
+  const [differentHash] = computeTemplateUpdates(
+    [{ slug: "hash-template", version: "h-old999" }],
+    entries,
+  );
+  assert.equal(differentHash.updateAvailable, true, "different hash ⇒ update");
+});
+
+test("computeTemplateUpdates: slug missing from catalog ⇒ no update, latestVersion undefined", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [],
+    bundleVersion: BUNDLE_VERSION,
+  });
+  const [check] = computeTemplateUpdates([{ slug: "ghost-template", version: "1.0.0" }], entries);
+  assert.equal(check.latestVersion, undefined);
+  assert.equal(check.updateAvailable, false);
+});
+
+test("computeTemplateUpdates: bundled winner compares against bundleVersion when passed", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [],
+    bundleVersion: BUNDLE_VERSION,
+  });
+  const stale = computeTemplateUpdates(
+    [{ slug: "crm", version: "0.1.0" }],
+    entries,
+    BUNDLE_VERSION,
+  );
+  assert.equal(stale[0].latestVersion, BUNDLE_VERSION);
+  assert.equal(stale[0].updateAvailable, true);
+
+  const noBundleVersion = computeTemplateUpdates([{ slug: "crm", version: "0.1.0" }], entries);
+  assert.equal(noBundleVersion[0].latestVersion, undefined, "no bundleVersion ⇒ nothing to compare");
+  assert.equal(noBundleVersion[0].updateAvailable, false);
+});
+
+test("computeTemplateUpdates: passes isPrivate through from the winning entry", () => {
+  const { entries } = mergeCatalog({
+    bundled: [bundled("crm")],
+    remote: [remote("private-pack", { isPrivate: true, version: "1.0.0" })],
+    bundleVersion: BUNDLE_VERSION,
+  });
+  const [check] = computeTemplateUpdates(
+    [{ slug: "private-pack", version: "0.9.0" }],
+    entries,
+  );
+  assert.equal(check.isPrivate, true);
+  assert.equal(check.updateAvailable, true);
+});

package/src/catalog.ts

@@ -371,3 +371,96 @@ export function assembleCatalog(input: AssembleCatalogInput): MergeCatalogResult
     remoteStatus: input.remoteStatus,
   });
 }
+
+// ============================================================================
+// Installed-vs-catalog update check
+// ============================================================================
+
+/** A template a pod has installed — the door reads `settings.packageVersion` off the workspace row. */
+export interface InstalledTemplate {
+  slug: string;
+  version: string;
+}
+
+/** Per-slug verdict: is a newer catalog version available than what's installed? */
+export interface TemplateUpdateCheck {
+  slug: string;
+  installedVersion: string;
+  /** `undefined` when the slug has no matching catalog entry, or a bundled winner and no `bundleVersion` was passed. */
+  latestVersion: string | undefined;
+  updateAvailable: boolean;
+  /** Passed through from the winning catalog entry, so callers can route private updates through the authed path. */
+  isPrivate?: boolean;
+}
+
+/**
+ * `true` when `version` is a CP content-hash stamp (`"h-<hash>"`) rather than semver.
+ * Content-hash versions are NOT semver-comparable — see `computeTemplateUpdates`.
+ */
+export function isHashVersion(version: string | undefined): boolean {
+  return typeof version === "string" && version.startsWith("h-");
+}
+
+/**
+ * Compare an installed version against a catalog's latest — reusing
+ * `remoteIsStrictlyNewer` for the semver path. Either side being a content-hash
+ * (`"h-..."`) makes the pair NOT semver-comparable, so an update is signalled
+ * whenever the two raw strings simply differ (equal ⇒ no update, by construction
+ * the CP only reissues a new hash when the template content actually changed).
+ */
+function isNewerVersion(installedVersion: string, latestVersion: string | undefined): boolean {
+  if (latestVersion === undefined) return false;
+  if (isHashVersion(installedVersion) || isHashVersion(latestVersion)) {
+    return installedVersion !== latestVersion;
+  }
+  return remoteIsStrictlyNewer(latestVersion, installedVersion);
+}
+
+/**
+ * Compute, per installed template, whether the CATALOG (bundled + remote,
+ * already merged by `mergeCatalog`/`assembleCatalog`) carries a newer version
+ * than what the pod installed — the shared "update available" check all three
+ * doors (browser, synap-app, CLI) reuse instead of re-deriving it.
+ *
+ * `installed` and `catalog` are BOTH already-fetched/computed by the caller —
+ * this stays PURE, same as the rest of this module (no fetch, no auth).
+ *
+ * The catalog's winning entry carries the latest version signal two ways:
+ *   • `source: "remote"` → `remote.definition?.sourcePackage?.version` (semver
+ *     OR, going forward, a CP content-hash `"h-<hash>"` stamp).
+ *   • `source: "bundled"` → bundled entries carry no version field at all
+ *     (`TemplateMeta` has none); pass `bundleVersion` (this client's compiled
+ *     package version, the same value fed to `mergeCatalog`) to compare against
+ *     it. Omit `bundleVersion` and bundled-backed slugs report `latestVersion:
+ *     undefined, updateAvailable: false` (nothing comparable).
+ *
+ * A slug with no matching catalog entry ⇒ `updateAvailable: false`,
+ * `latestVersion: undefined` — there is nothing to update TO.
+ */
+export function computeTemplateUpdates(
+  installed: InstalledTemplate[],
+  catalog: CatalogEntry[],
+  bundleVersion?: string,
+): TemplateUpdateCheck[] {
+  const bySlug = new Map(catalog.map((entry) => [entry.slug, entry]));
+
+  return installed.map(({ slug, version: installedVersion }) => {
+    const entry = bySlug.get(slug);
+    if (!entry) {
+      return { slug, installedVersion, latestVersion: undefined, updateAvailable: false };
+    }
+
+    const latestVersion =
+      entry.source === "remote"
+        ? entry.remote.definition?.sourcePackage?.version
+        : bundleVersion;
+
+    return {
+      slug,
+      installedVersion,
+      latestVersion,
+      updateAvailable: isNewerVersion(installedVersion, latestVersion),
+      isPrivate: entry.isPrivate,
+    };
+  });
+}

package/src/index.ts

@@ -61,7 +61,13 @@ export {
 
 export type { WorkspaceTemplateSlug } from "./templates.js";
 
-export { mergeCatalog, rowToRemoteEntry, assembleCatalog } from "./catalog.js";
+export {
+  mergeCatalog,
+  rowToRemoteEntry,
+  assembleCatalog,
+  computeTemplateUpdates,
+  isHashVersion,
+} from "./catalog.js";
 export type {
   MergeCatalogInput,
   MergeCatalogResult,
@@ -73,6 +79,8 @@ export type {
   RemoteCatalogEntry,
   CpPackageRow,
   AssembleCatalogInput,
+  InstalledTemplate,
+  TemplateUpdateCheck,
 } from "./catalog.js";
 
 export {