@taprootio/site-authoring 0.12.5 → 0.12.7

package/README.md

@@ -188,7 +188,7 @@ Which verbs apply depends on the site:
   `pull` snapshots its four settings documents, `theme push`, `footer push`,
   and `media upload` author them, and `deploy` stages and promotes them.
   Its pages, navigation, and redirects come from the Docs artifact, so
-  `pages push`, `nav push`, the `redirects` verbs, `approve`, and the
+  `pages push`, `nav push`, the `redirects` and `forms` verbs, `approve`, and the
   `preview` verbs refuse with `surface.presentation_only` before any request.
 - A **prebuilt Docs** site (`none`) serves its artifact unchanged and takes no
   verb; each refuses with `surface.none`.
@@ -373,6 +373,16 @@ validates the file offline and replaces the whole map; `help redirects`
 states the entry shape (`path`, `kind` redirect or gone, `target`, `status`
 defaulting to 301), the normalization rule, and every refusal.
 
+`forms pull` writes each live form to `forms/<key>.json` and records the
+version it read; `forms push` validates every file, refuses a form the site
+changed since (`forms.concurrent_modification`) and creates or updates the
+rest, appending a version when the definition changed. `forms validate` checks
+the files offline against the shared field schema with no credential. Both
+verbs write one canonical key order, so a pulled file pushed back is unchanged.
+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.
+
 `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,
@@ -537,8 +547,8 @@ completed deployment for the target, HTTP delivery of the authored routes and
 the favicon, images, module preloads and site bundle they declare (status and
 content type, no redirects followed), internal link targets, accidental
 local-only references, and the pinned runtime — the version the page names,
-its entry module and the capability modules the page declares, with a page
-that still names the pre-pinning runtime pointer reported as unverified until it is republished. The
+its entry module and the capability modules the page declares (a page that
+pins no runtime version and entry fails the runtime check). The
 browser dimension (a fresh and a returning load
 compared against the page's pinned entry, every document request in the browser,
 popups included, held to the site origin before it is sent, and cache reuse

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.12.5",
+  "version": "0.12.7",
   "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",
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@taprootio/espalier": "4.20.1"
+    "@taprootio/espalier": "5.0.0"
   },
   "scripts": {
     "test": "node --test",

package/src/capabilities.js

@@ -23,7 +23,7 @@ export const SITE_AUTHORING_CAPABILITIES = Object.freeze([
 
 /** What each capability lets an exchanged credential do, for help and `whoami`. */
 export const SITE_AUTHORING_CAPABILITY_SUMMARIES = Object.freeze({
-  "delegation.content": "write pages and media",
+  "delegation.content": "write pages, media, and form definitions",
   "delegation.design": "set the theme, navigation, and footer",
   "delegation.deployments": "stage and deploy",
 });

package/src/cli.js

@@ -20,6 +20,9 @@ import {
   VERB_STAGING_REVIEW,
   VERB_ENV,
   VERB_FOOTER_PUSH,
+  VERB_FORMS_PULL,
+  VERB_FORMS_PUSH,
+  VERB_FORMS_VALIDATE,
   VERB_HELP,
   VERB_LOGIN,
   VERB_LOGOUT,
@@ -71,14 +74,14 @@ import { VERB_HANDLERS } from "./verbs/index.js";
 /**
  * The verbs the local version gate applies to (TR00703).
  *
- * Exactly the three that make no request. Every other verb reaches Taproot,
+ * Exactly the ones that make no request. Every other verb reaches Taproot,
  * whose own refusal is authoritative and better informed than this recording,
  * so gating them here would only duplicate an answer — and gating `login`,
  * `logout`, or `env` would take away the commands an operator needs while they
  * are outdated. `--help` and `--version` are outside it for the same reason:
  * they are how someone finds out what they have.
  */
-const VERSION_GATED_OFFLINE_VERBS = Object.freeze([VERB_HELP, VERB_VALIDATE, VERB_WHOAMI]);
+const VERSION_GATED_OFFLINE_VERBS = Object.freeze([VERB_HELP, VERB_VALIDATE, VERB_FORMS_VALIDATE, VERB_WHOAMI]);
 
 // One entry per verb, in help order. `tokens` is the exact leading positional
 // sequence; matching prefers the longest sequence, so a two-token family can
@@ -281,6 +284,47 @@ const VERBS = Object.freeze([
       + "goes live with that deploy: staging first, production when promoted. "
       + "See 'taproot-site help redirects'.",
   },
+  {
+    name: VERB_FORMS_PULL,
+    surface: SURFACE_STANDARD,
+    // Forms are authored with the pages that place them, so they ride the
+    // content capability; the site's forms permissions decide what it may do.
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["forms", "pull"],
+    summary: "Write each live form to forms/<key>.json and record the versions read.",
+    note: "Needs a pulled workspace ('pull' first). It replaces a form's file with the site's copy and records the "
+      + "version, which 'forms push' uses to refuse a change made on the site since. An archived form is listed "
+      + "and not written. Submissions are never pulled: they are visitors' personal data and stay on the site. "
+      + "See 'taproot-site help forms'.",
+  },
+  {
+    name: VERB_FORMS_PUSH,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["forms", "push"],
+    positionals: "formKeys",
+    summary: "Validate forms/<key>.json and create or update each form on the site.",
+    note: "Every file is validated and compared with the site before anything is written. A form whose site "
+      + "version moved since the last pull is refused (forms.concurrent_modification), and a form the site has "
+      + "that this workspace never pulled is refused (forms.pull_required). Editing a definition appends a version; "
+      + "a page keeps the version it was published with until the next deploy. An after_submit page_path is looked "
+      + "up on the site, and a path that names no page is refused (forms.page_not_found), as is a generated, 404, legal, profile or integration page (forms.page_not_allowed). Name form keys to narrow "
+      + "the push. See 'taproot-site help forms'.",
+  },
+  {
+    name: VERB_FORMS_VALIDATE,
+    tokens: ["forms", "validate"],
+    offline: true,
+    // Offline, but it reads taproot-site.json to find the workspace.
+    readsLocalState: true,
+    positionals: "formKeys",
+    summary: "Validate the workspace's form files offline, against the shared field schema.",
+    note: "Reads forms/<key>.json and checks the file contract and every field definition with the same validator "
+      + "'forms push' and the published form use. Name form keys to narrow it; with none, every file under forms/ "
+      + "is checked. It cannot prove that the site accepts the key, that an after_submit page_path names a page, or "
+      + "that the caller may write forms. "
+      + "See 'taproot-site help forms'.",
+  },
   {
     name: VERB_THEME_PUSH,
     surface: SURFACE_DOCS_PRESENTATION,
@@ -556,6 +600,8 @@ function verbHelp(verb) {
     ? " [production | local | <url>]"
     : verb.positionals === "siteSelector"
     ? " <site-name-or-id>"
+    : verb.positionals === "formKeys"
+    ? " [form-key...]"
     : verb.positionals
     ? ` [${verb.positionals === "paths" ? "path" : "page-path"}...]`
     : "";
@@ -706,6 +752,7 @@ function parseReferenceArguments(arguments_) {
       || topic === "footer"
       || topic === "fixture"
       || topic === "redirects"
+      || topic === "forms"
       || topic === "walkthrough"
       || topic === "delivery"
       || topic === "import"
@@ -773,6 +820,7 @@ function referenceResult(parsed) {
     }
     case "nav":
     case "redirects":
+    case "forms":
     case "media":
     case "preview":
     case "fixture":

package/src/constants.js

@@ -87,6 +87,9 @@ export const VERB_NAV_PUSH = "nav push";
 export const VERB_REDIRECTS_CHECK = "redirects check";
 export const VERB_REDIRECTS_PULL = "redirects pull";
 export const VERB_REDIRECTS_PUSH = "redirects push";
+export const VERB_FORMS_PULL = "forms pull";
+export const VERB_FORMS_PUSH = "forms push";
+export const VERB_FORMS_VALIDATE = "forms validate";
 export const VERB_THEME_PUSH = "theme push";
 export const VERB_FOOTER_PUSH = "footer push";
 export const VERB_MEDIA_UPLOAD = "media upload";

package/src/content/components.js

@@ -286,6 +286,15 @@ const SPACER = Object.freeze({
   dividerWidth: num({ integer: true, minimum: 1 }),
 });
 
+/**
+ * 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.
+ */
+const FORM = Object.freeze({
+  formKey: str(),
+});
+
 function deepFreeze(value) {
   if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
   for (const child of Object.values(value)) deepFreeze(child);
@@ -555,6 +564,18 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       imageMotion: "parallax-subtle",
     },
   ),
+  "form": component(
+    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.",
+      "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.",
+    ],
+    { formKey: "contact" },
+  ),
 });
 
 export const COMPONENT_TYPES = Object.freeze(Object.keys(COMPONENT_DEFINITIONS));

package/src/content/free-form-section-registry.json

@@ -1,5 +1,5 @@
 {
-  "version": 7,
+  "version": 9,
   "section": {
     "nodeType": "section",
     "label": "Section",
@@ -554,6 +554,11 @@
       "label": "Image Banner",
       "measure": "wide",
       "rootPlacement": "root-band"
+    },
+    "form": {
+      "label": "Form",
+      "measure": "wide",
+      "rootPlacement": "flow"
     }
   },
   "integrationPlacement": {

package/src/delivery-check.js

@@ -205,8 +205,6 @@ export function parseBootstrap(html) {
   return {
     version: text(parsed.version).slice(0, 64),
     entry: text(parsed.entry),
-    // A release published before runtime pinning named a mutable pointer instead.
-    legacyPointer: typeof parsed.runtimeManifestUrl === "string" && parsed.runtimeManifestUrl !== "",
     siteBundleUrl: text(parsed.siteBundleUrl),
     runtimeCapabilities,
     capabilities,
@@ -506,9 +504,6 @@ async function observe(context, origin, sampledRoutes) {
     }
   }
   runtime.pinned = runtime.version !== "" && Boolean(bootstrap?.entry);
-  // Such a page still loads in a browser, but this check no longer reads the
-  // pointer, so its runtime is reported unverified rather than as passed or failed.
-  runtime.legacy = !runtime.pinned && Boolean(bootstrap?.legacyPointer);
   const entryUrl = runtime.pinned ? admit(bootstrap.entry) : undefined;
   if (entryUrl) {
     const { row } = await probe(context, entryUrl.href, "runtime-entry");
@@ -570,10 +565,7 @@ async function observe(context, origin, sampledRoutes) {
     ...assetResults.filter((row) => !row.ok).map((row) => `${row.kind} ${row.url}: ${row.failure}`),
     ...linkResults.filter((row) => !row.ok).map((row) => `link ${row.path}: ${row.failure}`),
     ...(runtime.declared ? [] : ["runtime: the home page declares no runtime bootstrap"]),
-    ...(runtime.declared && runtime.legacy
-      ? ["runtime: the page names a pre-pinning runtime pointer, which is not verified here; republish the site so it pins a runtime version"]
-      : []),
-    ...(runtime.declared && !runtime.pinned && !runtime.legacy
+    ...(runtime.declared && !runtime.pinned
       ? ["runtime: the page does not pin a runtime version and entry"]
       : []),
     ...(runtime.declared && runtime.pinned && !runtime.entry.ok
@@ -677,7 +669,7 @@ export async function checkDelivery({
 
   const verdict = observed.failuresTotal === 0
     ? "delivered"
-    : observed.routeRows.every((row) => row.ok) && (observed.runtime.compatible || observed.runtime.legacy)
+    : observed.routeRows.every((row) => row.ok) && observed.runtime.compatible
     ? "degraded"
     : "failed";
   const report = {
@@ -757,7 +749,6 @@ function withinOutputBudget(report, failuresTotal) {
         declared: runtime.declared,
         version: runtime.version,
         pinned: runtime.pinned,
-        legacy: runtime.legacy,
         capabilities: runtime.capabilities.length,
         capabilitiesResolvable: runtime.capabilitiesResolvable,
         compatible: runtime.compatible,

package/src/field-schema.json

@@ -0,0 +1,217 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://taproot.io/schemas/field-definitions.json",
+  "title": "Taproot field definitions",
+  "description": "A flat, closed list of typed fields. shared/field-validation.ts and the API validator interpret it; shared/field-validation-corpus.json is the evidence they agree. Limits: 30 fields, 16 KB of submitted content. JSON Schema maxLength counts code points while the validators count UTF-16 code units, so the validators are authoritative and stricter for astral characters.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["fields"],
+  "properties": {
+    "fields": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 30,
+      "items": { "$ref": "#/$defs/field" }
+    },
+    "contact_field": {
+      "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"
+    },
+    "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",
+      "minLength": 1,
+      "maxLength": 40
+    },
+    "after_submit": {
+      "description": "What a visitor sees once a response is sent. Omit it to show Taproot's default message. A page is named by its resource id and must belong to the same site; the release freezes the path the page has when it is built.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["show"],
+          "properties": {
+            "show": { "const": "message" },
+            "message": {
+              "description": "Omit it for Taproot's default. Must contain more than whitespace; the validator also rejects a blank message, which a schema cannot express.",
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 500
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["show", "page_resource_id"],
+          "properties": {
+            "show": { "const": "page" },
+            "page_resource_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }
+          }
+        }
+      ]
+    }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" },
+    "label": {
+      "description": "Must contain more than whitespace; the validator also rejects a blank label, which a schema cannot express.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "consentLabel": {
+      "description": "A consent field's label is the agreement the visitor accepts, so it is longer than any other label. Must contain more than whitespace; the validator also rejects a blank label.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000
+    },
+    "hint": {
+      "description": "Optional helper text drawn under the field. Must contain more than whitespace; the validator rejects a blank hint, which a schema cannot express.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "required": { "type": "boolean" },
+    "shortLength": { "type": "integer", "minimum": 0, "maximum": 500 },
+    "shortMaxLength": { "type": "integer", "minimum": 1, "maximum": 500 },
+    "longLength": { "type": "integer", "minimum": 0, "maximum": 5000 },
+    "longMaxLength": { "type": "integer", "minimum": 1, "maximum": 5000 },
+    "choices": {
+      "description": "Each choice must contain more than whitespace; the validator rejects blank choices, which a schema cannot express.",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 50,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1, "maxLength": 100 }
+    },
+    "isoDate": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "relativeDateBound": {
+      "description": "A date measured from the site's calendar date, resolved when the page loads and again when a submission arrives. offset_days is bounded to a year either side (366 covers a leap year); further out is a fixed date. A fixed date is the other form of a date bound.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["from"],
+      "properties": {
+        "from": {
+          "enum": ["today", "start_of_month", "end_of_month", "start_of_next_month", "end_of_next_month"]
+        },
+        "offset_days": { "type": "integer", "minimum": -366, "maximum": 366 }
+      }
+    },
+    "dateBound": {
+      "oneOf": [{ "$ref": "#/$defs/isoDate" }, { "$ref": "#/$defs/relativeDateBound" }]
+    },
+    "field": {
+      "type": "object",
+      "required": ["id", "type", "label"],
+      "oneOf": [
+        {
+          "properties": {
+            "id": { "$ref": "#/$defs/id" },
+            "type": { "const": "text" },
+            "label": { "$ref": "#/$defs/label" },
+            "hint": { "$ref": "#/$defs/hint" },
+            "required": { "$ref": "#/$defs/required" },
+            "min_length": { "$ref": "#/$defs/shortLength" },
+            "max_length": { "$ref": "#/$defs/shortMaxLength" },
+            "format": { "enum": ["digits", "alphanumeric"] }
+          },
+          "additionalProperties": false
+        },
+        {
+          "properties": {
+            "id": { "$ref": "#/$defs/id" },
+            "type": { "const": "long_text" },
+            "label": { "$ref": "#/$defs/label" },
+            "hint": { "$ref": "#/$defs/hint" },
+            "required": { "$ref": "#/$defs/required" },
+            "min_length": { "$ref": "#/$defs/longLength" },
+            "max_length": { "$ref": "#/$defs/longMaxLength" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "properties": {
+            "id": { "$ref": "#/$defs/id" },
+            "type": { "enum": ["email", "tel", "url"] },
+            "label": { "$ref": "#/$defs/label" },
+            "hint": { "$ref": "#/$defs/hint" },
+            "required": { "$ref": "#/$defs/required" },
+            "max_length": { "$ref": "#/$defs/shortMaxLength" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "properties": {
+            "id": { "$ref": "#/$defs/id" },
+            "type": { "const": "number" },
+            "label": { "$ref": "#/$defs/label" },
+            "hint": { "$ref": "#/$defs/hint" },
+            "required": { "$ref": "#/$defs/required" },
+            "min": { "type": "number" },
+            "max": { "type": "number" },
+            "format": { "enum": ["integer"] }
+          },
+          "additionalProperties": false
+        },
+        {
+          "properties": {
+            "id": { "$ref": "#/$defs/id" },
+            "type": { "const": "date" },
+            "label": { "$ref": "#/$defs/label" },
+            "hint": { "$ref": "#/$defs/hint" },
+            "required": { "$ref": "#/$defs/required" },
+            "min": { "$ref": "#/$defs/dateBound" },
+            "max": { "$ref": "#/$defs/dateBound" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "required": ["choices"],
+          "properties": {
+            "id": { "$ref": "#/$defs/id" },
+            "type": { "const": "single_choice" },
+            "label": { "$ref": "#/$defs/label" },
+            "hint": { "$ref": "#/$defs/hint" },
+            "required": { "$ref": "#/$defs/required" },
+            "choices": { "$ref": "#/$defs/choices" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "required": ["choices"],
+          "properties": {
+            "id": { "$ref": "#/$defs/id" },
+            "type": { "const": "multi_choice" },
+            "label": { "$ref": "#/$defs/label" },
+            "hint": { "$ref": "#/$defs/hint" },
+            "required": { "$ref": "#/$defs/required" },
+            "choices": { "$ref": "#/$defs/choices" },
+            "min": { "type": "integer", "minimum": 0, "maximum": 50 },
+            "max": { "type": "integer", "minimum": 0, "maximum": 50 }
+          },
+          "additionalProperties": false
+        },
+        {
+          "properties": {
+            "id": { "$ref": "#/$defs/id" },
+            "type": { "const": "checkbox" },
+            "label": { "$ref": "#/$defs/label" },
+            "hint": { "$ref": "#/$defs/hint" },
+            "required": { "$ref": "#/$defs/required" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "properties": {
+            "id": { "$ref": "#/$defs/id" },
+            "type": { "const": "consent" },
+            "label": { "$ref": "#/$defs/consentLabel" },
+            "hint": { "$ref": "#/$defs/hint" }
+          },
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
+}