@taprootio/site-authoring 0.18.0 → 0.19.0

package/README.md

@@ -524,6 +524,13 @@ Submissions are never pulled. `help forms` states the file shape and every
 refusal, and placing a form on a page is the free-form `form`
 component.
 
+The optional top-level `notify_owner` boolean opts a form into hourly,
+counts-only owner email. New forms default to false; omitting it on an
+existing form preserves the site's preference. It is independent of the sink
+and takes effect without publishing or a new form version. Delivery requires
+Taproot's rollout and email provider readiness; opt-in does not enable either
+or backfill earlier submissions. The CLI never pulls visitor answers.
+
 `preview page <page-path-or-id>` renders one persisted draft behind the
 staging gate and mints a browser handoff URL, reported only in the final JSON
 result. **Each handoff is single-use.** Opening the URL consumes it; a reused,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Taproot site authoring CLI: sign in once in the browser, then pull, validate, push, preview, approve, and deploy a site from the terminal",
   "type": "module",
   "license": "ISC",

package/src/field-schema.json

@@ -17,6 +17,11 @@
       "description": "The id of the email field whose value the API copies to subject_email. It must name an email field. Omit it when the form has one email field (that field is the contact); it is required with two or more.",
       "$ref": "#/$defs/id"
     },
+    "newsletter_audience_id": {
+      "description": "The active manual newsletter audience on the form's site that receives the reader after email confirmation. Omit it for newsletter only. The server checks ownership and availability when saving.",
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    },
     "submit_label": {
       "description": "The text on the submit button. Omit it for Taproot's default. Must contain more than whitespace; the validator also rejects a blank label, which a schema cannot express.",
       "type": "string",

package/src/field-validation.js

@@ -106,7 +106,7 @@ export function contactFieldId(definition) {
     const emails = definition.fields.filter((field) => field.type === "email");
     return emails.length === 1 ? emails[0].id : undefined;
 }
-const DEFINITION_KEYS = ["fields", "contact_field", "submit_label", "after_submit"];
+const DEFINITION_KEYS = ["fields", "contact_field", "submit_label", "after_submit", "newsletter_audience_id"];
 const BASE_FIELD_KEYS = ["id", "type", "label", "hint"];
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const isInteger = (value) => typeof value === "number" && Number.isInteger(value);
@@ -427,6 +427,10 @@ export function validateDefinition(definition) {
 }
 /** The button text and the after-submit choice, which sit beside the fields in a definition. */
 function validateFormSettings(definition, errors) {
+    const audience = definition.newsletter_audience_id;
+    if (audience !== undefined && (typeof audience !== "string" || !isResourceId(audience))) {
+        errors.push({ path: "newsletter_audience_id", code: "invalid_newsletter_audience" });
+    }
     const label = definition.submit_label;
     if (label !== undefined && (typeof label !== "string" || isBlank(label) || label.length > MAX_SUBMIT_LABEL_LENGTH)) {
         errors.push({ path: "submit_label", code: "invalid_submit_label" });

package/src/forms-api.js

@@ -1,7 +1,7 @@
 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 { FORM_DEFAULT_NOTIFY_OWNER, FORM_DEFAULT_SINK, FORM_SINKS, isFormKey, normalizePagePath } from "./forms-contract.js";
 import { ApiError } from "./transport.js";
 
 /**
@@ -38,12 +38,16 @@ function normalizeForm(value) {
   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");
   }
+  if (Object.hasOwn(value, "notifyOwner") && typeof value.notifyOwner !== "boolean") {
+    throw contract("Taproot returned an owner notification setting that is not a boolean.", "notifyOwner");
+  }
   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,
+    notifyOwner: value.notifyOwner ?? FORM_DEFAULT_NOTIFY_OWNER,
     archived: value.status === STATUS_ARCHIVED_WIRE,
     currentVersion: Number.isSafeInteger(value.currentVersion) ? value.currentVersion : 0,
   };
@@ -140,6 +144,7 @@ export async function createSiteForm(client, siteId, form) {
         name: form.name,
         sink: SINK_WIRE[form.sink],
         retentionDays: form.retention_days,
+        notifyOwner: form.notify_owner,
         definition: JSON.stringify(form.definition),
       },
       maximumResponseBytes: FORMS_RESPONSE_BYTES,
@@ -160,12 +165,14 @@ export async function updateSiteFormSettings(client, siteId, formId, form, expec
         name: form.name,
         sink: SINK_WIRE[form.sink],
         retentionDays: form.retention_days,
+        notifyOwner: form.notify_owner,
         ...(expected === undefined
           ? {}
           : {
             expectedName: expected.name,
             expectedSink: SINK_WIRE[expected.sink],
             expectedRetentionDays: expected.retention_days,
+            expectedNotifyOwner: expected.notify_owner,
           }),
       },
       maximumResponseBytes: FORMS_RESPONSE_BYTES,

package/src/forms-contract.js

@@ -5,7 +5,7 @@ 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
+ * its key, name, sink, retention, owner-notification preference 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
@@ -27,6 +27,7 @@ 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_DEFAULT_NOTIFY_OWNER = false;
 export const FORM_RETENTION_DAYS = Object.freeze({ minimum: 30, maximum: 730, default: 365 });
 export const FORM_LIMITS = Object.freeze({
   nameCharacters: 120,
@@ -35,7 +36,7 @@ export const FORM_LIMITS = Object.freeze({
   fileBytes: 256 * 1024,
 });
 
-const FORM_FILE_KEYS = ["key", "name", "sink", "retention_days", "definition"];
+const FORM_FILE_KEYS = ["key", "name", "sink", "retention_days", "notify_owner", "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.
@@ -101,14 +102,24 @@ function describeDefinitionErrors(errors) {
   return `${shown.join("; ")}${more}`;
 }
 
+/** Checks newsletter admission after the definition has passed shared validation. */
+export function validateNewsletterDefinition(file, definition) {
+  const fields = definition.fields;
+  const contact = fields.find((field) => field.id === contactFieldId(definition));
+  if (contact?.type !== "email" || contact.required !== true || !fields.some((field) => field.type === "consent")) {
+    throw invalid(file, "a newsletter sink requires a required email contact field and at least one consent checkbox.", "definition");
+  }
+}
+
 /**
  * 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.
+ * Only `forms push` defers newsletter admission until it compares the site's baseline.
  */
-export function validateFormDocument(document_, expectedKey) {
+export function validateFormDocument(document_, expectedKey, { deferNewsletterSemantics = false } = {}) {
   const file = formFileName(expectedKey);
   if (!isPlainObject(document_)) throw invalid(file, "the file must contain one JSON object.", "$");
   for (const name of Object.keys(document_)) {
@@ -138,6 +149,9 @@ export function validateFormDocument(document_, expectedKey) {
   if (document_.sink !== undefined && !FORM_SINKS.includes(document_.sink)) {
     throw invalid(file, `sink must be one of: ${FORM_SINKS.join(", ")}.`, "sink");
   }
+  if (Object.hasOwn(document_, "notify_owner") && typeof document_.notify_owner !== "boolean") {
+    throw invalid(file, "notify_owner must be true or false.", "notify_owner");
+  }
   const days = document_.retention_days;
   if (
     days !== undefined
@@ -156,6 +170,7 @@ export function validateFormDocument(document_, expectedKey) {
   if (errors.length > 0) {
     throw invalid(file, `the definition is invalid: ${describeDefinitionErrors(errors)}`, "definition");
   }
+  if (document_.sink === "newsletter" && !deferNewsletterSemantics) validateNewsletterDefinition(file, document_.definition);
   if (anyUnstorableString(document_.definition)) {
     throw invalid(file, "the definition cannot contain NUL or unpaired surrogate characters.", "definition");
   }
@@ -238,6 +253,16 @@ function rejectNonTarget(file, pages, id, field, name) {
   );
 }
 
+/** Operational settings in the same order for workspace files and saved baselines. */
+export function projectFormSettings(form) {
+  return {
+    name: form.name,
+    sink: form.sink ?? FORM_DEFAULT_SINK,
+    retention_days: form.retention_days ?? FORM_RETENTION_DAYS.default,
+    notify_owner: form.notify_owner ?? FORM_DEFAULT_NOTIFY_OWNER,
+  };
+}
+
 function canonicalField(field) {
   const ordered = {};
   for (const name of FIELD_KEY_ORDER) if (field[name] !== undefined) ordered[name] = field[name];
@@ -266,9 +291,7 @@ export function projectFormForWorkspace(form, pathById) {
   }
   return {
     key: form.key,
-    name: form.name,
-    sink: form.sink ?? FORM_DEFAULT_SINK,
-    retention_days: form.retention_days ?? FORM_RETENTION_DAYS.default,
+    ...projectFormSettings(form),
     definition,
   };
 }

package/src/forms-workspace.js

@@ -1,12 +1,12 @@
 import { SiteAuthoringError } from "./errors.js";
 import {
-  FORM_DEFAULT_SINK,
+  FORM_DEFAULT_NOTIFY_OWNER,
   FORM_FILE_EXTENSION,
-  FORM_RETENTION_DAYS,
   FORM_LIMITS,
   FORMS_DIRECTORY,
   formFileName,
   isFormKey,
+  projectFormSettings,
   validateFormDocument,
 } from "./forms-contract.js";
 import { readWorkspaceJson, walkWorkspaceFiles } from "./workspace.js";
@@ -18,8 +18,9 @@ import { readWorkspaceJson, walkWorkspaceFiles } from "./workspace.js";
  * 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.
+ * Newsletter admission is strict by default; `forms push` defers it for baseline comparison.
  */
-export async function readWorkspaceForms(workspaceDir, keys) {
+export async function readWorkspaceForms(workspaceDir, keys, validationOptions = {}) {
   const files = await walkWorkspaceFiles(workspaceDir, FORMS_DIRECTORY, [FORM_FILE_EXTENSION]);
   const known = new Map();
   for (const file of files) {
@@ -46,7 +47,7 @@ export async function readWorkspaceForms(workspaceDir, keys) {
       );
     }
     const document_ = await readWorkspaceJson(workspaceDir, file, FORM_LIMITS.fileBytes);
-    forms.push({ key, file, document: validateFormDocument(document_, key) });
+    forms.push({ key, file, document: validateFormDocument(document_, key, validationOptions) });
   }
   return forms;
 }
@@ -54,10 +55,9 @@ export async function readWorkspaceForms(workspaceDir, keys) {
 /**
  * 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.
+ * A browser edit since the last pull or push makes the next push refuse rather
+ * than overwrite it. Each mutation also sends this baseline so the site can
+ * refuse an edit made after the CLI compared them.
  */
 export const FORMS_MANIFEST_KEY = "forms";
 
@@ -67,15 +67,16 @@ function isObject(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
+ * it. Operational settings change without appending a version, so the
  * version alone cannot say they moved.
  */
 export function siteSettingsBaseline(siteForm) {
-  return {
+  return projectFormSettings({
     name: siteForm.name,
-    sink: siteForm.sink ?? FORM_DEFAULT_SINK,
-    retention_days: siteForm.retentionDays ?? FORM_RETENTION_DAYS.default,
-  };
+    sink: siteForm.sink,
+    retention_days: siteForm.retentionDays,
+    notify_owner: siteForm.notifyOwner,
+  });
 }
 
 /** The recorded baseline for one key, or undefined when this workspace never saw that form. */
@@ -85,7 +86,15 @@ export function recordedForm(manifest, key) {
   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 }
+    ? {
+      id: entry.id,
+      version: entry.version,
+      // Old baselines can prove only the default opt-out, never a remote opt-in.
+      settings: {
+        ...entry.settings,
+        notify_owner: Object.hasOwn(entry.settings, "notify_owner") ? entry.settings.notify_owner : FORM_DEFAULT_NOTIFY_OWNER,
+      },
+    }
     : undefined;
 }
 

package/src/reference-help.js

@@ -773,14 +773,19 @@ const WORKFLOW_REFERENCES = Object.freeze({
     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 `
+      `The file is { key, name, sink, retention_days, notify_owner, 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. "
+      + "'none' (store submissions only); 'newsletter' requests double-opt-in confirmation for the contact address. "
+      + "A newsletter sink requires a required email contact field and at least one consent checkbox; every consent checkbox must be checked. "
       + `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.",
+      "notify_owner is an optional top-level boolean, independent of the sink. New forms default to false; omitting it "
+      + "on an existing form preserves the site's preference. It opts into hourly counts-only email to the current site "
+      + "account owner, never visitor answers or addresses. This setting takes effect without a new version or publishing. "
+      + "Delivery also requires Taproot's rollout and email provider readiness; opt-in enables neither, and earlier submissions are not backfilled.",
       `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 "
@@ -835,7 +840,7 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "'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.concurrent_modification when the site's version or operational settings 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 "
@@ -854,6 +859,7 @@ const WORKFLOW_REFERENCES = Object.freeze({
       name: "Contact",
       sink: "none",
       retention_days: 365,
+      notify_owner: false,
       definition: Object.freeze({
         fields: Object.freeze([
           Object.freeze({ id: "name", type: "text", label: "Your name", required: true, max_length: 120 }),

package/src/verbs/forms-pull.js

@@ -41,9 +41,7 @@ export async function formsPull(invocation) {
     }
     const document_ = projectFormForWorkspace({
       key: form.key,
-      name: form.name,
-      sink: form.sink,
-      retention_days: form.retentionDays,
+      ...siteSettingsBaseline(form),
       definition: version.definition,
     }, pages?.pathById);
     await writeWorkspaceJson(config.workspaceDir, formFileName(form.key), document_);

package/src/verbs/forms-push.js

@@ -8,19 +8,24 @@ import {
   saveSiteFormVersion,
   updateSiteFormSettings,
 } from "../forms-api.js";
-import { afterSubmitPage, formFileName, projectFormForWorkspace, storedDefinition } from "../forms-contract.js";
+import { afterSubmitPage, formFileName, projectFormForWorkspace, storedDefinition, validateNewsletterDefinition } 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) {
+function changedOnTheSite(key, cause, applied) {
+  const outcome = applied.settings && applied.definition
+    ? "Its settings and definition were applied."
+    : applied.settings
+    ? "Its settings were applied; its definition was not."
+    : applied.definition
+    ? "Its definition was applied; its settings were not."
+    : "This form was not changed.";
   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."
-      }`,
+      + `reconcile the file, and retry. ${outcome}`,
     { field: formFileName(key), status: cause.status },
   );
 }
@@ -44,6 +49,7 @@ function planForm(form, remote, baseline, pages) {
   const desired = projectFormForWorkspace({
     ...form.document,
     retention_days: requestedRetention ?? remote?.form.retentionDays,
+    notify_owner: form.document.notify_owner ?? remote?.form.notifyOwner,
   }, pages?.pathById);
   if (remote === undefined) {
     if (baseline !== undefined) {
@@ -66,28 +72,27 @@ function planForm(form, remote, baseline, pages) {
   if (
     baseline.id !== remote.form.id
     || baseline.version !== remote.version.version
-    // Name, sink and retention change without a new version, so they are
+    // Operational settings 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, `
+        + `${baseline.version}, site has ${remote.version.version}; its settings 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,
+    ...siteSettings,
     definition: remote.version.definition,
   }, pages?.pathById);
   const settingsChanged = current.name !== desired.name
     || current.sink !== desired.sink
-    || current.retention_days !== desired.retention_days;
+    || current.retention_days !== desired.retention_days
+    || current.notify_owner !== desired.notify_owner;
   const versionChanged = JSON.stringify(current.definition) !== JSON.stringify(desired.definition);
   return {
     form,
@@ -114,7 +119,7 @@ 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);
+  const forms = await readWorkspaceForms(config.workspaceDir, invocation.formKeys, { deferNewsletterSemantics: true });
   onProgress(`Validated ${forms.length} form file${forms.length === 1 ? "" : "s"}.`);
   let manifest = await readManifest(config.workspaceDir, siteId);
 
@@ -132,6 +137,14 @@ export async function formsPush(invocation) {
       pages = await withRefusalGuidance(onProgress, "forms push", async () => await getPageIndex(client, siteId, { onProgress }));
     }
     const plan = planForm(form, remote, recordedForm(manifest, form.key), pages);
+    // Legacy newsletter definitions may stay only after the baseline matches.
+    // New capture or a changed definition must satisfy today's admission rules.
+    if (
+      plan.desired.sink === "newsletter"
+      && (plan.action === "create" || plan.remote.form.sink !== "newsletter" || plan.versionChanged)
+    ) {
+      validateNewsletterDefinition(form.file, plan.desired.definition);
+    }
     // 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.
@@ -151,7 +164,7 @@ export async function formsPush(invocation) {
     // 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;
+    const applied = { settings: false, definition: false };
     try {
       if (plan.action === "create") {
         const created = await withRefusalGuidance(
@@ -166,43 +179,48 @@ export async function formsPush(invocation) {
         // and normalized the name.
         desired = projectFormForWorkspace({
           ...desired,
-          name: created.form.name,
-          sink: created.form.sink,
-          retention_days: created.form.retentionDays,
+          ...settings,
         }, pages?.pathById);
       } else if (plan.action === "update") {
-        if (plan.settingsChanged) {
-          settings = siteSettingsBaseline(
-            await withRefusalGuidance(
+        // Enabling newsletter capture checks the stored definition, so its new
+        // email and consent fields must land first. Disabling must do the reverse.
+        const definitionFirst = plan.settingsChanged && plan.versionChanged
+          && settings.sink === "none" && desired.sink === "newsletter";
+        for (const mutation of definitionFirst ? ["definition", "settings"] : ["settings", "definition"]) {
+          if (mutation === "settings") {
+            if (!plan.settingsChanged) continue;
+            settings = siteSettingsBaseline(
+              await withRefusalGuidance(
+                onProgress,
+                "forms push",
+                async () => await updateSiteFormSettings(client, siteId, formId, desired, plan.baseline.settings),
+              ),
+            );
+            desired = projectFormForWorkspace({ ...desired, ...settings }, pages?.pathById);
+          } else {
+            if (!plan.versionChanged) continue;
+            version = (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.
+              async () => await saveSiteFormVersion(client, siteId, formId, { ...desired, definition: plan.wireDefinition }, plan.baseline.version),
+            )).version;
+          }
+          applied[mutation] = true;
+          // A retry must recognize either write as its own, even if the next
+          // mutation fails. Keep the other half of the baseline until it lands.
           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)
+        ? changedOnTheSite(form.key, caught, applied)
         : 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 (applied.settings || applied.definition) completed.push(form.key);
         if (completed.length > 0) throw error.withCompletedWrites(completed);
       }
       throw error;
@@ -222,6 +240,6 @@ export async function formsPush(invocation) {
   return successResult(VERB_FORMS_PUSH, siteId, {
     forms: { count: results.length, items: results },
     written: { items: written, count: written.length },
-    ...(written.length > 0 ? { nextStep: "deploy --staging" } : {}),
+    ...(plans.some((plan) => plan.action === "create" || plan.versionChanged) ? { nextStep: "deploy --staging" } : {}),
   });
 }