@taprootio/site-authoring 0.12.1 → 0.12.3

package/README.md

@@ -400,7 +400,11 @@ site.
 ## Output contract
 
 Human progress goes to stderr and `--quiet` silences it (except for `login`,
-whose approval code and URL exist only as progress). Stdout carries exactly
+whose approval code and URL exist only as progress). While a deployment is
+awaited, a terminal shows one in-place line (spinner, phase, elapsed time) that
+starts a new line only when the phase changes; a pipe or CI log never receives
+control characters, only one line per phase change plus a heartbeat at most
+every 60 seconds. 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

package/package.json

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

@@ -1207,7 +1207,7 @@ export async function poll({
     // poll runs every few seconds for up to fifteen minutes, and a line per
     // tick scrolls the one thing the operator still needs — the code — off the
     // top of the terminal.
-    if (result.progress !== undefined) onProgress(result.progress);
+    if (result.progress !== undefined) onProgress(result.progress, result.event);
     if (now() >= deadline) break;
     await client.sleep(Math.min(intervalMilliseconds, Math.max(1, deadline - now())), client.signal);
   }
@@ -1220,8 +1220,20 @@ export async function poll({
 }
 
 export async function waitForDeployment(client, { siteId, deploymentId, environment, onProgress, now }) {
+  try {
+    return await awaitDeployment(client, { siteId, deploymentId, environment, onProgress, now });
+  } finally {
+    // The wait is over whether the deployment finished or failed; the verb's later
+    // output (staging checks, the failure text) must not sit beside a spinner.
+    onProgress?.endWait?.();
+  }
+}
+
+async function awaitDeployment(client, { siteId, deploymentId, environment, onProgress, now }) {
   let misses = 0;
   let lastEvidence;
+  let truncatedReported = false;
+  const reportedPhases = new Set();
   return await poll({
     client,
     now,
@@ -1248,6 +1260,11 @@ export async function waitForDeployment(client, { siteId, deploymentId, environm
         lastEvidence = evidence;
         if (deployment.phaseTimings.known) {
           for (const phase of deployment.phaseTimings.phases) {
+            // Each phase is reported when it is entered and again when it ends,
+            // never re-listed on every later change.
+            const key = `${phase.status}|${phase.enteredAt}|${phase.durationMilliseconds ?? ""}`;
+            if (reportedPhases.has(key)) continue;
+            reportedPhases.add(key);
             onProgress(
               `Deployment phase ${phase.status} entered ${phase.enteredAt}`
                 + (phase.durationMilliseconds === undefined
@@ -1255,7 +1272,8 @@ export async function waitForDeployment(client, { siteId, deploymentId, environm
                   : `; ${phase.durationMilliseconds}ms until ${phase.endedAt}.`),
             );
           }
-          if (deployment.phaseTimings.truncated) {
+          if (deployment.phaseTimings.truncated && !truncatedReported) {
+            truncatedReported = true;
             onProgress("Earlier deployment phase evidence was truncated by the server.");
           }
         } else onProgress("Deployment phase timings are unknown for this legacy deployment.");
@@ -1270,7 +1288,11 @@ export async function waitForDeployment(client, { siteId, deploymentId, environm
           { status: deployment.status },
         );
       }
-      return { done: false, progress: `Waiting for the deployment (${deployment.status}).` };
+      // The phase a reader sees is the latest one the server recorded, or the
+      // deployment's own status when it recorded none.
+      const phases = deployment.phaseTimings.known ? deployment.phaseTimings.phases : [];
+      const phase = phases.length > 0 ? phases[phases.length - 1].status : deployment.status;
+      return { done: false, progress: `Waiting for the deployment (${phase}).`, event: { phase } };
     },
     timeoutCode: "deploy.timeout",
   });

package/src/cli.js

@@ -47,6 +47,7 @@ import {
   SiteAuthoringError,
 } from "./errors.js";
 import { failureResult, humanFailure, serializeResult, writeGithubActionsOutput } from "./output.js";
+import { createProgressReporter } from "./progress.js";
 import {
   formatReferenceResult,
   getAppearanceReference,
@@ -1134,6 +1135,7 @@ export async function runCli({
   signal,
 } = {}) {
   let parsed;
+  let progress;
   let completedPreviewRecovery;
   const isReferenceInvocation = Array.isArray(arguments_)
     && (
@@ -1178,6 +1180,11 @@ export async function runCli({
     if (typeof handler !== "function") {
       throw usageError("cli.unsupported_verb", `No handler is registered for '${parsed.verb}'.`);
     }
+    progress = createProgressReporter({
+      stream: stderr,
+      interactive: stderr.isTTY === true && environment.TERM !== "dumb",
+      quiet: parsed.quiet,
+    });
     const result = await handler(Object.freeze({
       verb: parsed.verb,
       cwd,
@@ -1202,13 +1209,17 @@ export async function runCli({
             : parsed.positionals.values,
         }
         : {}),
-      onProgress: parsed.quiet ? () => {} : (message) => stderr.write(`${message}\n`),
+      // `endWait` lets a wait say it is over while the verb goes on (staging checks).
+      onProgress: Object.assign((message, event) => progress.report(message, event), {
+        endWait: () => progress.endWait(),
+      }),
       fetch,
       signal,
     }));
     if (parsed.verb === VERB_PREVIEW_PAGE && result?.ok === true) {
       completedPreviewRecovery = normalizePreviewRecovery(result);
     }
+    progress.stop();
     const json = serializeResult(result);
     if (!isValidationInvocation && environment.GITHUB_OUTPUT) {
       await writeGithubActionsOutput(environment.GITHUB_OUTPUT, result);
@@ -1216,6 +1227,7 @@ export async function runCli({
     stdout.write(`${json}\n`);
     return 0;
   } catch (unknownError) {
+    progress?.stop();
     const error = asSiteAuthoringError(unknownError);
     if (completedPreviewRecovery) error.withPreviewRecovery(completedPreviewRecovery);
     const result = failureResult(error);

package/src/progress.js

@@ -0,0 +1,142 @@
+/**
+ * Human progress for a long wait, written to stderr (stdout stays the one JSON
+ * result). Verbs report plain lines through `report(message)`; a wait reports
+ * `report(message, { phase })` once per poll, and this decides how much of that
+ * a reader should see.
+ *
+ * - On a terminal, a wait is one in-place line (spinner, phase, elapsed time)
+ *   that redraws each second, and a new line starts only when the phase changes.
+ *   Any other line clears the in-place line first, then the wait line comes back.
+ * - Off a terminal (a pipe, CI), no control characters are ever written: one line
+ *   per phase change, plus a heartbeat at most every `heartbeatMilliseconds` so a
+ *   long silent phase does not look hung.
+ */
+const SPINNER_FRAMES = ["|", "/", "-", "\\"];
+const ERASE_LINE = "\r\u001B[2K";
+
+export const PROGRESS_HEARTBEAT_MILLISECONDS = 60_000;
+const REDRAW_MILLISECONDS = 1_000;
+
+export function formatElapsed(milliseconds) {
+  const totalSeconds = Math.max(0, Math.floor(milliseconds / 1_000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
+}
+
+/**
+ * @param {{
+ *   stream: { write(text: string): unknown, isTTY?: boolean, columns?: number },
+ *   interactive?: boolean,
+ *   quiet?: boolean,
+ *   now?: () => number,
+ *   heartbeatMilliseconds?: number,
+ *   setInterval?: typeof setInterval,
+ *   clearInterval?: typeof clearInterval,
+ * }} options
+ */
+export function createProgressReporter({
+  stream,
+  // A terminal that cannot redraw (TERM=dumb) is handled as a log, like a pipe.
+  interactive = stream.isTTY === true,
+  quiet = false,
+  now = Date.now,
+  heartbeatMilliseconds = PROGRESS_HEARTBEAT_MILLISECONDS,
+  setInterval: schedule = setInterval,
+  clearInterval: cancel = clearInterval,
+}) {
+  let phase;
+  let phaseStartedAt = 0;
+  let waitStartedAt = 0;
+  let lastLineAt = 0;
+  let frame = 0;
+  let inPlace = false;
+  let timer;
+
+  function draw() {
+    if (phase === undefined) return;
+    frame = (frame + 1) % SPINNER_FRAMES.length;
+    const short = phase.replace(/^DEPLOYMENT_STATUS_/u, "");
+    const inPhase = formatElapsed(now() - phaseStartedAt);
+    const total = formatElapsed(now() - waitStartedAt);
+    // One row only: a wrapped line would leave rows the next redraw cannot clear.
+    // The phase and both counters are what a reader needs, so the wording around
+    // them is what gives way on a narrow terminal.
+    const width = Math.max(10, (stream.columns ?? 80) - 1);
+    const candidates = [
+      `${SPINNER_FRAMES[frame]} Waiting for the deployment (${short}); ${inPhase} in this phase, ${total} total`,
+      `${SPINNER_FRAMES[frame]} ${short}: ${inPhase} in phase, ${total} total`,
+      `${SPINNER_FRAMES[frame]} ${short} ${inPhase} (${total} total)`,
+    ];
+    const text = candidates.find((candidate) => candidate.length <= width) ?? candidates.at(-1).slice(0, width);
+    stream.write(`${ERASE_LINE}${text}`);
+    inPlace = true;
+  }
+
+  function clearInPlace() {
+    if (!inPlace) return;
+    stream.write(ERASE_LINE);
+    inPlace = false;
+  }
+
+  function endWait() {
+    if (timer !== undefined) {
+      cancel(timer);
+      timer = undefined;
+    }
+    clearInPlace();
+    phase = undefined;
+  }
+
+  function line(text) {
+    stream.write(`${text}\n`);
+    lastLineAt = now();
+  }
+
+  return {
+    report(message, event) {
+      if (quiet) return;
+      if (event?.phase === undefined) {
+        // A plain line. On a terminal the wait line is wiped and redrawn by the
+        // next tick, so the message is never glued to a half-written spinner.
+        clearInPlace();
+        line(message);
+        if (interactive && phase !== undefined) draw();
+        return;
+      }
+      const at = now();
+      if (phase === undefined) waitStartedAt = at;
+      const changed = phase !== event.phase;
+      if (changed) {
+        // The finished phase stays on screen as a line of its own.
+        if (interactive && phase !== undefined) {
+          clearInPlace();
+          line(`Deployment phase ${phase} finished after ${formatElapsed(at - phaseStartedAt)}.`);
+        }
+        phase = event.phase;
+        phaseStartedAt = at;
+      }
+      if (interactive) {
+        draw();
+        if (timer === undefined) {
+          timer = schedule(draw, REDRAW_MILLISECONDS);
+          timer.unref?.();
+        }
+        return;
+      }
+      if (changed) {
+        line(message);
+      } else if (at - lastLineAt >= heartbeatMilliseconds) {
+        line(`Still waiting for the deployment (${phase}); ${formatElapsed(at - waitStartedAt)} elapsed.`);
+      }
+    },
+
+    /** Ends the wait for a deployment (it finished or failed) while the run carries on. */
+    endWait,
+
+    /** Ends any wait in progress. Safe to call more than once. */
+    stop() {
+      endWait();
+    },
+  };
+}

package/src/verbs/deploy.js

@@ -318,16 +318,22 @@ export async function deploy(invocation) {
     const stagedPageIds = presentationOnly ? [] : selection.stagedPageIds ?? defaults.stagedPageIds;
     const selectedSettingsTypes = selection.selectedSettingsTypes ?? defaults.selectedSettingsTypes;
     const includeNavigation = presentationOnly ? false : selection.includeNavigation ?? defaults.includeNavigation;
-    if (stagedPageIds.length === 0 && selectedSettingsTypes.length === 0 && !includeNavigation) {
-      throw new SiteAuthoringError(
+    const nothingSelected = stagedPageIds.length === 0 && selectedSettingsTypes.length === 0 && !includeNavigation;
+    // A managed Docs site stages settings only, so an empty selection is final.
+    // Any other site may still have a publishable change no selection names: an
+    // edited redirect map. Readiness below says whether it does.
+    const emptySelectionError = () =>
+      new SiteAuthoringError(
         "deploy.empty_selection",
         presentationOnly
           ? "A staging deployment on a managed Docs site needs at least one settings change; it stages settings "
             + "only. Change a theme, brand, header, or footer setting first."
-          : "A staging deployment needs at least one approved page, settings group, or navigation change. "
-            + "Run 'taproot-site approve' or change staged settings/navigation first.",
+          : "A staging deployment needs at least one approved page, settings group, or navigation change, or an "
+            + "edited redirect map. Run 'taproot-site approve' or change staged settings/navigation first.",
         { field: "Candidate" },
       );
+    if (nothingSelected && presentationOnly) {
+      throw emptySelectionError();
     }
 
     const candidate = {
@@ -353,6 +359,9 @@ export async function deploy(invocation) {
         { field: readiness.blockers[0].imageId || "blockers", status: readiness.blockers[0].state },
       );
     }
+    if (nothingSelected && !readiness.hasCandidateChanges) {
+      throw emptySelectionError();
+    }
     if (!readiness.hasCandidateChanges) {
       onProgress("Taproot reports this candidate contains no changes; deploying it anyway would be a no-op.");
     }