@taprootio/site-authoring 0.12.5 → 0.12.7

package/src/reference-help.js

@@ -20,6 +20,27 @@ import {
   SHIPPED_FIXTURE_NAME,
   shippedFixtureDirectory,
 } from "./fixture-contract.js";
+import {
+  DATE_ANCHORS,
+  FIELD_TYPES,
+  MAX_AFTER_SUBMIT_MESSAGE_LENGTH,
+  MAX_CONSENT_LABEL_LENGTH,
+  MAX_DATE_OFFSET_DAYS,
+  MAX_FIELDS,
+  MAX_HINT_LENGTH,
+  MAX_SUBMIT_LABEL_LENGTH,
+  MAX_LABEL_LENGTH,
+  MAX_SUBMISSION_BYTES,
+  RELATIVE_BOUND_GRACE_DAYS,
+} from "./field-validation.js";
+import {
+  FORM_FILE_EXTENSION,
+  FORM_KEY_MAXIMUM_LENGTH,
+  FORM_LIMITS,
+  FORM_RETENTION_DAYS,
+  FORM_SINKS,
+  FORMS_DIRECTORY,
+} from "./forms-contract.js";
 import {
   formatPresentationReference,
   getAppearanceReference,
@@ -50,7 +71,23 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 28;
+export const REFERENCE_VERSION = 31;
+
+// The date-limit examples `help forms` prints; tests run them through the form validator.
+export const FORM_DATE_WINDOW_FIELD = Object.freeze({
+  id: "visit_day",
+  type: "date",
+  label: "Day of your visit",
+  min: Object.freeze({ from: "today" }),
+  max: Object.freeze({ from: "today", offset_days: 30 }),
+});
+export const FORM_NEXT_MONTH_FIELD = Object.freeze({
+  id: "start_day",
+  type: "date",
+  label: "A day next month",
+  min: Object.freeze({ from: "start_of_next_month" }),
+  max: Object.freeze({ from: "end_of_next_month" }),
+});
 export const PAGE_TYPES = Object.freeze(["free-form", ...TYPED_PAGE_TYPES]);
 
 function deepFreeze(value) {
@@ -363,6 +400,11 @@ export const REFERENCE_TOPICS = Object.freeze([
     usage: `${CLI_BINARY_NAME} help redirects`,
     summary: "Author redirects.json: entry shape, normalization, and the refusals.",
   }),
+  Object.freeze({
+    name: "forms",
+    usage: `${CLI_BINARY_NAME} help forms`,
+    summary: "Author a form as forms/<key>.json: file shape, field types, validate, pull, push, and placing it on a page.",
+  }),
   Object.freeze({
     name: "media",
     usage: `${CLI_BINARY_NAME} help media`,
@@ -480,8 +522,7 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "image fails.",
       "Runtime: the page's bootstrap pins one runtime version, its entry module and the module each declared "
       + "capability resolves to. The entry must load as JavaScript and every declared capability must resolve and "
-      + "load. A page that still names the pre-pinning runtime pointer is reported as unverified, so the verdict is "
-      + "degraded, until the site is republished.",
+      + "load. A page whose bootstrap does not pin a runtime version and entry fails the runtime check.",
       "Browser: a fresh and a returning (same-context, cached) load are compared against the page's pinned entry when "
       + "Playwright resolves from the CLI's own install: npm install --global @taprootio/site-authoring@latest "
       + "playwright && npx playwright install chromium, then rerun through the installed taproot-site command (a "
@@ -505,8 +546,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "not delivery), local-only references (localhost, *.test, *.local) are reported rather than fetched, a "
       + "redirect Location that could reflect a credential is withheld, bodies are read up to a fixed bound, "
       + "member-only content is not exercised, and nothing is purged, republished or rolled back.",
-      "Verdicts: delivered (no findings), degraded (every route served and the runtime is compatible or a pre-pinning "
-      + "reference, but an asset, link or browser load did not match or the runtime could not be verified), failed (a route or the runtime did not deliver).",
+      "Verdicts: delivered (no findings), degraded (every route served and the runtime is compatible, "
+      + "but an asset, link or browser load did not match), failed (a route or the runtime did not deliver).",
     ]),
     example: Object.freeze({
       command: `${CLI_BINARY_NAME} delivery check --production --url https://www.example.com/ --wait 30`,
@@ -527,7 +568,10 @@ const WORKFLOW_REFERENCES = Object.freeze({
       `Pull the baseline: ${CLI_BINARY_NAME} pull writes settings/taproot-styles.json with both schemes' complete effective `
       + "themes (the stored theme resolved over the same defaults every consumer renders) beside brand.json, "
       + "site-header.json and site-publishing-preferences.json. Keep that pull as the baseline you edit; never build "
-      + "a theme from memory or from an example. semanticMappings holds only authored pins, listed in explicitMappingTokens.",
+      + "a theme from memory or from an example. semanticMappings holds only authored pins, listed in explicitMappingTokens. "
+      + "site-publishing-preferences.json also carries timeZone, the site's IANA zone (UTC until the owner sets it), "
+      + "which decides what \"today\" means for relative form date bounds; it is read-only here, so ask the owner to set "
+      + "it in the editor under Site settings.",
       "Edit both schemes: settings.lightTheme and settings.darkTheme are separate documents. Declare anchors, then roles "
       + "(help theme lists the role slots and how anchor references resolve), tune typography per scheme, and keep "
       + "contexts and intents paired across schemes. Set appearance scalars (default scheme, header, logos, favicon) "
@@ -682,6 +726,107 @@ const WORKFLOW_REFERENCES = Object.freeze({
       ]),
     }),
   }),
+  forms: Object.freeze({
+    title: "Form workspace contract",
+    summary: `A form is one JSON file, ${FORMS_DIRECTORY}/<key>${FORM_FILE_EXTENSION}. 'forms validate' proves it offline, `
+      + "'forms push' creates or updates it on the site, and 'forms pull' reads the site's copy back.",
+    usage: `${CLI_BINARY_NAME} forms validate [key...] | ${CLI_BINARY_NAME} forms pull | ${CLI_BINARY_NAME} forms push [key...]`,
+    details: Object.freeze([
+      `Run 'pull' once first: 'forms pull' and 'forms push' need the pulled workspace's manifest, which records the `
+      + "version of each form this workspace last saw. 'forms validate' needs only taproot-site.json.",
+      `The file is { key, name, sink, retention_days, definition }. key must equal the file's name `
+      + `and is lowercase letters, digits, and single hyphens, at most ${FORM_KEY_MAXIMUM_LENGTH} characters. name is `
+      + `1 to ${FORM_LIMITS.nameCharacters} characters. sink is one of ${FORM_SINKS.join(", ")} and defaults to `
+      + "'none' (store submissions only); 'newsletter' also subscribes the contact address to the site's newsletter. "
+      + `retention_days is ${FORM_RETENTION_DAYS.minimum} to ${FORM_RETENTION_DAYS.maximum} (a site's plan may cap it lower): `
+      + "submissions are deleted that many days after they arrive. Leave it out and the site chooses on creation (its "
+      + "plan's default, usually 365) and keeps the current value on an update. Shortening it deletes the submissions that fall outside it, "
+      + "so a key cannot do it; the site refuses it, and an owner or admin must make that change.",
+      `definition is { fields, contact_field?, submit_label?, after_submit? } (contact_field only with several email fields). Each field is { id, type, label, hint?, ...constraints }; the closed `
+      + `field types are ${FIELD_TYPES.join(", ")}. hint is optional helper text of up to ${MAX_HINT_LENGTH} `
+      + "characters, drawn under the field on the published form; it is the only author-defined text printed there, so a required "
+      + "field is not marked 'Required' and a visitor learns it from the error on submit. "
+      + `At most ${MAX_FIELDS} fields and ${MAX_SUBMISSION_BYTES} bytes `
+      + "per submission. There are no author-supplied regular expressions: use 'format' from its closed list. "
+      + "The exact constraints per type are in shared/field-schema.json, which 'forms validate' enforces by "
+      + "running the same validator the published form and the site use. Each refusal names the field path and a "
+      + "stable code such as duplicate_id or unknown_constraint.",
+      "A date field's min and max are each a fixed 'YYYY-MM-DD' date or a relative limit, { from, offset_days? }. "
+      + `from is one of ${DATE_ANCHORS.join(", ")}, the site's calendar date today or that day of this or next month; `
+      + `offset_days is a whole number of days from -${MAX_DATE_OFFSET_DAYS} to ${MAX_DATE_OFFSET_DAYS} (default 0; a `
+      + "year either way covers a leap year, and further out is a fixed date). There is no expression language. "
+      + "'Today' is the site's date in the site's time zone, which is UTC until the owner sets one in the editor's "
+      + "Site settings; 'pull' shows it as timeZone in settings/site-publishing-preferences.json, read-only here. "
+      + "The published form sets the date picker's limits when the page loads and checks them again when the visitor "
+      + `submits; the site lets a relative minimum reach back ${RELATIVE_BOUND_GRACE_DAYS} day so a visitor who loaded `
+      + "the page before midnight and submits after it is not refused for a date the page offered (a relative maximum "
+      + `and a fixed date are never loosened). Within the next 30 days: ${JSON.stringify(FORM_DATE_WINDOW_FIELD)}. `
+      + `A day next month: ${JSON.stringify(FORM_NEXT_MONTH_FIELD)}. A fixed and a relative limit may be mixed. 'forms `
+      + "validate' refuses an unknown anchor or an offset out of range as invalid_constraint, and a minimum after the "
+      + "maximum as min_exceeds_max only when both are fixed dates or both start from the same anchor; other pairs "
+      + "depend on the day and are not compared.",
+      `submit_label is the text on the submit button, up to ${MAX_SUBMIT_LABEL_LENGTH} characters; leave it out for "Send". `
+      + "after_submit says what the visitor sees once a response is sent. Leave it out, or write "
+      + `{ "show": "message" }, for Taproot's own confirmation; { "show": "message", "message": "..." } replaces `
+      + `its words (up to ${MAX_AFTER_SUBMIT_MESSAGE_LENGTH} characters, line breaks kept). { "show": "page", `
+      + `"page_path": "/thanks" } sends the visitor to that page on this site instead. The page is written as `
+      + "its path: a leading slash, no trailing slash, '/' for the home page. 'forms push' looks the page up "
+      + "and stores it by its resource id, so the form keeps pointing at the page if it is renamed, and 'forms "
+      + "pull' writes the page's current path back. A page_resource_id is accepted in place of page_path, and a "
+      + "pull keeps it only for a page that no longer exists. A file whose page_path names no page on the site is "
+      + "refused as forms.page_not_found, so push the page first. It need not be published to save the form, but "
+      + "a deploy whose release does not publish that page is refused, naming the form and the page. The path in "
+      + "each release is the one the page has in that release, so the published form never asks the site where "
+      + "to go. The page must be one you created, the home page included: a generated page (folder, tag or "
+      + "archive index), the 404 page, a legal page, a profile home and an integration-managed page are refused as forms.page_not_allowed. The button text and the confirmation belong to the form, not to the page that places it: "
+      + "the 'form' component takes only formKey.",
+      "A form's contact address is the value of one email field, stored with each submission. That is what lets the "
+      + "owner find and delete every row for a visitor who asks. With exactly one email field, that field is the "
+      + "contact address and the file leaves contact_field out (a file that names it anyway is accepted, and a pull "
+      + "writes it without). With two or more email fields, contact_field must name one of them; leaving it out is "
+      + "refused as contact_field_required. A form with no email field has no contact address, and contact_field "
+      + "there is refused as invalid_contact_field.",
+      `A consent field's label is the exact words the visitor agrees to, up to ${MAX_CONSENT_LABEL_LENGTH} characters `
+      + `(every other field's label is at most ${MAX_LABEL_LENGTH}); a form has no separate consent text. `
+      + "Each version freezes the labels, and every submission records the hash of each consent field's label as "
+      + "the visitor saw it, so a response shows what each box agreed to.",
+      "Editing a definition appends a version on the site; versions are never changed. A page keeps the form "
+      + "version it was published with until the next deploy, and a rollback restores the form it shipped with.",
+      "Both verbs write the file in one canonical key order, so a pulled file pushed back unchanged reports "
+      + "'unchanged' and leaves the bytes as they were. Write your own files in that order and a push rewrites "
+      + "nothing you did not change.",
+      "'forms push' validates every file and compares every form with the site before the first write. It refuses "
+      + "forms.concurrent_modification when the site's version moved since this workspace last read it, "
+      + "forms.pull_required when the site has a form with that key this workspace never pulled, and forms.archived "
+      + "when the form is archived on the site. Reconcile with 'forms pull' and retry; nothing was written.",
+      "Submissions are never pulled or pushed. They are visitors' personal data: read, mark, export and delete "
+      + "them on the site's Forms page.",
+      "To show a form, place the free-form component 'form' on a page (a component:form block) with formKey set "
+      + "to the form's key ('help component form' lists its properties). Push the form first and deploy: the release "
+      + "freezes the form it was built with.",
+      "The delegation.content capability carries site.forms.manage, which every forms verb needs: it covers "
+      + "definitions, settings and status. Visitors' submissions are in no capability: reading them "
+      + "(site.forms.submissions.read) and finding, marking or deleting them (site.forms.submissions.manage) belong "
+      + "to the site's owners and admins on the site's Forms page, never to a key. A refusal names the missing "
+      + "permission.",
+    ]),
+    example: Object.freeze({
+      key: "contact",
+      name: "Contact",
+      sink: "none",
+      retention_days: 365,
+      definition: Object.freeze({
+        fields: Object.freeze([
+          Object.freeze({ id: "name", type: "text", label: "Your name", required: true, max_length: 120 }),
+          Object.freeze({ id: "email", type: "email", label: "Email", required: true }),
+          Object.freeze({ id: "message", type: "long_text", label: "Message", required: true, max_length: 2000 }),
+          Object.freeze({ id: "agree", type: "consent", label: "I agree that you may store this message and reply to me." }),
+        ]),
+        submit_label: "Send message",
+        after_submit: Object.freeze({ show: "page", page_path: "/thanks" }),
+      }),
+    }),
+  }),
   media: Object.freeze({
     title: "Media upload contract",
     summary: "Upload workspace-root-relative raster files and receive component-ready media objects.",
@@ -747,6 +892,9 @@ const WORKFLOW_REFERENCES = Object.freeze({
       `Required root fields: ${FIXTURE_REQUIRED_ROOT_FIELDS.join(", ")}.`,
       `Optional root fields: ${FIXTURE_OPTIONAL_ROOT_FIELDS.join(", ")}. Appearance and footer metadata, when present, `
       + "must match the local settings. Snapshot times and deployments are not live evidence. Other root fields are refused.",
+      `The optional forms root field is { items: { <key>: { id, version } } }: 'forms pull' also records a settings baseline, which a fixture does not carry. Each key `
+      + `names a ${FORMS_DIRECTORY}/<key>${FORM_FILE_EXTENSION} that must validate as in 'help forms', and no form file `
+      + "may sit beside them unbound.",
       `manifestVersion must be ${MANIFEST_VERSION}; fixture.contractVersion must be ${FIXTURE_CONTRACT_VERSION}.`,
       "siteId, every pageId and resourceId, every settings entityId, and every fixture.imageIds entry is a canonical "
       + "lowercase UUID. They are deterministic fixture identities, not identities from a live site.",

package/src/settings-catalog.js

@@ -116,6 +116,9 @@ export const SETTINGS_GROUPS = Object.freeze([
       // exist is worse than one that omits the field.
       { name: "commentsMode", wireType: "enum", zero: "SITE_COMMENTS_MODE_UNSPECIFIED" },
       ...stringFields("tiptapImagePlacement"),
+      // One IANA zone id (TR01091). The server answers UTC for a site that
+      // never set one, so a pulled snapshot is never empty.
+      ...stringFields("timeZone"),
       { name: "allowSearch", wireType: "boolean" },
       { name: "showFollowButton", wireType: "boolean" },
       { name: "albumSeamless", wireType: "boolean" },

package/src/verbs/delivery-check.js

@@ -156,13 +156,6 @@ export async function deliveryCheck(invocation) {
     let browser;
     if (invocation.browser === false) {
       browser = { status: "unchecked", reason: "disabled", note: "Browser verification was not requested." };
-    } else if (report.runtime.legacy) {
-      // There is no pinned entry to compare a browser load against.
-      browser = {
-        status: "unchecked",
-        reason: "legacy_runtime_reference",
-        note: "The page names a pre-pinning runtime pointer, so no entry is pinned to compare a browser load against; republish the site and rerun.",
-      };
     } else {
       onProgress("Browser dimension: probing with Playwright when it is installed.");
       browser = await probeDeliveryWithBrowser({

package/src/verbs/forms-pull.js

@@ -0,0 +1,67 @@
+import { withRefusalGuidance } from "../api.js";
+import { VERB_FORMS_PULL } from "../constants.js";
+import { getPageIndex, getSiteForm, listSiteForms } from "../forms-api.js";
+import { afterSubmitPage, formFileName, projectFormForWorkspace } from "../forms-contract.js";
+import { formsManifestEntry, siteSettingsBaseline } from "../forms-workspace.js";
+import { boundedList, openSession, successResult } from "../session.js";
+import { readManifest, writeManifest, writeWorkspaceJson } from "../workspace.js";
+
+const MAXIMUM_REPORTED = 200;
+
+/**
+ * `forms pull` — write one file per live form and record the versions read.
+ *
+ * It overwrites a form's file with the site's state, so a local edit that was
+ * never pushed is replaced; that is what pull means everywhere else in this
+ * CLI. An archived form is reported and not written, because `forms push`
+ * refuses an archived form and a file that can never be pushed is noise.
+ */
+export async function formsPull(invocation) {
+  const { client, config, siteId, onProgress } = await openSession(invocation);
+  // The manifest is the pulled workspace this baseline belongs to, the same
+  // precondition every push has.
+  const manifest = await readManifest(config.workspaceDir, siteId);
+
+  const listed = await withRefusalGuidance(onProgress, "forms pull", async () => await listSiteForms(client, siteId));
+  const live = listed.filter((form) => !form.archived);
+  const archived = listed.filter((form) => form.archived).map((form) => form.key).sort();
+
+  const baselines = [];
+  const written = [];
+  // A form that sends visitors to a page is written with the page's path, which needs the page list once.
+  let pages;
+  for (const summary of live) {
+    const { form, version } = await withRefusalGuidance(
+      onProgress,
+      "forms pull",
+      async () => await getSiteForm(client, siteId, summary.id),
+    );
+    if (pages === undefined && afterSubmitPage(version.definition)) {
+      pages = await withRefusalGuidance(onProgress, "forms pull", async () => await getPageIndex(client, siteId, { onProgress }));
+    }
+    const document_ = projectFormForWorkspace({
+      key: form.key,
+      name: form.name,
+      sink: form.sink,
+      retention_days: form.retentionDays,
+      definition: version.definition,
+    }, pages?.pathById);
+    await writeWorkspaceJson(config.workspaceDir, formFileName(form.key), document_);
+    baselines.push([form.key, { id: form.id, version: version.version, settings: siteSettingsBaseline(form) }]);
+    written.push(form.key);
+  }
+
+  manifest.forms = formsManifestEntry(baselines);
+  await writeManifest(config.workspaceDir, manifest);
+  onProgress(`Wrote ${written.length} form file${written.length === 1 ? "" : "s"} and recorded their versions.`);
+
+  const reported = boundedList(written.sort(), MAXIMUM_REPORTED);
+  return successResult(VERB_FORMS_PULL, siteId, {
+    forms: {
+      total: written.length,
+      items: reported.items.map((key) => ({ key, file: formFileName(key) })),
+      ...(reported.truncated ? { itemsTruncated: true } : {}),
+      ...(archived.length > 0 ? { archived } : {}),
+    },
+  });
+}

package/src/verbs/forms-push.js

@@ -0,0 +1,227 @@
+import { withRefusalGuidance } from "../api.js";
+import { VERB_FORMS_PULL, VERB_FORMS_PUSH } from "../constants.js";
+import { SiteAuthoringError } from "../errors.js";
+import {
+  createSiteForm,
+  getPageIndex,
+  getSiteFormByKey,
+  saveSiteFormVersion,
+  updateSiteFormSettings,
+} from "../forms-api.js";
+import { afterSubmitPage, formFileName, projectFormForWorkspace, storedDefinition } from "../forms-contract.js";
+import { readWorkspaceForms, recordedForm, siteSettingsBaseline, withRecordedForm } from "../forms-workspace.js";
+import { openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
+import { ApiError } from "../transport.js";
+import { readManifest, writeManifest, writeWorkspaceJson } from "../workspace.js";
+
+function changedOnTheSite(key, cause, settingsApplied) {
+  return new SiteAuthoringError(
+    "forms.concurrent_modification",
+    `${formFileName(key)}: the form changed on the site while it was being pushed. Run '${VERB_FORMS_PULL}', `
+      + `reconcile the file, and retry. ${
+        settingsApplied ? "Its settings were applied; its definition was not." : "This form was not changed."
+      }`,
+    { field: formFileName(key), status: cause.status },
+  );
+}
+
+function pullRequired(key, reason) {
+  return new SiteAuthoringError(
+    "forms.pull_required",
+    `${reason} Run '${VERB_FORMS_PULL}', reconcile ${formFileName(key)}, and retry. Nothing was written.`,
+    { field: formFileName(key) },
+  );
+}
+
+/**
+ * Decides what one form needs, from the file, the site's copy and the
+ * baseline the last pull recorded. Throws before anything is written.
+ */
+function planForm(form, remote, baseline, pages) {
+  // An omitted retention means "the site's choice": the plan-aware default on
+  // creation, and the form's current value on an update.
+  const requestedRetention = form.document.retention_days;
+  const desired = projectFormForWorkspace({
+    ...form.document,
+    retention_days: requestedRetention ?? remote?.form.retentionDays,
+  }, pages?.pathById);
+  if (remote === undefined) {
+    if (baseline !== undefined) {
+      throw pullRequired(form.key, "This workspace recorded the form, but the site no longer has it.");
+    }
+    return { form, desired, request: { ...desired, retention_days: requestedRetention }, action: "create" };
+  }
+  if (remote.form.archived) {
+    throw new SiteAuthoringError(
+      "forms.archived",
+      `${formFileName(form.key)}: the site's form '${form.key}' is archived. Restore it on the site's Forms page, `
+        + "delete the file, or name the other keys to push. Nothing was written.",
+      { field: formFileName(form.key) },
+    );
+  }
+  if (baseline === undefined) {
+    throw pullRequired(form.key, "The site already has a form with this key that this workspace never pulled.");
+  }
+  const siteSettings = siteSettingsBaseline(remote.form);
+  if (
+    baseline.id !== remote.form.id
+    || baseline.version !== remote.version.version
+    // Name, sink and retention change without a new version, so they are
+    // fenced separately; a stale file would otherwise revert them.
+    || JSON.stringify(baseline.settings) !== JSON.stringify(siteSettings)
+  ) {
+    throw new SiteAuthoringError(
+      "forms.concurrent_modification",
+      `${formFileName(form.key)}: the form changed on the site after this workspace read it (recorded version `
+        + `${baseline.version}, site has ${remote.version.version}; its name, sink or retention may also have changed). Run '${VERB_FORMS_PULL}', reconcile the file, `
+        + "and retry. Nothing was written.",
+      { field: formFileName(form.key) },
+    );
+  }
+  const current = projectFormForWorkspace({
+    key: remote.form.key,
+    name: remote.form.name,
+    sink: remote.form.sink,
+    retention_days: remote.form.retentionDays,
+    definition: remote.version.definition,
+  }, pages?.pathById);
+  const settingsChanged = current.name !== desired.name
+    || current.sink !== desired.sink
+    || current.retention_days !== desired.retention_days;
+  const versionChanged = JSON.stringify(current.definition) !== JSON.stringify(desired.definition);
+  return {
+    form,
+    desired,
+    remote,
+    baseline,
+    action: settingsChanged || versionChanged ? "update" : "unchanged",
+    settingsChanged,
+    versionChanged,
+  };
+}
+
+/**
+ * `forms push` — create or update each form file in the workspace.
+ *
+ * Every file is validated and every form is compared with the site before the
+ * first write, so a conflict on the third form refuses the whole push rather
+ * than landing two. After that each form is written and its baseline advanced
+ * immediately, so a failure partway leaves a workspace that the next push can
+ * resume from. Editing a definition appends a version on the site; the
+ * published pages keep the version they were built with until the next deploy.
+ */
+export async function formsPush(invocation) {
+  const session = await openSession(invocation);
+  const { client, config, siteId, onProgress } = session;
+  warnIfExternalWritesPaused(session, VERB_FORMS_PUSH);
+  const forms = await readWorkspaceForms(config.workspaceDir, invocation.formKeys);
+  onProgress(`Validated ${forms.length} form file${forms.length === 1 ? "" : "s"}.`);
+  let manifest = await readManifest(config.workspaceDir, siteId);
+
+  // The site names the page after a response by resource id and the file by path, so the
+  // page list is read once, and only when a form on either side points at a page.
+  let pages;
+  const plans = [];
+  for (const form of forms) {
+    const remote = await withRefusalGuidance(
+      onProgress,
+      "forms push",
+      async () => await getSiteFormByKey(client, siteId, form.key),
+    );
+    if (pages === undefined && (afterSubmitPage(form.document.definition) || afterSubmitPage(remote?.version.definition))) {
+      pages = await withRefusalGuidance(onProgress, "forms push", async () => await getPageIndex(client, siteId, { onProgress }));
+    }
+    const plan = planForm(form, remote, recordedForm(manifest, form.key), pages);
+    // A page_path the site does not have is refused here, with the rest of the checks, not partway
+    // through the writes. Only a definition that is going to be sent is resolved: a settings-only
+    // update of a form whose page was deleted never sends it.
+    plans.push(
+      plan.action === "create" || plan.versionChanged
+        ? { ...plan, wireDefinition: storedDefinition(form.file, (plan.request ?? plan.desired).definition, pages) }
+        : plan,
+    );
+  }
+
+  const results = [];
+  for (const plan of plans) {
+    let { desired } = plan;
+    const { form } = plan;
+    let formId = plan.remote?.form.id;
+    let version = plan.remote?.version.version;
+    // The baseline is what the site stored, not what the file said: the site
+    // normalizes some values, and the next push is fenced against its copy.
+    let settings = plan.remote === undefined ? undefined : siteSettingsBaseline(plan.remote.form);
+    let settingsApplied = false;
+    try {
+      if (plan.action === "create") {
+        const created = await withRefusalGuidance(
+          onProgress,
+          "forms push",
+          async () => await createSiteForm(client, siteId, { ...plan.request, definition: plan.wireDefinition }),
+        );
+        formId = created.form.id;
+        version = created.version.version;
+        settings = siteSettingsBaseline(created.form);
+        // The file is written from what the site stored: it chose the retention
+        // and normalized the name.
+        desired = projectFormForWorkspace({
+          ...desired,
+          name: created.form.name,
+          sink: created.form.sink,
+          retention_days: created.form.retentionDays,
+        }, pages?.pathById);
+      } else if (plan.action === "update") {
+        if (plan.settingsChanged) {
+          settings = siteSettingsBaseline(
+            await withRefusalGuidance(
+              onProgress,
+              "forms push",
+              async () => await updateSiteFormSettings(client, siteId, formId, desired, plan.baseline.settings),
+            ),
+          );
+          settingsApplied = true;
+          // Recorded at once: if the version save below fails, the next push
+          // must not read the settings it just applied as someone else's edit.
+          manifest = withRecordedForm(manifest, form.key, { id: formId, version, settings });
+          await writeManifest(config.workspaceDir, manifest);
+        }
+        if (plan.versionChanged) {
+          version = (await withRefusalGuidance(
+            onProgress,
+            "forms push",
+            async () => await saveSiteFormVersion(client, siteId, formId, { ...desired, definition: plan.wireDefinition }, plan.baseline.version),
+          )).version;
+        }
+      }
+    } catch (caught) {
+      // The site checks the recorded version and settings under its own lock,
+      // which is what closes the gap between the comparison above and the write.
+      const error = caught instanceof ApiError && (caught.hasField("ExpectedVersion") || caught.hasField("ExpectedSettings"))
+        ? changedOnTheSite(form.key, caught, settingsApplied)
+        : caught;
+      if (error instanceof SiteAuthoringError) {
+        const completed = results.filter((item) => item.action !== "unchanged").map((item) => item.key);
+        // The settings write stands even though the version save after it failed.
+        if (settingsApplied) completed.push(form.key);
+        if (completed.length > 0) throw error.withCompletedWrites(completed);
+      }
+      throw error;
+    }
+    if (plan.action !== "unchanged") {
+      // The file is rewritten in canonical form so the workspace and the site
+      // agree byte for byte, and the baseline moves with it.
+      await writeWorkspaceJson(config.workspaceDir, formFileName(form.key), desired);
+      manifest = withRecordedForm(manifest, form.key, { id: formId, version, settings });
+      await writeManifest(config.workspaceDir, manifest);
+    }
+    results.push({ key: form.key, action: plan.action, version });
+    onProgress(`${form.key}: ${plan.action}${plan.action === "unchanged" ? "" : `, version ${version}`}.`);
+  }
+
+  const written = results.filter((item) => item.action !== "unchanged").map((item) => item.key);
+  return successResult(VERB_FORMS_PUSH, siteId, {
+    forms: { count: results.length, items: results },
+    written: { items: written, count: written.length },
+    ...(written.length > 0 ? { nextStep: "deploy --staging" } : {}),
+  });
+}

package/src/verbs/forms-validate.js

@@ -0,0 +1,36 @@
+import { VERB_FORMS_VALIDATE } from "../constants.js";
+import { SiteAuthoringError } from "../errors.js";
+import { readWorkspaceForms } from "../forms-workspace.js";
+import { openAnonymousSession, successResult } from "../session.js";
+
+/**
+ * `forms validate` — prove the workspace's form files offline.
+ *
+ * It runs the same file contract and the same shared field validator
+ * `forms push` does, so a file that passes here is not refused for its shape
+ * by the push. It cannot prove what only the site knows: whether the key is
+ * already taken by a form someone else changed, or whether the caller may
+ * write forms.
+ */
+export async function formsValidate(invocation) {
+  const { config, onProgress } = await openAnonymousSession({ ...invocation, client: null });
+  if (config === undefined) {
+    throw new SiteAuthoringError(
+      "config.not_found",
+      "No taproot-site.json was found. forms validate reads the workspace it names.",
+    );
+  }
+  const forms = await readWorkspaceForms(config.workspaceDir, invocation.formKeys);
+  onProgress(`Validated ${forms.length} form file${forms.length === 1 ? "" : "s"}.`);
+  return successResult(VERB_FORMS_VALIDATE, undefined, {
+    forms: {
+      count: forms.length,
+      items: forms.map((form) => ({
+        key: form.key,
+        file: form.file,
+        fields: form.document.definition.fields.length,
+        sink: form.document.sink ?? "none",
+      })),
+    },
+  });
+}

package/src/verbs/index.js

@@ -4,6 +4,9 @@ import {
   VERB_DEPLOY,
   VERB_ENV,
   VERB_FOOTER_PUSH,
+  VERB_FORMS_PULL,
+  VERB_FORMS_PUSH,
+  VERB_FORMS_VALIDATE,
   VERB_LOGIN,
   VERB_LOGOUT,
   VERB_MEDIA_UPLOAD,
@@ -28,6 +31,9 @@ import { deliveryCheck } from "./delivery-check.js";
 import { deploy } from "./deploy.js";
 import { env } from "./env.js";
 import { footerPush } from "./footer-push.js";
+import { formsPull } from "./forms-pull.js";
+import { formsPush } from "./forms-push.js";
+import { formsValidate } from "./forms-validate.js";
 import { login } from "./login.js";
 import { logout } from "./logout.js";
 import { mediaUpload } from "./media-upload.js";
@@ -84,6 +90,8 @@ import { whoami } from "./whoami.js";
  *   fixturePath,   // validate: one offline authoring-fixture directory
  *   paths,         // media upload: files and/or directories to upload;
  *                  //   with none, the workspace's media/ directory is walked
+ *   formKeys,      // forms validate / push: narrow to these form keys;
+ *                  //   with none, every file under forms/
  *   pagePaths,     // approve: narrow to these page paths; with none, every
  *                  //   draft the workspace manifest tracks is staged
  *   pageId,        // preview page: the one persisted draft UUID to render
@@ -124,6 +132,9 @@ export const VERB_HANDLERS = Object.freeze({
   [VERB_REDIRECTS_PUSH]: redirectsPush,
   [VERB_THEME_PUSH]: themePush,
   [VERB_FOOTER_PUSH]: footerPush,
+  [VERB_FORMS_PULL]: formsPull,
+  [VERB_FORMS_PUSH]: formsPush,
+  [VERB_FORMS_VALIDATE]: formsValidate,
   [VERB_MEDIA_UPLOAD]: mediaUpload,
   [VERB_APPROVE]: approve,
   [VERB_DEPLOY]: deploy,

package/src/verbs/pull.js

@@ -63,6 +63,7 @@ import {
   workspaceContentHash,
   workspaceFileExists,
   workspaceFileNameForPage,
+  readManifest,
   writeManifest,
   writeWorkspaceFile,
   writeWorkspaceJson,
@@ -1103,6 +1104,12 @@ export async function pull(invocation) {
       await writeWorkspaceJson(config.workspaceDir, document.file, document.value);
     }
 
+    // `forms pull` owns the forms baseline, and a plain pull does not read forms.
+    // Carrying it forward keeps the next `forms push` fenced instead of refusing
+    // it as never pulled. An unreadable old manifest has nothing to carry.
+    const formsBaseline = (await readManifest(config.workspaceDir, siteId, { required: false }).catch(() =>
+      undefined
+    ))?.forms;
     const manifest = {
       manifestVersion: MANIFEST_VERSION,
       siteId,
@@ -1123,6 +1130,7 @@ export async function pull(invocation) {
           : {}
       ),
       ...(presentationRevision === undefined ? {} : { presentation: presentationManifestEntry(presentationRevision) }),
+      ...(formsBaseline === undefined ? {} : { forms: formsBaseline }),
       pages: manifestPages,
     };
     await writeManifest(config.workspaceDir, manifest);