@taprootio/site-authoring 0.11.1 → 0.12.0

package/src/verbs/pull.js

@@ -8,7 +8,6 @@ import {
   PAGE_STATUS_DELETED,
   PAGE_STATUS_DRAFT,
   PAGE_STATUS_UNKNOWN,
-  TEMPLATE_TYPE_FREE_FORM,
   withRefusalGuidance,
 } from "../api.js";
 import {
@@ -32,6 +31,7 @@ import {
   SETTINGS_TYPE_TAPROOT_STYLES,
 } from "../settings-catalog.js";
 import { ApiError } from "../transport.js";
+import { isAuthorableTemplateType, sentDisplayDate, workspaceDocumentFromPage } from "../typed-pages.js";
 import {
   canonicalDocumentHash,
   deleteWorkspaceFile,
@@ -47,6 +47,7 @@ import {
   normalizePageBodyRevision,
   normalizePagePath,
   PAGE_SOURCE_EXTENSIONS,
+  pageContentKey,
   PAGE_SOURCE_FORMAT_MARKDOWN,
   PAGE_WORKSPACE_MODE_EDITABLE,
   PAGE_WORKSPACE_MODE_METADATA_ONLY,
@@ -481,13 +482,9 @@ function pathFromRead(page, summary) {
   return normalized === undefined ? summary.path : normalized;
 }
 
-function freeFormBody(page) {
-  const template = page.template;
-  if (template === null || typeof template !== "object") return undefined;
-  const data = template.freeFormData;
-  if (data === null || typeof data !== "object") return undefined;
-  const body = data.body;
-  return body !== null && typeof body === "object" && !Array.isArray(body) ? body : undefined;
+/** The date a read reports for a page whose push sends one, or `undefined` for a free-form page. */
+function trackedDisplayDate(page, templateType) {
+  return sentDisplayDate(templateType) ? (typeof page.displayDate === "string" ? page.displayDate : "") : undefined;
 }
 
 function notThisSite(message, field) {
@@ -601,9 +598,9 @@ export async function pull(invocation) {
       ({ pages, truncated } = await listSitePages(client, siteId, { onProgress }));
     }
     const live = pages.filter((summary) => summary.status !== PAGE_STATUS_DELETED);
-    const freeForm = live.filter((summary) => summary.templateType === TEMPLATE_TYPE_FREE_FORM);
-    const tracked = await resolveTrackedSources(config.workspaceDir, freeForm, registry, onProgress);
-    const pageFiles = assignPageFiles(freeForm, tracked);
+    const authorable = live.filter((summary) => isAuthorableTemplateType(summary.templateType));
+    const tracked = await resolveTrackedSources(config.workspaceDir, authorable, registry, onProgress);
+    const pageFiles = assignPageFiles(authorable, tracked);
 
     // The redirect map, with the revision a later push is fenced by (TR00702).
     // Read here, before the first workspace write, for the same reason the
@@ -732,18 +729,18 @@ export async function pull(invocation) {
     const conflicts = [];
     let bufferedBytes = 0;
     let revisionsRecordedWithoutBodyComparison = 0;
-    for (const summary of freeForm) {
+    for (const summary of authorable) {
       const source = tracked.get(summary.pageId);
       if (source === undefined) continue;
-      onProgress(`Reading free-form page '${summary.path}'.`);
+      onProgress(`Reading page '${summary.path}'.`);
       const page = await getPage(client, summary.pageId, bodyStatusFor(summary));
-      const body = freeFormBody(page);
+      const body = workspaceDocumentFromPage(page, summary.templateType);
       const description = typeof page.shortDescription === "string" ? page.shortDescription : "";
       if (body === undefined) {
         // The site's body is unreadable, but the workspace file is still this
         // page's one source. Dropping it from the registry would let the next
         // pull mint the competing document all over again.
-        onProgress(`Page '${summary.path}' has no readable free-form body; keeping '${source.file}' as its source.`);
+        onProgress(`Page '${summary.path}' has no readable body; keeping '${source.file}' as its source.`);
         trackedPlans.set(summary.pageId, {
           description,
           title: titleFromRead(page, summary),
@@ -798,9 +795,17 @@ export async function pull(invocation) {
       // projection moved across the API deploy. This costs one pull's detection
       // at the upgrade boundary, the same trade `withoutSupersededRemoteHashes`
       // accepts.
-      const remoteChanged = revision !== undefined
+      const revisionChanged = revision !== undefined
         ? source.baseline?.revision !== undefined && source.baseline.revision !== revision
         : source.baseline?.remoteHash !== undefined && source.baseline.remoteHash !== remoteHash;
+      // A typed page's display date is edited in the app and is not covered by
+      // the revision, so it is compared on its own: otherwise a push would
+      // silently write a stale date over the newer one (TR00893).
+      const remoteDisplayDate = trackedDisplayDate(page, summary.templateType);
+      const dateChanged = remoteDisplayDate !== undefined
+        && source.baseline?.displayDate !== undefined
+        && source.baseline.displayDate !== remoteDisplayDate;
+      const remoteChanged = revisionChanged || dateChanged;
       // Markdown is one-way, so a Markdown source can never be rewritten from
       // the site's document and is always kept. A ProseMirror source can be
       // refreshed — but only over content the author has not edited since the
@@ -860,12 +865,22 @@ export async function pull(invocation) {
           ? {
             remoteHash,
             sourceHash: localChanged ? source.baseline?.sourceHash : sourceHash,
+            // Carried, never minted here: a kept source is only known to match
+            // the site if a push or an earlier pull already said so.
+            ...(source.baseline?.contentKey === undefined ? {} : { contentKey: source.baseline.contentKey }),
             ...(revision === undefined ? {} : { revision }),
+            ...(remoteDisplayDate === undefined ? {} : { displayDate: remoteDisplayDate }),
           }
           : {
             remoteHash,
             sourceHash: workspaceContentHash(serialized),
+            contentKey: pageContentKey(workspaceContentHash(serialized), {
+              title: titleFromRead(page, summary),
+              path: pathFromRead(page, summary),
+              description,
+            }),
             ...(revision === undefined ? {} : { revision }),
+            ...(remoteDisplayDate === undefined ? {} : { displayDate: remoteDisplayDate }),
           },
         ...(keepLocal ? { baselineBody: serialized, baselineFile } : { refresh: serialized, baselineFile }),
       });
@@ -887,7 +902,10 @@ export async function pull(invocation) {
         // what the fallback comparison above is made against, so it is equally
         // the thing a record has to name.
         const observed = await readObservedPageRecord(config.workspaceDir, summary.pageId);
+        // A typed page's date moves without moving the revision, so the date
+        // the record showed must match too or its differences are stale.
         const alreadyShown = observed !== undefined
+          && observed.displayDate === remoteDisplayDate
           && (revision === undefined
             ? observed.revision === undefined && observed.remoteHash === remoteHash
             : observed.revision === revision);
@@ -922,6 +940,7 @@ export async function pull(invocation) {
             differences,
             observedRevision: revision,
             observedRemoteHash: remoteHash,
+            observedDisplayDate: remoteDisplayDate,
             observedRevisionFile: internalPageObservedRevisionFile(summary.pageId),
           });
         }
@@ -972,6 +991,7 @@ export async function pull(invocation) {
           ...(conflict.observedRevision === undefined
             ? { remoteHash: conflict.observedRemoteHash }
             : { revision: conflict.observedRevision }),
+          ...(conflict.observedDisplayDate === undefined ? {} : { displayDate: conflict.observedDisplayDate }),
           ...(conflict.differences === undefined ? {} : { differences: conflict.differences }),
         });
       }
@@ -993,7 +1013,7 @@ export async function pull(invocation) {
         isGenerated: summary.isGenerated,
         workspaceMode: PAGE_WORKSPACE_MODE_METADATA_ONLY,
       };
-      if (summary.templateType === TEMPLATE_TYPE_FREE_FORM) {
+      if (isAuthorableTemplateType(summary.templateType)) {
         // This pull is reconciling the page, so the manifest below carries the
         // newer and stronger claim and the "what the operator was shown" record
         // is spent. Leaving it would let a push override a remote change this
@@ -1026,9 +1046,9 @@ export async function pull(invocation) {
           manifestPages.push(entry);
           continue;
         }
-        onProgress(`Reading free-form page '${summary.path}'.`);
+        onProgress(`Reading page '${summary.path}'.`);
         const page = await getPage(client, summary.pageId, bodyStatusFor(summary));
-        const body = freeFormBody(page);
+        const body = workspaceDocumentFromPage(page, summary.templateType);
         entry.description = typeof page.shortDescription === "string" ? page.shortDescription : "";
         entry.title = titleFromRead(page, summary);
         entry.path = pathFromRead(page, summary);
@@ -1036,17 +1056,24 @@ export async function pull(invocation) {
           // The server accepts and stores a body it never validates, so an
           // unreadable one is a real state. It is reported rather than written
           // as an empty document that a later push would send back.
-          onProgress(`Page '${summary.path}' has no readable free-form body; snapshotting metadata only.`);
+          onProgress(`Page '${summary.path}' has no readable body; snapshotting metadata only.`);
         } else {
           entry.file = pageFiles.get(summary.pageId);
           const source = Buffer.from(`${JSON.stringify(body, undefined, 2)}\n`, "utf8");
           entry.workspaceMode = PAGE_WORKSPACE_MODE_EDITABLE;
           entry.sourceFormat = pageSourceFormat(entry.file);
           const revision = normalizePageBodyRevision(page.bodyRevision);
+          const displayDate = trackedDisplayDate(page, summary.templateType);
           entry.baseline = {
             remoteHash: canonicalDocumentHash(body),
             sourceHash: workspaceContentHash(source),
+            contentKey: pageContentKey(workspaceContentHash(source), {
+              title: entry.title,
+              path: entry.path,
+              description: entry.description,
+            }),
             ...(revision === undefined ? {} : { revision }),
+            ...(displayDate === undefined ? {} : { displayDate }),
           };
           await writeWorkspaceFile(config.workspaceDir, entry.file, source);
           bodies += 1;

package/src/verbs/validate.js

@@ -1,7 +1,7 @@
 import { lstat, realpath } from "node:fs/promises";
 import path from "node:path";
 
-import { NAVIGATION_MAXIMUM_DEPTH, TEMPLATE_TYPE_FREE_FORM } from "../api.js";
+import { NAVIGATION_MAXIMUM_DEPTH } from "../api.js";
 import { VERB_VALIDATE } from "../constants.js";
 import { freeFormRootPresentation, sharedThemeContextNames } from "../content/free-form-sections.js";
 import { isCanonicalUuid, SiteAuthoringError } from "../errors.js";
@@ -41,6 +41,7 @@ import { validateFooterWorkspaceDocument } from "./footer-push.js";
 import { validateNavigationWorkspaceDocument } from "./nav-push.js";
 import { validateWorkspacePageDocument, validateWorkspacePageSource } from "./pages-push.js";
 import { validateThemeWorkspace } from "./theme-push.js";
+import { documentImageIds, documentTemplate, isAuthorableTemplateType, PAGE_TEMPLATES } from "../typed-pages.js";
 
 const MAXIMUM_REPORTED = 200;
 const FIXTURE_ROOT_KEYS = new Set(FIXTURE_ROOT_FIELDS);
@@ -277,7 +278,7 @@ function validateFixtureManifest(manifest) {
       !isPlainObject(entry)
       || !isCanonicalUuid(entry.pageId)
       || !isCanonicalUuid(entry.resourceId)
-      || entry.templateType !== TEMPLATE_TYPE_FREE_FORM
+      || !isAuthorableTemplateType(entry.templateType)
       || entry.workspaceMode !== PAGE_WORKSPACE_MODE_EDITABLE
       || typeof entry.file !== "string"
       || !entry.file.startsWith(`${PAGES_DIRECTORY}/`)
@@ -286,7 +287,7 @@ function validateFixtureManifest(manifest) {
     ) {
       fail(
         "fixture.page_invalid",
-        `${field} must bind one editable free-form source to deterministic page/resource identities and a usable path.`,
+        `${field} must bind one editable page source to deterministic page/resource identities and a usable path.`,
         field,
       );
     }
@@ -499,7 +500,27 @@ export async function validateFixture(invocation = {}) {
         file,
       );
     }
+    // The manifest states which template the page has, and the source must be
+    // one: a recipe document bound as an article would push as the wrong type.
+    if (PAGE_TEMPLATES[documentTemplate(page.document)].wireType !== entry.templateType) {
+      fail(
+        "fixture.page_template_mismatch",
+        `'${file}' is a ${documentTemplate(page.document)} source, but its fixture manifest entry binds `
+          + `${entry.templateType}.`,
+        file,
+      );
+    }
     validatePageImageReferences(page.document, file, imageIds, deliveryOrigins);
+    // Album images and the cover image are bare ids with no delivery URL, so
+    // the walk above cannot see them.
+    const unknownImage = documentImageIds(page.document).find((imageId) => !imageIds.has(imageId));
+    if (unknownImage !== undefined) {
+      fail(
+        "fixture.image_reference_unknown",
+        `Fixture image '${unknownImage}' is not declared in fixture.imageIds.`,
+        file,
+      );
+    }
     validatedPages.push({ file, path: page.pagePath });
     if (pageUsesRootBand(page.document)) rootBandPages.push(file);
   }

package/src/workspace.js

@@ -218,7 +218,14 @@ export async function readObservedPageRecord(workspaceDir, pageId) {
   // A record naming neither version says nothing about what was shown, which is
   // the same position as no record at all.
   if (revision === undefined && remoteHash === undefined) return undefined;
-  return { revision, remoteHash, differences: normalizeObservedDifferences(parsed.differences) };
+  return {
+    revision,
+    remoteHash,
+    // The date the refusal showed, for a typed page. A date edit does not move
+    // the revision, so the record has to name it to say what was seen.
+    displayDate: normalizeBaselineDisplayDate(parsed.displayDate),
+    differences: normalizeObservedDifferences(parsed.differences),
+  };
 }
 
 /**
@@ -317,10 +324,31 @@ export function canonicalDocumentHash(document_) {
   return `sha256:${createHash("sha256").update(canonicalJson(document_, 0), "utf8").digest("hex")}`;
 }
 
+/**
+ * What a push would send for a page, as one hash: the source's bytes plus the
+ * title, path and description that travel with it (for a `.pm.json` source they
+ * come from the manifest, not the file). `pages push` skips a page whose key
+ * equals the one recorded when the workspace last agreed with the site, so an
+ * unedited page is never re-sent (an update would turn an approved page back
+ * into a draft). A Markdown source also folds in the hash of the document it
+ * converts to, because its media references resolve through the media manifest:
+ * re-uploading an image changes what is sent without changing the file.
+ */
+export function pageContentKey(sourceHash, { title, path, description }, documentHash = "") {
+  return workspaceContentHash(
+    Buffer.from(JSON.stringify([sourceHash, title ?? "", path ?? "", description ?? "", documentHash]), "utf8"),
+  );
+}
+
 function normalizeBaselineHash(value) {
   return typeof value === "string" && WORKSPACE_CONTENT_HASH.test(value) ? value : undefined;
 }
 
+// A calendar date or "" (no date). Anything else is a damaged baseline member.
+function normalizeBaselineDisplayDate(value) {
+  return typeof value === "string" && (value === "" || /^\d{4}-\d{2}-\d{2}$/u.test(value)) ? value : undefined;
+}
+
 /**
  * Whether a manifest entry names a file `walkWorkspaceFiles` could have
  * produced: under `pages/`, bounded, and every segment in the workspace
@@ -388,14 +416,20 @@ export function pageSourceRegistry(manifest) {
     const declared = entry.baseline;
     const remoteHash = normalizeBaselineHash(declared?.remoteHash);
     const sourceHash = normalizeBaselineHash(declared?.sourceHash);
+    const contentKey = normalizeBaselineHash(declared?.contentKey);
     const revision = normalizePageBodyRevision(declared?.revision);
-    const baseline = remoteHash === undefined && sourceHash === undefined && revision === undefined
-      ? undefined
-      : {
-        ...(remoteHash === undefined ? {} : { remoteHash }),
-        ...(sourceHash === undefined ? {} : { sourceHash }),
-        ...(revision === undefined ? {} : { revision }),
-      };
+    const displayDate = normalizeBaselineDisplayDate(declared?.displayDate);
+    const baseline =
+      remoteHash === undefined && sourceHash === undefined && revision === undefined && displayDate === undefined
+        && contentKey === undefined
+        ? undefined
+        : {
+          ...(remoteHash === undefined ? {} : { remoteHash }),
+          ...(sourceHash === undefined ? {} : { sourceHash }),
+          ...(contentKey === undefined ? {} : { contentKey }),
+          ...(revision === undefined ? {} : { revision }),
+          ...(displayDate === undefined ? {} : { displayDate }),
+        };
     const record = {
       pageId: entry.pageId,
       file: entry.file,