@taprootio/site-authoring 0.18.0 → 0.20.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,
@@ -638,6 +645,24 @@ Other C0/C1 controls, U+2028/U+2029, U+FEFF, and literal `<br>` tags are rejecte
 with the exact fact field path. A label is optional and stays outside the value's link. See
 `taproot-site help page free-form` and `taproot-site help component cta`.
 
+### Forms by id in 0.20.0
+
+A page stores the form it places by the form's id, so renaming a form never
+breaks a page, but a workspace still names a form by its key: `forms/<key>.json`
+and the `formKey` of a `component:form` block are unchanged, and the same files
+still push to a fresh site whose ids all differ. `pages push` looks each key up
+on the site, sends the form's id, and refuses a key the site does not have
+(`pages.form_unknown`) or has archived (`pages.form_archived`) before it writes
+anything; `plan` reports the same. `pages pull` writes the key back. An id the
+site no longer has stays an id in the pulled file, and a push of it is refused
+until you choose a form. Form names are now unique on a site, ignoring case.
+The deploy that introduces this rewrites the stored page bodies, which changes the
+body revision of every page that places a form, so the first `pages pull` after it
+can report `pages.pull_conflict` for such a Markdown page even though its content
+is the same. Run `taproot-site pages push <path>` for that page, or delete the file
+and pull again. `forms validate` and `forms push` also refuse two forms with the
+same name (`forms.name_duplicate`, `forms.name_taken`).
+
 ### Place categories in 0.18.0
 
 A place has one category for every site, taken from Google's types, and a place

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.18.0",
+  "version": "0.20.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/cli.js

@@ -239,7 +239,9 @@ const VERBS = Object.freeze([
       + "and announced on the human channel. New downloads and compared bodies are excluded. "
       + "A page Taproot generates (a tag, an archive, a place, a folder) is pulled as an update-only '.pm.json' "
       + "(template 'generated'): you edit its custom title, breadcrumb title, custom description and introduction, "
-      + "and the manifest keeps the title and description the site reports.",
+      + "and the manifest keeps the title and description the site reports. "
+      + "A form a page places is written back by its key, the name 'forms/<key>.json' uses, though the site stores "
+      + "the form's id.",
   },
   {
     name: VERB_PAGES_META_SET,
@@ -305,6 +307,8 @@ const VERBS = Object.freeze([
     positionals: "pagePaths",
     note:
       "Positional page paths narrow the push to those pages; with none, every workspace page is validated and sent. "
+      + "A page names a form by key (formKey); the push looks each key up on the site, sends the form's id, and "
+      + "refuses a key the site does not have or has archived (pages.form_unknown, pages.form_archived) before writing. "
       + "A link in a page being sent whose address is only http(s):// plus its own text is reported in linkWarnings "
       + "(content.link_autolinked) without refusing. "
       + "A page is created without an author unless its source names one ('author:' in the front matter, or 'pages "
@@ -394,7 +398,7 @@ const VERBS = Object.freeze([
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DESIGN],
     tokens: ["plan"],
     summary: "Check the whole workspace against the live site and order what is left to send. Writes nothing.",
-    note: "Runs every check the pushes run — each page against the site's pages, revisions and videos; media that "
+    note: "Runs every check the pushes run — each page against the site's pages, revisions, videos and forms; media that "
       + "pages reference and media upload has not sent; the theme, appearance and footer colors against the site's "
       + "presentation revision; the footer against its draft; navigation against the live page list — and lists "
       + "every problem with its area, file, code and field. It then orders the steps that remain: media upload, "

package/src/content/components.js

@@ -352,11 +352,14 @@ const SPACER = Object.freeze({
 
 /**
  * A form defined under Site → Forms (or with `forms push`), placed by key. The
- * key is checked against the site's forms when the page is published, not here:
- * this table only knows the shape.
+ * workspace names a form by its key so the same files push to any site; the site
+ * stores the form's id, and `pages push` and `pages pull` translate between the
+ * two (TR01216). The key is checked against the site's forms when the page is
+ * pushed, not here: this table only knows the shape.
  */
 const FORM = Object.freeze({
-  formKey: str(),
+  // Required: a placement with no form chosen can never publish, so it is refused here, not at deploy.
+  formKey: str({ required: true, nonWhitespace: true }),
 });
 
 function deepFreeze(value) {
@@ -648,9 +651,9 @@ const COMPONENT_DEFINITIONS = Object.freeze({
     FORM,
     "Form",
     "A form from Site → Forms that visitors fill in and submit.",
-    { formKey: "" },
+    {},
     [
-      "Set formKey to the key of an existing form ('forms push' creates it); an unknown or archived key fails the publish.",
+      "Set formKey to the key of an existing form ('forms push' creates it); 'pages push' refuses an unknown or archived key, and the site stores the form's id, not the key.",
       "The button text and what happens after a response is sent belong to the form, not the page: set submit_label and after_submit in the form's file (see 'help forms').",
       "The form's field labels are its accessible names; write each so it makes sense out of context.",
     ],

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/form-references.js

@@ -0,0 +1,103 @@
+import { listSiteForms } from "./forms-api.js";
+import { contentDocuments, parseComponentData } from "./typed-pages.js";
+
+/**
+ * Where the workspace and the site spell a placed form differently (TR01216).
+ *
+ * A workspace names a form by its key, as `forms/<key>.json` and the Markdown
+ * `form` fence do, so the same workspace can be pushed to a fresh site whose
+ * ids all differ. A page stored on the site names the form by its id. `pages
+ * push` turns keys into ids on the way out and `pages pull` turns ids back
+ * into keys, the way a form's `page_path` and `page_resource_id` already
+ * translate. The translation is block-scoped: a `formKey` anywhere but a `form`
+ * component block is author prose.
+ */
+
+const FORM_COMPONENT = "form";
+
+/** Each `form` component block in the document's content documents, with its parsed data. */
+function formBlocks(document_) {
+  const found = [];
+  const visit = (value) => {
+    if (Array.isArray(value)) {
+      value.forEach(visit);
+    } else if (value !== null && typeof value === "object") {
+      if (value.type === "componentBlock" && value.attrs?.componentType === FORM_COMPONENT) {
+        const data = typeof value.attrs.componentData === "string"
+          ? parseComponentData(value.attrs.componentData)
+          : undefined;
+        if (data !== null && typeof data === "object" && !Array.isArray(data)) found.push({ attrs: value.attrs, data });
+        return;
+      }
+      Object.values(value).forEach(visit);
+    }
+  };
+  for (const { doc } of contentDocuments(document_)) visit(doc);
+  return found;
+}
+
+/** The distinct form keys a workspace document places, in document order. */
+export function placedFormKeys(document_) {
+  const keys = [];
+  for (const { data } of formBlocks(document_)) {
+    if (typeof data.formKey === "string" && data.formKey !== "" && !keys.includes(data.formKey)) keys.push(data.formKey);
+  }
+  return keys;
+}
+
+/** Whether a document read from the site places any form by id. */
+export function placesFormIds(document_) {
+  return formBlocks(document_).some(({ data }) => typeof data.formId === "string");
+}
+
+/**
+ * A copy of the document with every placed form named by id, for the wire. A key
+ * the index does not know is left as it is: `placedFormProblems` has already
+ * refused the push for it, so nothing sends it.
+ */
+export function withFormIds(document_, idByKey) {
+  return translate(document_, (data) => {
+    const id = typeof data.formKey === "string" ? idByKey.get(data.formKey) : undefined;
+    if (id === undefined) return undefined;
+    const rest = { ...data };
+    delete rest.formKey;
+    return { ...rest, formId: id };
+  });
+}
+
+/**
+ * A copy of a document read from the site with every placed form named by key,
+ * for the workspace. An id the site no longer has stays an id: pull must not hide
+ * what the site holds, and a push of that file is refused until the author picks a form.
+ */
+export function withFormKeys(document_, keyById) {
+  return translate(document_, (data) => {
+    const key = typeof data.formId === "string" ? keyById.get(data.formId) : undefined;
+    if (key === undefined) return undefined;
+    const rest = { ...data };
+    delete rest.formId;
+    return { ...rest, formKey: key };
+  });
+}
+
+function translate(document_, convert) {
+  const copy = structuredClone(document_);
+  for (const { attrs, data } of formBlocks(copy)) {
+    const converted = convert(data);
+    if (converted !== undefined) attrs.componentData = JSON.stringify(converted);
+  }
+  return copy;
+}
+
+/** The site's forms by key and by id, archived ones marked. One request serves a whole push or pull. */
+export async function readFormIndex(client, siteId) {
+  const idByKey = new Map();
+  const keyById = new Map();
+  const archivedKeys = new Set();
+  for (const form of await listSiteForms(client, siteId)) {
+    keyById.set(form.id, form.key);
+    if (form.archived) archivedKeys.add(form.key);
+    else idByKey.set(form.key, form.id);
+  }
+  return { idByKey, keyById, archivedKeys };
+}

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,18 +47,41 @@ 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) });
   }
+  requireDistinctNames(forms);
   return forms;
 }
 
+/** A form name as the site compares it: trimmed, ignoring case (TR01216). */
+export function comparableFormName(name) {
+  return String(name).trim().toLowerCase();
+}
+
+/** Names are unique per site, so two files in one push cannot share one. */
+function requireDistinctNames(forms) {
+  const seen = new Map();
+  for (const form of forms) {
+    const name = comparableFormName(form.document.name);
+    const other = seen.get(name);
+    if (other !== undefined) {
+      throw new SiteAuthoringError(
+        "forms.name_duplicate",
+        `${form.file} and ${other} both name the form '${form.document.name}'. A form name is unique on a site, `
+          + "ignoring case; rename one of them.",
+        { field: `${form.file}:name` },
+      );
+    }
+    seen.set(name, form.file);
+  }
+}
+
 /**
  * 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 +91,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 +110,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

@@ -86,7 +86,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 36;
+export const REFERENCE_VERSION = 37;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -773,14 +773,21 @@ 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. "
+      + `1 to ${FORM_LIMITS.nameCharacters} characters and unique on the site, ignoring case: two files, or a file and another form on the site, with the same name `
+      + "are refused (forms.name_duplicate, forms.name_taken) before anything is written. "
+      + `sink is one of ${FORM_SINKS.join(", ")} and defaults to `
+      + "'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,14 +842,15 @@ 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 "
       + "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.",
+      + "to the form's key ('help component form' lists its properties). Push the form first: 'pages push' turns the "
+      + "key into the form's id for the site and refuses a key the site does not have or has archived, and 'pages pull' "
+      + "turns the id back into the key. Then 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 "
@@ -854,6 +862,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/typed-pages.js

@@ -769,7 +769,7 @@ export const COVER_IMAGE_UNUSED_MESSAGE = "The selected cover image must be used
  * component JSON, so a string that only parses once decoded is read the way the
  * server reads it.
  */
-function parseComponentData(text) {
+export function parseComponentData(text) {
   let decoded = text;
   for (let round = 0; round < 3 && /&(?:quot|amp|#39|lt|gt);/u.test(decoded); round += 1) {
     decoded = decoded.replace(/&quot;/gu, "\"").replace(/&#39;/gu, "'").replace(/&lt;/gu, "<").replace(/&gt;/gu, ">")

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

@@ -5,22 +5,28 @@ import {
   createSiteForm,
   getPageIndex,
   getSiteFormByKey,
+  listSiteForms,
   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 { afterSubmitPage, formFileName, projectFormForWorkspace, storedDefinition, validateNewsletterDefinition } from "../forms-contract.js";
+import { comparableFormName, 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 +50,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 +73,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 +120,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 +138,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.
@@ -142,6 +156,26 @@ export async function formsPush(invocation) {
     );
   }
 
+  // A form name is unique on the site, ignoring case, so a name another form holds is refused here with
+  // the rest of the checks, not by the first write that reaches it.
+  const naming = plans.filter((plan) => plan.action === "create" || plan.settingsChanged);
+  if (naming.length > 0) {
+    const siteForms = await withRefusalGuidance(onProgress, "forms push", async () => await listSiteForms(client, siteId));
+    for (const plan of naming) {
+      const name = comparableFormName(plan.desired.name);
+      const holder = siteForms.find((siteForm) => siteForm.key !== plan.form.key && comparableFormName(siteForm.name) === name);
+      if (holder !== undefined) {
+        throw new SiteAuthoringError(
+          "forms.name_taken",
+          `${formFileName(plan.form.key)}: the site's form '${holder.key}'${holder.archived ? " (archived)" : ""} already `
+            + `has the name '${plan.desired.name}'. A form name is unique on a site, ignoring case; rename one of them. `
+            + "Nothing was written.",
+          { field: `${formFileName(plan.form.key)}:name` },
+        );
+      }
+    }
+  }
+
   const results = [];
   for (const plan of plans) {
     let { desired } = plan;
@@ -151,7 +185,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 +200,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 +261,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" } : {}),
   });
 }

package/src/verbs/pages-push.js

@@ -21,6 +21,7 @@ import {
 } from "../authors-contract.js";
 import { VERB_PAGES_PUSH } from "../constants.js";
 import { autolinkWarnings } from "../content/link-warnings.js";
+import { placedFormKeys, readFormIndex, withFormIds } from "../form-references.js";
 import { ApiError } from "../transport.js";
 import { waitForProcessing } from "./media-upload.js";
 import { SiteAuthoringError } from "../errors.js";
@@ -878,6 +879,46 @@ export async function placedVideoProblems(client, siteId, planned) {
   return problems;
 }
 
+/**
+ * The pages that place a form the site does not have, or has archived, and the
+ * site's forms by key for the wire (TR01216). A page is stored with the form's id,
+ * so a key that names no active form cannot be sent at all. Pages that will not be
+ * sent are not asked about, and a push that places no form reads nothing.
+ */
+export async function placedFormProblems(client, siteId, planned) {
+  const placements = new Map();
+  for (const page of planned) {
+    if (page.unchanged) continue;
+    for (const key of placedFormKeys(page.document)) {
+      if (!placements.has(key)) placements.set(key, page.file);
+    }
+  }
+  if (placements.size === 0) return { problems: [], idByKey: new Map() };
+
+  const index = await readFormIndex(client, siteId);
+  const problems = [];
+  for (const [key, file] of placements) {
+    if (index.idByKey.has(key)) continue;
+    problems.push(...problemsOf(
+      index.archivedKeys.has(key)
+        ? documentError(
+          "pages.form_archived",
+          `'${file}' places the form '${key}', which is archived. Restore the form under Site → Forms or remove it `
+            + "from the page.",
+          file,
+        )
+        : documentError(
+          "pages.form_unknown",
+          `'${file}' places the form '${key}', which this site does not have. Run 'taproot-site forms push' to create `
+            + "it, or fix the key.",
+          file,
+        ),
+      { area: CHECK_AREA.pages, file },
+    ));
+  }
+  return { problems, idByKey: index.idByKey };
+}
+
 /**
  * Gives each `video-embed` block that has no poster the provider's thumbnail,
  * copied into the site's images by the server (TR01109). One request per provider
@@ -1565,6 +1606,9 @@ export async function pagesPush(invocation) {
     // push, before anything is written, so a page cannot be sent that
     // publishing would then refuse.
     plan.problems.push(...await placedVideoProblems(client, siteId, planned));
+    // Likewise a form: pages store its id, which only the site's own forms can supply.
+    const placedForms = await placedFormProblems(client, siteId, planned);
+    plan.problems.push(...placedForms.problems);
 
     // Under apply, the workspace read ledger has already held every source and
     // manifest to the plan. What it cannot see is the site: every page the plan
@@ -1634,7 +1678,7 @@ export async function pagesPush(invocation) {
           path: page.pagePath,
           title: page.title,
           shortDescription: page.description,
-          template: wireTemplate(page.document),
+          template: wireTemplate(withFormIds(page.document, placedForms.idByKey)),
           ...wirePageFields(page.document),
           // Only a name the site has not been told: repeating the author a page
           // already has would let a later change of that person's permissions

package/src/verbs/plan.js

@@ -45,6 +45,7 @@ import { navPush, validateNavigationWorkspaceDocument } from "./nav-push.js";
 import {
   liveAuthorsRefresher,
   pagesPush,
+  placedFormProblems,
   placedVideoProblems,
   planPages,
   plannedPageItem,
@@ -283,6 +284,7 @@ async function preflight(session, invocation) {
     });
     problems.push(...pages.problems);
     problems.push(...await placedVideoProblems(client, siteId, pages.planned));
+    problems.push(...(await placedFormProblems(client, siteId, pages.planned)).problems);
     const sending = pages.planned.filter((page) => !page.unchanged);
 
     // An image a page names must be one the site holds; an image this plan
@@ -433,7 +435,7 @@ function planReport(planned) {
     ready: problems.length === 0,
     steps,
     checked: [
-      "every page source, against the live site's pages, revisions, and video library",
+      "every page source, against the live site's pages, revisions, video library, and the forms it places",
       "media under media/ that pages reference and media upload has not sent",
       "the theme, appearance, and footer colors, against the site's presentation revision",
       "the footer document, against the site's footer draft and the pages it still holds",
@@ -441,7 +443,7 @@ function planReport(planned) {
       "navigation shape and page targets, against the live page list and navigation",
     ],
     notChecked: [
-      "redirects and forms: run 'redirects push' and 'forms push' on their own",
+      "redirects, and the forms files themselves: run 'redirects push' and 'forms push' on their own",
       "rendering: preview pages before approving them",
       "approval, staging, and production, which stay separate commands",
     ],

package/src/verbs/pull.js

@@ -33,6 +33,7 @@ import {
   SETTINGS_TYPE_TAPROOT_STYLES,
 } from "../settings-catalog.js";
 import { ApiError } from "../transport.js";
+import { placesFormIds, readFormIndex, withFormKeys } from "../form-references.js";
 import {
   generatedIdentity,
   isAuthorableTemplateType,
@@ -643,6 +644,15 @@ async function requireWorkspaceBelongsToSite(workspaceDir, siteId) {
 
 export async function pull(invocation) {
   const { client, config, siteId, surface, now, onProgress } = await openSession(invocation);
+  // A page names its forms by id on the site and by key in the workspace (TR01216). The
+  // site's forms are read once, and only when a page body places one.
+  let formKeys;
+  const workspaceBodyFromPage = async (page, listedTemplateType) => {
+    const body = workspaceDocumentFromPage(page, listedTemplateType);
+    if (body === undefined || !placesFormIds(body)) return body;
+    formKeys ??= readFormIndex(client, siteId).then((index) => index.keyById);
+    return withFormKeys(body, await formKeys);
+  };
   await ensureWorkspaceRoot(config);
 
   await requireWorkspaceBelongsToSite(config.workspaceDir, siteId);
@@ -891,7 +901,7 @@ export async function pull(invocation) {
       if (source === undefined) continue;
       onProgress(`Reading page '${summary.path}'.`);
       const page = await getPage(client, summary.pageId, bodyStatusFor(summary));
-      const body = workspaceDocumentFromPage(page, summary.templateType);
+      const body = await workspaceBodyFromPage(page, summary.templateType);
       const description = typeof page.shortDescription === "string" ? page.shortDescription : "";
       if (body === undefined) {
         // The site's body is unreadable, but the workspace file is still this
@@ -1261,7 +1271,7 @@ export async function pull(invocation) {
         }
         onProgress(`Reading page '${summary.path}'.`);
         const page = await getPage(client, summary.pageId, bodyStatusFor(summary));
-        const body = workspaceDocumentFromPage(page, summary.templateType);
+        const body = await workspaceBodyFromPage(page, summary.templateType);
         entry.description = typeof page.shortDescription === "string" ? page.shortDescription : "";
         entry.title = titleFromRead(page, summary);
         entry.path = pathFromRead(page, summary);