minutework 0.1.6 → 0.1.8

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

@@ -1,9 +1,10 @@
 import "server-only";
 
 import { cache } from "react";
-import type { ZodType } from "zod";
+import { z, type ZodType } from "zod";
 
 import type {
+  ContentStructurePage,
   MarketingPage,
   MarketingPageKey,
   PublicContentAdapter,
@@ -14,6 +15,7 @@ import type {
   SiteConfig,
 } from "@/lib/content/contracts";
 import {
+  contentStructurePageSchema,
   marketingPageResultSchema,
   publicEntryResultSchema,
   publicEntrySummaryListSchema,
@@ -110,6 +112,26 @@ export class ValidatedPublicContentAdapter implements PublicContentAdapter {
       await this.adapter.getEntry(kind, slugParts),
     );
   }
+
+  async getPageByPath(path: string): Promise<ContentStructurePage | null> {
+    if (!this.adapter.getPageByPath) return null;
+    return validateAdapterResult(
+      this.adapterLabel,
+      `CMS page for path "${path}"`,
+      contentStructurePageSchema.nullable(),
+      await this.adapter.getPageByPath(path),
+    );
+  }
+
+  async listPages(status?: string): Promise<ContentStructurePage[]> {
+    if (!this.adapter.listPages) return [];
+    return validateAdapterResult(
+      this.adapterLabel,
+      "CMS page list",
+      z.array(contentStructurePageSchema),
+      await this.adapter.listPages(status),
+    );
+  }
 }
 
 export async function fetchPublicSiteSnapshotEnvelope(input: {
@@ -197,6 +219,22 @@ export class MinuteWorkPublicSiteContentAdapter implements PublicContentAdapter
       ) ?? null
     );
   }
+
+  async getPageByPath(path: string): Promise<ContentStructurePage | null> {
+    const snapshot = await this.loadSnapshot();
+    const pages = snapshot.pages ?? [];
+    const normalizedPath = path.replace(/\/+$/, "") || "/";
+    return pages.find((p) => p.path === normalizedPath) ?? null;
+  }
+
+  async listPages(status?: string): Promise<ContentStructurePage[]> {
+    const snapshot = await this.loadSnapshot();
+    const pages = snapshot.pages ?? [];
+    if (status) {
+      return pages.filter((p) => p.status === status);
+    }
+    return pages;
+  }
 }
 
 const defaultPublicContentAdapter = new ValidatedPublicContentAdapter(
@@ -230,3 +268,11 @@ export const listEntries = cache(async (kind: PublicContentKind) =>
 export const getEntry = cache(async (kind: PublicContentKind, slugParts: string[]) =>
   getPublicContentAdapter().getEntry(kind, slugParts),
 );
+
+export const getPageByPath = cache(async (path: string) =>
+  getPublicContentAdapter().getPageByPath(path),
+);
+
+export const listPages = cache(async (status?: string) =>
+  getPublicContentAdapter().listPages(status),
+);

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

@@ -0,0 +1,138 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  contentSectionSchema,
+  contentStructurePageSchema,
+  publicContentSnapshotSchema,
+} from "./contracts";
+
+describe("content_structure contracts", () => {
+  it("validates a page with arbitrary section types", () => {
+    const page = {
+      page_key: "landing",
+      path: "/landing",
+      title: "Landing Page",
+      status: "published",
+      sort_order: 0,
+      content_structure: {
+        sections: [
+          {
+            section_key: "hero",
+            section_type: "hero_banner",
+            sort_order: 0,
+            data: { heading: "Welcome", subheading: "To our site" },
+          },
+          {
+            section_key: "features",
+            section_type: "custom_feature_grid",
+            sort_order: 1,
+            data: {
+              columns: 3,
+              items: [
+                { title: "Fast", icon: "bolt" },
+                { title: "Secure", icon: "lock" },
+              ],
+            },
+          },
+          {
+            section_key: "tenant_custom",
+            section_type: "my_custom_widget",
+            sort_order: 2,
+            data: { arbitrary: "tenant-defined", nested: { deep: true } },
+          },
+        ],
+      },
+      seo_metadata: {
+        title: "Landing Page",
+        description: "A landing page with arbitrary sections",
+      },
+    };
+
+    const result = contentStructurePageSchema.safeParse(page);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.content_structure.sections).toHaveLength(3);
+      expect(result.data.content_structure.sections[2]!.section_type).toBe(
+        "my_custom_widget",
+      );
+    }
+  });
+
+  it("rejects a section without section_key", () => {
+    const section = {
+      section_type: "text",
+      data: { heading: "Heading" },
+    };
+    const result = contentSectionSchema.safeParse(section);
+    expect(result.success).toBe(false);
+  });
+
+  it("allows empty sections array", () => {
+    const page = {
+      page_key: "empty",
+      path: "/empty",
+      title: "Empty Page",
+      status: "draft",
+      content_structure: { sections: [] },
+    };
+    const result = contentStructurePageSchema.safeParse(page);
+    expect(result.success).toBe(true);
+  });
+
+  it("snapshot schema accepts optional pages array", () => {
+    const snapshot = {
+      site: {
+        siteName: "Test",
+        siteDescription: "Test site",
+        organizationName: "Org",
+        footerBlurb: "Footer",
+        primaryCta: { label: "CTA", href: "/" },
+        secondaryCta: { label: "CTA2", href: "/docs" },
+        primaryNavigation: [{ label: "Home", href: "/" }],
+        collections: {
+          docs: { eyebrow: "Docs", title: "Docs", description: "Documentation" },
+          blog: { eyebrow: "Blog", title: "Blog", description: "Updates" },
+        },
+      },
+      marketingPages: [],
+      docs: [],
+      blog: [],
+      pages: [
+        {
+          page_key: "about",
+          path: "/about",
+          title: "About",
+          status: "published",
+          content_structure: { sections: [] },
+        },
+      ],
+    };
+
+    const result = publicContentSnapshotSchema.safeParse(snapshot);
+    expect(result.success).toBe(true);
+  });
+
+  it("snapshot schema works without pages field (backward compat)", () => {
+    const snapshot = {
+      site: {
+        siteName: "Test",
+        siteDescription: "Test site",
+        organizationName: "Org",
+        footerBlurb: "Footer",
+        primaryCta: { label: "CTA", href: "/" },
+        secondaryCta: { label: "CTA2", href: "/docs" },
+        primaryNavigation: [{ label: "Home", href: "/" }],
+        collections: {
+          docs: { eyebrow: "Docs", title: "Docs", description: "Documentation" },
+          blog: { eyebrow: "Blog", title: "Blog", description: "Updates" },
+        },
+      },
+      marketingPages: [],
+      docs: [],
+      blog: [],
+    };
+
+    const result = publicContentSnapshotSchema.safeParse(snapshot);
+    expect(result.success).toBe(true);
+  });
+});

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

@@ -93,11 +93,48 @@ export type DocsEntry = DocsEntrySummary & PublicEntryBody;
 export type BlogEntry = BlogEntrySummary & PublicEntryBody;
 export type PublicEntry = DocsEntry | BlogEntry;
 
+/**
+ * A single section/block within a CMS page's content_structure.
+ *
+ * Section types are extensible strings — not a closed enum.  This allows
+ * tenant-specific or extension-pack sections without modifying the baseline.
+ */
+export type ContentSection = {
+  section_key: string;
+  section_type: string;
+  sort_order?: number;
+  data: Record<string, unknown>;
+};
+
+/**
+ * A CMS page backed by the mw.core.site runtime baseline.
+ *
+ * content_structure is an open, ordered section/block graph — not a fixed
+ * template.  The section renderer maps section_type to React components.
+ */
+export type ContentStructurePage = {
+  page_key: string;
+  path: string;
+  title: string;
+  status: string;
+  sort_order?: number;
+  content_structure: {
+    sections: ContentSection[];
+  };
+  seo_metadata?: SeoMetadata;
+  og_metadata?: Record<string, string>;
+  visibility?: string;
+};
+
 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>;
+  /** Retrieve a CMS page by its URL path. Returns null if not found. */
+  getPageByPath?(path: string): Promise<ContentStructurePage | null>;
+  /** List all CMS pages, optionally filtered by status. */
+  listPages?(status?: string): Promise<ContentStructurePage[]>;
 }
 
 export const publicLinkSchema = z.object({
@@ -234,11 +271,33 @@ export const blogEntrySchema = blogEntrySummarySchema.extend(
 
 export const publicEntrySchema = z.union([docsEntrySchema, blogEntrySchema]);
 
+export const contentSectionSchema = z.object({
+  section_key: z.string().min(1),
+  section_type: z.string().min(1),
+  sort_order: z.number().optional(),
+  data: z.record(z.unknown()),
+});
+
+export const contentStructurePageSchema = z.object({
+  page_key: z.string().min(1),
+  path: z.string().min(1),
+  title: z.string().min(1),
+  status: z.string().min(1),
+  sort_order: z.number().optional(),
+  content_structure: z.object({
+    sections: z.array(contentSectionSchema),
+  }),
+  seo_metadata: seoMetadataSchema.optional(),
+  og_metadata: z.record(z.string()).optional(),
+  visibility: z.string().optional(),
+});
+
 export const publicContentSnapshotSchema = z.object({
   site: siteConfigSchema,
   marketingPages: marketingPagesSchema,
   docs: z.array(docsEntrySchema),
   blog: z.array(blogEntrySchema),
+  pages: z.array(contentStructurePageSchema).optional(),
 });
 
 export const publicSiteSnapshotEnvironmentSchema = z.enum(["preview", "live"]);

package/assets/templates/next-tenant-app/src/lib/content/release-manifest.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+
+import { buildReleaseManifest, releaseManifestSchema } from "./release-manifest";
+
+describe("release-manifest", () => {
+  it("builds a valid manifest from composition input", () => {
+    const manifest = buildReleaseManifest({
+      appPackId: "mw.core.site",
+      snapshotSchemaVersion: 1,
+      releaseClass: "static_export",
+      config: { site_title: "Test Site" },
+      pages: [
+        {
+          page_key: "home",
+          path: "/",
+          title: "Home",
+          sections: [{ section_key: "hero", section_type: "hero", data: {} }],
+        },
+        {
+          page_key: "about",
+          path: "/about",
+          title: "About",
+          sections: [],
+        },
+      ],
+      navigation: [
+        { nav_key: "header", slot: "header", items: [{ label: "Home" }] },
+      ],
+      forms: [
+        { form_key: "contact", schema: { fields: [{ name: "email" }] } },
+      ],
+      contentDigest: "sha256-abc123",
+    });
+
+    const parsed = releaseManifestSchema.safeParse(manifest);
+    expect(parsed.success).toBe(true);
+    expect(manifest.manifest_version).toBe(1);
+    expect(manifest.composition.config_updated).toBe(true);
+    expect(manifest.composition.pages).toHaveLength(2);
+    expect(manifest.composition.pages[0]!.section_count).toBe(1);
+    expect(manifest.composition.pages[1]!.section_count).toBe(0);
+    expect(manifest.composition.navigation[0]!.item_count).toBe(1);
+    expect(manifest.composition.forms[0]!.field_count).toBe(1);
+  });
+
+  it("handles null config", () => {
+    const manifest = buildReleaseManifest({
+      appPackId: "mw.core.site",
+      snapshotSchemaVersion: 1,
+      releaseClass: "ssr_container",
+      config: null,
+      pages: [],
+      navigation: [],
+      forms: [],
+      contentDigest: "sha256-empty",
+    });
+
+    expect(manifest.composition.config_updated).toBe(false);
+  });
+
+  it("validates against the schema", () => {
+    const invalid = {
+      manifest_version: 2, // wrong version
+      app_pack_id: "",
+    };
+
+    const parsed = releaseManifestSchema.safeParse(invalid);
+    expect(parsed.success).toBe(false);
+  });
+});

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

@@ -0,0 +1,106 @@
+import { z } from "zod";
+
+import { contentStructurePageSchema, siteConfigSchema } from "./contracts";
+
+/**
+ * Release manifest contract for Builder output.
+ *
+ * When Builder composes a site, it emits a manifest that describes what
+ * was generated.  This manifest is inspectable, diffable, and can be
+ * used to verify that releases match expectations.
+ *
+ * The manifest is NOT the release artifact itself — it describes the
+ * composition that produced the artifact.
+ */
+
+export const releaseManifestSchema = z.object({
+  /** Manifest format version. */
+  manifest_version: z.literal(1),
+
+  /** The app pack ID that was composed. */
+  app_pack_id: z.string().min(1),
+
+  /** Snapshot schema version for compatibility gating. */
+  snapshot_schema_version: z.number().int().positive(),
+
+  /** Release class from the hosted vocabulary. */
+  release_class: z.enum(["static_export", "ssr_container", "runtime_local_sidecar"]),
+
+  /** Summary of what was composed. */
+  composition: z.object({
+    config_updated: z.boolean(),
+    pages: z.array(
+      z.object({
+        page_key: z.string().min(1),
+        path: z.string().min(1),
+        title: z.string().min(1),
+        section_count: z.number().int().min(0),
+      }),
+    ),
+    navigation: z.array(
+      z.object({
+        nav_key: z.string().min(1),
+        slot: z.string().min(1),
+        item_count: z.number().int().min(0),
+      }),
+    ),
+    forms: z.array(
+      z.object({
+        form_key: z.string().min(1),
+        field_count: z.number().int().min(0),
+      }),
+    ),
+  }),
+
+  /** Digest of the composed content for integrity verification. */
+  content_digest: z.string().min(1),
+
+  /** Timestamp of the manifest generation. */
+  generated_at: z.string().min(1),
+});
+
+export type ReleaseManifest = z.infer<typeof releaseManifestSchema>;
+
+/**
+ * Build a release manifest from a Builder composition result.
+ *
+ * This is called by Builder after compose_site_from_builder_payload
+ * to produce an inspectable record of what was generated.
+ */
+export function buildReleaseManifest(input: {
+  appPackId: string;
+  snapshotSchemaVersion: number;
+  releaseClass: "static_export" | "ssr_container" | "runtime_local_sidecar";
+  config: Record<string, unknown> | null;
+  pages: { page_key: string; path: string; title: string; sections: unknown[] }[];
+  navigation: { nav_key: string; slot: string; items: unknown[] }[];
+  forms: { form_key: string; schema?: { fields?: unknown[] } }[];
+  contentDigest: string;
+}): ReleaseManifest {
+  return {
+    manifest_version: 1,
+    app_pack_id: input.appPackId,
+    snapshot_schema_version: input.snapshotSchemaVersion,
+    release_class: input.releaseClass,
+    composition: {
+      config_updated: input.config !== null,
+      pages: input.pages.map((p) => ({
+        page_key: p.page_key,
+        path: p.path,
+        title: p.title,
+        section_count: p.sections?.length ?? 0,
+      })),
+      navigation: input.navigation.map((n) => ({
+        nav_key: n.nav_key,
+        slot: n.slot,
+        item_count: n.items?.length ?? 0,
+      })),
+      forms: input.forms.map((f) => ({
+        form_key: f.form_key,
+        field_count: f.schema?.fields?.length ?? 0,
+      })),
+    },
+    content_digest: input.contentDigest,
+    generated_at: new Date().toISOString(),
+  };
+}

package/assets/templates/next-tenant-app/template.json

@@ -1,9 +1,9 @@
 {
   "template_id": "next-tenant-app",
-  "template_kind": "sidecar_nextjs_private",
+  "template_kind": "combined_web",
   "template_profile": "platform_session_bff",
   "template_bundle_ref": "runtime/builder/templates/next-tenant-app",
-  "template_version": "0.2.0",
+  "template_version": "0.3.0",
   "materialize": {
     "destination": "app"
   },

package/assets/templates/next-tenant-app/template.schema.json

@@ -24,7 +24,8 @@
       "type": "string",
       "enum": [
         "sidecar_nextjs_private",
-        "sidecar_fastapi_internal"
+        "sidecar_fastapi_internal",
+        "combined_web"
       ]
     },
     "template_profile": {

package/assets/templates/next-tenant-app/tools/template/with-public-site-fixture.mjs

@@ -0,0 +1,130 @@
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+
+const [command, ...args] = process.argv.slice(2);
+const storybookHeapMb = process.env.MW_STORYBOOK_NODE_HEAP_MB ?? "768";
+
+if (!command) {
+  console.error("Usage: node tools/template/with-public-site-fixture.mjs <command> [args...]");
+  process.exit(1);
+}
+
+const emptySnapshot = {
+  site: {
+    siteName: "MinuteWork Combined Starter",
+    siteDescription: "Validation fixture snapshot for the combined starter.",
+    organizationName: "MinuteWork",
+    footerBlurb: "Validation fixture content.",
+    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: "Documentation",
+        description: "Validation fixture docs collection.",
+      },
+      blog: {
+        eyebrow: "Blog",
+        title: "Updates",
+        description: "Validation fixture blog collection.",
+      },
+    },
+  },
+  marketingPages: [],
+  docs: [],
+  blog: [],
+};
+
+const server = createServer((request, response) => {
+  const requestUrl = new URL(request.url ?? "/", "http://127.0.0.1");
+  if (
+    request.method !== "GET" ||
+    requestUrl.pathname !== "/api/v1/developer/public-site/snapshots/main-site/"
+  ) {
+    response.writeHead(404, { "content-type": "application/json" });
+    response.end(JSON.stringify({ detail: "Not found" }));
+    return;
+  }
+
+  const environment = requestUrl.searchParams.get("environment") ?? "preview";
+  const sourceBoundary = environment === "live" ? "published_live" : "runtime_preview";
+
+  response.writeHead(200, { "content-type": "application/json" });
+  response.end(
+    JSON.stringify({
+      environment,
+      source_boundary: sourceBoundary,
+      snapshot: emptySnapshot,
+    }),
+  );
+});
+
+try {
+  const baseUrl = await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        reject(new Error("Unable to resolve validation fixture server address."));
+        return;
+      }
+      resolve(`http://127.0.0.1:${address.port}`);
+    });
+  });
+
+  const exitCode = await new Promise((resolve, reject) => {
+    const childEnv = {
+      ...process.env,
+      MW_CONTENT_API_TOKEN: "validate-content-token",
+      MW_PLATFORM_BASE_URL: baseUrl,
+      MW_PUBLIC_BASE_URL: "https://public.example.com",
+      MW_PUBLIC_SITE_ENV: "preview",
+      MW_PUBLIC_SITE_PROPERTY_KEY: "main-site",
+    };
+    if (
+      command === "storybook" &&
+      !/\bmax-old-space-size=/.test(childEnv.NODE_OPTIONS ?? "")
+    ) {
+      childEnv.NODE_OPTIONS = [childEnv.NODE_OPTIONS, `--max-old-space-size=${storybookHeapMb}`]
+        .filter(Boolean)
+        .join(" ");
+    }
+    const child = spawn(command, args, {
+      env: childEnv,
+      stdio: "inherit",
+    });
+
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (signal) {
+        reject(new Error(`Validation fixture command exited via signal ${signal}.`));
+        return;
+      }
+      resolve(code ?? 1);
+    });
+  });
+
+  process.exitCode = exitCode;
+} finally {
+  await new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve(undefined);
+    });
+  });
+}

package/dist/agent.d.ts

@@ -0,0 +1,19 @@
+import type { CliIo } from "./index.js";
+import type { CliStatePaths, PlatformName } from "./paths.js";
+export type AgentDependencies = {
+    closeInput?: () => void;
+    fetchImpl?: typeof fetch;
+    heartbeatIntervalMs?: number;
+    inputLines?: AsyncIterable<string>;
+    pollIntervalMs?: number;
+    sleepImpl?: (ms: number) => Promise<void>;
+};
+export declare function runAgentCommand(options: {
+    args: string[];
+    cwd: string;
+    dependencies?: AgentDependencies;
+    env: NodeJS.ProcessEnv;
+    io: CliIo;
+    paths: CliStatePaths;
+    platform: PlatformName;
+}): Promise<number>;