@taprootio/site-authoring 0.8.5 → 0.8.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "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

@@ -103,6 +103,15 @@ export const DEPLOYMENT_STATUSES = Object.freeze([
   DEPLOYMENT_STATUS_FAILED,
 ]);
 
+// DeploySite's admission outcome (TR00839): whether this request created the
+// deployment or coalesced into an already-anchored one.
+export const DEPLOYMENT_REQUEST_OUTCOME_ACCEPTED = "DEPLOYMENT_REQUEST_OUTCOME_ACCEPTED";
+export const DEPLOYMENT_REQUEST_OUTCOME_COALESCED = "DEPLOYMENT_REQUEST_OUTCOME_COALESCED";
+export const DEPLOYMENT_REQUEST_OUTCOMES = Object.freeze([
+  DEPLOYMENT_REQUEST_OUTCOME_ACCEPTED,
+  DEPLOYMENT_REQUEST_OUTCOME_COALESCED,
+]);
+
 export const IMAGE_PROCESSING_STATE_UNKNOWN = "IMAGE_PROCESSING_STATE_UNKNOWN";
 export const IMAGE_PROCESSING_STATE_COMPLETE = "IMAGE_PROCESSING_STATE_COMPLETE";
 export const IMAGE_PROCESSING_STATE_FAILED = "IMAGE_PROCESSING_STATE_FAILED";
@@ -351,7 +360,11 @@ const REFUSAL_GUIDANCE = Object.freeze({
   [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.",
-  [REFUSAL_THROTTLED]: "This credential exceeded its request budget. Back off and retry with delay.",
+  // Covers both the per-key request-budget throttle and the durable
+  // per-site/per-account deployment request limit (TR00839): both surface as
+  // gRPC ResourceExhausted / HTTP 429, and the remedy is identical either way.
+  [REFUSAL_THROTTLED]:
+    "Too many deployment requests for this site or account. Back off and retry after the delay the server reported.",
 });
 
 /**
@@ -436,6 +449,12 @@ export function announceRefusal(error, onProgress, action = "request") {
   }
   const guidance = REFUSAL_GUIDANCE[kind];
   if (guidance) onProgress(guidance);
+  // The retry-after trailer (TR00839) is the exact delay the server measured;
+  // surface it when the transport captured it rather than leaving the agent
+  // to guess a backoff.
+  if (kind === REFUSAL_THROTTLED && typeof error.retryAfterSeconds === "number") {
+    onProgress(`  Retry after: ${error.retryAfterSeconds}s.`);
+  }
 }
 
 /**
@@ -1017,6 +1036,9 @@ export function normalizeDeployment(value) {
     errorMessage: text(deployment.errorMessage),
     pageCount: safeCount(deployment.pageCount),
     phaseTimings: normalizePhaseTimings(deployment.phaseHistory),
+    // Identical requests coalesced into this deployment inside its settling
+    // window (TR00839). Zero for a deployment that never anchored one.
+    coalescedRequestCount: safeCount(deployment.coalescedRequestCount),
   };
 }
 
@@ -1074,7 +1096,19 @@ export async function deploySite(client, siteId, body) {
     }
     throw error;
   }
-  return normalizeDeployment(response.deployment);
+  const deployment = normalizeDeployment(response.deployment);
+  // `DEPLOYMENT_REQUEST_OUTCOME_ACCEPTED` is the zero-adjacent default: an
+  // older server that omits the field, or the immutable Standard/Docs
+  // branches that never run through the admission seam, both read as this
+  // request creating its own deployment (TR00839).
+  const outcome = enumValue(
+    response.outcome,
+    DEPLOYMENT_REQUEST_OUTCOMES,
+    DEPLOYMENT_REQUEST_OUTCOME_ACCEPTED,
+    "api.deployment_contract",
+    "deployment request outcome",
+  );
+  return { ...deployment, outcome };
 }
 
 /**

package/src/constants.js

@@ -1,5 +1,5 @@
 export const CLI_NAME = "@taprootio/site-authoring";
-export const CLI_VERSION = "0.8.5";
+export const CLI_VERSION = "0.8.6";
 export const CLI_BINARY_NAME = "taproot-site";
 export const RESULT_SCHEMA_VERSION = 1;
 export const CONFIG_FILE_NAME = "taproot-site.json";

package/src/transport.js

@@ -396,8 +396,21 @@ export function capabilityRefusal(value) {
   return undefined;
 }
 
+/**
+ * Reads the `retry-after` response header as a non-negative integer number of
+ * seconds. `headers` is a Fetch `Headers` instance when available; anything
+ * else, a missing header, or a value that does not parse as a non-negative
+ * number, returns undefined rather than throwing.
+ */
+function parseRetryAfterHeader(headers) {
+  const raw = typeof headers?.get === "function" ? headers.get("retry-after") : undefined;
+  if (typeof raw !== "string" || raw.length === 0) return undefined;
+  const seconds = Number(raw);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;
+}
+
 export class ApiError extends SiteAuthoringError {
-  constructor(httpStatus, body) {
+  constructor(httpStatus, body, headers) {
     const grpcCode = Number.isSafeInteger(body?.code) ? body.code : undefined;
     const fields = fieldViolations(body);
     const capability = capabilityRefusal(body);
@@ -433,6 +446,11 @@ export class ApiError extends SiteAuthoringError {
     this.fields = fields;
     this.violationDescriptions = fieldDescriptions(body);
     this.capability = capability;
+    // The `retry-after` trailer (TR00839's deployment throttle, or any other
+    // ResourceExhausted refusal that sets it) transcodes to an ordinary
+    // response header. Undefined when absent or unparseable — callers must
+    // not assume every throttle carries a delay.
+    this.retryAfterSeconds = parseRetryAfterHeader(headers);
   }
 
   hasField(field) {
@@ -767,7 +785,7 @@ export class SiteApiClient {
         responseBody = Object.create(null);
       }
       if (remainingBudget(deadline, now) <= 0) throw deadlineError();
-      throw new ApiError(response.status, responseBody);
+      throw new ApiError(response.status, responseBody, response.headers);
     }
     throw new SiteAuthoringError("transport.retry_exhausted", "The Taproot API request exhausted its retry budget.");
   }

package/src/verbs/deploy.js

@@ -1,6 +1,7 @@
 import {
   DEPLOYMENT_ENVIRONMENT_PRODUCTION,
   DEPLOYMENT_ENVIRONMENT_STAGING,
+  DEPLOYMENT_REQUEST_OUTCOME_COALESCED,
   DEPLOYMENT_STATUS_COMPLETED,
   deploySite,
   getDeploySelection,
@@ -80,6 +81,16 @@ function usageError(code, message, field) {
   return new SiteAuthoringError(code, message, { field, exitCode: 2 });
 }
 
+/**
+ * One line when this request coalesced into an already in-flight or recently
+ * anchored identical deployment (TR00839), instead of creating a new one.
+ */
+function announceOutcome(created, onProgress) {
+  if (created.outcome === DEPLOYMENT_REQUEST_OUTCOME_COALESCED) {
+    onProgress(`An identical deployment request is already in progress; reusing deployment ${created.id}.`);
+  }
+}
+
 function explicitSelection(invocation) {
   const stagedPageIds = Array.isArray(invocation.stagedPageIds) ? invocation.stagedPageIds : undefined;
   const selectedSettingsTypes = Array.isArray(invocation.selectedSettingsTypes)
@@ -268,6 +279,7 @@ export async function deploy(invocation) {
         ...(invocation.allowFailedPreview === true ? { allowFailedPreview: true } : {}),
       });
       onProgress(`Production deployment ${created.id} accepted; waiting for it to complete.`);
+      announceOutcome(created, onProgress);
       const completed = await waitForDeployment(client, {
         siteId,
         deploymentId: created.id,
@@ -283,6 +295,7 @@ export async function deploy(invocation) {
         ...(presentationOnly ? { authoringSurface: SURFACE_DOCS_PRESENTATION } : {}),
         promotedStagingDeploymentId: stagingDeploymentId,
         deployment: completed,
+        outcome: created.outcome,
         readiness: reportReadiness(readiness),
       });
     }
@@ -357,6 +370,7 @@ export async function deploy(invocation) {
       ...(invocation.allowFailedPreview === true ? { allowFailedPreview: true } : {}),
     });
     onProgress(`Staging deployment ${created.id} accepted; waiting for it to complete.`);
+    announceOutcome(created, onProgress);
     const completed = await waitForDeployment(client, {
       siteId,
       deploymentId: created.id,
@@ -377,6 +391,7 @@ export async function deploy(invocation) {
           includeNavigation: false,
         },
         deployment: completed,
+        outcome: created.outcome,
         readiness: reportReadiness(readiness),
         stagingPreview,
         nextStep: stagingPreview.url === "" ? "staging review" : "deploy --production",
@@ -393,6 +408,7 @@ export async function deploy(invocation) {
         includeNavigation,
       },
       deployment: completed,
+      outcome: created.outcome,
       readiness: reportReadiness(readiness),
       stagingPreview,
       nextStep: stagingPreview.redirects?.verified === true ? "deploy --production" : "redirects check",