minutework 0.1.0

package/assets/templates/next-tenant-app/src/lib/content/__fixtures__/public-site-snapshot.ts

@@ -0,0 +1,189 @@
+import type { PublicContentSnapshot } from "@/lib/content/contracts";
+
+export const publicSiteFixtureSnapshot: PublicContentSnapshot = {
+  site: {
+    siteName: "MinuteWork Combined Starter",
+    siteDescription:
+      "SEO-first marketing, docs, blog, and authenticated workspace routes served from one governed Next.js starter.",
+    organizationName: "MinuteWork",
+    footerBlurb:
+      "One codebase for public discovery, operator sign-in, and the private Builder-ready workspace shell.",
+    primaryCta: {
+      label: "Sign In",
+      href: "/login",
+    },
+    secondaryCta: {
+      label: "Docs",
+      href: "/docs",
+    },
+    primaryNavigation: [
+      { label: "Home", href: "/" },
+      { label: "Pricing", href: "/pricing" },
+      { label: "Docs", href: "/docs" },
+      { label: "Blog", href: "/blog" },
+    ],
+    collections: {
+      docs: {
+        eyebrow: "Docs",
+        title: "Starter Docs",
+        description: "Route public content through the MinuteWork public-site snapshot seam.",
+      },
+      blog: {
+        eyebrow: "Blog",
+        title: "Starter Blog",
+        description: "Notes about the combined public and private starter.",
+      },
+    },
+  },
+  marketingPages: [
+    {
+      pageKey: "home",
+      path: "/",
+      heroEyebrow: "Public Site API",
+      heroTitle: "Public routes now read from MinuteWork content snapshots.",
+      heroBody:
+        "The tenant-app starter loads public-site content from the MinuteWork gateway during preview and build, while private routes stay behind the platform-session BFF.",
+      primaryCta: {
+        label: "Sign In",
+        href: "/login",
+      },
+      secondaryCta: {
+        label: "Read the docs",
+        href: "/docs",
+      },
+      sections: [
+        {
+          eyebrow: "Authoring",
+          title: "Preview reads stay server-only",
+          body:
+            "The Next server fetches preview or live-safe public-site content with a server-only content token.",
+        },
+        {
+          eyebrow: "Publishing",
+          title: "Live reads stay publication-safe",
+          body:
+            "Anonymous production traffic reads static output generated from a published-live snapshot contract.",
+        },
+        {
+          eyebrow: "Boundaries",
+          title: "Private app routes stay on the BFF path",
+          body:
+            "Public discovery routes and private workspace routes keep separate auth and data boundaries.",
+        },
+      ],
+      seo: {
+        title: "MinuteWork Combined Starter",
+        description:
+          "A combined starter with public-site snapshot reads for anonymous routes and a platform-session BFF for private routes.",
+      },
+    },
+    {
+      pageKey: "pricing",
+      path: "/pricing",
+      heroEyebrow: "Pricing",
+      heroTitle: "Static-first public pages with remote content by default.",
+      heroBody:
+        "Pricing, docs, and blog routes build from the same public-site snapshot contract, so developers do not have to maintain local seed content.",
+      primaryCta: {
+        label: "Get started",
+        href: "/login",
+      },
+      secondaryCta: {
+        label: "See docs",
+        href: "/docs",
+      },
+      sections: [
+        {
+          eyebrow: "DX",
+          title: "No seeded runtime mode",
+          body:
+            "The generated starter expects real public-site content from MinuteWork during development and build.",
+        },
+        {
+          eyebrow: "Safety",
+          title: "Empty snapshots still render",
+          body:
+            "Fresh properties can ship before authored content exists because built-in empty-state shells handle missing marketing pages.",
+        },
+        {
+          eyebrow: "Ops",
+          title: "One API for preview and live",
+          body:
+            "The same gateway path serves runtime-backed preview reads and published-live snapshots with an explicit source boundary.",
+        },
+      ],
+      seo: {
+        title: "MinuteWork Combined Starter Pricing",
+        description:
+          "MinuteWork public-site snapshots let pricing and landing pages stay static-first without local content seeds.",
+      },
+    },
+  ],
+  docs: [
+    {
+      kind: "docs",
+      slug: ["guides", "public-site-content"],
+      eyebrow: "Guide",
+      title: "Use the public-site snapshot API",
+      description:
+        "Configure the tenant-app starter to load preview and live-safe public-site content from MinuteWork.",
+      publishedAt: "2026-03-26T09:00:00.000Z",
+      readingTime: "3 min read",
+      body: {
+        intro:
+          "The public-site adapter now talks to the MinuteWork gateway with a server-only content token and unwraps a public-site snapshot envelope.",
+        sections: [
+          {
+            heading: "Environment contract",
+            paragraphs: [
+              "Use MW_CONTENT_API_TOKEN for server-only authentication.",
+              "Use MW_PUBLIC_SITE_PROPERTY_KEY to select the PublishedWebProperty backing the site.",
+            ],
+          },
+          {
+            heading: "Preview and live",
+            paragraphs: [
+              "MW_PUBLIC_SITE_ENV=preview fetches runtime-backed preview snapshots.",
+              "MW_PUBLIC_SITE_ENV=live fetches publication-safe published snapshots only.",
+            ],
+          },
+        ],
+      },
+      seo: {
+        title: "Use the public-site snapshot API",
+        description:
+          "Configure the MinuteWork tenant-app starter to fetch public-site snapshots during preview and build.",
+      },
+    },
+  ],
+  blog: [
+    {
+      kind: "blog",
+      slug: ["public-site-api-default"],
+      eyebrow: "Launch note",
+      title: "Public-site snapshots are now the starter default",
+      description:
+        "The generated tenant-app no longer depends on seeded public content for its public route surface.",
+      publishedAt: "2026-03-26T10:00:00.000Z",
+      readingTime: "2 min read",
+      body: {
+        intro:
+          "MinuteWork tenant-app starters now fetch public-site content from a gateway API using a dedicated server-only content token.",
+        sections: [
+          {
+            heading: "What changed",
+            paragraphs: [
+              "Seeded local public content is no longer the runtime path for generated starters.",
+              "Public routes render from a remote snapshot envelope with explicit preview and live boundaries.",
+            ],
+          },
+        ],
+      },
+      seo: {
+        title: "Public-site snapshots are now the starter default",
+        description:
+          "The tenant-app starter now defaults to server-only MinuteWork public-site content reads during preview and build.",
+      },
+    },
+  ],
+};

package/assets/templates/next-tenant-app/src/lib/content/adapter.server.test.ts

@@ -0,0 +1,318 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type {
+  BlogEntrySummary,
+  DocsEntrySummary,
+  MarketingPageKey,
+  PublicContentAdapter,
+  PublicContentKind,
+} from "@/lib/content/contracts";
+import { publicSiteFixtureSnapshot } from "@/lib/content/__fixtures__/public-site-snapshot";
+import {
+  MinuteWorkPublicSiteContentAdapter,
+  PUBLIC_CONTENT_REVALIDATE_SECONDS,
+  fetchPublicSiteSnapshotEnvelope,
+} from "@/lib/content/adapter.server";
+
+const originalEnv = { ...process.env };
+
+function jsonResponse(body: unknown, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json",
+    },
+  });
+}
+
+function normalizeSlugParts(slugParts: readonly string[]) {
+  return slugParts.map((part) => part.trim().toLowerCase()).filter(Boolean).join("/");
+}
+
+function getFixtureMarketingPage(pageKey: MarketingPageKey) {
+  return (
+    publicSiteFixtureSnapshot.marketingPages.find((page) => page.pageKey === pageKey) ??
+    null
+  );
+}
+
+function getFixtureEntry(kind: PublicContentKind, slugParts: readonly string[]) {
+  return (
+    publicSiteFixtureSnapshot[kind].find(
+      (entry) => normalizeSlugParts(entry.slug) === normalizeSlugParts(slugParts),
+    ) ?? null
+  );
+}
+
+function toDocsEntrySummary(
+  entry: typeof publicSiteFixtureSnapshot.docs[number],
+): DocsEntrySummary {
+  return {
+    description: entry.description,
+    eyebrow: entry.eyebrow,
+    kind: entry.kind,
+    publishedAt: entry.publishedAt,
+    readingTime: entry.readingTime,
+    slug: entry.slug,
+    title: entry.title,
+  };
+}
+
+function toBlogEntrySummary(
+  entry: typeof publicSiteFixtureSnapshot.blog[number],
+): BlogEntrySummary {
+  return {
+    description: entry.description,
+    eyebrow: entry.eyebrow,
+    kind: entry.kind,
+    publishedAt: entry.publishedAt,
+    readingTime: entry.readingTime,
+    slug: entry.slug,
+    title: entry.title,
+  };
+}
+
+function getFixtureEntrySummaries(kind: "docs"): DocsEntrySummary[];
+function getFixtureEntrySummaries(kind: "blog"): BlogEntrySummary[];
+function getFixtureEntrySummaries(kind: PublicContentKind) {
+  if (kind === "docs") {
+    return publicSiteFixtureSnapshot.docs.map(toDocsEntrySummary);
+  }
+
+  return publicSiteFixtureSnapshot.blog.map(toBlogEntrySummary);
+}
+
+function createCustomAdapter(
+  overrides: Partial<PublicContentAdapter> = {},
+): PublicContentAdapter {
+  return {
+    async getSiteConfig() {
+      return publicSiteFixtureSnapshot.site;
+    },
+    async getMarketingPage(pageKey) {
+      return getFixtureMarketingPage(pageKey);
+    },
+    async listEntries(kind) {
+      return kind === "docs"
+        ? getFixtureEntrySummaries("docs")
+        : getFixtureEntrySummaries("blog");
+    },
+    async getEntry(kind, slugParts) {
+      return getFixtureEntry(kind, slugParts);
+    },
+    ...overrides,
+  };
+}
+
+function createEnvelope(
+  overrides: Partial<Awaited<ReturnType<typeof fetchPublicSiteSnapshotEnvelope>>> = {},
+) {
+  return {
+    environment: "preview" as const,
+    source_boundary: "runtime_preview" as const,
+    snapshot: publicSiteFixtureSnapshot,
+    ...overrides,
+  };
+}
+
+function restoreProcessEnv() {
+  for (const key of Object.keys(process.env)) {
+    if (!(key in originalEnv)) {
+      delete process.env[key];
+    }
+  }
+
+  Object.assign(process.env, originalEnv);
+}
+
+function applyServerEnv(overrides: Record<string, string | undefined>) {
+  restoreProcessEnv();
+  process.env.MW_PLATFORM_BASE_URL = "http://127.0.0.1:8000";
+  process.env.MW_CONTENT_API_TOKEN = "test-content-token";
+  process.env.MW_PUBLIC_BASE_URL = "http://127.0.0.1:3000";
+  process.env.MW_PUBLIC_SITE_PROPERTY_KEY = "main-site";
+  process.env.MW_PUBLIC_SITE_ENV = "preview";
+  process.env.MW_ENABLE_RUNTIME_COMMAND_EXAMPLE = "false";
+
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+}
+
+describe("public content adapter", () => {
+  afterEach(() => {
+    restoreProcessEnv();
+    vi.unstubAllGlobals();
+    vi.resetModules();
+    vi.doUnmock("@/lib/content/custom-adapter");
+  });
+
+  it("loads a public-site snapshot envelope through a cacheable bearer-authenticated fetch", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse(createEnvelope()));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const envelope = await fetchPublicSiteSnapshotEnvelope({
+      contentApiToken: "content-token",
+      environment: "preview",
+      platformBaseUrl: "https://platform.example.com",
+      propertyKey: "main-site",
+    });
+
+    expect(envelope.snapshot.site.siteName).toBe("MinuteWork Combined Starter");
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://platform.example.com/api/v1/developer/public-site/snapshots/main-site/?environment=preview",
+      expect.objectContaining({
+        headers: {
+          accept: "application/json",
+          authorization: "Bearer content-token",
+        },
+        next: {
+          revalidate: PUBLIC_CONTENT_REVALIDATE_SECONDS,
+          tags: [
+            "public-site-content",
+            "public-site-content:main-site",
+            "public-site-content:preview",
+          ],
+        },
+      }),
+    );
+  });
+
+  it("rejects invalid environment and source-boundary combinations", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      jsonResponse(
+        createEnvelope({
+          environment: "live",
+          source_boundary: "runtime_preview",
+        }),
+      ),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(
+      fetchPublicSiteSnapshotEnvelope({
+        contentApiToken: "content-token",
+        environment: "live",
+        platformBaseUrl: "https://platform.example.com",
+        propertyKey: "main-site",
+      }),
+    ).rejects.toThrow("published_live");
+  });
+
+  it("maps MinuteWork public-site snapshots through the adapter interface", async () => {
+    const adapter = new MinuteWorkPublicSiteContentAdapter(async () =>
+      createEnvelope({
+        environment: "live",
+        source_boundary: "published_live",
+      }),
+    );
+
+    await expect(adapter.getMarketingPage("home")).resolves.toEqual(
+      publicSiteFixtureSnapshot.marketingPages[0],
+    );
+    await expect(adapter.listEntries("blog")).resolves.toEqual(
+      publicSiteFixtureSnapshot.blog,
+    );
+    await expect(
+      adapter.getEntry("blog", ["public-site-api-default"]),
+    ).resolves.toEqual(publicSiteFixtureSnapshot.blog[0]);
+  });
+
+  it("allows empty marketing-page snapshots from the default gateway adapter", async () => {
+    const adapter = new MinuteWorkPublicSiteContentAdapter(async () =>
+      createEnvelope({
+        snapshot: {
+          ...publicSiteFixtureSnapshot,
+          marketingPages: [],
+        },
+      }),
+    );
+
+    await expect(adapter.getMarketingPage("pricing")).resolves.toBeNull();
+  });
+
+  it("loads the default MinuteWork public-site path when no custom adapter is provided", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse(createEnvelope()));
+    vi.stubGlobal("fetch", fetchMock);
+    applyServerEnv({});
+    vi.doMock("@/lib/content/custom-adapter", () => ({
+      resolveCustomPublicContentAdapter: () => null,
+    }));
+
+    const adapterModule = await import("./adapter.server");
+
+    await expect(adapterModule.getSiteConfig()).resolves.toEqual(
+      publicSiteFixtureSnapshot.site,
+    );
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("accepts valid custom adapter output through the shared contract wrapper", async () => {
+    vi.doMock("@/lib/content/custom-adapter", () => ({
+      resolveCustomPublicContentAdapter: () => createCustomAdapter(),
+    }));
+
+    const adapterModule = await import("./adapter.server");
+
+    await expect(adapterModule.getMarketingPage("pricing")).resolves.toEqual(
+      getFixtureMarketingPage("pricing"),
+    );
+    await expect(adapterModule.listEntries("blog")).resolves.toEqual(
+      getFixtureEntrySummaries("blog"),
+    );
+  });
+
+  it("rejects a custom adapter when a marketing page violates the canonical route contract", async () => {
+    vi.doMock("@/lib/content/custom-adapter", () => ({
+      resolveCustomPublicContentAdapter: () =>
+        createCustomAdapter({
+          async getMarketingPage(pageKey) {
+            const page = getFixtureMarketingPage(pageKey);
+
+            if (!page || pageKey !== "pricing") {
+              return page;
+            }
+
+            return {
+              ...page,
+              path: "/plans",
+            };
+          },
+        }),
+    }));
+
+    const adapterModule = await import("./adapter.server");
+
+    await expect(adapterModule.getMarketingPage("pricing")).rejects.toThrow(
+      '"pricing" marketing page must use the "/pricing" route.',
+    );
+  });
+
+  it("rejects a custom adapter when blog summaries use multi-segment slugs", async () => {
+    vi.doMock("@/lib/content/custom-adapter", () => ({
+      resolveCustomPublicContentAdapter: () =>
+        createCustomAdapter({
+          async listEntries(kind) {
+            if (kind !== "blog") {
+              return getFixtureEntrySummaries("docs");
+            }
+
+            return publicSiteFixtureSnapshot.blog.map((entry) => ({
+              ...entry,
+              slug: ["release", "v1"],
+            }));
+          },
+        }),
+    }));
+
+    const adapterModule = await import("./adapter.server");
+
+    await expect(adapterModule.listEntries("blog")).rejects.toThrow(
+      "Array must contain at most 1 element(s)",
+    );
+  });
+});