@taprootio/site-authoring 0.2.0 → 0.4.0

package/README.md

@@ -34,13 +34,50 @@ Node 22 or later. The package has one runtime dependency,
 against one Espalier theme contract, and a floating range would let an install
 resolve a different contract than the CLI was tested against.
 
+## Keeping the CLI current
+
+Taproot accepts only the latest published release of this package. There is no
+compatibility window: the contract moves with every release, and a CLI behind
+the current one is refused at sign-in and at every online verb that exchanges
+the sign-in for a site credential, before it validates or writes anything.
+`TAPROOT_SITE_KEY` runs perform no sign-in and no exchange, so they are not
+version-gated and their `status` reports `cliRelease.latestKnown: false`; keep
+an automation's CLI current yourself.
+
+```bash
+npm install -g @taprootio/site-authoring@latest
+```
+
+A refusal names the field `CliUpgradeRequired`, classifies as
+`refusal: "cli_outdated"`, and carries both versions and that command. Nothing
+is wrong with the credential, the request, or the site, and no retry of an
+outdated version succeeds. If the newer release is only minutes old, npm may
+not serve it yet — wait a moment and run the upgrade again.
+
+Each sign-in exchange also reports the latest published release. `status` shows
+it as `cliRelease`, `whoami` reports what the last exchange recorded (dated with
+that exchange), and once a newer release has been recorded the offline verbs —
+`help`, `validate`, and `whoami` — refuse with the same message rather than
+letting an agent keep authoring against a contract that has moved. With nothing
+recorded they run, so a clean machine can still validate a fixture.
+`taproot-site --version` and `--help` always answer.
+
+Do not pin this package's version in a script. Every release retires the one
+before it, so a pin is a scheduled outage.
+
+**0.4.0 introduces this gate.** From the API deploy that ships with it, every
+CLI older than the release that API was built with is refused with
+`CliUpgradeRequired`. The release order is: merge to private `main`, then the
+npm publish of 0.4.0, then the API deploy — publishing first is what keeps the
+upgrade available to anyone the deploy refuses.
+
 ## First commands
 
 `taproot-site --help` lists every verb and the configuration contract.
 `taproot-site help` is the offline reference family agents read before
 authoring: page types, components, navigation, media, previews, themes,
-appearance, and the footer, each with `--json` for stable machine-readable
-output.
+appearance, the footer, and the offline fixture contract, each with `--json`
+for stable machine-readable output.
 
 ```bash
 taproot-site help
@@ -50,7 +87,8 @@ taproot-site help component hero-section --json
 
 `taproot-site validate <fixture-directory>` checks a complete offline fixture
 with no credential, no network, and no write: a directory laid out like a
-pulled workspace — `pages/`, `nav.json`, and the four `settings/` documents —
+pulled workspace — `pages/`, `nav.json`, `redirects.json`, and the four
+`settings/` documents —
 whose `manifest.fixture.json` binds deterministic page, resource, image, and
 settings identities under a versioned `fixture` block. It proves structure,
 page content and theme contexts, navigation references, the complete theme,
@@ -58,6 +96,23 @@ appearance, header, brand, and footer, and fixture-local image identities. It
 does not prove authorization, site ownership, concurrency, server round trips,
 or rendering; a real pull and an authorized preview do that.
 
+The package ships one, so `validate` is runnable the moment the install
+finishes. `taproot-site help fixture` states the manifest contract and prints
+the shipped fixture's absolute path along with the exact command to validate
+it:
+
+```bash
+taproot-site help fixture
+taproot-site validate "$(npm root --global)/@taprootio/site-authoring/examples/riverbend-wellness"
+```
+
+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
+somewhere writable before you edit it; `validate` never writes to the fixture
+it reads.
+
 ## Authorize
 
 Sign in once. `login` starts a device-style authorization: it prints an
@@ -169,9 +224,12 @@ taproot-site deploy --staging
 taproot-site deploy --production
 ```
 
-`pull` snapshots pages, navigation, and settings into the workspace:
-`pages/`, `nav.json`, `settings/`, `media/`, and two dot-prefixed manifests
-that carry site binding and page identity between commands. Every page path
+`pull` snapshots pages, navigation, redirects, and settings into the
+workspace: `pages/`, `nav.json`, `redirects.json`, `settings/`, `media/`, and
+two dot-prefixed manifests that carry site binding and page identity between
+commands. Against a Taproot that does not serve the redirect map yet, `pull`
+writes no `redirects.json` and records no redirect baseline, and
+`redirects push` asks for a pull once the site has one. Every page path
 has exactly one authoritative source — `pages/<name>.md` in the documented
 Markdown subset with `title`, `path`, and `description` front matter, or
 `pages/<name>.pm.json` as a ProseMirror document — and pull never writes a
@@ -182,11 +240,18 @@ 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 push [page-path...]` validates and sends the selected pages, or every
-workspace page when none is named; the homepage is addressed as `/`.
+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
+moved since this workspace last reconciled with it, naming both revisions;
+`pull` first, or push after a refused pull has shown you the site's version.
 `media upload [path...]` uploads raster files and records component-ready
 delivery fields. `nav push`, `theme push`, and `footer push` replace the whole
 navigation tree, the complete light/dark theme pair with its appearance
-settings, and the closed footer document.
+settings, and the closed footer document. `redirects pull` writes the site's
+redirect map to `redirects.json` with a baseline, and `redirects push`
+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.
 
 `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
@@ -199,7 +264,8 @@ for another. The handoff also expires two minutes after it is minted;
 `approve [page-path...]` publishes drafts into the approved candidate pool.
 It stages; nothing reaches an audience until `deploy --staging` publishes the
 candidate and `deploy --production` promotes that completed staging
-deployment. `status` reports deployments, readiness, and image processing.
+deployment. `status` reports the platform authoring switch, the CLI release,
+deployments, readiness, and image processing.
 
 ## Output contract
 
@@ -208,11 +274,17 @@ whose approval code and URL exist only as progress). Stdout carries exactly
 one JSON object per run, schema version `1`: `ok`, the CLI name and version,
 the verb, and the verb's own result on success; a stable `error.code` with an
 optional `field`, `status`, and classified `refusal` on failure. Exit codes are
-`0` success, `1` failure, and `2` usage fault. The four refusal classes an
-automation should branch on are `platform_paused` (external authoring is
+`0` success, `1` failure, and `2` usage fault. The six refusal classes an
+automation should branch on are `cli_outdated` (this package is behind the
+latest published release, which is the only one Taproot accepts; upgrade it,
+and see "Keeping the CLI current"), `platform_paused` (external authoring is
 paused; retry later), `credential_rejected` (stop and re-issue),
-`plan_limit` (the plan's published-page allowance, surfaced at deploy), and
-`throttled` (back off).
+`capability_missing` (the credential is valid and correctly scoped but was
+not exchanged for a capability the request needs; the refusal carries
+`field: "GrantedCapabilities"`, and the CLI's human progress names the
+granted and required capabilities, so report the verb's declared set rather
+than re-issuing the key), `plan_limit` (the plan's published-page allowance,
+surfaced at deploy), and `throttled` (back off).
 
 When `GITHUB_OUTPUT` names the runner's existing output file, every
 operational verb appends the same JSON under `taproot_site_result` through a
@@ -221,6 +293,27 @@ Authorization values, signed upload headers, preview handoffs outside the
 final result, and page bodies never appear in progress, diagnostics, JSON, or
 Actions output.
 
+### Every write answers `platform_paused`
+
+`pull` and `status` succeed, and every write is refused with
+`refusal: "platform_paused"` and `field: "SiteAuthoringRollout"`. Nothing is
+wrong with the credential, the request, or the site: Taproot has external site
+authoring switched off platform-wide. A Taproot administrator turns it back on
+with the platform setting `site_authoring.external_writes_enabled`, under
+Admin → Platform settings → Site Authoring ("External site authoring writes
+enabled"); nobody else can, and no amount of retrying or re-issuing changes it.
+
+You do not have to discover this from a refusal. Each sign-in exchange reports
+the switch's state, so `status` names it as `platform.externalWritesEnabled`
+and every write verb prints one warning before it does any work when the last
+exchange said the platform was paused. The warning is advisory and never a
+gate — the switch is enforced inside each write's own transaction, so a run
+that starts while it is off still succeeds if an operator turns it on
+meanwhile. `whoami` stays offline and reports what the last exchange recorded,
+dated with that exchange; `status` is where a current answer comes from.
+`TAPROOT_SITE_KEY` runs perform no exchange, so their `status` reports
+`platform.externalWritesKnown: false` rather than guessing.
+
 ## Public release
 
 Private Taproot is the source authority. Merging a version bump to private

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

@@ -0,0 +1,79 @@
+{
+  "manifestVersion": 6,
+  "siteId": "a0000000-0000-4000-8000-000000000001",
+  "pulledAt": "2026-09-04T00:00:00.000Z",
+  "pages": [
+    {
+      "pageId": "a0000000-0000-4000-8000-000000000010",
+      "resourceId": "a0000000-0000-4000-8000-000000000011",
+      "path": "",
+      "title": "Riverbend Wellness",
+      "status": "PAGE_STATUS_DRAFT",
+      "templateType": "TEMPLATE_TYPE_FREE_FORM",
+      "hasDraft": true,
+      "isGenerated": false,
+      "description": "An example home page for the offline authoring fixture.",
+      "file": "pages/index.md",
+      "sourceFormat": "markdown",
+      "workspaceMode": "editable"
+    },
+    {
+      "pageId": "a0000000-0000-4000-8000-000000000012",
+      "resourceId": "a0000000-0000-4000-8000-000000000013",
+      "path": "visit",
+      "title": "Visit the studio",
+      "status": "PAGE_STATUS_DRAFT",
+      "templateType": "TEMPLATE_TYPE_FREE_FORM",
+      "hasDraft": true,
+      "isGenerated": false,
+      "description": "An example second page for the offline authoring fixture.",
+      "file": "pages/visit.md",
+      "sourceFormat": "markdown",
+      "workspaceMode": "editable"
+    }
+  ],
+  "pagesTruncated": false,
+  "navigation": {
+    "file": "nav.json",
+    "items": 3
+  },
+  "redirects": {
+    "file": "redirects.json",
+    "revision": "0000000000000000000000000000000000000000000000000000000000000001",
+    "entries": 4
+  },
+  "settings": [
+    {
+      "settingsType": "SETTING_TYPE_TAPROOT_STYLES",
+      "file": "settings/taproot-styles.json",
+      "entityId": "a0000000-0000-4000-8000-000000000020"
+    },
+    {
+      "settingsType": "SETTING_TYPE_BRAND",
+      "file": "settings/brand.json",
+      "entityId": "a0000000-0000-4000-8000-000000000021"
+    },
+    {
+      "settingsType": "SETTING_TYPE_SITE_HEADER",
+      "file": "settings/site-header.json",
+      "entityId": "a0000000-0000-4000-8000-000000000022"
+    },
+    {
+      "settingsType": "SETTING_TYPE_SITE_PUBLISHING_PREFERENCES",
+      "file": "settings/site-publishing-preferences.json",
+      "entityId": "a0000000-0000-4000-8000-000000000023"
+    }
+  ],
+  "settingsSkipped": [],
+  "fixture": {
+    "contractVersion": 1,
+    "imageIds": [
+      "a0000000-0000-4000-8000-0000000000a0",
+      "a0000000-0000-4000-8000-0000000000a1",
+      "a0000000-0000-4000-8000-0000000000a2"
+    ],
+    "deliveryOrigins": [
+      "https://static.example.test"
+    ]
+  }
+}

package/examples/riverbend-wellness/nav.json

@@ -0,0 +1,26 @@
+{
+  "siteId": "a0000000-0000-4000-8000-000000000001",
+  "navItems": [
+    {
+      "id": "a0000000-0000-4000-8000-000000000030",
+      "kind": "NAV_ITEM_KIND_PAGE",
+      "title": "Home",
+      "resourceId": "a0000000-0000-4000-8000-000000000011",
+      "children": []
+    },
+    {
+      "id": "a0000000-0000-4000-8000-000000000031",
+      "kind": "NAV_ITEM_KIND_PAGE",
+      "title": "Visit",
+      "resourceId": "a0000000-0000-4000-8000-000000000013",
+      "children": []
+    },
+    {
+      "id": "a0000000-0000-4000-8000-000000000032",
+      "kind": "NAV_ITEM_KIND_EXTERNAL_URL",
+      "title": "Book a class",
+      "externalUrl": "https://schedule.example.test/riverbend",
+      "children": []
+    }
+  ]
+}

package/examples/riverbend-wellness/pages/index.md

@@ -0,0 +1,93 @@
+---
+title: Riverbend Wellness
+path: ""
+description: An example home page for the offline authoring fixture.
+---
+
+```component:hero-section
+{
+  "overline": "Riverbend Wellness · Elm Harbor",
+  "title": "An example site you can validate before you have one.",
+  "titleSize": "display",
+  "lead": "Riverbend Wellness is invented. It exists so taproot-site validate has a complete workspace to check on a machine that has never pulled a real site.",
+  "primaryAction": {
+    "label": "Visit the studio",
+    "url": "/visit"
+  },
+  "secondaryAction": {
+    "label": "Book a class",
+    "url": "https://schedule.example.test/riverbend"
+  },
+  "alignment": "start",
+  "media": {
+    "imageId": "a0000000-0000-4000-8000-0000000000a2",
+    "src": "https://static.example.test/site/img/riverbend-studio-1280.webp",
+    "urls": [
+      {
+        "minWidth": 640,
+        "url": "https://static.example.test/site/img/riverbend-studio-640.webp"
+      },
+      {
+        "minWidth": 1280,
+        "url": "https://static.example.test/site/img/riverbend-studio-1280.webp"
+      }
+    ],
+    "width": 1600,
+    "height": 1067,
+    "alt": "An example photograph placeholder for the fixture studio"
+  },
+  "mediaArrangement": "split",
+  "mediaPosition": "after",
+  "mediaWidth": "equal"
+}
+```
+
+:::section {"context":"subtle","contentPadding":"standard","surface":"none"}
+## What this fixture is for
+
+Every value here is fictional. The studio, the street, the telephone number,
+and the image delivery host are all invented, and the image identities are
+declared in `manifest.fixture.json` under the `fixture` block so `validate`
+can bind them without a network.
+
+Run `taproot-site help fixture` for the manifest contract this directory
+follows, and `taproot-site help page free-form` for the document vocabulary
+these pages are written in.
+
+```inline-facts
+[
+  {
+    "value": "2 pages",
+    "label": "Free-form sources"
+  },
+  {
+    "value": "(555) 555-0147",
+    "label": "Reserved example number",
+    "url": "tel:+15555550147"
+  },
+  {
+    "value": "12 Alder Street, Elm Harbor",
+    "label": "Invented address"
+  }
+]
+```
+:::
+
+:::section {"context":"inverted","contentPadding":"standard","surface":"none"}
+## Change one thing and watch it fail
+
+The fastest way to learn the contract is to break it. Point a navigation item
+at a resource identity this fixture does not declare, or set
+`defaultScheme` to a value outside `system`, `light`, and `dark`, and
+`validate` names the file and the field it refused.
+
+```component:cta
+{
+  "heading": "Then put it back.",
+  "description": "Copy this directory somewhere writable before you edit it; validate never writes to the fixture it reads.",
+  "buttonText": "Visit the studio",
+  "buttonUrl": "/visit",
+  "variant": "primary"
+}
+```
+:::

package/examples/riverbend-wellness/pages/visit.md

@@ -0,0 +1,33 @@
+---
+title: Visit the studio
+path: visit
+description: An example second page for the offline authoring fixture.
+---
+
+:::section {"contentPadding":"standard","surface":"none"}
+## Visit the studio
+
+Riverbend Wellness is a fictional studio in the fictional town of Elm Harbor.
+Nothing on this page describes a real place, and no address, telephone number,
+or hostname here resolves to one.
+
+- **12 Alder Street, Elm Harbor** — an invented address
+- **(555) 555-0147** — from the reserved example telephone range
+- **hello@example.test** — a reserved example domain
+
+This page exists so the fixture binds more than one page identity: the
+navigation tree points at both, the footer links to both, and `validate`
+proves every reference resolves inside the fixture.
+:::
+
+:::section {"context":"raised","contentPadding":"standard","surface":"elevated"}
+## Hours
+
+| Day | Doors | Last class |
+| --- | --- | --- |
+| Monday to Friday | 6:00 AM | 7:30 PM |
+| Saturday | 7:30 AM | 4:00 PM |
+| Sunday | 8:00 AM | 2:00 PM |
+
+Every figure above is invented for the fixture.
+:::

package/examples/riverbend-wellness/redirects.json

@@ -0,0 +1,33 @@
+{
+  "siteId": "a0000000-0000-4000-8000-000000000001",
+  "revision": "0000000000000000000000000000000000000000000000000000000000000001",
+  "entries": [
+    {
+      "path": "/classes.html",
+      "kind": "redirect",
+      "target": "/visit",
+      "status": 301,
+      "origin": "authored"
+    },
+    {
+      "path": "/schedule",
+      "kind": "redirect",
+      "target": "https://booking.example.test/riverbend",
+      "status": 302,
+      "origin": "authored"
+    },
+    {
+      "path": "/summer-2019-retreat.html",
+      "kind": "gone",
+      "status": 410,
+      "origin": "authored"
+    },
+    {
+      "path": "/welcome.html",
+      "kind": "redirect",
+      "target": "/",
+      "status": 301,
+      "origin": "path_history"
+    }
+  ]
+}

package/examples/riverbend-wellness/settings/brand.json

@@ -0,0 +1,7 @@
+{
+  "entityId": "a0000000-0000-4000-8000-000000000021",
+  "settingsType": "SETTING_TYPE_BRAND",
+  "settings": {
+    "faviconId": "a0000000-0000-4000-8000-0000000000a0"
+  }
+}

package/examples/riverbend-wellness/settings/site-header.json

@@ -0,0 +1,21 @@
+{
+  "entityId": "a0000000-0000-4000-8000-000000000022",
+  "settingsType": "SETTING_TYPE_SITE_HEADER",
+  "settings": {
+    "headerLayout": "standard",
+    "headerWidth": "contained",
+    "navDrawerStyle": "full-screen",
+    "navDrawerTransition": "fade",
+    "brandText": "Riverbend Wellness",
+    "logoAlt": "Riverbend Wellness",
+    "navMenuDisplay": "auto",
+    "headerPosition": "sticky",
+    "showThemeToggle": true,
+    "showBrandText": true,
+    "brandLogoSize": "standard",
+    "brandHoverGrow": false,
+    "brandColor": "--esp-color-headings",
+    "lightBrandColor": "--esp-color-headings",
+    "darkBrandColor": "--esp-color-headings"
+  }
+}

package/examples/riverbend-wellness/settings/site-publishing-preferences.json

@@ -0,0 +1,107 @@
+{
+  "entityId": "a0000000-0000-4000-8000-000000000023",
+  "settingsType": "SETTING_TYPE_SITE_PUBLISHING_PREFERENCES",
+  "settings": {
+    "footerSettings": {
+      "enabled": true,
+      "showBrand": true,
+      "showBrandText": true,
+      "asideCta": {
+        "id": "a0000000-0000-4000-8000-000000000040",
+        "label": "Book a class",
+        "externalUrl": "https://schedule.example.test/riverbend"
+      },
+      "bottomLinks": [
+        {
+          "id": "a0000000-0000-4000-8000-000000000041",
+          "label": "Visit",
+          "pageResourceId": "a0000000-0000-4000-8000-000000000013"
+        }
+      ],
+      "light": {
+        "backgroundColor": "--esp-color-layer-1",
+        "textColor": "--esp-color-text",
+        "headingColor": "--esp-color-headings",
+        "linkColor": "--esp-color-link",
+        "linkHoverColor": "--esp-color-link-hover",
+        "backgroundImageId": "",
+        "backgroundImageOpacity": 0,
+        "backgroundPresentation": "FOOTER_BACKGROUND_PRESENTATION_COVER",
+        "backgroundFade": "FOOTER_FADE_MODE_NONE",
+        "backgroundRepeatHeightPx": 160,
+        "additionalTopPaddingRem": 1
+      },
+      "dark": {
+        "backgroundColor": "--esp-color-layer-1",
+        "textColor": "--esp-color-text",
+        "headingColor": "--esp-color-headings",
+        "linkColor": "--esp-color-link",
+        "linkHoverColor": "--esp-color-link-hover",
+        "backgroundImageId": "",
+        "backgroundImageOpacity": 0,
+        "backgroundPresentation": "FOOTER_BACKGROUND_PRESENTATION_COVER",
+        "backgroundFade": "FOOTER_FADE_MODE_NONE",
+        "backgroundRepeatHeightPx": 160,
+        "additionalTopPaddingRem": 1
+      },
+      "linkColumns": [
+        {
+          "id": "a0000000-0000-4000-8000-000000000042",
+          "groups": [
+            {
+              "id": "a0000000-0000-4000-8000-000000000043",
+              "heading": "Studio",
+              "links": [
+                {
+                  "id": "a0000000-0000-4000-8000-000000000044",
+                  "label": "Home",
+                  "pageResourceId": "a0000000-0000-4000-8000-000000000011"
+                },
+                {
+                  "id": "a0000000-0000-4000-8000-000000000045",
+                  "label": "Visit",
+                  "pageResourceId": "a0000000-0000-4000-8000-000000000013"
+                }
+              ]
+            }
+          ]
+        }
+      ],
+      "asideHeadingContent": {
+        "paragraphs": [
+          {
+            "runs": [
+              {
+                "text": "Everything here is invented.",
+                "bold": true
+              }
+            ]
+          }
+        ]
+      },
+      "asideBodyContent": {
+        "paragraphs": [
+          {
+            "runs": [
+              {
+                "text": "Riverbend Wellness is a fictional studio used to demonstrate the authoring contract offline."
+              }
+            ]
+          }
+        ]
+      },
+      "bottomContent": {
+        "paragraphs": [
+          {
+            "runs": [
+              {
+                "text": "An example fixture. Not a real business."
+              }
+            ]
+          }
+        ]
+      },
+      "featureImage": null
+    }
+  }
+}