@taprootio/site-authoring 0.7.2 → 0.8.1

package/src/session.js

@@ -22,8 +22,9 @@ import {
 } from "./credentials.js";
 import { SiteAuthoringError } from "./errors.js";
 import { exchangeSiteAuthoringToken, withRefusalGuidance } from "./api.js";
-import { SiteApiClient } from "./transport.js";
+import { ApiError, SiteApiClient } from "./transport.js";
 import { readStoredApiBaseUrl } from "./settings.js";
+import { capabilitiesForSurface, surfaceAllows, surfaceRefusal } from "./surface.js";
 
 /**
  * The two things every verb does at its edges: open a credentialed session, and
@@ -75,6 +76,46 @@ function keyMissingError() {
   );
 }
 
+/**
+ * Refuses a verb the recorded surface cannot take, before any credential is
+ * used (TR00790). Offline on purpose: the answer is in the configuration `use`
+ * wrote, and an agent that runs `pages push` against a Docs site should be
+ * told in words, now, rather than after an exchange and a refused request.
+ * The exchange's own answer is checked again afterwards, because the
+ * recording can be stale.
+ */
+function requireRecordedSurface(invocation, config) {
+  if (invocation.surface === undefined || config.authoringSurface === undefined) return;
+  if (!surfaceAllows(config.authoringSurface, invocation.surface)) {
+    throw surfaceRefusal(invocation.verb ?? "This verb", config.authoringSurface, { source: "config" });
+  }
+}
+
+/**
+ * The verb's capability request, narrowed to the recorded surface (TR00790).
+ *
+ * A verb may declare its own set for a surface (`surfaceCapabilities`) where
+ * plain intersection would be wrong; otherwise the declared set is
+ * intersected with what the surface offers. Either way a request that started
+ * non-empty must not end empty: on the wire an empty list means "everything
+ * the surface offers", so sending one would hand a narrow verb a wide
+ * credential. That case is a verb-table defect and is refused as one.
+ */
+function narrowedCapabilities(invocation, surface) {
+  const requested = invocation.capabilities ?? [];
+  if (surface === undefined) return requested;
+  const narrowed = invocation.surfaceCapabilities?.[surface] ?? capabilitiesForSurface(surface, requested);
+  if (requested.length > 0 && narrowed.length === 0) {
+    throw new SiteAuthoringError(
+      "surface.capabilities_unavailable",
+      `'${invocation.verb ?? "This verb"}' declares no capability the ${surface} surface offers, so no credential `
+        + "can be minted for it there.",
+      { field: "authoringSurface", status: surface, exitCode: 2 },
+    );
+  }
+  return narrowed;
+}
+
 function siteMissingError() {
   return new SiteAuthoringError(
     "config.site_missing",
@@ -189,6 +230,7 @@ export async function openSession(invocation = {}) {
     const apiBaseUrl = await resolveApiBaseUrl(environment);
     const config = await loadConfig(invocation);
     if (!config.siteId) throw siteMissingError();
+    requireRecordedSurface(invocation, config);
     const client = invocation.client
       ?? new SiteApiClient(buildClientOptions(invocation, apiBaseUrl, environmentToken));
     // No exchange happens on this path, and nothing else on the contract reads
@@ -199,6 +241,7 @@ export async function openSession(invocation = {}) {
       config,
       client,
       siteId: config.siteId,
+      surface: config.authoringSurface,
       platform: UNKNOWN_PLATFORM,
       release: UNKNOWN_CLI_RELEASE,
       now,
@@ -214,6 +257,7 @@ export async function openSession(invocation = {}) {
     return apiBaseUrl;
   });
   if (!config.siteId) throw siteMissingError();
+  requireRecordedSurface(invocation, config);
 
   // The server is the authority on expiry, so an expired sign-in is still sent
   // — the clock here may simply be wrong. What is worth saying out loud is that
@@ -233,6 +277,7 @@ export async function openSession(invocation = {}) {
       config,
       client: invocation.client,
       siteId: config.siteId,
+      surface: config.authoringSurface,
       platform: UNKNOWN_PLATFORM,
       release: UNKNOWN_CLI_RELEASE,
       now,
@@ -247,15 +292,42 @@ export async function openSession(invocation = {}) {
   // as a field name and nothing else. That matters most for `cli_outdated`,
   // whose whole remedy is a command the operator has to be handed (TR00703),
   // but it is true of every classified refusal the exchange can raise.
-  const exchanged = await withRefusalGuidance(
-    onProgress,
-    "sign-in token exchange",
-    async () =>
-      await exchangeSiteAuthoringToken(accountClient, {
-        siteId: config.siteId,
-        capabilities: invocation.capabilities ?? [],
-      }),
-  );
+  let exchanged;
+  try {
+    exchanged = await withRefusalGuidance(
+      onProgress,
+      "sign-in token exchange",
+      async () =>
+        await exchangeSiteAuthoringToken(accountClient, {
+          siteId: config.siteId,
+          // Narrowed to what the recorded surface offers (TR00790): a managed
+          // Docs site's exchange refuses Content by name, and a verb that only
+          // reads with it — deploy, pull — still runs there without it.
+          capabilities: narrowedCapabilities(invocation, config.authoringSurface),
+        }),
+    );
+  } catch (error) {
+    // A site the exchange no longer offers answers Not found, and one way a
+    // site that was offered stops being offered is a Docs source becoming
+    // prebuilt after `use` recorded it (TR00790). The server deliberately says
+    // nothing more — the answer is the same for a site that never existed —
+    // so the recording is what makes the hint possible, and the hint is what
+    // turns "not found" into the command that fixes it.
+    if (error instanceof ApiError && error.httpStatus === 404 && config.authoringSurface !== undefined) {
+      onProgress(
+        `The site recorded in the configuration (${config.authoringSurface}) is no longer available to author. `
+          + "If it is a Docs site, its publication mode may have changed; run "
+          + `'${CLI_BINARY_NAME} ${VERB_USE} <site>' again to see what it accepts now.`,
+      );
+    }
+    throw error;
+  }
+  // The live answer outranks the recording. A site whose Docs source moved
+  // since `use` ran is refused here, before any request the server would
+  // refuse anyway, and the message says to record the new surface.
+  if (invocation.surface !== undefined && !surfaceAllows(exchanged.authoringSurface, invocation.surface)) {
+    throw surfaceRefusal(invocation.verb ?? "This verb", exchanged.authoringSurface, { source: "exchange" });
+  }
   // Two non-secret facts the store should now carry: the sign-in's slid
   // deadline, and what this exchange actually produced — the latter is the only
   // thing that lets `whoami` answer offline with the real grant rather than the
@@ -306,6 +378,7 @@ export async function openSession(invocation = {}) {
     config,
     client,
     siteId: config.siteId,
+    surface: exchanged.authoringSurface,
     exchanged: {
       keyId: exchanged.keyId,
       keyPrefix: exchanged.keyPrefix,

package/src/surface.js

@@ -0,0 +1,152 @@
+import { CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS, CAPABILITY_DESIGN } from "./capabilities.js";
+import {
+  AUTHORING_SURFACES,
+  CLI_BINARY_NAME,
+  SURFACE_DOCS_PRESENTATION,
+  SURFACE_NONE,
+  SURFACE_STANDARD,
+  VERB_USE,
+} from "./constants.js";
+import { SiteAuthoringError } from "./errors.js";
+
+/**
+ * Which authoring verbs a site accepts (TR00790), as the CLI reads it.
+ *
+ * Taproot resolves the surface from a site's kind and, for a Docs site, its
+ * current publication mode: a STANDARD site takes every verb, a managed Docs
+ * site takes only the design and theming surface (its pages, navigation, and
+ * redirects come from the artifact the Docs shell renders), and a prebuilt
+ * Docs site takes nothing, because it serves its artifact's file tree
+ * unchanged. The server re-resolves it on every write; what the CLI holds is a
+ * recording, used to refuse a verb before a request that would be refused
+ * anyway and to say why in words rather than a field name.
+ */
+
+const WIRE_SURFACES = Object.freeze({
+  SITE_AUTHORING_SURFACE_STANDARD: SURFACE_STANDARD,
+  SITE_AUTHORING_SURFACE_DOCS_PRESENTATION: SURFACE_DOCS_PRESENTATION,
+  SITE_AUTHORING_SURFACE_NONE: SURFACE_NONE,
+});
+
+const WIRE_SITE_KINDS = Object.freeze({
+  SITE_TYPE_STANDARD: "standard",
+  SITE_TYPE_DOCS: "docs",
+  SITE_TYPE_PROFILE: "profile",
+});
+
+const WIRE_DOCS_MODES = Object.freeze({
+  DOCS_PUBLICATION_MODE_MANAGED: "managed",
+  DOCS_PUBLICATION_MODE_PREBUILT: "prebuilt",
+});
+
+// Wider surfaces satisfy narrower requirements, so one comparison decides.
+const SURFACE_WIDTH = Object.freeze({
+  [SURFACE_NONE]: 0,
+  [SURFACE_DOCS_PRESENTATION]: 1,
+  [SURFACE_STANDARD]: 2,
+});
+
+/**
+ * The capabilities each surface's exchange may carry. Content is absent from
+ * the Docs surface because the site has no pages for it to write, and an
+ * exchange that asks for it anyway is refused by name.
+ */
+const SURFACE_CAPABILITIES = Object.freeze({
+  [SURFACE_STANDARD]: Object.freeze([CAPABILITY_CONTENT, CAPABILITY_DESIGN, CAPABILITY_DEPLOYMENTS]),
+  [SURFACE_DOCS_PRESENTATION]: Object.freeze([CAPABILITY_DESIGN, CAPABILITY_DEPLOYMENTS]),
+  [SURFACE_NONE]: Object.freeze([]),
+});
+
+/**
+ * Reads the wire enum. Anything unrecognized — absent, unspecified, or a value
+ * this CLI does not know — is `undefined`: not a surface, so nothing gates on
+ * it. The CLI's gate is a courtesy ahead of the server's own refusal, and a
+ * courtesy that refused on a value it could not read would refuse for the
+ * wrong reason; the server still refuses what the site cannot take.
+ */
+export function surfaceFromWire(value) {
+  return typeof value === "string" && Object.hasOwn(WIRE_SURFACES, value) ? WIRE_SURFACES[value] : undefined;
+}
+
+export function siteKindFromWire(value) {
+  return typeof value === "string" && Object.hasOwn(WIRE_SITE_KINDS, value) ? WIRE_SITE_KINDS[value] : "unknown";
+}
+
+/** Absent for a STANDARD site, which has no Docs mode at all. */
+export function docsPublicationModeFromWire(value) {
+  return typeof value === "string" && Object.hasOwn(WIRE_DOCS_MODES, value) ? WIRE_DOCS_MODES[value] : undefined;
+}
+
+export function isKnownSurface(value) {
+  return typeof value === "string" && AUTHORING_SURFACES.includes(value);
+}
+
+/**
+ * Whether a site of `surface` accepts a verb that needs `required`. An
+ * unknown surface on either side allows: there is nothing to gate on, and the
+ * server decides.
+ */
+export function surfaceAllows(surface, required) {
+  return SURFACE_WIDTH[surface] === undefined
+    || SURFACE_WIDTH[required] === undefined
+    || SURFACE_WIDTH[surface] >= SURFACE_WIDTH[required];
+}
+
+/** The verb's capability request, narrowed to what its site's surface offers. */
+export function capabilitiesForSurface(surface, requested) {
+  const offered = SURFACE_CAPABILITIES[surface];
+  if (offered === undefined) return requested;
+  return requested.filter((capability) => offered.includes(capability));
+}
+
+/** One short phrase per surface, for listings and `whoami`. */
+export function describeSurface(surface) {
+  switch (surface) {
+    case SURFACE_STANDARD:
+      return "every authoring verb";
+    case SURFACE_DOCS_PRESENTATION:
+      return "design and theming only; pages, navigation, and redirects come from the Docs artifact";
+    case SURFACE_NONE:
+      return "no authoring verb; a prebuilt Docs site serves its artifact unchanged";
+    default:
+      return "not reported by Taproot; each verb is decided on the server";
+  }
+}
+
+/** How a listing labels a site's kind, with the Docs mode when it has one. */
+export function describeSiteKind(site) {
+  if (site.siteType === "docs") {
+    return site.docsPublicationMode === undefined ? "docs" : `docs, ${site.docsPublicationMode}`;
+  }
+  return site.siteType;
+}
+
+/**
+ * The refusal a verb raises when its site's surface is too narrow. Two codes,
+ * one per surface, so an agent can branch on which without parsing prose; the
+ * message names the verb, the surface, and the remedy when there is one.
+ *
+ * `source` says where the surface came from: the configuration `use` wrote,
+ * or the exchange that just answered. A refusal from a recording says how to
+ * refresh it; a refusal from the live answer says the site changed.
+ */
+export function surfaceRefusal(verb, surface, { source = "config" } = {}) {
+  const remedy = source === "config"
+    ? ` This is the surface recorded by '${CLI_BINARY_NAME} ${VERB_USE}'; run it again if the site has changed.`
+    : ` Taproot reported this on the exchange just now; run '${CLI_BINARY_NAME} ${VERB_USE}' again to record it.`;
+  if (surface === SURFACE_DOCS_PRESENTATION) {
+    return new SiteAuthoringError(
+      "surface.presentation_only",
+      `'${verb}' does not apply to a managed Docs site: its pages, navigation, and redirects come from the Docs `
+        + "artifact, and the CLI authors only its design — theme, brand, header, and footer settings, the images "
+        + `they reference, and their deployment.${remedy}`,
+      { field: "authoringSurface", status: surface, exitCode: 2 },
+    );
+  }
+  return new SiteAuthoringError(
+    "surface.none",
+    `'${verb}' does not apply to this site: a prebuilt Docs site serves its artifact's files unchanged, so no `
+      + `authoring verb applies to it.${remedy}`,
+    { field: "authoringSurface", status: SURFACE_NONE, exitCode: 2 },
+  );
+}

package/src/verbs/deploy.js

@@ -10,7 +10,7 @@ import {
   waitForDeployment,
   withRefusalGuidance,
 } from "../api.js";
-import { DEPLOY_TARGET_PRODUCTION, DEPLOY_TARGET_STAGING, VERB_DEPLOY } from "../constants.js";
+import { DEPLOY_TARGET_PRODUCTION, DEPLOY_TARGET_STAGING, SURFACE_DOCS_PRESENTATION, VERB_DEPLOY } from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
 import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import { checkStagingRedirects } from "../staging-check.js";
@@ -167,7 +167,12 @@ export async function deploy(invocation) {
     );
   }
   const session = await openSession(invocation);
-  const { client, config, siteId, now, onProgress } = session;
+  const { client, config, siteId, surface, now, onProgress } = session;
+  // A managed Docs site deploys its settings and nothing else (TR00790): the
+  // Docs shell takes pages, navigation, and redirects from the artifact, so
+  // the staging redirect inspection that follows a standard deployment has
+  // nothing to inspect and the handoff it mints is refused there.
+  const presentationOnly = surface === SURFACE_DOCS_PRESENTATION;
   // One advisory line before this verb does any work, and only when the
   // exchange said the platform is paused. It changes nothing else: the write
   // still runs and its refusal still classifies as platform_paused (TR00692).
@@ -203,26 +208,49 @@ export async function deploy(invocation) {
         now,
       });
       await recordDeployment(config, manifest, "production", completed);
-      onProgress(REDIRECT_PROPAGATION_NOTE);
+      if (!presentationOnly) onProgress(REDIRECT_PROPAGATION_NOTE);
       return successResult(VERB_DEPLOY, siteId, {
         target,
         environment: DEPLOYMENT_ENVIRONMENT_PRODUCTION,
+        ...(presentationOnly ? { authoringSurface: SURFACE_DOCS_PRESENTATION } : {}),
         promotedStagingDeploymentId: stagingDeploymentId,
         deployment: completed,
         readiness: reportReadiness(readiness),
       });
     }
 
+    // An explicit page or navigation selection on a managed Docs site is
+    // refused before the review is read: the caller asked for something the
+    // site cannot take. The review's own defaults are a different matter,
+    // handled below.
+    if (
+      presentationOnly
+      && ((selection.stagedPageIds?.length ?? 0) > 0 || selection.includeNavigation === true)
+    ) {
+      throw usageError(
+        "deploy.presentation_only",
+        "A managed Docs site deploys settings only: its pages and navigation come from the Docs artifact, so a "
+          + "candidate naming pages or navigation cannot be staged from here.",
+        "Candidate",
+      );
+    }
     onProgress("Reading the changed release set shown on the Deployments page.");
     const defaults = await getDeploySelection(client, siteId);
-    const stagedPageIds = selection.stagedPageIds ?? defaults.stagedPageIds;
+    // The review is site-type-blind, and a Docs site's settings-only
+    // production manifest makes any draft navigation row read as a change
+    // forever. The Deployments page zeroes pages and navigation for a Docs
+    // site rather than refusing on them, and this does the same (TR00790).
+    const stagedPageIds = presentationOnly ? [] : selection.stagedPageIds ?? defaults.stagedPageIds;
     const selectedSettingsTypes = selection.selectedSettingsTypes ?? defaults.selectedSettingsTypes;
-    const includeNavigation = selection.includeNavigation ?? defaults.includeNavigation;
+    const includeNavigation = presentationOnly ? false : selection.includeNavigation ?? defaults.includeNavigation;
     if (stagedPageIds.length === 0 && selectedSettingsTypes.length === 0 && !includeNavigation) {
       throw new SiteAuthoringError(
         "deploy.empty_selection",
-        "A staging deployment needs at least one approved page, settings group, or navigation change. "
-          + "Run 'taproot-site approve' or change staged settings/navigation first.",
+        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.",
         { field: "Candidate" },
       );
     }
@@ -269,6 +297,22 @@ export async function deploy(invocation) {
       now,
     });
     await recordDeployment(config, manifest, "staging", completed);
+    if (presentationOnly) {
+      onProgress("Review the staged presentation on the site's staging host, then promote it.");
+      return successResult(VERB_DEPLOY, siteId, {
+        target,
+        environment: DEPLOYMENT_ENVIRONMENT_STAGING,
+        authoringSurface: SURFACE_DOCS_PRESENTATION,
+        selection: {
+          stagedPageCount: 0,
+          selectedSettingsTypes,
+          includeNavigation: false,
+        },
+        deployment: completed,
+        readiness: reportReadiness(readiness),
+        nextStep: "deploy --production",
+      });
+    }
     const stagingPreview = await inspectStagingPreview(client, siteId, onProgress, now);
     onProgress(REDIRECT_PROPAGATION_NOTE);
     return successResult(VERB_DEPLOY, siteId, {

package/src/verbs/pull.js

@@ -10,7 +10,12 @@ import {
   TEMPLATE_TYPE_FREE_FORM,
   withRefusalGuidance,
 } from "../api.js";
-import { REFUSAL_CAPABILITY_MISSING, REFUSAL_UNCLASSIFIED, VERB_PULL } from "../constants.js";
+import {
+  REFUSAL_CAPABILITY_MISSING,
+  REFUSAL_UNCLASSIFIED,
+  SURFACE_DOCS_PRESENTATION,
+  VERB_PULL,
+} from "../constants.js";
 import { sanitizeDiagnostic, SiteAuthoringError } from "../errors.js";
 import { appearanceManifestEntry, footerManifestEntry } from "../footer-workspace.js";
 import { describeJsonDifferences, reportableDifferencePaths } from "../json-path-diff.js";
@@ -560,16 +565,31 @@ async function requireWorkspaceBelongsToSite(workspaceDir, siteId) {
 }
 
 export async function pull(invocation) {
-  const { client, config, siteId, now, onProgress } = await openSession(invocation);
+  const { client, config, siteId, surface, now, onProgress } = await openSession(invocation);
   await ensureWorkspaceRoot(config);
 
   await requireWorkspaceBelongsToSite(config.workspaceDir, siteId);
 
   const registry = await readSourceRegistry(config.workspaceDir, siteId);
 
+  // A managed Docs site has no pages, navigation, or redirects of its own to
+  // snapshot (TR00790): the Docs shell takes those from the artifact, and the
+  // reads would be refused. What it has is the four settings documents, which
+  // are the whole of what this workspace holds for it.
+  const presentationOnly = surface === SURFACE_DOCS_PRESENTATION;
+
   return await withRefusalGuidance(onProgress, "pull", async () => {
-    onProgress("Listing the site's pages.");
-    const { pages, truncated } = await listSitePages(client, siteId, { onProgress });
+    let pages = [];
+    let truncated = false;
+    if (presentationOnly) {
+      onProgress(
+        "This is a managed Docs site: pulling its settings only; pages, navigation, and redirects are not "
+          + "authored here.",
+      );
+    } else {
+      onProgress("Listing the site's pages.");
+      ({ pages, truncated } = await listSitePages(client, siteId, { onProgress }));
+    }
     const live = pages.filter((summary) => summary.status !== PAGE_STATUS_DELETED);
     const freeForm = live.filter((summary) => summary.templateType === TEMPLATE_TYPE_FREE_FORM);
     const tracked = await resolveTrackedSources(config.workspaceDir, freeForm, registry, onProgress);
@@ -581,22 +601,24 @@ export async function pull(invocation) {
     // predates the map answers the route with 404; that pull then records no
     // redirect baseline, and `redirects push` asks for a pull against a site
     // that has one rather than guessing.
-    onProgress("Reading the redirect map.");
     let redirectMap;
-    try {
-      redirectMap = await getSiteRedirectMap(client, siteId);
-    } catch (error) {
-      if (
-        error instanceof ApiError
-        && error.refusalKind() === REFUSAL_UNCLASSIFIED
-        && error.httpStatus === 404
-      ) {
-        onProgress(
-          `This Taproot does not serve a redirect map yet; ${REDIRECTS_FILE_NAME} is not written and the manifest `
-            + "records no redirect baseline.",
-        );
-      } else {
-        throw error;
+    if (!presentationOnly) {
+      onProgress("Reading the redirect map.");
+      try {
+        redirectMap = await getSiteRedirectMap(client, siteId);
+      } catch (error) {
+        if (
+          error instanceof ApiError
+          && error.refusalKind() === REFUSAL_UNCLASSIFIED
+          && error.httpStatus === 404
+        ) {
+          onProgress(
+            `This Taproot does not serve a redirect map yet; ${REDIRECTS_FILE_NAME} is not written and the manifest `
+              + "records no redirect baseline.",
+          );
+        } else {
+          throw error;
+        }
       }
     }
 
@@ -988,9 +1010,12 @@ export async function pull(invocation) {
       manifestPages.push(entry);
     }
 
-    onProgress("Reading the navigation tree.");
-    const navItems = await getNavigation(client, siteId);
-    await writeWorkspaceJson(config.workspaceDir, NAVIGATION_FILE_NAME, { siteId, navItems });
+    let navItems;
+    if (!presentationOnly) {
+      onProgress("Reading the navigation tree.");
+      navItems = await getNavigation(client, siteId);
+      await writeWorkspaceJson(config.workspaceDir, NAVIGATION_FILE_NAME, { siteId, navItems });
+    }
 
     if (redirectMap !== undefined) {
       await writeWorkspaceJson(
@@ -1008,8 +1033,12 @@ export async function pull(invocation) {
       manifestVersion: MANIFEST_VERSION,
       siteId,
       pulledAt: new Date(now()).toISOString(),
+      // Recorded so an offline reader of this workspace — validate, a later
+      // push — knows the absence of pages and navigation is the site's shape,
+      // not a partial pull.
+      ...(presentationOnly ? { authoringSurface: SURFACE_DOCS_PRESENTATION } : {}),
       pagesTruncated: truncated,
-      navigation: { file: NAVIGATION_FILE_NAME, items: navItems.length },
+      ...(navItems === undefined ? {} : { navigation: { file: NAVIGATION_FILE_NAME, items: navItems.length } }),
       ...(redirectMap === undefined ? {} : { redirects: redirectsManifestEntry(redirectMap) }),
       settings: pulledSettings,
       settingsSkipped: skippedSettings,
@@ -1046,6 +1075,7 @@ export async function pull(invocation) {
     );
     return successResult(VERB_PULL, siteId, {
       manifestFile: MANIFEST_FILE_NAME,
+      ...(presentationOnly ? { authoringSurface: SURFACE_DOCS_PRESENTATION } : {}),
       pages: {
         total: manifestPages.length,
         bodies,
@@ -1059,7 +1089,7 @@ export async function pull(invocation) {
         items: reported.items,
         ...(reported.truncated ? { itemsTruncated: true } : {}),
       },
-      navigation: { file: NAVIGATION_FILE_NAME, items: navItems.length },
+      ...(navItems === undefined ? {} : { navigation: { file: NAVIGATION_FILE_NAME, items: navItems.length } }),
       // Absent, not zeroed, when the site served no map: an agent reading
       // `entries: 0` would take the site for one with no redirects.
       ...(redirectMap === undefined ? {} : {

package/src/verbs/sites.js

@@ -1,19 +1,20 @@
 import { listAuthorableSites, withRefusalGuidance } from "../api.js";
-import { CLI_BINARY_NAME, VERB_SITES, VERB_USE } from "../constants.js";
+import { CLI_BINARY_NAME, SURFACE_STANDARD, VERB_SITES, VERB_USE } from "../constants.js";
 import { sanitizeDiagnostic } from "../errors.js";
 import { boundedList, openAccountSession, successResult } from "../session.js";
+import { describeSiteKind, describeSurface } from "../surface.js";
 
 /**
- * `taproot-site sites` — the sites this sign-in may author.
+ * `taproot-site sites` — this account's sites and what each accepts.
  *
  * The answer that used to require reading a site id out of the browser's URL
  * bar and pasting it into a hand-written configuration file (TR00645). It runs
  * on the sign-in credential, which is the only thing that can enumerate an
  * account's sites, and it is one of exactly two things that credential can do.
  *
- * The server has already filtered the list to sites an exchange would accept,
- * so everything printed here is something `use` can select and the next command
- * can author.
+ * Every standard and Docs site is listed with its authoring surface (TR00790).
+ * A Docs site that accepts no verb is shown rather than hidden: an operator who
+ * cannot see a site they own cannot learn why the CLI refuses it.
  */
 
 /**
@@ -31,16 +32,20 @@ export async function sites(invocation) {
     const reported = boundedList(authorable, MAXIMUM_SITES);
 
     if (authorable.length === 0) {
-      onProgress("This account has no sites that can be authored from the CLI.");
+      onProgress("This account has no standard or Docs sites.");
     } else {
       for (const site of reported.items) {
         // Sanitized on the way to the terminal, raw in the JSON result. Site
         // names are authored by people and can carry terminal controls or bidi
         // overrides; a listing is exactly where that would be used to make one
-        // site read as another the operator then selects.
+        // site read as another the operator then selects. The domain gets the
+        // same treatment; the kind and surface are this CLI's own words.
         const name = sanitizeDiagnostic(site.name, site.siteId);
         const domain = site.primaryDomain ? `  ${sanitizeDiagnostic(site.primaryDomain, "")}` : "";
-        onProgress(`${site.siteId}  ${name}${domain}`);
+        onProgress(`${site.siteId}  ${name}  [${describeSiteKind(site)}]${domain}`);
+        if (site.authoringSurface !== SURFACE_STANDARD) {
+          onProgress(`    ${site.authoringSurface ?? "surface unknown"}: ${describeSurface(site.authoringSurface)}.`);
+        }
       }
       onProgress(`Select one with '${CLI_BINARY_NAME} ${VERB_USE} <name or id>'.`);
     }