Builder CMS live writes + multi-source row-union content databases

templates/content/README.md

@@ -28,3 +28,19 @@ Open http://localhost:8080 and create your first page.
 ## Data
 
 Documents are stored in the app's SQL database. Local development defaults to SQLite at `data/app.db`; deployed apps should set `DATABASE_URL` to a persistent SQL database. The agent should use content actions for normal document operations and reserve `db-query` / `db-exec` for inspection or maintenance.
+
+## Enable Builder live writes
+
+Connect Builder through the existing Builder Connect flow, the same connection used by the AI assistant. Once connected, Content resolves the key automatically for the user, or for org owners/admins through the org connection. There is no separate key entry. In local development, `BUILDER_PRIVATE_KEY` and `BUILDER_PUBLIC_KEY` in `.env.local` also work; see `DEVELOPING.md` for local env opt-in details.
+
+Live writes are only allowed for the safe write model `agent-native-blog-article-test` (`BUILDER_CMS_SAFE_WRITE_MODEL`). Other Builder models stay read-only by design.
+
+Write access is an intentional per-source choice from the source panel selector. Sources start at `read_only`, can move to `stage_only` to push approved changes as Builder autosave revisions, and can move to `publish_updates` for state-preserving live writes. Autosave staging stays quiet; update-in-place and publish writes trigger Builder webhooks so downstream rebuilds can run.
+
+In `publish_updates`, Content PATCHes the Builder entry in place and preserves its current publication state: published entries stay published and drafts stay draft. Content never sends a `published` field, so a normal content push cannot publish or unpublish. Builder merges the field changes and preserves the entry envelope, including scheduling and targeting.
+
+Publication transitions are explicit per-row choices in the review/diff, only when the source enables **Allow publish/unpublish per item**. Publishing a draft or unpublishing a published entry is never a bulk default, and unpublish requires confirmation because it takes live content down. New Builder entries are created as drafts.
+
+**Push all approved (N)** runs approved rows in a concurrency-capped batch. It continues after individual errors, reports per-item `succeeded`, `blocked`, or `failed` status, and can be resumed because already-succeeded items are skipped.
+
+Before each write, Content reads the target's current state from Builder. A write blocks if the entry changed or was deleted since the diff, or if a requested publish/unpublish transition no longer matches the real Builder state. Body diffs remain non-executable for now; they are planned for a later slice.

templates/content/actions/_builder-cms-read-client.ts

@@ -19,6 +19,13 @@ export interface BuilderCmsReadResult {
   message: string | null;
 }
 
+export interface BuilderCmsEntryLiveState {
+  exists: boolean;
+  published: "published" | "draft" | string | null;
+  lastUpdated: number | string | null;
+  id: string | null;
+}
+
 type FetchLike = typeof fetch;
 
 type BuilderMcpContentPart = {
@@ -52,6 +59,80 @@ function entryArrayFromResponse(value: unknown) {
   return Array.isArray(record.results) ? record.results : [];
 }
 
+function stringFromUnknown(value: unknown) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function stringOrNumberFromUnknown(value: unknown) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  return stringFromUnknown(value);
+}
+
+function liveStateFromBuilderEntry(value: unknown): BuilderCmsEntryLiveState {
+  if (Array.isArray(value)) {
+    return value.length > 0
+      ? liveStateFromBuilderEntry(value[0])
+      : {
+          exists: false,
+          published: null,
+          lastUpdated: null,
+          id: null,
+        };
+  }
+  if (!value || typeof value !== "object") {
+    return {
+      exists: false,
+      published: null,
+      lastUpdated: null,
+      id: null,
+    };
+  }
+
+  const record = value as Record<string, unknown>;
+  if (Array.isArray(record.results)) {
+    return liveStateFromBuilderEntry(record.results);
+  }
+  if (Object.keys(record).length === 0) {
+    return {
+      exists: false,
+      published: null,
+      lastUpdated: null,
+      id: null,
+    };
+  }
+
+  const data =
+    record.data &&
+    typeof record.data === "object" &&
+    !Array.isArray(record.data)
+      ? (record.data as Record<string, unknown>)
+      : {};
+  const id =
+    stringFromUnknown(record.id) ??
+    stringFromUnknown(record["@id"]) ??
+    stringFromUnknown(record.uuid);
+  if (!id) {
+    return {
+      exists: false,
+      published: null,
+      lastUpdated: null,
+      id: null,
+    };
+  }
+
+  return {
+    exists: true,
+    published:
+      stringFromUnknown(record.published) ?? stringFromUnknown(data.published),
+    lastUpdated:
+      stringOrNumberFromUnknown(record.lastUpdated) ??
+      stringOrNumberFromUnknown(record.updatedDate) ??
+      stringOrNumberFromUnknown(record.updatedAt) ??
+      stringOrNumberFromUnknown(data.updatedAt),
+    id,
+  };
+}
+
 function readLimit(limit: number | undefined) {
   if (typeof limit === "number" && Number.isFinite(limit) && limit > 0) {
     return Math.min(Math.floor(limit), BUILDER_CMS_MAX_READ_LIMIT);
@@ -506,6 +587,50 @@ async function readBuilderCmsContentEntriesViaContentApi(args: {
   };
 }
 
+export async function readBuilderCmsEntryLiveState(args: {
+  model: string;
+  entryId: string;
+  fetchImpl?: FetchLike;
+}): Promise<BuilderCmsEntryLiveState> {
+  const publicKey = await resolveBuilderCredential("BUILDER_PUBLIC_KEY");
+  if (!publicKey) {
+    throw new Error(
+      "Builder CMS live entry read skipped because BUILDER_PUBLIC_KEY is not configured.",
+    );
+  }
+
+  const url = new URL(
+    `/api/v3/content/${encodeURIComponent(args.model)}/${encodeURIComponent(
+      args.entryId,
+    )}`,
+    builderContentApiHost(),
+  );
+  url.searchParams.set("apiKey", publicKey);
+  url.searchParams.set("includeUnpublished", "true");
+  url.searchParams.set("cachebust", String(Date.now()));
+
+  const response = await fetchBuilderContentPage({
+    fetchImpl: args.fetchImpl ?? fetch,
+    url,
+  });
+  if (response.status === 404) {
+    return {
+      exists: false,
+      published: null,
+      lastUpdated: null,
+      id: null,
+    };
+  }
+  if (!response.ok) {
+    throw new Error(
+      `Builder CMS live entry read failed with HTTP ${response.status}.`,
+    );
+  }
+
+  const json = (await response.json()) as unknown;
+  return liveStateFromBuilderEntry(json);
+}
+
 export async function listBuilderCmsModels(
   args: {
     fetchImpl?: FetchLike;

templates/content/actions/_builder-cms-source-adapter.test.ts

@@ -66,12 +66,15 @@ describe("Builder CMS source adapter", () => {
     );
   });
 
-  it("records Builder metadata with natural key and autosave push mode", () => {
+  it("records Builder metadata with natural key and read-only write mode", () => {
     expect(builderCmsSourceMetadata("blog_article")).toMatchObject({
       primaryKey: "id",
       titleField: "data.title",
       naturalKeyField: "/blog/[slug]",
-      pushMode: "autosave",
+      pushMode: "none",
+      writeMode: "read_only",
+      allowPublicationTransitions: false,
+      allowedWriteModes: [],
       label: "builder.cms.blog_article",
     });
   });
@@ -206,6 +209,36 @@ describe("Builder CMS source adapter", () => {
     });
   });
 
+  it("uses numeric Builder lastUpdated as the row source baseline", () => {
+    const lastUpdated = 1782328870774;
+    const entry = normalizeBuilderCmsApiEntry(
+      {
+        id: "entry-numeric-last-updated",
+        lastUpdated,
+        data: {
+          title: "Numeric timestamp entry",
+          url: "/blog/numeric-timestamp-entry",
+        },
+      },
+      "blog_article",
+    );
+
+    if (!entry) throw new Error("Expected Builder entry to normalize.");
+    expect(entry.updatedAt).toBe(String(lastUpdated));
+    expect(entry.sourceValues.lastUpdated).toBe(String(lastUpdated));
+    expect(
+      builderCmsSourceRowIdentity({
+        item: item("Local title"),
+        sourceTable: "blog_article",
+        now: "2026-06-08T12:30:00.000Z",
+        entry,
+      }),
+    ).toMatchObject({
+      sourceRowId: "entry-numeric-last-updated",
+      lastSourceUpdatedAt: String(lastUpdated),
+    });
+  });
+
   it("renders Builder reference fields as readable labels, not raw JSON", () => {
     const result = normalizeBuilderCmsApiEntry(
       {

templates/content/actions/_builder-cms-source-adapter.ts

@@ -164,11 +164,13 @@ export function builderCmsSourceMetadata(sourceTable: string) {
     primaryKey: "id",
     titleField: "data.title",
     naturalKeyField: "/blog/[slug]",
-    pushMode: "autosave" as const,
-    pushModeLabel: "Save revision / autosave",
+    pushMode: "none" as const,
+    pushModeLabel: "No writes",
     pushModeDescription:
-      "Local-only Builder revision staging. No Builder API write runs in this slice.",
-    allowedWriteModes: ["autosave"],
+      "Read-only Builder source. Choose a write tier before any Builder API write can run.",
+    writeMode: "read_only" as const,
+    allowPublicationTransitions: false,
+    allowedWriteModes: [],
     allowDraftWrites: false,
     allowPublishWrites: false,
     notes:
@@ -196,6 +198,22 @@ function stringFromRecord(
   return null;
 }
 
+function timestampStringFromRecord(
+  value: Record<string, unknown>,
+  keys: string[],
+): string | null {
+  for (const key of keys) {
+    const candidate = value[key];
+    if (typeof candidate === "number" && Number.isFinite(candidate)) {
+      return String(candidate);
+    }
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+  return null;
+}
+
 function pickStringField(
   obj: Record<string, unknown>,
   keys: string[],
@@ -317,8 +335,12 @@ export function normalizeBuilderCmsApiEntry(
     stringFromRecord(data, ["url", "urlPath", "path"]) ??
     (slug ? `/blog/${slug.replace(/^\/+/, "")}` : `/blog/${id}`);
   const updatedAt =
-    stringFromRecord(record, ["lastUpdated", "updatedDate", "updatedAt"]) ??
-    stringFromRecord(data, ["updatedAt"]) ??
+    timestampStringFromRecord(record, [
+      "lastUpdated",
+      "updatedDate",
+      "updatedAt",
+    ]) ??
+    timestampStringFromRecord(data, ["updatedAt"]) ??
     new Date().toISOString();
 
   return {