minutework 0.1.0

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

@@ -0,0 +1,232 @@
+import "server-only";
+
+import { cache } from "react";
+import type { ZodType } from "zod";
+
+import type {
+  MarketingPage,
+  MarketingPageKey,
+  PublicContentAdapter,
+  PublicContentKind,
+  PublicEntry,
+  PublicEntrySummary,
+  PublicSiteSnapshotEnvelope,
+  SiteConfig,
+} from "@/lib/content/contracts";
+import {
+  marketingPageResultSchema,
+  publicEntryResultSchema,
+  publicEntrySummaryListSchema,
+  publicSiteSnapshotEnvelopeSchema,
+  siteConfigSchema,
+} from "@/lib/content/contracts";
+import { resolveCustomPublicContentAdapter } from "@/lib/content/custom-adapter";
+import { env } from "@/lib/platform/env.server";
+
+export const PUBLIC_CONTENT_REVALIDATE_SECONDS = 300;
+
+function normalizeSlugParts(slugParts: readonly string[]) {
+  return slugParts.map((part) => part.trim().toLowerCase()).filter(Boolean).join("/");
+}
+
+function compareSlugParts(left: readonly string[], right: readonly string[]) {
+  return normalizeSlugParts(left) === normalizeSlugParts(right);
+}
+
+function sortEntriesByDate(entries: readonly PublicEntrySummary[]) {
+  return [...entries].sort((left, right) => {
+    const leftTime = left.publishedAt ? Date.parse(left.publishedAt) : 0;
+    const rightTime = right.publishedAt ? Date.parse(right.publishedAt) : 0;
+    return rightTime - leftTime;
+  });
+}
+
+function formatZodIssues(
+  issues: readonly { message: string; path: readonly (string | number)[] }[],
+) {
+  return issues
+    .map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join(".") : "root";
+      return `${path}: ${issue.message}`;
+    })
+    .join("; ");
+}
+
+function validateAdapterResult<T>(
+  adapterLabel: string,
+  methodLabel: string,
+  schema: ZodType<T>,
+  value: unknown,
+) {
+  const parsedValue = schema.safeParse(value);
+
+  if (!parsedValue.success) {
+    throw new Error(
+      `${adapterLabel} returned invalid ${methodLabel}: ${formatZodIssues(parsedValue.error.issues)}`,
+    );
+  }
+
+  return parsedValue.data;
+}
+
+export class ValidatedPublicContentAdapter implements PublicContentAdapter {
+  constructor(
+    private readonly adapter: PublicContentAdapter,
+    private readonly adapterLabel: string,
+  ) {}
+
+  async getSiteConfig(): Promise<SiteConfig> {
+    return validateAdapterResult(
+      this.adapterLabel,
+      "site config",
+      siteConfigSchema,
+      await this.adapter.getSiteConfig(),
+    );
+  }
+
+  async getMarketingPage(pageKey: MarketingPageKey): Promise<MarketingPage | null> {
+    return validateAdapterResult(
+      this.adapterLabel,
+      `marketing page for "${pageKey}"`,
+      marketingPageResultSchema(pageKey),
+      await this.adapter.getMarketingPage(pageKey),
+    );
+  }
+
+  async listEntries(kind: PublicContentKind): Promise<PublicEntrySummary[]> {
+    return validateAdapterResult(
+      this.adapterLabel,
+      `${kind} entry summaries`,
+      publicEntrySummaryListSchema(kind),
+      await this.adapter.listEntries(kind),
+    );
+  }
+
+  async getEntry(kind: PublicContentKind, slugParts: string[]): Promise<PublicEntry | null> {
+    return validateAdapterResult(
+      this.adapterLabel,
+      `${kind} entry for "${normalizeSlugParts(slugParts)}"`,
+      publicEntryResultSchema(kind, slugParts),
+      await this.adapter.getEntry(kind, slugParts),
+    );
+  }
+}
+
+export async function fetchPublicSiteSnapshotEnvelope(input: {
+  contentApiToken: string;
+  environment: "preview" | "live";
+  platformBaseUrl: string;
+  propertyKey: string;
+}): Promise<PublicSiteSnapshotEnvelope> {
+  const requestUrl = new URL(
+    `/api/v1/developer/public-site/snapshots/${encodeURIComponent(input.propertyKey)}/`,
+    `${input.platformBaseUrl.replace(/\/$/, "")}/`,
+  );
+  requestUrl.searchParams.set("environment", input.environment);
+
+  const response = await fetch(requestUrl.toString(), {
+    headers: {
+      accept: "application/json",
+      authorization: `Bearer ${input.contentApiToken}`,
+    },
+    next: {
+      revalidate: PUBLIC_CONTENT_REVALIDATE_SECONDS,
+      tags: [
+        "public-site-content",
+        `public-site-content:${input.propertyKey}`,
+        `public-site-content:${input.environment}`,
+      ],
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Unable to load public-site ${input.environment} snapshot for "${input.propertyKey}" (${response.status}).`,
+    );
+  }
+
+  const payload = await response.json();
+  const parsedEnvelope = publicSiteSnapshotEnvelopeSchema.safeParse(payload);
+
+  if (!parsedEnvelope.success) {
+    throw new Error(
+      `Public-site snapshot envelope is invalid: ${formatZodIssues(parsedEnvelope.error.issues)}`,
+    );
+  }
+
+  return parsedEnvelope.data;
+}
+
+const loadPublicSiteSnapshotEnvelope = cache(async () =>
+  fetchPublicSiteSnapshotEnvelope({
+    contentApiToken: env.MW_CONTENT_API_TOKEN,
+    environment: env.MW_PUBLIC_SITE_ENV,
+    platformBaseUrl: env.MW_PLATFORM_BASE_URL,
+    propertyKey: env.MW_PUBLIC_SITE_PROPERTY_KEY,
+  }),
+);
+
+export class MinuteWorkPublicSiteContentAdapter implements PublicContentAdapter {
+  constructor(
+    private readonly loadEnvelope: () => Promise<PublicSiteSnapshotEnvelope> = loadPublicSiteSnapshotEnvelope,
+  ) {}
+
+  private async loadSnapshot() {
+    return (await this.loadEnvelope()).snapshot;
+  }
+
+  async getSiteConfig(): Promise<SiteConfig> {
+    return (await this.loadSnapshot()).site;
+  }
+
+  async getMarketingPage(pageKey: MarketingPageKey): Promise<MarketingPage | null> {
+    return (
+      (await this.loadSnapshot()).marketingPages.find((page) => page.pageKey === pageKey) ??
+      null
+    );
+  }
+
+  async listEntries(kind: PublicContentKind): Promise<PublicEntrySummary[]> {
+    return sortEntriesByDate((await this.loadSnapshot())[kind]);
+  }
+
+  async getEntry(kind: PublicContentKind, slugParts: string[]): Promise<PublicEntry | null> {
+    return (
+      (await this.loadSnapshot())[kind].find((entry) =>
+        compareSlugParts(entry.slug, slugParts),
+      ) ?? null
+    );
+  }
+}
+
+const defaultPublicContentAdapter = new ValidatedPublicContentAdapter(
+  new MinuteWorkPublicSiteContentAdapter(),
+  "MinuteWork public-site content adapter",
+);
+
+export const getPublicContentAdapter = cache(() => {
+  const customAdapter = resolveCustomPublicContentAdapter();
+
+  if (customAdapter) {
+    return new ValidatedPublicContentAdapter(
+      customAdapter,
+      "Custom public content adapter",
+    );
+  }
+
+  return defaultPublicContentAdapter;
+});
+
+export const getSiteConfig = cache(async () => getPublicContentAdapter().getSiteConfig());
+
+export const getMarketingPage = cache(async (pageKey: MarketingPageKey) =>
+  getPublicContentAdapter().getMarketingPage(pageKey),
+);
+
+export const listEntries = cache(async (kind: PublicContentKind) =>
+  getPublicContentAdapter().listEntries(kind),
+);
+
+export const getEntry = cache(async (kind: PublicContentKind, slugParts: string[]) =>
+  getPublicContentAdapter().getEntry(kind, slugParts),
+);

package/assets/templates/next-tenant-app/src/lib/content/contracts.ts

@@ -0,0 +1,339 @@
+import { z } from "zod";
+
+export const marketingPageKeys = ["home", "pricing"] as const;
+export const publicContentKinds = ["docs", "blog"] as const;
+export const requiredMarketingPagePaths = {
+  home: "/",
+  pricing: "/pricing",
+} as const;
+
+export type MarketingPageKey = (typeof marketingPageKeys)[number];
+export type PublicContentKind = (typeof publicContentKinds)[number];
+
+export type PublicLink = {
+  label: string;
+  href: string;
+};
+
+export type ContentCollectionConfig = {
+  eyebrow: string;
+  title: string;
+  description: string;
+};
+
+export type SiteConfig = {
+  siteName: string;
+  siteDescription: string;
+  organizationName: string;
+  footerBlurb: string;
+  primaryCta: PublicLink;
+  secondaryCta: PublicLink;
+  primaryNavigation: PublicLink[];
+  collections: Record<PublicContentKind, ContentCollectionConfig>;
+};
+
+export type SeoMetadata = {
+  title: string;
+  description: string;
+};
+
+export type MarketingSection = {
+  eyebrow?: string;
+  title: string;
+  body: string;
+  points?: string[];
+};
+
+export type MarketingPage = {
+  pageKey: MarketingPageKey;
+  path: string;
+  heroEyebrow: string;
+  heroTitle: string;
+  heroBody: string;
+  primaryCta: PublicLink;
+  secondaryCta?: PublicLink | null;
+  sections: MarketingSection[];
+  seo: SeoMetadata;
+};
+
+type PublicEntrySummaryBase = {
+  title: string;
+  description: string;
+  eyebrow?: string;
+  publishedAt?: string | null;
+  readingTime?: string | null;
+};
+
+export type DocsEntrySummary = PublicEntrySummaryBase & {
+  kind: "docs";
+  slug: string[];
+};
+
+export type BlogEntrySummary = PublicEntrySummaryBase & {
+  kind: "blog";
+  slug: [string];
+};
+
+export type PublicEntrySummary = DocsEntrySummary | BlogEntrySummary;
+
+export type PublicEntrySection = {
+  heading: string;
+  paragraphs: string[];
+};
+
+type PublicEntryBody = {
+  body: {
+    intro: string;
+    sections: PublicEntrySection[];
+  };
+  seo: SeoMetadata;
+};
+
+export type DocsEntry = DocsEntrySummary & PublicEntryBody;
+export type BlogEntry = BlogEntrySummary & PublicEntryBody;
+export type PublicEntry = DocsEntry | BlogEntry;
+
+export interface PublicContentAdapter {
+  getSiteConfig(): Promise<SiteConfig>;
+  getMarketingPage(pageKey: MarketingPageKey): Promise<MarketingPage | null>;
+  listEntries(kind: PublicContentKind): Promise<PublicEntrySummary[]>;
+  getEntry(kind: PublicContentKind, slugParts: string[]): Promise<PublicEntry | null>;
+}
+
+export const publicLinkSchema = z.object({
+  label: z.string().trim().min(1),
+  href: z.string().trim().min(1),
+});
+
+export const seoMetadataSchema = z.object({
+  title: z.string().trim().min(1),
+  description: z.string().trim().min(1),
+});
+
+export const contentCollectionConfigSchema = z.object({
+  eyebrow: z.string().trim().min(1),
+  title: z.string().trim().min(1),
+  description: z.string().trim().min(1),
+});
+
+export const siteConfigSchema = z.object({
+  siteName: z.string().trim().min(1),
+  siteDescription: z.string().trim().min(1),
+  organizationName: z.string().trim().min(1),
+  footerBlurb: z.string().trim().min(1),
+  primaryCta: publicLinkSchema,
+  secondaryCta: publicLinkSchema,
+  primaryNavigation: z.array(publicLinkSchema).min(1),
+  collections: z.object({
+    docs: contentCollectionConfigSchema,
+    blog: contentCollectionConfigSchema,
+  }),
+});
+
+export const marketingSectionSchema = z.object({
+  eyebrow: z.string().trim().min(1).optional(),
+  title: z.string().trim().min(1),
+  body: z.string().trim().min(1),
+  points: z.array(z.string().trim().min(1)).optional(),
+});
+
+export const marketingPageSchema = z
+  .object({
+    pageKey: z.enum(marketingPageKeys),
+    path: z.string().trim().min(1),
+    heroEyebrow: z.string().trim().min(1),
+    heroTitle: z.string().trim().min(1),
+    heroBody: z.string().trim().min(1),
+    primaryCta: publicLinkSchema,
+    secondaryCta: publicLinkSchema.nullish(),
+    sections: z.array(marketingSectionSchema).min(1),
+    seo: seoMetadataSchema,
+  })
+  .superRefine((page, context) => {
+    const requiredPath = requiredMarketingPagePaths[page.pageKey];
+
+    if (page.path !== requiredPath) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["path"],
+        message: `"${page.pageKey}" marketing page must use the "${requiredPath}" route.`,
+      });
+    }
+  });
+
+const marketingPagesSchema = z
+  .array(marketingPageSchema)
+  .superRefine((pages, context) => {
+    const counts = new Map<MarketingPageKey, number>();
+
+    for (const [index, page] of pages.entries()) {
+      const nextCount = (counts.get(page.pageKey) ?? 0) + 1;
+      counts.set(page.pageKey, nextCount);
+
+      if (nextCount > 1) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [index, "pageKey"],
+          message: `Duplicate marketing page for "${page.pageKey}".`,
+        });
+      }
+    }
+  });
+
+const slugSegmentSchema = z.string().trim().min(1);
+
+const publicEntrySummaryBaseSchema = z.object({
+  title: z.string().trim().min(1),
+  description: z.string().trim().min(1),
+  eyebrow: z.string().trim().min(1).optional(),
+  publishedAt: z.string().trim().min(1).nullable().optional(),
+  readingTime: z.string().trim().min(1).nullable().optional(),
+});
+
+export const docsEntrySummarySchema = publicEntrySummaryBaseSchema.extend({
+  kind: z.literal("docs"),
+  slug: z.array(slugSegmentSchema).min(1),
+});
+
+export const blogEntrySummarySchema = publicEntrySummaryBaseSchema.extend({
+  kind: z.literal("blog"),
+  slug: z.tuple([slugSegmentSchema]),
+});
+
+export const publicEntrySummarySchema = z.union([
+  docsEntrySummarySchema,
+  blogEntrySummarySchema,
+]);
+
+function normalizeSlugParts(slugParts: readonly string[]) {
+  return slugParts.map((part) => part.trim().toLowerCase()).filter(Boolean).join("/");
+}
+
+const publicEntryBodySchema = z.object({
+  body: z.object({
+    intro: z.string().trim().min(1),
+    sections: z
+      .array(
+        z.object({
+          heading: z.string().trim().min(1),
+          paragraphs: z.array(z.string().trim().min(1)).min(1),
+        }),
+      )
+      .min(1),
+  }),
+  seo: seoMetadataSchema,
+});
+
+export const docsEntrySchema = docsEntrySummarySchema.extend(
+  publicEntryBodySchema.shape,
+);
+
+export const blogEntrySchema = blogEntrySummarySchema.extend(
+  publicEntryBodySchema.shape,
+);
+
+export const publicEntrySchema = z.union([docsEntrySchema, blogEntrySchema]);
+
+export const publicContentSnapshotSchema = z.object({
+  site: siteConfigSchema,
+  marketingPages: marketingPagesSchema,
+  docs: z.array(docsEntrySchema),
+  blog: z.array(blogEntrySchema),
+});
+
+export const publicSiteSnapshotEnvironmentSchema = z.enum(["preview", "live"]);
+export const publicSiteSnapshotSourceBoundarySchema = z.enum([
+  "runtime_preview",
+  "published_live",
+]);
+
+export const publicSiteSnapshotEnvelopeSchema = z
+  .object({
+    environment: publicSiteSnapshotEnvironmentSchema,
+    source_boundary: publicSiteSnapshotSourceBoundarySchema,
+    snapshot: publicContentSnapshotSchema,
+  })
+  .superRefine((value, context) => {
+    if (
+      value.environment === "preview" &&
+      value.source_boundary !== "runtime_preview"
+    ) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["source_boundary"],
+        message:
+          'Preview public-site snapshots must declare the "runtime_preview" source boundary.',
+      });
+    }
+
+    if (
+      value.environment === "live" &&
+      value.source_boundary !== "published_live"
+    ) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["source_boundary"],
+        message:
+          'Live public-site snapshots must declare the "published_live" source boundary.',
+      });
+    }
+  });
+
+export function marketingPageResultSchema(
+  pageKey: MarketingPageKey,
+): z.ZodType<MarketingPage | null> {
+  return marketingPageSchema.nullable().superRefine((page, context) => {
+    if (!page) {
+      return;
+    }
+
+    if (page.pageKey !== pageKey) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["pageKey"],
+        message: `Expected "${pageKey}" marketing page.`,
+      });
+    }
+  });
+}
+
+export function publicEntrySummaryListSchema(
+  kind: PublicContentKind,
+): z.ZodType<PublicEntrySummary[]> {
+  return z.array(kind === "docs" ? docsEntrySummarySchema : blogEntrySummarySchema);
+}
+
+export function publicEntryResultSchema(
+  kind: PublicContentKind,
+  slugParts: readonly string[],
+): z.ZodType<PublicEntry | null> {
+  const refineEntryResult = <
+    TEntry extends DocsEntry | BlogEntry | null,
+  >(
+    entry: TEntry,
+    context: z.RefinementCtx,
+  ) => {
+    if (!entry) {
+      return;
+    }
+
+    if (normalizeSlugParts(entry.slug) !== normalizeSlugParts(slugParts)) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["slug"],
+        message: `Expected "${kind}" entry slug to match "${slugParts.join("/")}".`,
+      });
+    }
+  };
+
+  if (kind === "docs") {
+    return docsEntrySchema.nullable().superRefine(refineEntryResult);
+  }
+
+  return blogEntrySchema.nullable().superRefine(refineEntryResult);
+}
+
+export type PublicContentSnapshot = z.infer<typeof publicContentSnapshotSchema>;
+export type PublicSiteSnapshotEnvelope = z.infer<
+  typeof publicSiteSnapshotEnvelopeSchema
+>;

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

@@ -0,0 +1,5 @@
+import type { PublicContentAdapter } from "@/lib/content/contracts";
+
+export function resolveCustomPublicContentAdapter(): PublicContentAdapter | null {
+  return null;
+}

package/assets/templates/next-tenant-app/src/lib/content/empty-state.ts

@@ -0,0 +1,96 @@
+import type {
+  MarketingPage,
+  MarketingPageKey,
+  SiteConfig,
+} from "@/lib/content/contracts";
+
+const emptyMarketingPageConfig: Record<
+  MarketingPageKey,
+  Pick<
+    MarketingPage,
+    | "heroEyebrow"
+    | "heroTitle"
+    | "heroBody"
+    | "path"
+    | "sections"
+  >
+> = {
+  home: {
+    heroEyebrow: "Public site",
+    heroTitle: "Your public site is ready for published content.",
+    heroBody:
+      "Connect this starter to MinuteWork public-site content and publish your first marketing page, docs entry, or blog post.",
+    path: "/",
+    sections: [
+      {
+        eyebrow: "First run",
+        title: "No published home page yet",
+        body:
+          "This starter now reads public-site content from the MinuteWork gateway during development and build.",
+      },
+      {
+        eyebrow: "Preview",
+        title: "Use preview for local authoring",
+        body:
+          "Set MW_PUBLIC_SITE_ENV=preview to render draft-safe preview content through the same API contract.",
+      },
+      {
+        eyebrow: "Publish",
+        title: "Live stays publication-safe",
+        body:
+          "Switch builds and deploys to MW_PUBLIC_SITE_ENV=live once the property has published content available.",
+      },
+    ],
+  },
+  pricing: {
+    heroEyebrow: "Pricing",
+    heroTitle: "Add your first published pricing page.",
+    heroBody:
+      "The pricing route is live, but the property has not published pricing content yet. Publish a pricing page to replace this empty-state shell.",
+    path: "/pricing",
+    sections: [
+      {
+        eyebrow: "Authoring source",
+        title: "Published pages stay externalized",
+        body:
+          "Marketing content now comes from the MinuteWork public-site snapshot API instead of seeded in-repo copy.",
+      },
+      {
+        eyebrow: "Build behavior",
+        title: "Static-first output still works",
+        body:
+          "Builds succeed with valid empty snapshots, so fresh properties can ship before authored content exists.",
+      },
+      {
+        eyebrow: "Next step",
+        title: "Publish pricing content when ready",
+        body:
+          "As soon as the property publishes a pricing page, this shell is replaced automatically by the fetched snapshot.",
+      },
+    ],
+  },
+};
+
+export function buildEmptyMarketingPage(
+  pageKey: MarketingPageKey,
+  siteConfig: SiteConfig,
+): MarketingPage {
+  const config = emptyMarketingPageConfig[pageKey];
+  const titlePrefix =
+    pageKey === "home" ? siteConfig.siteName : `${siteConfig.siteName} Pricing`;
+
+  return {
+    pageKey,
+    path: config.path,
+    heroEyebrow: config.heroEyebrow,
+    heroTitle: config.heroTitle,
+    heroBody: config.heroBody,
+    primaryCta: siteConfig.primaryCta,
+    secondaryCta: siteConfig.secondaryCta,
+    sections: config.sections,
+    seo: {
+      title: titlePrefix,
+      description: siteConfig.siteDescription,
+    },
+  };
+}