@taprootio/site-authoring 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.2.0",
+  "version": "0.4.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",
@@ -22,6 +22,7 @@
   },
   "files": [
     "bin/",
+    "examples/",
     "src/",
     "LICENSE",
     "README.md"

package/src/api.js

@@ -1,18 +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.
@@ -307,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.",
@@ -329,6 +360,53 @@ 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("");
+    onProgress(`CAPABILITY MISSING (refusal=${REFUSAL_CAPABILITY_MISSING}, field=${CAPABILITY_REFUSAL_FIELD})`);
+    onProgress(
+      `  Taproot refused this ${action} because the credential it runs on was not exchanged for a capability `
+        + `that grants '${permission}'.`,
+    );
+    onProgress(`  Granted: ${granted.length > 0 ? granted.join(", ") : "(none)"}.`);
+    onProgress(
+      required.length > 0
+        ? `  Carried by: ${required.join(", ")}.`
+        : "  Carried by: no site-authoring capability — this permission is not reachable by any credential.",
+    );
+    // The credential is exactly what was asked for, so re-issuing it changes
+    // nothing. What is wrong is the verb's declared capability set, and saying
+    // so is the whole point of the named refusal: the first agent to meet this
+    // had to read the package source to find out.
+    onProgress(
+      `  The credential is not the problem: the exchange minted precisely what the ${action} asked for. `
+        + "The verb's declared capability set in the CLI's verb table is short of the requests it makes; "
+        + "report it rather than minting a wider key.",
+    );
+    onProgress("");
+    return;
+  }
   if (kind === REFUSAL_PLAN_LIMIT) {
     onProgress("");
     onProgress("PLAN LIMIT (refusal=plan_limit, field=UpgradePrompt)");
@@ -379,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),
   };
 }
 
@@ -473,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
@@ -1298,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",
   );
@@ -1376,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",
@@ -1403,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 },
+  );
+}