@taprootio/site-authoring 0.3.0 → 0.5.0

package/README.md

@@ -34,6 +34,43 @@ 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.
@@ -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,
@@ -186,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
@@ -199,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
@@ -216,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
 
@@ -225,8 +274,10 @@ 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 five 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),
 `capability_missing` (the credential is valid and correctly scoped but was
 not exchanged for a capability the request needs; the refusal carries
@@ -242,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

@@ -1,5 +1,5 @@
 {
-  "manifestVersion": 5,
+  "manifestVersion": 6,
   "siteId": "a0000000-0000-4000-8000-000000000001",
   "pulledAt": "2026-09-04T00:00:00.000Z",
   "pages": [
@@ -37,6 +37,11 @@
     "file": "nav.json",
     "items": 3
   },
+  "redirects": {
+    "file": "redirects.json",
+    "revision": "0000000000000000000000000000000000000000000000000000000000000001",
+    "entries": 4
+  },
   "settings": [
     {
       "settingsType": "SETTING_TYPE_TAPROOT_STYLES",

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/package.json

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

package/src/api.js

@@ -1,20 +1,48 @@
 import {
   CANONICAL_TIMESTAMP,
   CAPABILITY_REFUSAL_FIELD,
+  CLI_UPGRADE_COMMAND,
+  CLI_UPGRADE_REFUSAL_FIELD,
+  CLI_VERSION,
+  EXTERNAL_WRITES_SETTING_KEY,
+  EXTERNAL_WRITES_SETTING_LOCATION,
   LIMITS,
   REFUSAL_CAPABILITY_MISSING,
+  REFUSAL_CLI_OUTDATED,
   REFUSAL_CREDENTIAL_REJECTED,
   REFUSAL_PLAN_LIMIT,
   REFUSAL_PLATFORM_PAUSED,
   REFUSAL_THROTTLED,
   REFUSAL_UNCLASSIFIED,
 } from "./constants.js";
+import { normalizeLatestCliVersion } from "./cli-release.js";
 // The display-prefix shape lives with the store because acceptance on claim
 // must equal acceptance on save — a prefix admitted here but refused there
 // would turn a successful mint into an orphaned key.
 import { KEY_PREFIX } from "./credentials.js";
 import { isCanonicalUuid, sanitizeDiagnostic, SiteAuthoringError } from "./errors.js";
+import {
+  DEFAULT_REDIRECT_STATUS,
+  GONE_STATUS,
+  REDIRECT_KIND_GONE,
+  REDIRECT_KIND_REDIRECT,
+  REDIRECT_ORIGIN_AUTHORED,
+  REDIRECT_ORIGIN_PATH_HISTORY,
+} from "./redirects-contract.js";
 import { ApiError, isWellFormedCredential } from "./transport.js";
+// The revision's shape lives with the manifest that records it: a value this
+// module admitted but the registry then dropped would be recorded on a push
+// and unreadable on the next pull, which reads as "never reconciled" forever.
+import { normalizePageBodyRevision } from "./workspace.js";
+
+/**
+ * The proto enum spellings the redirect map travels as. The CLI's own
+ * vocabulary is the lowercase word the workspace file uses; these are the wire
+ * identities it is translated from, kept beside the translation.
+ */
+const REDIRECT_KIND_REDIRECT_WIRE = "SITE_REDIRECT_KIND_REDIRECT";
+const REDIRECT_KIND_GONE_WIRE = "SITE_REDIRECT_KIND_GONE";
+const REDIRECT_ORIGIN_AUTHORED_WIRE = "SITE_REDIRECT_ORIGIN_AUTHORED";
 
 /**
  * The wire vocabulary and the read helpers every verb shares.
@@ -309,7 +337,8 @@ export function sitePath(siteId, suffix) {
 const REFUSAL_GUIDANCE = Object.freeze({
   [REFUSAL_PLATFORM_PAUSED]:
     "Taproot has paused external site authoring platform-wide. The credential and the request are both fine; "
-    + "retry later or ask the operator.",
+    + "retry later, or ask a Taproot administrator to re-enable the platform setting "
+    + `'${EXTERNAL_WRITES_SETTING_KEY}' (${EXTERNAL_WRITES_SETTING_LOCATION}).`,
   [REFUSAL_CREDENTIAL_REJECTED]:
     "The site authoring credential was rejected: it is invalid, revoked, or bound to a different site. "
     + "Stop and re-issue it; retrying cannot succeed.",
@@ -331,6 +360,27 @@ const REFUSAL_GUIDANCE = Object.freeze({
 export function announceRefusal(error, onProgress, action = "request") {
   if (!(error instanceof ApiError)) return;
   const kind = error.refusalKind();
+  if (kind === REFUSAL_CLI_OUTDATED) {
+    onProgress("");
+    onProgress(`CLI UPGRADE REQUIRED (refusal=${REFUSAL_CLI_OUTDATED}, field=${CLI_UPGRADE_REFUSAL_FIELD})`);
+    onProgress(
+      `  Taproot supports only the latest published release of this package, and refused this ${action} because `
+        + `this CLI (${CLI_VERSION}) is behind it. Nothing about the credential, the request, or the site is wrong, `
+        + "and no retry of this version can succeed.",
+    );
+    onProgress(`  Upgrade with: ${CLI_UPGRADE_COMMAND}`);
+    // The server names both versions and says when waiting is the right move
+    // (a deploy that landed ahead of its npm publish). Surface it verbatim
+    // rather than restating a policy this side does not own; the bounded
+    // ApiError message stays the fallback for a server that sent no
+    // description.
+    const serverDescription = error.descriptionFor?.(CLI_UPGRADE_REFUSAL_FIELD);
+    onProgress(`  Taproot's own detail: ${
+      sanitizeDiagnostic(serverDescription ?? error.message, "the request was rejected.")
+    }`);
+    onProgress("");
+    return;
+  }
   if (kind === REFUSAL_CAPABILITY_MISSING) {
     const { permission, granted, required } = error.capability;
     onProgress("");
@@ -407,6 +457,12 @@ export function normalizePageSummary(value) {
     status: enumValue(summary.status, PAGE_STATUSES, PAGE_STATUS_UNKNOWN, "api.page_status", "page status"),
     hasDraft: summary.hasDraft === true,
     isGenerated: summary.isGenerated === true,
+    // Absent against a Taproot that predates the revision contract, and absent
+    // on the listings that never resolve stored body state. Both mean the same
+    // thing to a caller — "this read cannot say what version you are looking
+    // 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),
   };
 }
 
@@ -501,6 +557,98 @@ export async function saveNavigation(client, siteId, navItems) {
   return Array.isArray(response.navItems) ? response.navItems : [];
 }
 
+/**
+ * Reads the site's whole redirect map with the revision a replace must carry
+ * (TR00702).
+ */
+export async function getSiteRedirectMap(client, siteId) {
+  return requireRedirectMap(
+    await client.request(sitePath(siteId, "redirects"), {
+      maximumResponseBytes: LIMITS.redirectMapResponseBytes,
+    }),
+    siteId,
+  );
+}
+
+/**
+ * Replaces the whole map. `expectedRevision` is the revision the map was read
+ * at; the site refuses the write rather than dropping an entry a rename
+ * recorded since.
+ */
+export async function replaceSiteRedirectMap(client, siteId, expectedRevision, entries) {
+  return requireRedirectMap(
+    await client.request(sitePath(siteId, "redirects"), {
+      method: "PUT",
+      body: { siteId, expectedRevision, entries: entries.map(toWireRedirectEntry) },
+      // The reply is the whole replaced map, as large as the read.
+      maximumResponseBytes: LIMITS.redirectMapResponseBytes,
+    }),
+    siteId,
+  );
+}
+
+/**
+ * The wire shape of one entry. `origin` is deliberately not sent: it is what
+ * the site decided about a stored row, and echoing a pulled value back would
+ * be asking to relabel a rename-recorded entry as one this workspace authored.
+ */
+function toWireRedirectEntry(entry) {
+  return entry.kind === REDIRECT_KIND_GONE
+    ? { path: entry.path, kind: REDIRECT_KIND_GONE_WIRE, status: GONE_STATUS }
+    : {
+      path: entry.path,
+      kind: REDIRECT_KIND_REDIRECT_WIRE,
+      target: entry.target,
+      status: entry.status,
+    };
+}
+
+function requireRedirectMap(value, siteId) {
+  const response = requireObject(value, "api.redirects_contract", "site redirects");
+  if (typeof response.revision !== "string" || response.revision === "") {
+    throw new SiteAuthoringError(
+      "api.redirects_contract",
+      "Taproot returned a redirect map with no revision, so a later push could not be fenced against it.",
+      { field: "revision" },
+    );
+  }
+  if (typeof response.siteId === "string" && response.siteId !== "" && response.siteId !== siteId) {
+    throw new SiteAuthoringError(
+      "api.redirects_contract",
+      "Taproot returned a redirect map for a different site.",
+      { field: "siteId" },
+    );
+  }
+  const entries = Array.isArray(response.entries) ? response.entries : [];
+  return {
+    revision: response.revision,
+    entries: entries.map((entry) => normalizeRedirectMapEntry(entry)),
+  };
+}
+
+/**
+ * Reads one entry off the wire. Transcoding omits proto default values, so an
+ * absent `kind`, `status`, or `origin` is the enum's zero — which the contract
+ * reads as a redirect, the default status, and path history respectively.
+ */
+function normalizeRedirectMapEntry(entry) {
+  const source = requireObject(entry, "api.redirects_contract", "site redirect entry");
+  const kind = source.kind === REDIRECT_KIND_GONE_WIRE ? REDIRECT_KIND_GONE : REDIRECT_KIND_REDIRECT;
+  return {
+    path: typeof source.path === "string" ? source.path : "",
+    kind,
+    target: kind === REDIRECT_KIND_GONE || typeof source.target !== "string" ? "" : source.target,
+    status: Number.isSafeInteger(source.status) && source.status > 0
+      ? source.status
+      : kind === REDIRECT_KIND_GONE
+      ? GONE_STATUS
+      : DEFAULT_REDIRECT_STATUS,
+    origin: source.origin === REDIRECT_ORIGIN_AUTHORED_WIRE
+      ? REDIRECT_ORIGIN_AUTHORED
+      : REDIRECT_ORIGIN_PATH_HISTORY,
+  };
+}
+
 /**
  * Reads one *draft* settings group for the site. Same rule as navigation:
  * `GetSettings` calls `RequireEnvironment`, so the zero value is refused rather
@@ -1326,7 +1474,14 @@ export async function startCliAuthorization(client, { keyName }, requestOptions
   const response = requireObject(
     // No site: TR00645 made the account-level sign-in the front door, so the
     // CLI no longer has to know a site id before it can authorize at all.
-    await client.request(CLI_AUTHORIZATION_PATH, { ...requestOptions, method: "POST", body: { keyName } }),
+    // `cliVersion` is sent on both calls every online verb passes through
+    // (TR00703). Sign-in is the earlier of the two, so an outdated CLI is told
+    // to upgrade before an owner is asked to approve anything.
+    await client.request(CLI_AUTHORIZATION_PATH, {
+      ...requestOptions,
+      method: "POST",
+      body: { keyName, cliVersion: CLI_VERSION },
+    }),
     "login.start_contract",
     "CLI authorization",
   );
@@ -1404,7 +1559,7 @@ export async function exchangeSiteAuthoringToken(client, { siteId, capabilities
     await client.request(TOKEN_EXCHANGE_PATH, {
       ...requestOptions,
       method: "POST",
-      body: { siteId, capabilities },
+      body: { siteId, capabilities, cliVersion: CLI_VERSION },
     }),
     "exchange.contract",
     "token exchange",
@@ -1431,6 +1586,23 @@ export async function exchangeSiteAuthoringToken(client, { siteId, capabilities
     ...(typeof response.signInExpiresAt === "string" && response.signInExpiresAt.length > 0
       ? { signInExpiresAt: requireCanonicalTimestamp(response.signInExpiresAt, "exchange.contract", "signInExpiresAt").value }
       : {}),
+    // Whether the platform is accepting external authoring writes at all
+    // (TR00692). Read strictly: only a real boolean is a state, so a server
+    // that predates the field leaves this undefined rather than reading as
+    // paused and warning before every write against a healthy platform.
+    ...(typeof response.externalWritesEnabled === "boolean"
+      ? { externalWritesEnabled: response.externalWritesEnabled }
+      : {}),
+    // The latest published release Taproot accepts (TR00703). This exchange
+    // already succeeded, so it is never news about *this* request — it is what
+    // lets the offline verbs refuse later. Read strictly for the same reason
+    // the switch above is: only a value this side can compare is kept, so a
+    // server that predates the field, or one that answers something
+    // unparseable, leaves the local gate silent rather than refusing work it
+    // cannot justify.
+    ...(normalizeLatestCliVersion(response.latestCliVersion) === undefined
+      ? {}
+      : { latestCliVersion: response.latestCliVersion }),
   };
 }
 

package/src/cli-release.js

@@ -0,0 +1,152 @@
+import {
+  CLI_UPGRADE_COMMAND,
+  CLI_UPGRADE_REFUSAL_FIELD,
+  CLI_VERSION,
+  REFUSAL_CLI_OUTDATED,
+} from "./constants.js";
+import { SiteAuthoringError } from "./errors.js";
+
+/**
+ * Whether this CLI is still the release Taproot accepts (TR00703).
+ *
+ * **The server is the authority, and this is its mirror.** Taproot refuses a
+ * CLI that is behind the latest published release at sign-in and at token
+ * exchange, so every online verb already gets a definitive answer without any
+ * of this. What this file is for is the case where there is no request to be
+ * refused: `help`, `validate`, and `whoami` run entirely offline, and an agent
+ * that keeps authoring against a contract that has moved will happily spend a
+ * whole session validating documents the site can no longer accept.
+ *
+ * So the exchange returns the latest version, the CLI records it beside the
+ * sign-in, and the offline verbs refuse against that recording. A recording is
+ * weaker evidence than a refusal, and the rules here follow from that: nothing
+ * recorded means proceed (a clean machine can still validate a fixture), an
+ * unreadable or malformed recording means proceed, and only a value this side
+ * can actually parse and compare is allowed to stop anything.
+ */
+
+// Exactly the shape `release/trunk/public-repo/scripts/npm-release-guard.mjs`
+// admits to npm, and exactly the shape the API's `SiteAuthoringCliRelease`
+// parses: three numeric components with no leading zeroes, plus optional
+// dot-separated prerelease identifiers. Build metadata is deliberately absent —
+// no version this project publishes carries any.
+const SEMANTIC_VERSION =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/u;
+
+// A version string is a handful of characters. Anything longer is not one, and
+// bounding it before the regex keeps a hostile response from spending time here.
+const MAXIMUM_VERSION_LENGTH = 64;
+
+const NUMERIC_IDENTIFIER = /^\d+$/u;
+
+/**
+ * Parses a version into what precedence needs, or returns `undefined`. A
+ * leading zero on a numeric prerelease identifier is invalid, exactly as the
+ * release guard treats it.
+ */
+export function parseCliVersion(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > MAXIMUM_VERSION_LENGTH) {
+    return undefined;
+  }
+  const match = SEMANTIC_VERSION.exec(value);
+  if (!match) return undefined;
+  const prerelease = match[4] === undefined ? [] : match[4].split(".");
+  if (prerelease.some((part) => NUMERIC_IDENTIFIER.test(part) && part.length > 1 && part.startsWith("0"))) {
+    return undefined;
+  }
+  return { core: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease };
+}
+
+function comparePrereleaseIdentifier(left, right) {
+  if (left === right) return 0;
+  const leftNumeric = NUMERIC_IDENTIFIER.test(left);
+  const rightNumeric = NUMERIC_IDENTIFIER.test(right);
+  if (leftNumeric && rightNumeric) {
+    // Digit-only with no leading zero, so length then lexicographic order is
+    // numeric order at any magnitude — the same rule the API applies, where a
+    // fixed-width parse would lose precision or overflow.
+    if (left.length !== right.length) return left.length < right.length ? -1 : 1;
+    return left < right ? -1 : 1;
+  }
+  // A numeric identifier always has lower precedence than an alphanumeric one.
+  if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+  return left < right ? -1 : 1;
+}
+
+/**
+ * Semantic-version precedence, or `undefined` when either side is unparseable.
+ * Not string order: `0.10.0` is above `0.9.0`, and a prerelease is below the
+ * release it leads to, so `0.4.0-rc.1` is behind `0.4.0`.
+ */
+export function compareCliVersions(leftVersion, rightVersion) {
+  const left = parseCliVersion(leftVersion);
+  const right = parseCliVersion(rightVersion);
+  if (left === undefined || right === undefined) return undefined;
+  for (let index = 0; index < left.core.length; index += 1) {
+    if (left.core[index] !== right.core[index]) return left.core[index] < right.core[index] ? -1 : 1;
+  }
+  if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+    if (left.prerelease.length === right.prerelease.length) return 0;
+    return left.prerelease.length === 0 ? 1 : -1;
+  }
+  const shared = Math.min(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < shared; index += 1) {
+    const comparison = comparePrereleaseIdentifier(left.prerelease[index], right.prerelease[index]);
+    if (comparison !== 0) return comparison;
+  }
+  if (left.prerelease.length === right.prerelease.length) return 0;
+  return left.prerelease.length < right.prerelease.length ? -1 : 1;
+}
+
+/**
+ * A latest-version value from the wire, kept only if this side can compare it.
+ *
+ * Read strictly and dropped silently on anything else. The value drives an
+ * advisory local gate, so a server that predates the field, or one that sends
+ * something this parser does not understand, must leave the CLI working rather
+ * than refusing offline work it cannot justify.
+ */
+export function normalizeLatestCliVersion(value) {
+  return parseCliVersion(value) === undefined ? undefined : value;
+}
+
+/**
+ * Whether {@link CLI_VERSION} is strictly behind a recorded latest. Anything
+ * unparseable on either side is not behind: an answer this side cannot compute
+ * is not evidence.
+ */
+export function isBehindLatest(latestVersion, currentVersion = CLI_VERSION) {
+  const comparison = compareCliVersions(currentVersion, latestVersion);
+  return comparison !== undefined && comparison < 0;
+}
+
+/**
+ * The offline refusal.
+ *
+ * It classifies as `cli_outdated` and carries the server's own field name
+ * rather than CLI-local labels, because an agent branching on `refusal` or
+ * `field` should not have to know whether the answer came from Taproot or from
+ * the recording of Taproot's last answer — the remedy is identical. The `code`
+ * is what says it was raised here: `cli.outdated` rather than
+ * `api.request_rejected`.
+ */
+class CliOutdatedError extends SiteAuthoringError {
+  refusalKind() {
+    return REFUSAL_CLI_OUTDATED;
+  }
+}
+
+/**
+ * The offline refusal, worded to match what the server says on the wire so an
+ * operator meeting it either way reads the same instruction.
+ */
+export function cliOutdatedError(latestVersion) {
+  return new CliOutdatedError(
+    "cli.outdated",
+    `This CLI is version ${CLI_VERSION}, and the last Taproot sign-in exchange reported ${latestVersion} as the `
+      + "latest published release. Taproot accepts only the latest, so every online verb is refused until this "
+      + `package is upgraded. Upgrade with: ${CLI_UPGRADE_COMMAND}. If ${latestVersion} was published in the last `
+      + "few minutes, npm may not serve it yet — wait a moment and retry the upgrade.",
+    { field: CLI_UPGRADE_REFUSAL_FIELD },
+  );
+}