@taprootio/site-authoring 0.30.0 → 0.32.0

package/src/verbs/media-images.js

@@ -0,0 +1,67 @@
+import { getSiteImageDescription, listSiteImageDescriptions, updateSiteImageDescription, withRefusalGuidance } from "../api.js";
+import { VERB_MEDIA_IMAGES_DESCRIBE, VERB_MEDIA_IMAGES_GET, VERB_MEDIA_IMAGES_LIST } from "../constants.js";
+import { SiteAuthoringError } from "../errors.js";
+import { imageDescriptionOptions, imageListOptions, requireImageId } from "../image-description-contract.js";
+import { serializeResult } from "../output.js";
+import { openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
+import { ApiError } from "../transport.js";
+
+export async function mediaImagesList(invocation) {
+  const options = imageListOptions(invocation);
+  const { client, siteId, onProgress } = await openSession(invocation);
+  const images = await withRefusalGuidance(onProgress, VERB_MEDIA_IMAGES_LIST, () =>
+    listSiteImageDescriptions(client, siteId, options));
+  const result = successResult(VERB_MEDIA_IMAGES_LIST, siteId, {
+    images: { ...images, count: images.items.length, missingDescription: options.missingDescription },
+  });
+  try {
+    serializeResult(result);
+  } catch (error) {
+    if (!(error instanceof SiteAuthoringError) || error.code !== "output.too_large") throw error;
+    throw new SiteAuthoringError("media.image_page_too_large",
+      "This page exceeds the output bound. Repeat the same cursor with a smaller --page-size; no items were omitted.",
+      { field: "pageSize" });
+  }
+  onProgress(`${images.items.length} image(s) returned${images.nextPageToken ? "; use images.nextPageToken for the next page" : ""}.`);
+  return result;
+}
+
+export async function mediaImagesGet(invocation) {
+  const imageId = requireImageId(invocation.imageId);
+  const { client, siteId, onProgress } = await openSession(invocation);
+  const image = await withRefusalGuidance(onProgress, VERB_MEDIA_IMAGES_GET, () =>
+    getSiteImageDescription(client, siteId, imageId));
+  onProgress(`Read image ${image.imageId}, description revision ${image.descriptionRevision}.`);
+  return successResult(VERB_MEDIA_IMAGES_GET, siteId, { image });
+}
+
+export async function mediaImagesDescribe(invocation) {
+  const imageId = requireImageId(invocation.imageId);
+  const body = imageDescriptionOptions(invocation);
+  const session = await openSession(invocation);
+  warnIfExternalWritesPaused(session, VERB_MEDIA_IMAGES_DESCRIBE);
+  const { client, siteId, onProgress } = session;
+  const image = await withRefusalGuidance(onProgress, VERB_MEDIA_IMAGES_DESCRIBE, async () => {
+    try {
+      return await updateSiteImageDescription(client, siteId, imageId, body);
+    } catch (error) {
+      if (error instanceof ApiError && error.hasField("ExpectedRevision")) {
+        throw new SiteAuthoringError("media.image_description_conflict",
+          "The description changed. Read it with 'media images get', reconcile the text, and supply that revision.",
+          { field: "expectedRevision", status: error.status });
+      }
+      if (error instanceof ApiError && error.hasField("OnlyIfMissing")) {
+        throw new SiteAuthoringError("media.image_description_exists", "This image already has a default description; nothing changed.",
+          { field: "onlyIfMissing", status: error.status });
+      }
+      if (error instanceof ApiError && error.hasField("DefaultDescription")) {
+        throw new SiteAuthoringError("media.image_description_invalid",
+          error.descriptionFor("DefaultDescription") ?? "Taproot refused the default description.",
+          { field: "defaultDescription", status: error.status });
+      }
+      throw error;
+    }
+  });
+  onProgress(`Saved image ${image.imageId}, description revision ${image.descriptionRevision}. Deploy to update published usages.`);
+  return successResult(VERB_MEDIA_IMAGES_DESCRIBE, siteId, { image });
+}

package/src/verbs/pages-push.js

@@ -1548,7 +1548,8 @@ export async function planPages({
         pagePath,
         title: sentTitle,
         // Only the owner's own description is warned about for length: the derived one is not theirs to shorten.
-        ...(generated ? { declaredDescription: document_.data.customDescription } : {}),
+        declaredDescription: generated ? document_.data.customDescription : declaredDescription,
+        metadataDescriptionKnown: generated || typeof declaredDescription === "string",
         contentKey,
         unchanged,
         description: sentDescription,

package/src/verbs/status.js

@@ -1,3 +1,4 @@
+import { describeNavigationReadiness, reportNavigationReadiness } from "../navigation-readiness.js";
 import {
   getDeploySelection,
   getPublishingReadiness,
@@ -162,7 +163,7 @@ export async function status(invocation) {
     if (!presentationOnly) {
       onProgress("Reading image processing state.");
       ({ images, summary, truncated } = await listSiteImages(client, siteId));
-      onProgress("Reading site health.");
+      onProgress("Reading the stored deployment health report.");
       health = await getSiteHealth(client, siteId);
     }
     const reportedFindings = boundedList(health.findings, MAXIMUM_HEALTH_FINDINGS);
@@ -184,10 +185,14 @@ export async function status(invocation) {
     const reportedDeployments = boundedList(deployments, MAXIMUM_DEPLOYMENTS);
     const blockers = boundedList(readiness.blockers, MAXIMUM_BLOCKERS);
 
+    onProgress(describeNavigationReadiness(readiness.navigationReadiness));
+    const assessed = ["complete", "incomplete"].includes(health.status) && Boolean(health.deploymentId);
     if (!presentationOnly) {
-      onProgress(
-        `Site health: ${health.errorCount} problem(s) and ${health.warningCount} warning(s) on ${health.pageCount} page(s).`,
-      );
+      onProgress(assessed
+        ? `Site health (${health.environment}, checked ${health.checkedAt}): ${health.errorCount} problem(s) and ${health.warningCount} warning(s). Unpublished changes are outside this report.`
+        : health.status === "not_checked"
+        ? "Site health: not checked yet. Deploy the site to create a report."
+        : "Site health: no complete supported deployment assessment is available.");
     }
 
     return successResult(VERB_STATUS, siteId, {
@@ -196,6 +201,7 @@ export async function status(invocation) {
       ...(presentationOnly ? { authoringSurface: SURFACE_DOCS_PRESENTATION } : {}),
       readiness: {
         state: readiness.state,
+        navigationReadiness: reportNavigationReadiness(readiness.navigationReadiness),
         approvedPageCount: readiness.approvedPageCount,
         blockedPageCount: readiness.blockedPageCount,
         hasCandidateChanges: readiness.hasCandidateChanges,
@@ -227,12 +233,20 @@ export async function status(invocation) {
         ...(truncated ? { listTruncated: true } : {}),
       },
       siteHealth: presentationOnly ? { covered: false, reason: DOCS_SITE_NOT_COVERED_NOTE } : {
-        covered: true,
+        covered: assessed,
+        status: health.status ?? "unknown",
+        ...(assessed ? {
+        deploymentId: health.deploymentId, outputReleaseId: health.outputReleaseId,
+        inputHash: health.inputHash, checkedAt: health.checkedAt, ruleVersion: health.ruleVersion,
+        coverage: health.coverage, assessedPages: health.assessedPageCount, environment: health.environment,
+        unpublishedChangesAssessed: false,
         errors: health.errorCount,
         warnings: health.warningCount,
         pages: health.pageCount,
         findings: reportedFindings.items,
+        imageFindings: health.images,
         ...(reportedFindings.truncated || health.truncated ? { findingsTruncated: true } : {}),
+        } : { reason: health.status === "not_checked" ? "Not checked yet; deploy the site to create a report." : "A complete supported deployment assessment is unavailable." }),
       },
     });
   });