@tribe-nest/forge 1.13.0

package/src/server/_tests/buildWebManifest.spec.ts

@@ -0,0 +1,313 @@
+// Unit tests for buildWebManifest() — the React-free Forge server builder that
+// turns the extended site-config `pwa` block + the content-doc theme.* colors
+// into a web app manifest. Pure function, no DB, no network.
+//
+// Coverage (pure-function analogue of the 7-point standard):
+//  - happy path w/ deep shape assertions (with + without screenshots)
+//  - optional-field permutations (screenshots optional; icons partial)
+//  - FORGE_STATE-independent minimal-manifest gating (no pwa → not installable)
+//  - theme color derivation + fallback (bare + localized values + defaults)
+//  - maskable icon derive (icon192 = maskable, icon512 = any)
+//  - overrides (shortcuts) merge + precedence
+//  - determinism / idempotence (same input → identical output twice)
+//
+// Source: packages/forge/src/server/pwa.ts. Spec: docs/pwa-custom-code-initiative.md.
+
+import { describe, it, expect } from "vitest";
+import { buildWebManifest, type BuildWebManifestOptions } from "../pwa";
+import type { SiteConfig, PwaConfig } from "../../data/queries/useWebsite";
+import type { ContentDocument } from "../../content/types";
+
+const DEFAULT_PRIMARY = "#6d28d9";
+const DEFAULT_BACKGROUND = "#ffffff";
+
+function fullPwa(overrides: Partial<PwaConfig> = {}): PwaConfig {
+  return {
+    name: "Nova Sound",
+    shortName: "Nova",
+    description: "The Nova Sound fan app",
+    icon96: "https://cdn.tribenest.co/p/nova/icon-96.png",
+    icon192: "https://cdn.tribenest.co/p/nova/icon-192.png",
+    icon512: "https://cdn.tribenest.co/p/nova/icon-512.png",
+    screenshotWide1280X720: "https://cdn.tribenest.co/p/nova/wide.png",
+    screenshotNarrow750X1334: "https://cdn.tribenest.co/p/nova/narrow.png",
+    ...overrides,
+  };
+}
+
+function siteConfig(overrides: Partial<SiteConfig> = {}): SiteConfig {
+  return {
+    currency: "USD",
+    metaPixelId: null,
+    stripeAccountId: null,
+    paystackAccountId: null,
+    paymentProviderName: null,
+    paymentProviderPublicKey: null,
+    stripePublishableKey: null,
+    siteName: "Nova Sound",
+    pwa: fullPwa(),
+    ...overrides,
+  };
+}
+
+/** A content document with theme.* color fields set to bare string values. */
+function themedDoc(primary?: string, background?: string): ContentDocument {
+  const fields: ContentDocument["fields"] = {};
+  if (primary !== undefined) fields["theme.primary"] = { type: "color", localized: false, value: primary };
+  if (background !== undefined)
+    fields["theme.background"] = { type: "color", localized: false, value: background };
+  return { version: 3, defaultLocale: "en", locales: ["en"], fields };
+}
+
+describe("buildWebManifest — happy path (full pwaConfig)", () => {
+  const manifest = buildWebManifest({
+    siteConfig: siteConfig(),
+    contentDoc: themedDoc("#112233", "#f5f5f5"),
+  });
+
+  it("produces the full installable manifest shape with deep field assertions", () => {
+    expect(manifest).toMatchObject({
+      name: "Nova Sound",
+      short_name: "Nova",
+      description: "The Nova Sound fan app",
+      start_url: "/",
+      scope: "/",
+      display: "standalone",
+      orientation: "portrait-primary",
+      background_color: "#f5f5f5",
+      theme_color: "#112233",
+      lang: "en",
+      dir: "ltr",
+      prefer_related_applications: false,
+      categories: ["social", "business", "productivity"],
+    });
+  });
+
+  it("derives maskable/any icons from icon192/icon512", () => {
+    expect(manifest.icons).toEqual([
+      { src: "https://cdn.tribenest.co/p/nova/icon-192.png", sizes: "192x192", type: "image/png", purpose: "maskable" },
+      { src: "https://cdn.tribenest.co/p/nova/icon-512.png", sizes: "512x512", type: "image/png", purpose: "any" },
+    ]);
+  });
+
+  it("includes both screenshots with the correct form factors + labels", () => {
+    expect(manifest.screenshots).toEqual([
+      {
+        src: "https://cdn.tribenest.co/p/nova/wide.png",
+        sizes: "1280x720",
+        type: "image/png",
+        form_factor: "wide",
+        label: "Desktop view",
+      },
+      {
+        src: "https://cdn.tribenest.co/p/nova/narrow.png",
+        sizes: "750x1334",
+        type: "image/png",
+        form_factor: "narrow",
+        label: "Mobile view",
+      },
+    ]);
+  });
+});
+
+describe("buildWebManifest — screenshots optional", () => {
+  it("omits the screenshots key entirely when neither screenshot is set", () => {
+    const manifest = buildWebManifest({
+      siteConfig: siteConfig({ pwa: fullPwa({ screenshotWide1280X720: undefined, screenshotNarrow750X1334: undefined }) }),
+      contentDoc: themedDoc("#000", "#fff"),
+    });
+    expect("screenshots" in manifest).toBe(false);
+    expect(manifest.screenshots).toBeUndefined();
+    // installability is unaffected — icons still present
+    expect(manifest.icons.length).toBe(2);
+  });
+
+  it("includes only the wide screenshot when the narrow one is absent", () => {
+    const manifest = buildWebManifest({
+      siteConfig: siteConfig({ pwa: fullPwa({ screenshotNarrow750X1334: undefined }) }),
+    });
+    expect(manifest.screenshots).toEqual([
+      expect.objectContaining({ form_factor: "wide", sizes: "1280x720" }),
+    ]);
+  });
+
+  it("includes only the narrow screenshot when the wide one is absent", () => {
+    const manifest = buildWebManifest({
+      siteConfig: siteConfig({ pwa: fullPwa({ screenshotWide1280X720: undefined }) }),
+    });
+    expect(manifest.screenshots).toEqual([
+      expect.objectContaining({ form_factor: "narrow", sizes: "750x1334" }),
+    ]);
+  });
+});
+
+describe("buildWebManifest — icon permutations", () => {
+  it("emits only the maskable icon when icon512 is missing", () => {
+    const manifest = buildWebManifest({
+      siteConfig: siteConfig({ pwa: fullPwa({ icon512: "" as unknown as string }) }),
+    });
+    expect(manifest.icons).toEqual([
+      expect.objectContaining({ sizes: "192x192", purpose: "maskable" }),
+    ]);
+  });
+
+  it("emits only the any icon when icon192 is missing", () => {
+    const manifest = buildWebManifest({
+      siteConfig: siteConfig({ pwa: fullPwa({ icon192: "" as unknown as string }) }),
+    });
+    expect(manifest.icons).toEqual([
+      expect.objectContaining({ sizes: "512x512", purpose: "any" }),
+    ]);
+  });
+
+  it("emits an empty icons array when both icons are missing (still a valid manifest)", () => {
+    const manifest = buildWebManifest({
+      siteConfig: siteConfig({ pwa: fullPwa({ icon192: "" as unknown as string, icon512: "" as unknown as string }) }),
+    });
+    expect(manifest.icons).toEqual([]);
+  });
+});
+
+describe("buildWebManifest — theme color derivation + fallback", () => {
+  it("falls back to Forge default colors when the content doc has no theme fields", () => {
+    const manifest = buildWebManifest({ siteConfig: siteConfig(), contentDoc: themedDoc() });
+    expect(manifest.theme_color).toBe(DEFAULT_PRIMARY);
+    expect(manifest.background_color).toBe(DEFAULT_BACKGROUND);
+  });
+
+  it("falls back to defaults when contentDoc is null/undefined", () => {
+    const nullDoc = buildWebManifest({ siteConfig: siteConfig(), contentDoc: null });
+    const noDoc = buildWebManifest({ siteConfig: siteConfig() });
+    expect(nullDoc.theme_color).toBe(DEFAULT_PRIMARY);
+    expect(nullDoc.background_color).toBe(DEFAULT_BACKGROUND);
+    expect(noDoc.theme_color).toBe(DEFAULT_PRIMARY);
+    expect(noDoc.background_color).toBe(DEFAULT_BACKGROUND);
+  });
+
+  it("resolves a localized theme color using defaultLocale, then first entry", () => {
+    const doc: ContentDocument = {
+      version: 1,
+      defaultLocale: "fr",
+      locales: ["fr", "en"],
+      fields: {
+        "theme.primary": { type: "color", localized: true, value: { en: "#111111", fr: "#222222" } },
+        // no default locale key present → first Object.values entry used
+        "theme.background": { type: "color", localized: true, value: { en: "#eeeeee" } },
+      },
+    };
+    const manifest = buildWebManifest({ siteConfig: siteConfig(), contentDoc: doc });
+    expect(manifest.theme_color).toBe("#222222"); // fr (defaultLocale) wins
+    expect(manifest.background_color).toBe("#eeeeee"); // only entry
+  });
+
+  it("ignores an empty-string color value and falls back", () => {
+    const manifest = buildWebManifest({ siteConfig: siteConfig(), contentDoc: themedDoc("", "") });
+    expect(manifest.theme_color).toBe(DEFAULT_PRIMARY);
+    expect(manifest.background_color).toBe(DEFAULT_BACKGROUND);
+  });
+});
+
+describe("buildWebManifest — no pwaConfig (not installable / minimal)", () => {
+  it("returns a minimal name-only manifest with no icons when pwa is null", () => {
+    const manifest = buildWebManifest({
+      siteConfig: siteConfig({ pwa: null }),
+      contentDoc: themedDoc("#abcabc", "#defdef"),
+    });
+    expect(manifest).toEqual({
+      name: "Nova Sound",
+      short_name: "Nova Sound",
+      start_url: "/",
+      scope: "/",
+      display: "standalone",
+      background_color: "#defdef",
+      theme_color: "#abcabc",
+      icons: [],
+    });
+    // not installable — empty icons, no orientation/categories
+    expect(manifest.icons).toEqual([]);
+    expect(manifest.categories).toBeUndefined();
+    expect(manifest.orientation).toBeUndefined();
+  });
+
+  it("falls back name to 'App' when neither pwa nor siteName is present", () => {
+    const manifest = buildWebManifest({ siteConfig: siteConfig({ pwa: null, siteName: null }) });
+    expect(manifest.name).toBe("App");
+    expect(manifest.short_name).toBe("App");
+  });
+
+  it("returns the minimal manifest when siteConfig itself is null", () => {
+    const manifest = buildWebManifest({ siteConfig: null });
+    expect(manifest.name).toBe("App");
+    expect(manifest.icons).toEqual([]);
+    expect(manifest.theme_color).toBe(DEFAULT_PRIMARY);
+    expect(manifest.background_color).toBe(DEFAULT_BACKGROUND);
+  });
+});
+
+describe("buildWebManifest — name/short_name fallback chain", () => {
+  it("uses pwa.name over siteName", () => {
+    const manifest = buildWebManifest({
+      siteConfig: siteConfig({ siteName: "Legal Name", pwa: fullPwa({ name: "Brand" }) }),
+    });
+    expect(manifest.name).toBe("Brand");
+  });
+
+  it("falls short_name back to pwa.name when shortName is empty", () => {
+    const manifest = buildWebManifest({
+      siteConfig: siteConfig({ pwa: fullPwa({ shortName: "" }) }),
+    });
+    expect(manifest.short_name).toBe("Nova Sound");
+  });
+
+  it("omits description when it is empty", () => {
+    const manifest = buildWebManifest({
+      siteConfig: siteConfig({ pwa: fullPwa({ description: "" }) }),
+    });
+    expect(manifest.description).toBeUndefined();
+  });
+});
+
+describe("buildWebManifest — overrides (shortcuts) merge", () => {
+  const overrides: BuildWebManifestOptions["overrides"] = {
+    shortcuts: [
+      { name: "Members", short_name: "Members", url: "/i/members" },
+      { name: "Account", short_name: "Account", url: "/i/account" },
+    ],
+  };
+
+  it("merges overrides.shortcuts into an installable manifest (no hardcoded shortcuts)", () => {
+    const withOverrides = buildWebManifest({ siteConfig: siteConfig(), overrides });
+    const without = buildWebManifest({ siteConfig: siteConfig() });
+    expect(without.shortcuts).toBeUndefined();
+    expect(withOverrides.shortcuts).toEqual(overrides!.shortcuts);
+  });
+
+  it("lets overrides win over computed keys (last-spread precedence)", () => {
+    const manifest = buildWebManifest({
+      siteConfig: siteConfig(),
+      overrides: { name: "Overridden", display: "fullscreen" },
+    });
+    expect(manifest.name).toBe("Overridden");
+    expect(manifest.display).toBe("fullscreen");
+  });
+
+  it("applies overrides to the minimal (no-pwa) manifest too", () => {
+    const manifest = buildWebManifest({
+      siteConfig: siteConfig({ pwa: null }),
+      overrides: { display: "browser" },
+    });
+    expect(manifest.display).toBe("browser");
+    expect(manifest.icons).toEqual([]);
+  });
+});
+
+describe("buildWebManifest — determinism", () => {
+  it("returns identical output for identical input on repeated calls", () => {
+    const opts = { siteConfig: siteConfig(), contentDoc: themedDoc("#123123", "#321321") };
+    const a = buildWebManifest(opts);
+    const b = buildWebManifest(opts);
+    expect(a).toEqual(b);
+    // JSON round-trip stability (the manifest route serializes it)
+    expect(JSON.stringify(a)).toEqual(JSON.stringify(b));
+  });
+});

package/src/server/_tests/forgeServiceWorkerScript.spec.ts

@@ -0,0 +1,251 @@
+// Unit tests for forgeServiceWorkerScript() — the React-free Forge server builder
+// that returns the site's service-worker SOURCE as a dependency-free vanilla-JS
+// string (served verbatim by the starter's `/sw.js` route). Pure function.
+//
+// We can't spin up a real ServiceWorkerGlobalScope here, so we assert on the
+// generated source's contract + behavior by:
+//  - structural assertions on the cache name (Forge version baked in → old caches
+//    purged on activate)
+//  - syntactic validity (the string must parse as JS — a broken SW bricks the site)
+//  - behavior extraction: we evaluate the script against a fake `self` that records
+//    addEventListener handlers, then drive the push/notificationclick/fetch/install/
+//    activate handlers with fake events and assert the FROZEN payload contract
+//    ({ title, body, type, url, profileId, channelId, spaceId, icon }) matches the
+//    client SW, plus offline-fallback + asset-cache + skipWaiting/clients.claim.
+//
+// Source: packages/forge/src/server/pwa.ts. Spec: docs/pwa-custom-code-initiative.md.
+
+import { describe, it, expect, vi } from "vitest";
+import { forgeServiceWorkerScript, FORGE_PWA_VERSION } from "../pwa";
+
+describe("forgeServiceWorkerScript — source shape", () => {
+  it("bakes the Forge version into the cache name (default)", () => {
+    const src = forgeServiceWorkerScript();
+    expect(src).toContain(`const CACHE = "forge-pwa-v${FORGE_PWA_VERSION}"`);
+    expect(src).toContain('const OFFLINE_URL = "/offline"');
+  });
+
+  it("honors an explicit version argument in the cache name + header", () => {
+    const src = forgeServiceWorkerScript("9.9.9");
+    expect(src).toContain('const CACHE = "forge-pwa-v9.9.9"');
+    expect(src).toContain("Forge service worker (v9.9.9)");
+  });
+
+  it("registers install/activate/fetch/push/notificationclick handlers", () => {
+    const src = forgeServiceWorkerScript();
+    for (const evt of ["install", "activate", "fetch", "push", "notificationclick"]) {
+      expect(src).toContain(`addEventListener("${evt}"`);
+    }
+    // safe self-activation with no HTML precache
+    expect(src).toContain("self.skipWaiting()");
+    expect(src).toContain("self.clients.claim()");
+  });
+
+  it("is syntactically valid JS (parses without throwing)", () => {
+    const src = forgeServiceWorkerScript();
+    // `self` is a free identifier in the SW; wrap so Function() can parse it.
+    expect(() => new Function("self", src)).not.toThrow();
+  });
+
+  it("is deterministic for a given version", () => {
+    expect(forgeServiceWorkerScript("2.0.0")).toEqual(forgeServiceWorkerScript("2.0.0"));
+  });
+});
+
+// ---- Behavior harness: evaluate the SW source against a fake global. ----
+
+type Handler = (event: unknown) => void;
+
+interface FakeCache {
+  store: Map<string, unknown>;
+  addAll: ReturnType<typeof vi.fn>;
+  match: ReturnType<typeof vi.fn>;
+  put: ReturnType<typeof vi.fn>;
+}
+
+function makeFakeCache(): FakeCache {
+  const store = new Map<string, unknown>();
+  return {
+    store,
+    addAll: vi.fn(async () => {}),
+    match: vi.fn(async (key: unknown) => store.get(String(typeof key === "string" ? key : (key as Request)?.url))),
+    put: vi.fn(async () => {}),
+  };
+}
+
+/**
+ * Load the SW source and return the registered handlers + the fake globals so a
+ * test can drive events. `location.origin` is set so same-origin checks pass.
+ */
+function loadSw(version = FORGE_PWA_VERSION) {
+  const handlers: Record<string, Handler> = {};
+  const cache = makeFakeCache();
+  const showNotification = vi.fn(async () => {});
+  const openWindow = vi.fn(async () => ({}));
+  const focus = vi.fn(() => ({}));
+  const matchAll = vi.fn(async () => [] as Array<{ url: string; focus: typeof focus }>);
+  const skipWaiting = vi.fn();
+  const claim = vi.fn(async () => {});
+
+  // `caches` is referenced both bare (install/activate) and via `self.caches`
+  // in the SW source, so it must exist as a free global AND on `self`.
+  const caches = {
+    open: vi.fn(async () => cache),
+    keys: vi.fn(async () => ["forge-pwa-vOLD", `forge-pwa-v${version}`]),
+    delete: vi.fn(async () => true),
+    match: vi.fn(async () => undefined),
+  };
+
+  const self: Record<string, unknown> = {
+    location: { origin: "https://nova.tribenest.co" },
+    caches,
+    registration: { showNotification },
+    clients: { matchAll, openWindow, claim },
+    skipWaiting,
+    addEventListener: (name: string, fn: Handler) => {
+      handlers[name] = fn;
+    },
+  };
+  (self.clients as { claim: typeof claim }).claim = claim;
+
+  // eslint-disable-next-line @typescript-eslint/no-implied-eval
+  new Function("self", "caches", "URL", "Response", "fetch", "Promise", forgeServiceWorkerScript(version)).call(
+    undefined,
+    self,
+    caches,
+    URL,
+    Response,
+    globalThis.fetch,
+    Promise,
+  );
+
+  return { handlers, self, caches, cache, showNotification, openWindow, focus, matchAll, skipWaiting, claim };
+}
+
+/** A minimal waitUntil-capturing event. */
+function fakeEvent(extra: Record<string, unknown> = {}) {
+  let waited: Promise<unknown> | undefined;
+  return {
+    waitUntil: (p: Promise<unknown>) => {
+      waited = p;
+    },
+    respondWith: vi.fn(),
+    get waited() {
+      return waited;
+    },
+    ...extra,
+  };
+}
+
+describe("forgeServiceWorkerScript — install/activate behavior", () => {
+  it("precaches the offline page on install and self-activates", async () => {
+    const { handlers, cache, skipWaiting } = loadSw();
+    const event = fakeEvent();
+    handlers.install!(event);
+    await event.waited;
+    expect(cache.addAll).toHaveBeenCalledWith(["/offline"]);
+    expect(skipWaiting).toHaveBeenCalledOnce();
+  });
+
+  it("purges stale caches (keeps only the current version) and claims clients on activate", async () => {
+    const { handlers, caches, claim } = loadSw("3.3.3");
+    const event = fakeEvent();
+    handlers.activate!(event);
+    await event.waited;
+    // the OLD cache is deleted, the current one is not
+    expect(caches.delete).toHaveBeenCalledWith("forge-pwa-vOLD");
+    expect(caches.delete).not.toHaveBeenCalledWith("forge-pwa-v3.3.3");
+    expect(claim).toHaveBeenCalledOnce();
+  });
+});
+
+describe("forgeServiceWorkerScript — push payload contract (frozen, shared with client SW)", () => {
+  it("renders a chat notification tagged by channelId with the payload icon", async () => {
+    const { handlers, showNotification } = loadSw();
+    const event = fakeEvent({
+      data: {
+        json: () => ({
+          title: "New message",
+          body: "hey!",
+          type: "chat_message",
+          url: "/i/chat/42",
+          profileId: "prof-1",
+          channelId: "chan-9",
+          icon: "https://cdn.tribenest.co/p/nova/icon-192.png",
+        }),
+      },
+    });
+    handlers.push!(event);
+    await event.waited;
+    expect(showNotification).toHaveBeenCalledWith("New message", {
+      body: "hey!",
+      icon: "https://cdn.tribenest.co/p/nova/icon-192.png",
+      tag: "chat-chan-9",
+      data: { url: "/i/chat/42", type: "chat_message" },
+    });
+  });
+
+  it("tags DMs as chat and post notifications by profileId; icon falls back to undefined", async () => {
+    const { handlers, showNotification } = loadSw();
+    const post = fakeEvent({
+      data: { json: () => ({ title: "New post", body: "check it", type: "new_post", url: "/blog/x", profileId: "prof-7" }) },
+    });
+    handlers.push!(post);
+    await post.waited;
+    expect(showNotification).toHaveBeenCalledWith("New post", {
+      body: "check it",
+      icon: undefined,
+      tag: "post-prof-7",
+      data: { url: "/blog/x", type: "new_post" },
+    });
+  });
+
+  it("tags space notifications by spaceId", async () => {
+    const { handlers, showNotification } = loadSw();
+    const event = fakeEvent({
+      data: { json: () => ({ title: "Space update", body: "b", type: "space_post", url: "/s/1", profileId: "p", spaceId: "space-5" }) },
+    });
+    handlers.push!(event);
+    await event.waited;
+    expect(showNotification).toHaveBeenCalledWith(
+      "Space update",
+      expect.objectContaining({ tag: "space-space-5" }),
+    );
+  });
+
+  it("swallows a malformed push (no data / bad JSON) without throwing or notifying", async () => {
+    const { handlers, showNotification } = loadSw();
+    // no data → early return
+    const noData = fakeEvent({ data: null });
+    expect(() => handlers.push!(noData)).not.toThrow();
+    // data.json throws → caught
+    const bad = fakeEvent({ data: { json: () => { throw new Error("bad"); } } });
+    expect(() => handlers.push!(bad)).not.toThrow();
+    expect(showNotification).not.toHaveBeenCalled();
+  });
+});
+
+describe("forgeServiceWorkerScript — notificationclick", () => {
+  it("focuses an existing client matching the deep-link URL", async () => {
+    const { handlers, matchAll, openWindow } = loadSw();
+    const focus = vi.fn(() => ({}));
+    matchAll.mockResolvedValueOnce([{ url: "https://nova.tribenest.co/i/chat/42", focus }]);
+    const close = vi.fn();
+    const event = fakeEvent({ notification: { close, data: { url: "/i/chat/42" } } });
+    handlers.notificationclick!(event);
+    await event.waited;
+    expect(close).toHaveBeenCalledOnce();
+    expect(focus).toHaveBeenCalledOnce();
+    expect(openWindow).not.toHaveBeenCalled();
+  });
+
+  it("opens a new window when no client matches, defaulting url to '/'", async () => {
+    const { handlers, matchAll, openWindow } = loadSw();
+    matchAll.mockResolvedValueOnce([]);
+    const close = vi.fn();
+    const event = fakeEvent({ notification: { close, data: undefined } });
+    handlers.notificationclick!(event);
+    await event.waited;
+    expect(openWindow).toHaveBeenCalledWith("/");
+  });
+});