@taprootio/site-authoring 0.11.1 → 0.12.1

package/README.md

@@ -99,6 +99,7 @@ taproot-site help
 taproot-site help designs
 taproot-site help design professional-portfolio
 taproot-site help page free-form
+taproot-site help page recipe
 taproot-site help component hero-section --json
 ```
 
@@ -141,8 +142,8 @@ taproot-site validate "$(npm root --global)/@taprootio/site-authoring/examples/r
 
 The fixture is a fictional wellness studio — `example.test` hostnames, a
 reserved `555-01xx` telephone number, an invented street and town — with two
-free-form pages, a three-item navigation tree, and all four settings
-documents. Nothing in it describes a real business. Copy the directory
+free-form pages and one each of the article, recipe, album and place-review
+templates, a three-item navigation tree, and all four settings documents. Nothing in it describes a real business. Copy the directory
 somewhere writable before you edit it; `validate` never writes to the fixture
 it reads.
 
@@ -338,6 +339,17 @@ the site's own document is kept as internal state under
 edited on the site since the last pull is a `pages.pull_conflict` refusal
 before anything under `pages/` changes, with both recovery paths named.
 
+Pages are not only free-form. A source chooses its template with `template:` in
+its front matter — `article`, `recipe`, `album` or `place-review`; free-form is
+the default — and `pull` writes the other four as a `.pm.json` wrapper
+(`{ "template", "displayDate", "coverImageId", "data" }`) that `pages push`
+sends back unchanged. Typed pages also carry `displayDate` (so an import keeps
+its original publication date) and `coverImage`, which the site requires to be an
+image the page itself uses (place it in the body too; `pages.cover_image_unused`). A page's template is fixed when
+it is created: a source for another template is refused with
+`pages.template_immutable`. `taproot-site help page <type>` gives each
+template's fields and one worked example.
+
 `pages push [page-path...]` validates and sends the selected pages, or every
 workspace page when none is named; the homepage is addressed as `/`. It fails
 closed with `pages.push_conflict` when a page's stored-state revision has
@@ -489,7 +501,7 @@ fingerprint supply no gating evidence. Typed preview failure diagnostics contain
 only error class and known page/node/attribute labels, never renderer messages.
 
 Staging deploys check the current redirect map through the real staging edge.
-Run `taproot-site redirects check` to repeat after eventual edge propagation.
+Run `taproot-site redirects check` to repeat once the deployment has completed; a redirect is a file inside the release, so it is live exactly when its release is served.
 The Node CLI consumes a separate handoff, retains its short staging cookie in
 memory, and requests each map path without following redirects. Results report
 path, HTTP status and Location; `verified` requires all entries to match and the
@@ -549,7 +561,7 @@ taproot-site validate ../authoring-fixture
 The destination must be new, outside the source workspace, and its parent must exist. Use
 `taproot-site --config path/to/taproot-site.json validate --init ../authoring-fixture`
 to select another source configuration. Initialization needs no credential or
-network. It exports editable free-form pages as ProseMirror with navigation,
+network. It exports editable pages of every template as workspace documents with navigation,
 redirects, settings, and version-7 appearance/footer metadata, validates the
 result, and leaves the source unchanged. Excluded metadata-only pages are
 counted; unresolved references to them fail validation.

package/examples/riverbend-wellness/manifest.fixture.json

@@ -30,6 +30,62 @@
       "file": "pages/visit.md",
       "sourceFormat": "markdown",
       "workspaceMode": "editable"
+    },
+    {
+      "pageId": "a0000000-0000-4000-8000-000000000040",
+      "resourceId": "a0000000-0000-4000-8000-000000000041",
+      "path": "journal/welcome",
+      "title": "Welcome to the Riverbend journal",
+      "status": "PAGE_STATUS_DRAFT",
+      "templateType": "TEMPLATE_TYPE_ARTICLE",
+      "hasDraft": true,
+      "isGenerated": false,
+      "description": "An example article for the offline authoring fixture.",
+      "file": "pages/journal-welcome.md",
+      "sourceFormat": "markdown",
+      "workspaceMode": "editable"
+    },
+    {
+      "pageId": "a0000000-0000-4000-8000-000000000042",
+      "resourceId": "a0000000-0000-4000-8000-000000000043",
+      "path": "recipes/green-smoothie",
+      "title": "Green morning smoothie",
+      "status": "PAGE_STATUS_DRAFT",
+      "templateType": "TEMPLATE_TYPE_RECIPE",
+      "hasDraft": true,
+      "isGenerated": false,
+      "description": "An example recipe for the offline authoring fixture.",
+      "file": "pages/green-smoothie.md",
+      "sourceFormat": "markdown",
+      "workspaceMode": "editable"
+    },
+    {
+      "pageId": "a0000000-0000-4000-8000-000000000044",
+      "resourceId": "a0000000-0000-4000-8000-000000000045",
+      "path": "albums/studio-tour",
+      "title": "A tour of the studio",
+      "status": "PAGE_STATUS_DRAFT",
+      "templateType": "TEMPLATE_TYPE_ALBUM",
+      "hasDraft": true,
+      "isGenerated": false,
+      "description": "An example album for the offline authoring fixture.",
+      "file": "pages/studio-tour.pm.json",
+      "sourceFormat": "prosemirror",
+      "workspaceMode": "editable"
+    },
+    {
+      "pageId": "a0000000-0000-4000-8000-000000000046",
+      "resourceId": "a0000000-0000-4000-8000-000000000047",
+      "path": "reviews/juice-bar",
+      "title": "The corner juice bar",
+      "status": "PAGE_STATUS_DRAFT",
+      "templateType": "TEMPLATE_TYPE_PLACE_REVIEW",
+      "hasDraft": true,
+      "isGenerated": false,
+      "description": "An example place review for the offline authoring fixture.",
+      "file": "pages/juice-bar.md",
+      "sourceFormat": "markdown",
+      "workspaceMode": "editable"
     }
   ],
   "pagesTruncated": false,

package/examples/riverbend-wellness/pages/green-smoothie.md

@@ -0,0 +1,28 @@
+---
+title: Green morning smoothie
+path: recipes/green-smoothie
+description: An example recipe for the offline authoring fixture.
+template: recipe
+prepTimeMinutes: 5
+servings: 2
+recipeCategory: Drink
+---
+
+A fictional studio favorite that takes five minutes.
+
+## Ingredients
+
+### Base
+
+- 1 cup spinach
+- 1 banana
+- 1 cup oat milk
+
+### Finish
+
+- 1 tablespoon chia seeds
+
+## Instructions
+
+1. Blend the base until smooth.
+2. Stir in the chia seeds and rest for two minutes.

package/examples/riverbend-wellness/pages/journal-welcome.md

@@ -0,0 +1,13 @@
+---
+title: Welcome to the Riverbend journal
+path: journal/welcome
+description: An example article for the offline authoring fixture.
+template: article
+displayDate: 2024-03-01
+---
+
+The journal is where the fictional Riverbend Wellness studio shares notes from
+the studio floor. This page is an **article**: a title, a body, and an
+original publication date kept with `displayDate`.
+
+A page's template is chosen once, when it is created, and never changes.

package/examples/riverbend-wellness/pages/juice-bar.md

@@ -0,0 +1,11 @@
+---
+title: The corner juice bar
+path: reviews/juice-bar
+description: An example place review for the offline authoring fixture.
+template: place-review
+placeId: a0000000-0000-4000-8000-0000000000b0
+rating: will-return
+---
+
+An invented juice bar in the fictional town of Elm Harbor. Nothing here
+describes a real business.

package/examples/riverbend-wellness/pages/studio-tour.pm.json

@@ -0,0 +1,34 @@
+{
+  "template": "album",
+  "coverImageId": "a0000000-0000-4000-8000-0000000000a1",
+  "data": {
+    "introductionBody": {
+      "type": "doc",
+      "content": [
+        {
+          "type": "paragraph",
+          "content": [
+            {
+              "type": "text",
+              "text": "A fictional tour of the studio. An album keeps its images by id, so its source is a JSON document."
+            }
+          ]
+        }
+      ]
+    },
+    "images": [
+      {
+        "imageId": "a0000000-0000-4000-8000-0000000000a1",
+        "caption": "The main room",
+        "width": 1920,
+        "height": 1080
+      },
+      {
+        "imageId": "a0000000-0000-4000-8000-0000000000a2",
+        "caption": "The tea corner",
+        "width": 1200,
+        "height": 1600
+      }
+    ]
+  }
+}

package/package.json

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

@@ -490,6 +490,9 @@ export function normalizePageSummary(value) {
     // at" — and both are carried as `undefined` rather than as a sentinel that
     // would compare unequal to every recorded baseline and refuse every push.
     bodyRevision: normalizePageBodyRevision(summary.bodyRevision),
+    // The page's calendar date, empty when it has none. It is not part of
+    // `bodyRevision`, so a typed page's push guard compares it separately.
+    displayDate: typeof summary.displayDate === "string" ? summary.displayDate : "",
   };
 }
 
@@ -526,14 +529,6 @@ export async function getPage(client, pageId, status) {
   );
 }
 
-export function freeFormTemplate(body) {
-  return {
-    templateType: TEMPLATE_TYPE_FREE_FORM,
-    templateVersion: FREE_FORM_TEMPLATE_VERSION,
-    freeFormData: { body },
-  };
-}
-
 export async function createPage(client, body) {
   return normalizePageSummary(await client.request("v1/pages", { method: "POST", body }));
 }
@@ -1118,7 +1113,6 @@ export async function listDeployments(
         `deployments${
           query([
             ["pageSize", pageSize],
-            ["includeStaging", true],
             ["environment", environment],
           ])
         }`,

package/src/cli.js

@@ -251,7 +251,8 @@ const VERBS = Object.freeze([
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS],
     tokens: ["redirects", "check"],
     summary: "Check the current redirect map through the authenticated staging edge.",
-    note: "Reports path, HTTP status and Location without following redirects. Re-run after edge propagation. "
+    note: "Reports path, HTTP status and Location without following redirects. A redirect is live only with the release "
+      + "that carries it, so this reads the staged release. "
       + "The result includes a fresh single-use staging handoff; keep it private.",
   },
   {
@@ -275,7 +276,8 @@ const VERBS = Object.freeze([
     summary: "Validate redirects.json and replace the whole redirect map.",
     note: "Run 'redirects pull' first. The whole file is validated locally by entry index — path normalization, "
       + "targets, statuses, duplicates, chains, and loops — before anything is sent, and the site refuses a "
-      + "source a live page occupies. Entries take effect on the next deploy. "
+      + "source a live page occupies or a file the site generates. An entry is a file inside the next release, so it "
+      + "goes live with that deploy: staging first, production when promoted. "
       + "See 'taproot-site help redirects'.",
   },
   {
@@ -705,6 +707,7 @@ function parseReferenceArguments(arguments_) {
       || topic === "redirects"
       || topic === "walkthrough"
       || topic === "delivery"
+      || topic === "import"
     )
     && (subject !== undefined || extra.length > 0)
   ) {
@@ -774,6 +777,7 @@ function referenceResult(parsed) {
     case "fixture":
     case "walkthrough":
     case "delivery":
+    case "import":
       return {
         ...result,
         topic: "workflow",

package/src/content/components.js

@@ -157,10 +157,6 @@ const CTA = Object.freeze({
   }),
   imagePosition: enumOf("top", "left", "right"),
   mediaImage: image(),
-  // TR00890: "waitlist" replaces the link button with an email-capture form
-  // that posts to the platform's public waitlist endpoint. buttonUrl is
-  // ignored in that mode; buttonText becomes the submit button's label.
-  formMode: enumOf("none", "waitlist"),
 });
 
 /** `FeatureGridData`. */
@@ -363,12 +359,10 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       borderWidth: 0,
       imagePosition: "top",
       mediaImage: null,
-      formMode: "none",
     },
     [
       "Button text must describe its action or destination.",
       "Give meaningful media a descriptive alt value and decorative media an empty alt value.",
-      "formMode \"waitlist\" renders an email-capture form instead of the link button; leave buttonUrl empty and use buttonText for the submit label.",
     ],
     {
       heading: "Ready to begin?",

package/src/redirects-contract.js

@@ -42,13 +42,16 @@ export const REDIRECT_STATUSES = Object.freeze([301, 302, 307, 308]);
 
 /**
  * Bounds, mirrored from `SiteRedirectMapContract` on the server. The path bound
- * is what fits a Workers KV key beside its `redirect:{environment}:{site}:`
- * envelope; the target bound is the edge's own.
+ * is the map's own; the target bound is the edge's own, and a target must also
+ * fit as metadata on its redirect file once encoded.
  */
 export const REDIRECT_LIMITS = Object.freeze({
   entries: 2_000,
   pathBytes: 400,
   targetBytes: 2_048,
+  // Once percent-encoded, a target rides on its redirect file as object
+  // metadata; the server pins the same number (MaxMarkerTargetEncodedLength).
+  targetEncodedCharacters: 1_810,
 });
 
 // C0, DEL, and C1 — every code point the server's own `char.IsControl`
@@ -88,8 +91,7 @@ const UNSENDABLE_SPELLING = /[^!-~]|["<>`{}]|%(?![0-9a-fA-F]{2})/u;
  * between the API's .NET and the edge's WHATWG parser, so a spelling this pass
  * encoded would still not be the one the Worker computes and the layers would
  * go on comparing different strings. Write what a browser sends and every layer
- * compares it unchanged — and the byte bounds then measure the spelling the KV
- * key actually costs.
+ * compares it unchanged — and the byte bounds then measure that same spelling.
  */
 function isRequestSpelling(value) {
   return !UNSENDABLE_SPELLING.test(value);
@@ -154,6 +156,70 @@ export function normalizeRedirectPath(value) {
   return trimmed === "" ? "/" : trimmed;
 }
 
+// The root segment the published output reserves for integration data; the release
+// inventory leaves everything under it out.
+const RESERVED_INTEGRATION_DATA_SEGMENT = "integrations";
+
+// Root-level files the site generates. A redirect is a marker file inside the
+// published site (TR00968), so a source that names one has nowhere to live.
+const GENERATED_ROOT_FILES = Object.freeze(["404.html", "sitemap.xml", "robots.txt", "favicon.ico"]);
+// The longest decoded path segment a marker file name may have; the API rule and the
+// generator use the same 200 bytes.
+const MAX_MARKER_SEGMENT_BYTES = 200;
+const WINDOWS_DEVICE_STEMS = new Set(["con", "prn", "aux", "nul"]);
+
+function isWindowsDeviceSegment(segment) {
+  const stem = segment.split(".", 1)[0].toLowerCase();
+  return WINDOWS_DEVICE_STEMS.has(stem) || /^(?:com|lpt)[1-9]$/u.test(stem);
+}
+
+/**
+ * Why a normalized source path cannot be a redirect, or undefined when it can.
+ * A mirror of `SiteRedirectMapContract.SourceRefusalReason` on the server (the
+ * API is the authority; both run the same test vectors): `…/index.html` is
+ * answered by the platform for every page, the generator writes the files
+ * named above, and the marker is stored under the decoded spelling, so a path
+ * that cannot be stored once decoded (an escaped percent sign, a dot-prefixed
+ * segment, a reserved device name) is refused. The site root is left to the
+ * occupancy rule.
+ */
+export function redirectSourceRefusalReason(path) {
+  if (path === "/") return undefined;
+  // Every rule reads the decoded spelling: it is the name the marker is stored
+  // under, and the name the generator's own files use (`/%69ndex.html` is
+  // `/index.html`).
+  let decoded;
+  try {
+    decoded = path.replace(/^\/+|\/+$/gu, "").split("/").map(decodeURIComponent).join("/");
+  } catch {
+    return "it holds a percent escape that does not decode.";
+  }
+  const segments = decoded.split("/");
+  const first = segments[0].toLowerCase();
+  if (segments.some((segment) => segment.toLowerCase() === "index.html")) {
+    return "the platform already redirects every '…/index.html' address to its directory, so it cannot also be "
+      + "a redirect source, and the page or home file there is generated.";
+  }
+  if (first === RESERVED_INTEGRATION_DATA_SEGMENT) {
+    return `'/${segments[0]}' is reserved for integration data, so nothing under it can be a redirect source.`;
+  }
+  if (GENERATED_ROOT_FILES.includes(first)) {
+    return `'/${segments[0]}' is a file the site generates, so neither it nor anything under it can be a redirect source.`;
+  }
+  if (
+    decoded.includes("..")
+    || decoded !== decoded.normalize("NFC")
+    || segments.some((segment) =>
+      segment === "" || segment.startsWith(".") || /[%\\?#\u0000-\u001F\u007F-\u009F]/u.test(segment)
+      || isWindowsDeviceSegment(segment) || new TextEncoder().encode(segment).length > MAX_MARKER_SEGMENT_BYTES
+    )
+  ) {
+    return "a redirect is stored as a file in the published site, and this path cannot be one (no dot-prefixed "
+      + "segments, reserved device names, '..', escaped percent signs, or segments over 200 bytes).";
+  }
+  return undefined;
+}
+
 function looksAbsolute(value) {
   return !value.startsWith("/") && value.includes("://");
 }
@@ -235,14 +301,21 @@ function validateEntry(value, index, seen) {
       `${field}.path`,
     );
   }
-  if (seen.has(path.toLowerCase())) {
+  const sourceRefusal = redirectSourceRefusalReason(path);
+  if (sourceRefusal !== undefined) {
+    throw entryError("redirects.path_unpublishable", `'${path}': ${sourceRefusal}`, `${field}.path`);
+  }
+  // The marker is stored under the decoded spelling, so `/a%41` and `/aA` are one
+  // file, and the second would silently replace the first.
+  const markerKey = decodeURIComponent(path).toLowerCase();
+  if (seen.has(markerKey)) {
     throw entryError(
       "redirects.path_duplicate",
       `'${path}' appears more than once; one path has one entry.`,
       `${field}.path`,
     );
   }
-  seen.add(path.toLowerCase());
+  seen.add(markerKey);
 
   const kind = value.kind === undefined ? REDIRECT_KIND_REDIRECT : value.kind;
   if (!REDIRECT_KINDS.includes(kind)) {
@@ -296,6 +369,15 @@ function validateEntry(value, index, seen) {
     );
   }
 
+  if (encodeURIComponent(rawTarget).length > REDIRECT_LIMITS.targetEncodedCharacters) {
+    throw entryError(
+      "redirects.target_too_long_to_store",
+      "'target' is stored as metadata on the published site's redirect file and is too long to fit "
+        + `(${REDIRECT_LIMITS.targetEncodedCharacters} characters once percent-encoded).`,
+      `${field}.target`,
+    );
+  }
+
   let target;
   if (looksAbsolute(rawTarget)) {
     if (!isAbsoluteRedirectTarget(rawTarget)) {
@@ -341,13 +423,23 @@ function validateEntry(value, index, seen) {
   return { path, kind: REDIRECT_KIND_REDIRECT, target, status };
 }
 
+// The marker is stored under the decoded spelling, so `/%61` and `/a` are one route
+// and `/%61 -> /a` is a loop. A target's escape may not decode; it then compares raw.
+function routeIdentity(path) {
+  try {
+    return decodeURIComponent(path).toLowerCase();
+  } catch {
+    return path.toLowerCase();
+  }
+}
+
 function assertNoChains(entries) {
-  const sources = new Set(entries.map((entry) => entry.path.toLowerCase()));
+  const sources = new Set(entries.map((entry) => routeIdentity(entry.path)));
   entries.forEach((entry, index) => {
     const targetPath = internalRedirectTargetPath(entry);
-    if (targetPath === undefined || !sources.has(targetPath.toLowerCase())) return;
+    if (targetPath === undefined || !sources.has(routeIdentity(targetPath))) return;
     const field = `entries[${index}].target`;
-    if (targetPath.toLowerCase() === entry.path.toLowerCase()) {
+    if (routeIdentity(targetPath) === routeIdentity(entry.path)) {
       throw entryError("redirects.loop", `'${entry.path}' redirects to itself.`, field);
     }
     throw entryError(