@taprootio/site-authoring 0.12.5 → 0.12.7

package/src/fixture-contract.js

@@ -33,7 +33,7 @@ export const FIXTURE_REQUIRED_ROOT_FIELDS = Object.freeze([
  * evidence. When appearance/footer are present, validate checks their local
  * image bindings and footer hashes against the fixture settings.
  */
-export const FIXTURE_OPTIONAL_ROOT_FIELDS = Object.freeze(["pulledAt", "deployments", "appearance", "footer"]);
+export const FIXTURE_OPTIONAL_ROOT_FIELDS = Object.freeze(["pulledAt", "deployments", "appearance", "footer", "forms"]);
 
 /** Every root field the manifest may declare. Anything else is refused. */
 export const FIXTURE_ROOT_FIELDS = Object.freeze(

package/src/fixture-init.js

@@ -6,6 +6,8 @@ import { loadSiteConfig } from "./config.js";
 import { isCanonicalUuid, SiteAuthoringError } from "./errors.js";
 import { FIXTURE_CONTRACT_VERSION, FIXTURE_MANIFEST_FILE_NAME } from "./fixture-contract.js";
 import { appearanceManifestEntry, footerManifestEntry } from "./footer-workspace.js";
+import { formFileName } from "./forms-contract.js";
+import { formsManifestEntry, readWorkspaceForms } from "./forms-workspace.js";
 import { SETTINGS_GROUPS, SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES } from "./settings-catalog.js";
 import { validateWorkspacePageSource } from "./verbs/pages-push.js";
 import { validateThemeWorkspace } from "./verbs/theme-push.js";
@@ -194,6 +196,18 @@ export async function initializeFixture(invocation, validate) {
   // A fixture hash is a local placeholder, not authority to mutate the original site.
   const revision = createHash("sha256").update(JSON.stringify(redirects.entries)).digest("hex");
   if (Object.hasOwn(redirects, "revision")) redirects.revision = revision;
+  // Forms are optional in a workspace. The ones the pull manifest recorded are
+  // carried through the same sanitizer as every other document, so a consent
+  // text that links somewhere never leaves a real origin in a shared fixture.
+  const formItems = Object.keys(source.forms?.items ?? {}).sort();
+  const forms = formItems.length === 0 ? [] : await readWorkspaceForms(workspaceDir, formItems);
+  for (const form of forms) add(formFileName(form.key), sanitize(form.document));
+  const formsManifest = forms.length === 0
+    ? undefined
+    : formsManifestEntry(forms.map((form) => [form.key, {
+      id: identity(source.forms.items[form.key].id),
+      version: source.forms.items[form.key].version,
+    }]));
   const footer = footerManifestEntry(appearanceDocuments[SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES].footerSettings);
   const appearance = appearanceManifestEntry(appearanceDocuments);
   for (const id of [...footer.imageIds, ...appearance.imageIds]) imageIds.add(id);
@@ -208,6 +222,7 @@ export async function initializeFixture(invocation, validate) {
     settingsSkipped: [],
     appearance,
     footer,
+    ...(formsManifest === undefined ? {} : { forms: formsManifest }),
     fixture: {
       contractVersion: FIXTURE_CONTRACT_VERSION,
       imageIds: [...imageIds].sort(),

package/src/forms-api.js

@@ -0,0 +1,192 @@
+import { listSitePages, sitePath } from "./api.js";
+import { HTTP_NOT_FOUND } from "./constants.js";
+import { isCanonicalUuid, SiteAuthoringError } from "./errors.js";
+import { FORM_DEFAULT_SINK, FORM_SINKS, isFormKey, normalizePagePath } from "./forms-contract.js";
+import { ApiError } from "./transport.js";
+
+/**
+ * The owner-side forms routes `forms pull` and `forms push` call (TR01061).
+ *
+ * The wire spells a sink and a status as proto enum names; the workspace file
+ * uses the lowercase word. The translation lives here so neither side learns
+ * the other's vocabulary. A form's definition travels as JSON text and comes
+ * back as canonical JSON text; it is parsed on the way in so the verbs handle
+ * one shape.
+ */
+
+const SINK_WIRE = Object.freeze({ none: "SITE_FORM_SINK_NONE", newsletter: "SITE_FORM_SINK_NEWSLETTER" });
+const STATUS_ARCHIVED_WIRE = "SITE_FORM_STATUS_ARCHIVED";
+// The cap is the owner's own forms list, which the site bounds; this is the
+// reply-size bound for the largest form a workspace file may describe.
+const FORMS_RESPONSE_BYTES = 2 * 1024 * 1024;
+
+function contract(message, field) {
+  return new SiteAuthoringError("api.forms_contract", message, { field });
+}
+
+function sinkFromWire(value) {
+  if (value === undefined || value === "" || value === "SITE_FORM_SINK_UNSPECIFIED") return FORM_DEFAULT_SINK;
+  const sink = FORM_SINKS.find((candidate) => SINK_WIRE[candidate] === value);
+  if (sink === undefined) throw contract("Taproot returned an unsupported form sink.", "sink");
+  return sink;
+}
+
+function normalizeForm(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw contract("Taproot returned a form that is not an object.", "form");
+  }
+  if (!isCanonicalUuid(value.id) || !isFormKey(value.key)) {
+    throw contract("Taproot returned a form with no usable id or a key this workspace cannot store.", "form");
+  }
+  return {
+    id: value.id,
+    key: value.key,
+    name: typeof value.name === "string" ? value.name : "",
+    sink: sinkFromWire(value.sink),
+    retentionDays: Number.isSafeInteger(value.retentionDays) ? value.retentionDays : undefined,
+    archived: value.status === STATUS_ARCHIVED_WIRE,
+    currentVersion: Number.isSafeInteger(value.currentVersion) ? value.currentVersion : 0,
+  };
+}
+
+function normalizeVersion(value) {
+  if (value === null || typeof value !== "object" || typeof value.definition !== "string") {
+    throw contract("Taproot returned a form with no current version.", "currentVersion");
+  }
+  let definition;
+  try {
+    definition = JSON.parse(value.definition);
+  } catch {
+    throw contract("Taproot returned a form definition that is not JSON.", "definition");
+  }
+  return {
+    version: Number.isSafeInteger(value.version) ? value.version : 0,
+    definition,
+  };
+}
+
+function normalizeFormResponse(value) {
+  const form = normalizeForm(value?.form);
+  return { form, version: normalizeVersion(value?.currentVersion) };
+}
+
+/**
+ * The site's pages by path and by resource id, for the one place a form file and the
+ * site spell a page differently. `truncated` says the listing hit its bound, so a
+ * path that is not here may still exist and an id that is not here is not proof.
+ * `notTargetIds` holds the pages a form may not send visitors to.
+ */
+export async function getPageIndex(client, siteId, options) {
+  const { pages, truncated } = await listSitePages(client, siteId, options);
+  const idByPath = new Map();
+  const pathById = new Map();
+  const notTargetIds = new Set();
+  for (const page of pages) {
+    if (page.resourceId === "") continue;
+    const path = normalizePagePath(page.path);
+    idByPath.set(path, page.resourceId);
+    pathById.set(page.resourceId, path);
+    if (!isAfterSubmitTarget(page, path)) notTargetIds.add(page.resourceId);
+  }
+  return { idByPath, pathById, notTargetIds, truncated };
+}
+
+// The site's rule for where a form may send visitors: a page an author creates, the home page included.
+// Generated pages, the 404 page, integration-managed pages, legal pages and a profile home are not targets.
+const NOT_TARGET_TEMPLATES = new Set([
+  "TEMPLATE_TYPE_GENERATED",
+  "TEMPLATE_TYPE_INTEGRATION_MANAGED",
+  "TEMPLATE_TYPE_LEGAL",
+  "TEMPLATE_TYPE_PROFILE_HOME",
+]);
+function isAfterSubmitTarget(page, path) {
+  return !page.isGenerated && !NOT_TARGET_TEMPLATES.has(page.templateType) && path.toLowerCase() !== "/404";
+}
+
+/** Every form on the site, archived ones included. */
+export async function listSiteForms(client, siteId) {
+  const response = await client.request(sitePath(siteId, "forms"), { maximumResponseBytes: FORMS_RESPONSE_BYTES });
+  return (Array.isArray(response?.forms) ? response.forms : []).map(normalizeForm);
+}
+
+export async function getSiteForm(client, siteId, formId) {
+  return normalizeFormResponse(
+    await client.request(sitePath(siteId, `forms/${encodeURIComponent(formId)}`), {
+      maximumResponseBytes: FORMS_RESPONSE_BYTES,
+    }),
+  );
+}
+
+/** The form with this key and its current version, or undefined when the site has none. */
+export async function getSiteFormByKey(client, siteId, key) {
+  try {
+    return normalizeFormResponse(
+      await client.request(sitePath(siteId, `form-keys/${encodeURIComponent(key)}`), {
+        maximumResponseBytes: FORMS_RESPONSE_BYTES,
+      }),
+    );
+  } catch (error) {
+    if (error instanceof ApiError && error.httpStatus === HTTP_NOT_FOUND) return undefined;
+    throw error;
+  }
+}
+
+export async function createSiteForm(client, siteId, form) {
+  return normalizeFormResponse(
+    await client.request(sitePath(siteId, "forms"), {
+      method: "POST",
+      body: {
+        key: form.key,
+        name: form.name,
+        sink: SINK_WIRE[form.sink],
+        retentionDays: form.retention_days,
+        definition: JSON.stringify(form.definition),
+      },
+      maximumResponseBytes: FORMS_RESPONSE_BYTES,
+    }),
+  );
+}
+
+/**
+ * `expected` is the settings the caller last read; the site refuses the update
+ * (field ExpectedSettings) when the form no longer holds them, so a change made
+ * by someone else in between is not replaced.
+ */
+export async function updateSiteFormSettings(client, siteId, formId, form, expected) {
+  return normalizeForm(
+    await client.request(sitePath(siteId, `forms/${encodeURIComponent(formId)}/settings`), {
+      method: "PUT",
+      body: {
+        name: form.name,
+        sink: SINK_WIRE[form.sink],
+        retentionDays: form.retention_days,
+        ...(expected === undefined
+          ? {}
+          : {
+            expectedName: expected.name,
+            expectedSink: SINK_WIRE[expected.sink],
+            expectedRetentionDays: expected.retention_days,
+          }),
+      },
+      maximumResponseBytes: FORMS_RESPONSE_BYTES,
+    }),
+  );
+}
+
+/**
+ * Appends a version; the site returns the current one when nothing changed.
+ * `expectedVersion` is the version the caller last read; the site refuses the
+ * save (field ExpectedVersion) when the form has moved past it.
+ */
+export async function saveSiteFormVersion(client, siteId, formId, form, expectedVersion) {
+  return normalizeVersion(
+    await client.request(sitePath(siteId, `forms/${encodeURIComponent(formId)}/versions`), {
+      method: "POST",
+      body: {
+        definition: JSON.stringify(form.definition),
+        ...(expectedVersion === undefined ? {} : { expectedVersion }),
+      },
+      maximumResponseBytes: FORMS_RESPONSE_BYTES,
+    }),
+  );
+}

package/src/forms-contract.js

@@ -0,0 +1,274 @@
+import { SiteAuthoringError } from "./errors.js";
+import { contactFieldId, validateDefinition } from "./field-validation.js";
+
+/**
+ * The workspace contract for a form (TR01061).
+ *
+ * A form is one JSON file, `forms/<key>.json`, holding what an author decides:
+ * its key, name, sink, retention and definition. The definition holds the fields
+ * and the form's own settings (`contact_field`, `submit_label`, `after_submit`),
+ * exactly as the site stores it, so one validator reads one shape. The
+ * definition's own rules belong to `shared/field-validation.ts` and are run
+ * here through the generated copy, so this file never restates them. The one
+ * translation is a page: the site names the page after a response by resource
+ * id, and the file by `page_path`, which `forms push` resolves and `forms pull`
+ * writes back, so an author never handles an id. Everything
+ * the site decides (the version, the form id, who edited it last) stays out of
+ * the file and in the pull manifest, which is what lets `forms pull` and
+ * `forms push` round-trip the file byte for byte.
+ */
+
+export const FORMS_DIRECTORY = "forms";
+export const FORM_FILE_EXTENSION = ".json";
+
+// Mirrors SiteFormContract.IsValidKey on the API: the key is also a file name
+// and an attribute value, so it stays lowercase and URL-safe.
+export const FORM_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+export const FORM_KEY_MAXIMUM_LENGTH = 64;
+export const FORM_SINKS = Object.freeze(["none", "newsletter"]);
+export const FORM_DEFAULT_SINK = "none";
+export const FORM_RETENTION_DAYS = Object.freeze({ minimum: 30, maximum: 730, default: 365 });
+export const FORM_LIMITS = Object.freeze({
+  nameCharacters: 120,
+  // The site refuses a definition larger than this once serialized.
+  definitionBytes: 64 * 1024,
+  fileBytes: 256 * 1024,
+});
+
+const FORM_FILE_KEYS = ["key", "name", "sink", "retention_days", "definition"];
+// The order `forms pull` writes, which `forms push` writes back after a save.
+// Fixed rather than inherited from the response so the same form is always the
+// same bytes.
+const FIELD_KEY_ORDER = ["id", "type", "label", "hint", "required", "min_length", "max_length", "min", "max", "format", "choices"];
+const AFTER_SUBMIT_KEY_ORDER = ["show", "message", "page_path", "page_resource_id"];
+// A nil id stands in for a `page_path` while the shared validator checks everything else about the file.
+const PLACEHOLDER_RESOURCE_ID = "00000000-0000-0000-0000-000000000000";
+const MAXIMUM_REPORTED_ERRORS = 20;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function invalid(file, message, field) {
+  return new SiteAuthoringError("forms.file_invalid", `${file}: ${message}`, { field: `${file}:${field}` });
+}
+
+/**
+ * A site page path as the file writes it: a leading slash, no trailing one, and none of the
+ * characters that would make it a query, a fragment or another origin. `/` is the home page.
+ */
+export function isCanonicalPagePath(path) {
+  return path === "/" || /^\/[^\s\\?#/]+(?:\/[^\s\\?#/]+)*$/u.test(path);
+}
+
+/** The canonical spelling of a path a page summary reports, which may carry or lack slashes at either end. */
+export function normalizePagePath(path) {
+  return `/${path.replace(/^\/+|\/+$/gu, "")}`;
+}
+
+/** The `after_submit` that sends visitors to a page, or undefined for a form that shows its message. */
+export function afterSubmitPage(definition) {
+  const after = definition?.after_submit;
+  return isPlainObject(after) && after.show === "page" ? after : undefined;
+}
+
+/** The workspace path a form key is stored at. */
+export function formFileName(key) {
+  return `${FORMS_DIRECTORY}/${key}${FORM_FILE_EXTENSION}`;
+}
+
+export function isFormKey(value) {
+  return typeof value === "string" && value.length <= FORM_KEY_MAXIMUM_LENGTH && FORM_KEY_PATTERN.test(value);
+}
+
+/** NUL and lone surrogates cannot be stored by the site; it refuses them as invalid_characters. */
+function hasUnstorableCharacters(text) {
+  return /\u0000|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(text);
+}
+
+function anyUnstorableString(value) {
+  if (typeof value === "string") return hasUnstorableCharacters(value);
+  if (Array.isArray(value)) return value.some(anyUnstorableString);
+  if (value !== null && typeof value === "object") {
+    return Object.entries(value).some(([key, child]) => hasUnstorableCharacters(key) || anyUnstorableString(child));
+  }
+  return false;
+}
+
+function describeDefinitionErrors(errors) {
+  const shown = errors.slice(0, MAXIMUM_REPORTED_ERRORS).map((error) => `${error.path || "definition"}: ${error.code}`);
+  const more = errors.length > shown.length ? ` (and ${errors.length - shown.length} more)` : "";
+  return `${shown.join("; ")}${more}`;
+}
+
+/**
+ * Validates one parsed form file and returns it unchanged in meaning.
+ *
+ * `expectedKey` is the key the file's name promises; a mismatch is refused
+ * because a rename on disk would otherwise push a different form than the one
+ * the author thinks they are editing.
+ */
+export function validateFormDocument(document_, expectedKey) {
+  const file = formFileName(expectedKey);
+  if (!isPlainObject(document_)) throw invalid(file, "the file must contain one JSON object.", "$");
+  for (const name of Object.keys(document_)) {
+    if (!FORM_FILE_KEYS.includes(name)) {
+      throw invalid(file, `'${name}' is not a form property. Allowed: ${FORM_FILE_KEYS.join(", ")}.`, name);
+    }
+  }
+  if (document_.key !== expectedKey) {
+    throw invalid(file, `key must be '${expectedKey}', the name of the file.`, "key");
+  }
+  if (!isFormKey(expectedKey)) {
+    throw invalid(file, `the key must be lowercase letters, digits, and single hyphens between them, at most ${FORM_KEY_MAXIMUM_LENGTH} characters.`, "key");
+  }
+  // The site stores the trimmed name, so a padded one could never match the baseline pull records.
+  if (
+    typeof document_.name !== "string"
+    || document_.name.trim() === ""
+    || document_.name !== document_.name.trim()
+    || document_.name.length > FORM_LIMITS.nameCharacters
+  ) {
+    throw invalid(
+      file,
+      `name must be 1 to ${FORM_LIMITS.nameCharacters} characters with no space at either end.`,
+      "name",
+    );
+  }
+  if (document_.sink !== undefined && !FORM_SINKS.includes(document_.sink)) {
+    throw invalid(file, `sink must be one of: ${FORM_SINKS.join(", ")}.`, "sink");
+  }
+  const days = document_.retention_days;
+  if (
+    days !== undefined
+    && (!Number.isInteger(days) || days < FORM_RETENTION_DAYS.minimum || days > FORM_RETENTION_DAYS.maximum)
+  ) {
+    throw invalid(
+      file,
+      `retention_days must be a whole number from ${FORM_RETENTION_DAYS.minimum} to ${FORM_RETENTION_DAYS.maximum}.`,
+      "retention_days",
+    );
+  }
+  if (hasUnstorableCharacters(document_.name)) {
+    throw invalid(file, "name cannot contain NUL or unpaired surrogate characters.", "name");
+  }
+  const errors = validateDefinition(shapeCheckedDefinition(file, document_.definition));
+  if (errors.length > 0) {
+    throw invalid(file, `the definition is invalid: ${describeDefinitionErrors(errors)}`, "definition");
+  }
+  if (anyUnstorableString(document_.definition)) {
+    throw invalid(file, "the definition cannot contain NUL or unpaired surrogate characters.", "definition");
+  }
+  if (Buffer.byteLength(JSON.stringify(document_.definition), "utf8") > FORM_LIMITS.definitionBytes) {
+    throw invalid(file, `the definition is larger than ${FORM_LIMITS.definitionBytes} bytes.`, "definition");
+  }
+  return document_;
+}
+
+/**
+ * The definition the shared validator can read: a `page_path` is checked here and
+ * replaced by a placeholder id, because the validator only knows the stored shape.
+ */
+function shapeCheckedDefinition(file, definition) {
+  const after = afterSubmitPage(definition);
+  if (after === undefined || !("page_path" in after)) return definition;
+  if ("page_resource_id" in after) {
+    throw invalid(file, "after_submit names its page twice: use page_path or page_resource_id, not both.", "definition.after_submit");
+  }
+  if (typeof after.page_path !== "string" || !isCanonicalPagePath(after.page_path)) {
+    throw invalid(
+      file,
+      "after_submit.page_path must be a site path such as '/thanks': a leading slash, no trailing slash, no query or fragment.",
+      "definition.after_submit.page_path",
+    );
+  }
+  const { page_path: _path, ...rest } = after;
+  return { ...definition, after_submit: { ...rest, page_resource_id: PLACEHOLDER_RESOURCE_ID } };
+}
+
+function canonicalAfterSubmit(afterSubmit, pathById) {
+  const path = afterSubmit.show === "page" ? pathById?.get(afterSubmit.page_resource_id) : undefined;
+  const source = path === undefined ? afterSubmit : { ...afterSubmit, page_resource_id: undefined, page_path: path };
+  const ordered = {};
+  for (const name of AFTER_SUBMIT_KEY_ORDER) if (source[name] !== undefined) ordered[name] = source[name];
+  return ordered;
+}
+
+/**
+ * The definition as the site stores it: `page_path` replaced by the page's resource id.
+ * `pages` is the site's page index, which the caller loads when `afterSubmitPage` says it is needed.
+ */
+export function storedDefinition(file, definition, pages) {
+  const after = afterSubmitPage(definition);
+  if (after === undefined) return definition;
+  const { page_path: path, ...rest } = after;
+  if (path !== undefined) {
+    const id = pages?.idByPath.get(path);
+    if (id === undefined) {
+      throw new SiteAuthoringError(
+        "forms.page_not_found",
+        pages?.truncated
+          ? `${file}: the site has more pages than this CLI lists, so '${path}' could not be looked up. `
+            + "Name the page by page_resource_id instead."
+          : `${file}: no page on the site has the path '${path}'. Push the page first, or name a page that exists.`,
+        { field: `${file}:definition.after_submit.page_path` },
+      );
+    }
+    rejectNonTarget(file, pages, id, "page_path", path);
+    return { ...definition, after_submit: { ...rest, page_resource_id: id } };
+  }
+  if (pages !== undefined && !pages.truncated && !pages.pathById.has(after.page_resource_id)) {
+    throw new SiteAuthoringError(
+      "forms.page_not_found",
+      `${file}: no page on the site has the resource id '${after.page_resource_id}'. Name the page by its path instead.`,
+      { field: `${file}:definition.after_submit.page_resource_id` },
+    );
+  }
+  if (pages !== undefined) rejectNonTarget(file, pages, after.page_resource_id, "page_resource_id", pages.pathById.get(after.page_resource_id));
+  return definition;
+}
+
+// A form may send visitors only to a page an author created, so this refuses before any write.
+function rejectNonTarget(file, pages, id, field, name) {
+  if (!pages.notTargetIds?.has(id)) return;
+  throw new SiteAuthoringError(
+    "forms.page_not_allowed",
+    `${file}: '${name ?? id}' is a generated, system, legal, profile or integration page. A form can send visitors only to a page you created. Name another page.`,
+    { field: `${file}:definition.after_submit.${field}` },
+  );
+}
+
+function canonicalField(field) {
+  const ordered = {};
+  for (const name of FIELD_KEY_ORDER) if (field[name] !== undefined) ordered[name] = field[name];
+  // Anything the site returns that this release does not know is kept after
+  // the known names rather than dropped, so an older CLI cannot erase a
+  // constraint a newer site added.
+  for (const name of Object.keys(field).sort()) if (ordered[name] === undefined) ordered[name] = field[name];
+  return ordered;
+}
+
+/**
+ * The form file for a form as the site holds it. Defaults are written out so a
+ * pulled file states the retention and sink it is actually running with. `pathById`
+ * maps page resource ids to their paths; a page it knows is written as `page_path`,
+ * so the same page is always the same bytes whichever spelling the file used.
+ */
+export function projectFormForWorkspace(form, pathById) {
+  const definition = { fields: form.definition.fields.map(canonicalField) };
+  // The named field stays only when the form's own fields would not pick it, so a form with one email field
+  // is written without it and an explicit file still round-trips as unchanged.
+  const { contact_field: named } = form.definition;
+  if (named !== undefined && contactFieldId({ fields: definition.fields }) !== named) definition.contact_field = named;
+  if (form.definition.submit_label !== undefined) definition.submit_label = form.definition.submit_label;
+  if (form.definition.after_submit !== undefined) {
+    definition.after_submit = canonicalAfterSubmit(form.definition.after_submit, pathById);
+  }
+  return {
+    key: form.key,
+    name: form.name,
+    sink: form.sink ?? FORM_DEFAULT_SINK,
+    retention_days: form.retention_days ?? FORM_RETENTION_DAYS.default,
+    definition,
+  };
+}

package/src/forms-workspace.js

@@ -0,0 +1,100 @@
+import { SiteAuthoringError } from "./errors.js";
+import {
+  FORM_DEFAULT_SINK,
+  FORM_FILE_EXTENSION,
+  FORM_RETENTION_DAYS,
+  FORM_LIMITS,
+  FORMS_DIRECTORY,
+  formFileName,
+  isFormKey,
+  validateFormDocument,
+} from "./forms-contract.js";
+import { readWorkspaceJson, walkWorkspaceFiles } from "./workspace.js";
+
+/**
+ * Reads and validates the workspace's form files (TR01061).
+ *
+ * `keys` narrows the read to named forms and refuses a name with no file, so a
+ * typo never reads as a successful empty push. With none, every file under
+ * `forms/` is read. A file whose name is not a form key is refused rather than
+ * skipped: skipping it would report success with one form left behind.
+ */
+export async function readWorkspaceForms(workspaceDir, keys) {
+  const files = await walkWorkspaceFiles(workspaceDir, FORMS_DIRECTORY, [FORM_FILE_EXTENSION]);
+  const known = new Map();
+  for (const file of files) {
+    const key = file.slice(FORMS_DIRECTORY.length + 1, -FORM_FILE_EXTENSION.length);
+    if (key.includes("/") || !isFormKey(key)) {
+      throw new SiteAuthoringError(
+        "forms.file_invalid",
+        `${file}: a form file is forms/<key>.json directly under forms/, with a key of lowercase letters, `
+          + "digits, and single hyphens between them.",
+        { field: file },
+      );
+    }
+    known.set(key, file);
+  }
+  const selected = keys === undefined ? [...known.keys()].sort() : [...new Set(keys)].sort();
+  const forms = [];
+  for (const key of selected) {
+    const file = known.get(key);
+    if (file === undefined) {
+      throw new SiteAuthoringError(
+        "forms.file_missing",
+        `There is no ${formFileName(key)} in the workspace.`,
+        { field: formFileName(key) },
+      );
+    }
+    const document_ = await readWorkspaceJson(workspaceDir, file, FORM_LIMITS.fileBytes);
+    forms.push({ key, file, document: validateFormDocument(document_, key) });
+  }
+  return forms;
+}
+
+/**
+ * The forms baseline in the pull manifest (TR01061).
+ *
+ * The site has no compare-and-set for a form, so `forms push` fences itself:
+ * it writes a form only when the site's current version is the one the last
+ * pull or push recorded here. A form edited in the browser since then makes
+ * the push refuse toward pull instead of overwriting it.
+ */
+export const FORMS_MANIFEST_KEY = "forms";
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * The settings half of a baseline, from the form exactly as the site returned
+ * it. Name, sink and retention change without appending a version, so the
+ * version alone cannot say they moved.
+ */
+export function siteSettingsBaseline(siteForm) {
+  return {
+    name: siteForm.name,
+    sink: siteForm.sink ?? FORM_DEFAULT_SINK,
+    retention_days: siteForm.retentionDays ?? FORM_RETENTION_DAYS.default,
+  };
+}
+
+/** The recorded baseline for one key, or undefined when this workspace never saw that form. */
+export function recordedForm(manifest, key) {
+  const items = manifest[FORMS_MANIFEST_KEY]?.items;
+  if (!isObject(items) || !Object.hasOwn(items, key)) return undefined;
+  const entry = items[key];
+  return isObject(entry) && typeof entry.id === "string" && Number.isSafeInteger(entry.version)
+      && isObject(entry.settings)
+    ? { id: entry.id, version: entry.version, settings: entry.settings }
+    : undefined;
+}
+
+export function formsManifestEntry(items) {
+  return { items: Object.fromEntries([...items].sort(([left], [right]) => (left < right ? -1 : 1))) };
+}
+
+/** Sets one form's baseline and keeps every other entry, in key order. */
+export function withRecordedForm(manifest, key, entry) {
+  const current = isObject(manifest[FORMS_MANIFEST_KEY]?.items) ? manifest[FORMS_MANIFEST_KEY].items : {};
+  return { ...manifest, [FORMS_MANIFEST_KEY]: formsManifestEntry(Object.entries({ ...current, [key]: entry })) };
+}