@taprootio/site-authoring 0.7.2 → 0.8.0

package/src/verbs/status.js

@@ -17,6 +17,7 @@ import {
   PUBLISH_KEY_ENVIRONMENT_VARIABLE,
   REFUSAL_CLI_OUTDATED,
   REFUSAL_PLATFORM_PAUSED,
+  SURFACE_DOCS_PRESENTATION,
   VERB_STATUS,
 } from "../constants.js";
 import { boundedList, openSession, successResult } from "../session.js";
@@ -100,8 +101,20 @@ function reportPlatform(platform, onProgress) {
   return { externalWritesEnabled: enabled };
 }
 
+/**
+ * What a managed Docs site's status leaves out (TR00790), said the same way
+ * the platform switch says "unknown": by shape. The image library and the
+ * broken-reference report are page-authoring reads a Docs site refuses, so
+ * they are reported as not covered rather than as empty — an automation
+ * reading `failed: 0` off a report that was never made would be reading a lie.
+ */
+const DOCS_SITE_NOT_COVERED_NOTE =
+  "This is a managed Docs site: its pages come from the Docs artifact, so the image library and broken-reference "
+  + "reads do not apply and were not made.";
+
 export async function status(invocation) {
-  const { client, siteId, platform, release, onProgress } = await openSession(invocation);
+  const { client, siteId, surface, platform, release, onProgress } = await openSession(invocation);
+  const presentationOnly = surface === SURFACE_DOCS_PRESENTATION;
   // Said first, and before any wire read: an operator running `status` because
   // writes are being refused should not have to wait on network calls to
   // learn that the platform is paused — and this answer needs none of them.
@@ -110,7 +123,15 @@ export async function status(invocation) {
 
   return await withRefusalGuidance(onProgress, "status check", async () => {
     onProgress("Reading publishing readiness.");
-    const selection = await getDeploySelection(client, siteId);
+    const reviewed = await getDeploySelection(client, siteId);
+    // The review is site-type-blind: a managed Docs site's settings-only
+    // production manifest makes any draft navigation row read as changed
+    // forever. Readiness is asked about the candidate `deploy` would actually
+    // send there — settings only — so hasCandidateChanges answers for it
+    // (TR00790).
+    const selection = presentationOnly
+      ? { ...reviewed, stagedPageIds: [], includeNavigation: false }
+      : reviewed;
     const readiness = await getPublishingReadiness(client, siteId, {
       ...selection,
       stagedPageIds: selection.stagedPageIds.length > 100 ? undefined : selection.stagedPageIds,
@@ -120,10 +141,19 @@ export async function status(invocation) {
       deployments,
       truncated: deploymentsTruncated,
     } = await listDeployments(client, siteId, { pageSize: MAXIMUM_DEPLOYMENTS });
-    onProgress("Reading image processing state.");
-    const { images, summary, truncated } = await listSiteImages(client, siteId);
-    onProgress("Reading broken references.");
-    const brokenReferencePages = await getSiteBrokenReferences(client, siteId);
+    if (presentationOnly) {
+      onProgress(DOCS_SITE_NOT_COVERED_NOTE);
+    }
+    let images = [];
+    let summary = { totalImages: 0, processingImages: 0 };
+    let truncated = false;
+    let brokenReferencePages = [];
+    if (!presentationOnly) {
+      onProgress("Reading image processing state.");
+      ({ images, summary, truncated } = await listSiteImages(client, siteId));
+      onProgress("Reading broken references.");
+      brokenReferencePages = await getSiteBrokenReferences(client, siteId);
+    }
     const reportedBrokenPages = boundedList(brokenReferencePages, MAXIMUM_BROKEN_REFERENCE_PAGES);
     const brokenPages = reportedBrokenPages.items.map((page) => {
       const images = boundedList(page.missingImageIds, MAXIMUM_MISSING_TARGETS);
@@ -154,11 +184,14 @@ export async function status(invocation) {
     const reportedDeployments = boundedList(deployments, MAXIMUM_DEPLOYMENTS);
     const blockers = boundedList(readiness.blockers, MAXIMUM_BLOCKERS);
 
-    onProgress(`Broken references: ${brokenReferencePages.length} page(s) with missing targets.`);
+    if (!presentationOnly) {
+      onProgress(`Broken references: ${brokenReferencePages.length} page(s) with missing targets.`);
+    }
 
     return successResult(VERB_STATUS, siteId, {
       platform: platformReport,
       cliRelease: cliReleaseReport,
+      ...(presentationOnly ? { authoringSurface: SURFACE_DOCS_PRESENTATION } : {}),
       readiness: {
         state: readiness.state,
         approvedPageCount: readiness.approvedPageCount,
@@ -177,7 +210,8 @@ export async function status(invocation) {
         ...(reportedDeployments.truncated ? { itemsTruncated: true } : {}),
         ...(deploymentsTruncated ? { listTruncated: true } : {}),
       },
-      images: {
+      images: presentationOnly ? { covered: false, reason: DOCS_SITE_NOT_COVERED_NOTE } : {
+        covered: true,
         total: summary.totalImages,
         processing: summary.processingImages,
         complete: byState[IMAGE_PROCESSING_STATE_COMPLETE] ?? 0,
@@ -187,7 +221,7 @@ export async function status(invocation) {
         ...(failedImages.truncated ? { failedItemsTruncated: true } : {}),
         ...(truncated ? { listTruncated: true } : {}),
       },
-      brokenReferences: {
+      brokenReferences: presentationOnly ? { covered: false, reason: DOCS_SITE_NOT_COVERED_NOTE } : {
         covered: true,
         totalPages: brokenReferencePages.length,
         pages: brokenPages,

package/src/verbs/use.js

@@ -7,11 +7,13 @@ import {
   CONFIG_FILE_NAME,
   CONFIG_VERSION,
   DEFAULT_WORKSPACE_DIR,
+  SURFACE_STANDARD,
   VERB_SITES,
   VERB_USE,
 } from "../constants.js";
 import { isCanonicalUuid, sanitizeDiagnostic, SiteAuthoringError } from "../errors.js";
 import { openAccountSession, successResult } from "../session.js";
+import { describeSiteKind, describeSurface } from "../surface.js";
 
 /**
  * `taproot-site use <site>` — choose the site the next command writes to.
@@ -88,6 +90,11 @@ export async function use(invocation) {
         {
           configVersion: CONFIG_VERSION,
           siteId: site.siteId,
+          // What the site accepts, as Taproot reported it just now (TR00790).
+          // Recorded so a verb the site cannot take is refused offline, in
+          // words; every write re-checks it on the server, so this is a
+          // convenience that can go stale, never an authority.
+          ...(site.authoringSurface === undefined ? {} : { authoringSurface: site.authoringSurface }),
           workspaceDir,
           // No endpoint. Which Taproot this is talking to lives with the
           // credential, per machine — writing it here would pin a project to
@@ -116,13 +123,25 @@ export async function use(invocation) {
     });
 
     // Sanitized for the same reason the listing is: the name is authored
-      // by a person and this line is what confirms the selection.
-      onProgress(`Now authoring ${sanitizeDiagnostic(site.name, site.siteId)} (${site.siteId}).`);
+    // by a person and this line is what confirms the selection.
+    onProgress(
+      `Now authoring ${sanitizeDiagnostic(site.name, site.siteId)} (${site.siteId}) [${describeSiteKind(site)}].`,
+    );
+    if (site.authoringSurface !== undefined && site.authoringSurface !== SURFACE_STANDARD) {
+      onProgress(`Authoring surface ${site.authoringSurface}: ${describeSurface(site.authoringSurface)}.`);
+    }
     onProgress(`Recorded in ${configPath}.`);
 
     return successResult(VERB_USE, site.siteId, {
       accountId: signIn.accountId,
-      site: { siteId: site.siteId, name: site.name, primaryDomain: site.primaryDomain },
+      site: {
+        siteId: site.siteId,
+        name: site.name,
+        primaryDomain: site.primaryDomain,
+        siteType: site.siteType,
+        ...(site.docsPublicationMode === undefined ? {} : { docsPublicationMode: site.docsPublicationMode }),
+        ...(site.authoringSurface === undefined ? {} : { authoringSurface: site.authoringSurface }),
+      },
       configPath: configPath,
     });
   });

package/src/verbs/whoami.js

@@ -15,6 +15,7 @@ import { credentialApiOrigin, findCredential } from "../credentials.js";
 import { SITE_AUTHORING_CAPABILITIES } from "../capabilities.js";
 import { openAnonymousSession, successResult } from "../session.js";
 import { environmentNameFor } from "../settings.js";
+import { describeSurface } from "../surface.js";
 
 /**
  * What the last exchange recorded about the platform authoring switch, dated
@@ -109,7 +110,11 @@ export async function whoami(invocation) {
   }
   onProgress(
     config?.siteId
-      ? `Site: ${config.siteId}`
+      ? `Site: ${config.siteId}${
+        config.authoringSurface === undefined
+          ? ""
+          : ` (${config.authoringSurface}: ${describeSurface(config.authoringSurface)})`
+      }`
       : `No site selected. Run '${CLI_BINARY_NAME} ${VERB_USE} <site>'.`,
   );
   // What the last exchange actually produced, when there has been one. That is
@@ -156,6 +161,9 @@ export async function whoami(invocation) {
       credentialPath,
     }),
     ...(config?.configPath === undefined ? {} : { configPath: config.configPath }),
+    // As `use` recorded it (TR00790); absent from a configuration written
+    // before the field existed, and never a live read.
+    ...(config?.authoringSurface === undefined ? {} : { authoringSurface: config.authoringSurface }),
     // Named for what each is. `capabilities` alone would conflate the ceiling
     // with the grant, which are different numbers and differently trustworthy.
     capabilityCeiling: SITE_AUTHORING_CAPABILITIES,