@taprootio/site-authoring 0.1.0

package/src/verbs/approve.js

@@ -0,0 +1,178 @@
+import {
+  listSitePages,
+  PAGE_STATUS_DELETED,
+  publishDrafts,
+  TEMPLATE_TYPE_FREE_FORM,
+  withRefusalGuidance,
+} from "../api.js";
+import { VERB_APPROVE } from "../constants.js";
+import { SiteAuthoringError } from "../errors.js";
+import { boundedList, openSession, successResult } from "../session.js";
+import {
+  normalizePagePath,
+  readManifest,
+  readOnlySystem404Projections,
+  SYSTEM_PAGE_NOT_FOUND_PATH,
+  writeManifest,
+} from "../workspace.js";
+
+/**
+ * `approve` — publish the site's drafts.
+ *
+ * `PublishDrafts` *stages*: it moves a page's draft into the approved candidate
+ * pool. Nothing reaches an audience until `deploy` runs, and this verb says so
+ * rather than letting an agent read "publish" as "live".
+ *
+ * The selection is the workspace's own: pages that the manifest knows about and
+ * that Taproot currently reports as carrying a draft. Restricting to the
+ * manifest is deliberate — a site can have drafts an owner is still working on
+ * in the browser, and an agent's approve step must not sweep those into the
+ * next deployment.
+ */
+
+const MAXIMUM_REPORTED = 200;
+// `PublishDrafts` resolves the credential from the first page id in the batch,
+// so batches stay one-site and bounded rather than unbounded and clever.
+const MAXIMUM_BATCH = 100;
+
+export async function approve(invocation) {
+  const { client, config, siteId, onProgress } = await openSession(invocation);
+  const manifest = await readManifest(config.workspaceDir, siteId);
+  const manifestByPageId = new Map(
+    manifest.pages.filter((entry) => typeof entry?.pageId === "string").map((entry) => [entry.pageId, entry]),
+  );
+  const readOnlyProjections = readOnlySystem404Projections(manifest);
+
+  // Positional arguments narrow the selection to those page paths; `cli.js`
+  // hands them over as `pagePaths`, and a programmatic caller can supply the
+  // same key directly. With none, every draft the manifest tracks is staged.
+  //
+  // A path this CLI cannot use is refused by name rather than dropped. Dropping
+  // it silently is the worst available outcome: the remaining selection would
+  // narrow — possibly to nothing — and the verb would exit 0 reporting the work
+  // done, telling an agent that asked to stage a page that it had been staged.
+  const requestedPaths = Array.isArray(invocation.pagePaths)
+    ? new Set(invocation.pagePaths.map((value) => {
+      const normalized = normalizePagePath(value);
+      if (normalized === undefined) {
+        throw new SiteAuthoringError(
+          "approve.page_path_invalid",
+          `'${typeof value === "string" ? value : String(value)}' is not a usable page path. `
+            + "Use the path as 'pull' records it in the manifest — no '.', '..', empty, or backslash segments.",
+          { field: typeof value === "string" ? value : undefined, exitCode: 2 },
+        );
+      }
+      return normalized;
+    }))
+    : undefined;
+
+  return await withRefusalGuidance(onProgress, "approve", async () => {
+    onProgress("Listing the site's pages to find approvable drafts.");
+    const { pages, truncated } = await listSitePages(client, siteId, { onProgress });
+    if (truncated) {
+      // The selection *is* this list. A partial one stages a subset and then
+      // reports success, which reads as "everything is approved".
+      throw new SiteAuthoringError(
+        "approve.live_list_truncated",
+        "The site has more pages than this CLI can enumerate, so the drafts to approve cannot be determined. "
+          + "Nothing was approved.",
+        { field: "pages" },
+      );
+    }
+    const pagesById = new Map(pages.map((summary) => [summary.pageId, summary]));
+    for (const projection of readOnlyProjections) {
+      const summary = pagesById.get(projection.pageId);
+      if (
+        summary?.status === PAGE_STATUS_DELETED
+        || normalizePagePath(summary?.path)?.toLowerCase() !== SYSTEM_PAGE_NOT_FOUND_PATH
+        || summary?.templateType !== TEMPLATE_TYPE_FREE_FORM
+      ) {
+        const index = manifest.pages.indexOf(projection);
+        throw new SiteAuthoringError(
+          "workspace.manifest_invalid",
+          `The read-only page projection at pages[${index}] does not identify the live free-form system 404. `
+            + "Nothing was approved; run 'taproot-site pull' again.",
+          { field: `pages[${index}].pageId` },
+        );
+      }
+    }
+    const readOnlyPageIds = new Set(readOnlyProjections.map((entry) => entry.pageId));
+    if (requestedPaths !== undefined) {
+      const requestedReadOnly = readOnlyProjections.find((entry) =>
+        requestedPaths.has(normalizePagePath(entry.path) ?? entry.path));
+      if (requestedReadOnly !== undefined) {
+        const pagePath = normalizePagePath(requestedReadOnly.path) ?? requestedReadOnly.path;
+        throw new SiteAuthoringError(
+          "approve.page_read_only",
+          `Page path '${pagePath}' is the pulled read-only system 404 projection and cannot be approved.`,
+          { field: pagePath },
+        );
+      }
+    }
+    const candidates = pages.filter((summary) =>
+      summary.status !== PAGE_STATUS_DELETED
+      && summary.hasDraft
+      && manifestByPageId.has(summary.pageId)
+      && !readOnlyPageIds.has(summary.pageId)
+      && (requestedPaths === undefined || requestedPaths.has(normalizePagePath(summary.path) ?? summary.path)));
+
+    if (requestedPaths !== undefined) {
+      const matched = new Set(candidates.map((summary) => normalizePagePath(summary.path) ?? summary.path));
+      const missing = [...requestedPaths].filter((value) => !matched.has(value)).sort();
+      if (missing.length > 0) {
+        // The homepage normalizes to the empty path, which the result
+        // emitters drop as falsy; name it by its documented '/' spelling so
+        // the stable error contract keeps a field for every unknown path.
+        throw new SiteAuthoringError(
+          "approve.page_not_found",
+          `No approvable draft was found for page path '${missing[0] || "/"}'.`,
+          { field: missing[0] || "/" },
+        );
+      }
+    }
+
+    if (candidates.length === 0) {
+      onProgress("No page in this workspace is carrying a draft; there is nothing to approve.");
+      return successResult(VERB_APPROVE, siteId, {
+        approved: { total: 0, items: [] },
+        stagedNotDeployed: true,
+        nextStep: "deploy --staging",
+      });
+    }
+
+    const approved = [];
+    let manifestDirty = false;
+    try {
+      for (let offset = 0; offset < candidates.length; offset += MAXIMUM_BATCH) {
+        const batch = candidates.slice(offset, offset + MAXIMUM_BATCH);
+        onProgress(`Approving ${batch.length} draft page(s).`);
+        const summaries = await publishDrafts(client, batch.map((summary) => summary.pageId));
+        manifestDirty = true;
+        for (const summary of summaries) {
+          approved.push({ pageId: summary.pageId, path: summary.path, status: summary.status });
+          const entry = manifestByPageId.get(summary.pageId);
+          if (entry !== undefined) {
+            entry.status = summary.status;
+            entry.hasDraft = summary.hasDraft;
+            entry.pendingApproval = false;
+          }
+        }
+      }
+    } finally {
+      if (manifestDirty) await writeManifest(config.workspaceDir, manifest);
+    }
+
+    const reported = boundedList(approved, MAXIMUM_REPORTED);
+    onProgress(`Approved ${approved.length} page(s). Nothing is published until 'taproot-site deploy' runs.`);
+    return successResult(VERB_APPROVE, siteId, {
+      approved: {
+        total: approved.length,
+        items: reported.items,
+        ...(reported.truncated ? { itemsTruncated: true } : {}),
+      },
+      // Said explicitly so a caller cannot read "approve" as "live".
+      stagedNotDeployed: true,
+      nextStep: "deploy --staging",
+    });
+  });
+}

package/src/verbs/deploy.js

@@ -0,0 +1,327 @@
+import {
+  DEPLOYMENT_ENVIRONMENT_PRODUCTION,
+  DEPLOYMENT_ENVIRONMENT_STAGING,
+  DEPLOYMENT_STATUS_COMPLETED,
+  deploySite,
+  getPublishingReadiness,
+  getStagingPreviewStatus,
+  listDeployments,
+  listSitePages,
+  PAGE_STATUS_APPROVED,
+  waitForDeployment,
+  withRefusalGuidance,
+} from "../api.js";
+import {
+  DEPLOY_TARGET_PRODUCTION,
+  DEPLOY_TARGET_STAGING,
+  VERB_DEPLOY,
+} from "../constants.js";
+import { SiteAuthoringError } from "../errors.js";
+import { boundedList, openSession, successResult } from "../session.js";
+import { CANDIDATE_SELECTABLE_SETTINGS_TYPES } from "../settings-catalog.js";
+import { readManifest, writeManifest } from "../workspace.js";
+
+/**
+ * `deploy --staging` / `deploy --production` — readiness, deploy, poll to
+ * completion.
+ *
+ * Staging publishes a *candidate*: approved pages, navigation, and the
+ * candidate-selectable settings groups. The server refuses an empty candidate,
+ * so the CLI refuses it first and says what to do about it.
+ *
+ * Production is a promotion and only a promotion. `DeploySite` rejects a
+ * production request that carries both a `stagingDeploymentId` and explicit
+ * candidate changes ("Choose either a completed staging deployment or explicit
+ * candidate changes, not both"), so the CLI never sends a selection alongside
+ * one — and refuses locally if a caller supplies both.
+ *
+ * Completion is observed by polling `GET /v1/sites/{id}/deployments`. The SSE
+ * deployment stream is user-session-scoped and therefore unreachable from a
+ * key-authorized CLI; the repo's no-polling rule governs UX surfaces and does
+ * not reach this one. proto3 omits zero-valued enums, so a deployment listed
+ * without a status is queued, not unknown.
+ *
+ * The published-page quota has no pre-flight read anywhere on the contract. It
+ * surfaces here, at deploy time, as an `UpgradePrompt` field violation —
+ * classified `plan_limit` and announced prominently by `announceRefusal` — and
+ * the CLI never invents the numeric limit it was not told.
+ */
+
+const MAXIMUM_REPORTED_BLOCKERS = 50;
+const STAGING_ROUTE_PROBE_MILLISECONDS = 5_000;
+// Staged page ids ride in the readiness query string, so a very large candidate
+// is checked at site level instead of pushing an unbounded URL at the API.
+const MAXIMUM_READINESS_PAGE_IDS = 100;
+
+function usageError(code, message, field) {
+  return new SiteAuthoringError(code, message, { field, exitCode: 2 });
+}
+
+function explicitSelection(invocation) {
+  const stagedPageIds = Array.isArray(invocation.stagedPageIds) ? invocation.stagedPageIds : undefined;
+  const selectedSettingsTypes = Array.isArray(invocation.selectedSettingsTypes)
+    ? invocation.selectedSettingsTypes
+    : undefined;
+  const includeNavigation = typeof invocation.includeNavigation === "boolean"
+    ? invocation.includeNavigation
+    : undefined;
+  const present = (stagedPageIds !== undefined && stagedPageIds.length > 0)
+    || (selectedSettingsTypes !== undefined && selectedSettingsTypes.length > 0)
+    || includeNavigation === true;
+  return { stagedPageIds, selectedSettingsTypes, includeNavigation, present };
+}
+
+function manifestSettingsTypes(manifest) {
+  const pulled = Array.isArray(manifest?.settings)
+    ? manifest.settings.map((entry) => entry?.settingsType).filter((value) => typeof value === "string")
+    : [];
+  return CANDIDATE_SELECTABLE_SETTINGS_TYPES.filter((type) => pulled.includes(type));
+}
+
+async function recordDeployment(config, manifest, key, deployment) {
+  if (manifest === undefined) return;
+  manifest.deployments = { ...(manifest.deployments ?? {}) };
+  manifest.deployments[key] = {
+    id: deployment.id,
+    status: deployment.status,
+    completedAt: deployment.completedAt,
+  };
+  await writeManifest(config.workspaceDir, manifest);
+}
+
+async function resolveStagingDeploymentId(client, siteId, invocation, manifest, onProgress) {
+  if (typeof invocation.stagingDeploymentId === "string" && invocation.stagingDeploymentId !== "") {
+    return invocation.stagingDeploymentId;
+  }
+  const recorded = manifest?.deployments?.staging;
+  if (recorded !== null && typeof recorded === "object" && typeof recorded.id === "string" && recorded.id !== "") {
+    return recorded.id;
+  }
+  onProgress("Looking for the most recent completed staging deployment to promote.");
+  const { deployments } = await listDeployments(client, siteId, { environment: DEPLOYMENT_ENVIRONMENT_STAGING });
+  const completed = deployments.find((deployment) => deployment.status === DEPLOYMENT_STATUS_COMPLETED);
+  if (completed === undefined) {
+    throw new SiteAuthoringError(
+      "deploy.staging_required",
+      "Production promotes a completed staging deployment, and this site has none. "
+        + "Run 'taproot-site deploy --staging' first.",
+      { field: "stagingDeploymentId" },
+    );
+  }
+  return completed.id;
+}
+
+function reportReadiness(readiness) {
+  const blockers = boundedList(readiness.blockers, MAXIMUM_REPORTED_BLOCKERS);
+  return {
+    state: readiness.state,
+    approvedPageCount: readiness.approvedPageCount,
+    selectedPageCount: readiness.selectedPageCount,
+    blockedPageCount: readiness.blockedPageCount,
+    hasCandidateChanges: readiness.hasCandidateChanges,
+    blockers: blockers.items,
+    ...(blockers.truncated ? { blockersTruncated: true } : {}),
+  };
+}
+
+function stagingWarning(message) {
+  return { routeCheck: "unresolved", warning: message };
+}
+
+async function inspectStagingPreview(client, siteId, onProgress) {
+  let status;
+  try {
+    status = await getStagingPreviewStatus(client, siteId);
+  } catch {
+    const warning = "The staging deployment completed, but Taproot could not report its staging URL."
+      + " Check the site's staging-host configuration before treating the deployment as viewable.";
+    onProgress(`Warning: ${warning}`);
+    return { url: "", ...stagingWarning(warning) };
+  }
+  if (!status.ready) {
+    const warning = "The staging deployment completed, but Taproot does not report a ready staging URL.";
+    onProgress(`Warning: ${warning}`);
+    return { url: "", ...stagingWarning(warning) };
+  }
+
+  const stagingUrl = status.stagingUrl;
+  onProgress(`Staging URL: ${stagingUrl}`);
+  let response;
+  try {
+    const timeout = client.timeoutSignal(STAGING_ROUTE_PROBE_MILLISECONDS);
+    const signal = client.signal ? AbortSignal.any([client.signal, timeout]) : timeout;
+    response = await client.fetch(stagingUrl, {
+      method: "GET",
+      redirect: "manual",
+      signal,
+      headers: {
+        accept: "text/html",
+        "user-agent": "taproot-site/staging-route-check",
+      },
+    });
+  } catch {
+    const warning = `The staging deployment completed at ${stagingUrl}, but the host could not be reached.`;
+    onProgress(`Warning: ${warning}`);
+    return { url: stagingUrl, ...stagingWarning(warning) };
+  }
+
+  const location = response.headers.get("location");
+  await response.body?.cancel().catch(() => {});
+  let handoff;
+  try {
+    handoff = location ? new URL(location, stagingUrl) : undefined;
+  } catch {
+    handoff = undefined;
+  }
+  const stagingHost = new URL(stagingUrl).hostname;
+  const resolvesToSite = response.status >= 300
+    && response.status < 400
+    && handoff?.protocol === "https:"
+    && handoff.username === ""
+    && handoff.password === ""
+    && handoff.hash === ""
+    && handoff.pathname === "/api/v1/staging-preview/handoff"
+    && handoff.searchParams.getAll("siteId").length === 1
+    && handoff.searchParams.get("siteId") === siteId
+    && handoff.searchParams.getAll("host").length === 1
+    && handoff.searchParams.get("host") === stagingHost;
+  if (resolvesToSite) return { url: stagingUrl, routeCheck: "resolved" };
+
+  const warning = `The staging deployment completed at ${stagingUrl}, but the host returned HTTP ${response.status}`
+    + " instead of this site's staging gate. The deployment artifacts are complete, but the URL is not viewable.";
+  onProgress(`Warning: ${warning}`);
+  return { url: stagingUrl, ...stagingWarning(warning) };
+}
+
+export async function deploy(invocation) {
+  const target = invocation.deployTarget;
+  if (target !== DEPLOY_TARGET_STAGING && target !== DEPLOY_TARGET_PRODUCTION) {
+    throw usageError(
+      "deploy.target_missing",
+      "deploy requires exactly one of --staging or --production.",
+      "deployTarget",
+    );
+  }
+  const { client, config, siteId, now, onProgress } = await openSession(invocation);
+  const manifest = await readManifest(config.workspaceDir, siteId, { required: false });
+  const selection = explicitSelection(invocation);
+
+  return await withRefusalGuidance(onProgress, "deploy", async () => {
+    if (target === DEPLOY_TARGET_PRODUCTION) {
+      if (selection.present) {
+        throw usageError(
+          "deploy.production_selection",
+          "deploy --production promotes a completed staging deployment and cannot also carry an explicit page, "
+            + "settings, or navigation selection. Deploy the selection to staging first, then promote it.",
+          "stagingDeploymentId",
+        );
+      }
+      const stagingDeploymentId = await resolveStagingDeploymentId(client, siteId, invocation, manifest, onProgress);
+      onProgress(`Checking publishing readiness before promoting staging deployment ${stagingDeploymentId}.`);
+      const readiness = await getPublishingReadiness(client, siteId);
+      const created = await deploySite(client, siteId, {
+        siteId,
+        environment: DEPLOYMENT_ENVIRONMENT_PRODUCTION,
+        stagingDeploymentId,
+      });
+      onProgress(`Production deployment ${created.id} accepted; waiting for it to complete.`);
+      const completed = await waitForDeployment(client, {
+        siteId,
+        deploymentId: created.id,
+        environment: DEPLOYMENT_ENVIRONMENT_PRODUCTION,
+        onProgress,
+        now,
+      });
+      await recordDeployment(config, manifest, "production", completed);
+      return successResult(VERB_DEPLOY, siteId, {
+        target,
+        environment: DEPLOYMENT_ENVIRONMENT_PRODUCTION,
+        promotedStagingDeploymentId: stagingDeploymentId,
+        deployment: completed,
+        readiness: reportReadiness(readiness),
+      });
+    }
+
+    onProgress("Listing approved pages for the staging candidate.");
+    const { pages, truncated } = await listSitePages(client, siteId, { onProgress });
+    if (truncated) {
+      // The candidate is built from this list, so a partial one silently
+      // publishes a subset of what was approved — and the deployment that
+      // follows reports success.
+      throw new SiteAuthoringError(
+        "deploy.live_list_truncated",
+        "The site has more pages than this CLI can enumerate, so the staging candidate would omit approved "
+          + "pages without saying so. Nothing was deployed.",
+        { field: "stagedPageIds" },
+      );
+    }
+    const stagedPageIds = selection.stagedPageIds
+      ?? pages.filter((summary) => summary.status === PAGE_STATUS_APPROVED).map((summary) => summary.pageId);
+    const selectedSettingsTypes = selection.selectedSettingsTypes ?? manifestSettingsTypes(manifest);
+    const includeNavigation = selection.includeNavigation ?? manifest?.navigation !== undefined;
+    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' (and 'taproot-site pull' to pick up navigation and settings) first.",
+        { field: "Candidate" },
+      );
+    }
+
+    const candidate = {
+      stagedPageIds,
+      selectedSettingsTypes,
+      includeNavigation,
+    };
+    onProgress(
+      `Checking publishing readiness for ${stagedPageIds.length} page(s), `
+      + `${selectedSettingsTypes.length} settings group(s), `
+      + `navigation ${includeNavigation ? "included" : "excluded"}.`,
+    );
+    const readiness = await getPublishingReadiness(client, siteId, {
+      ...candidate,
+      stagedPageIds: stagedPageIds.length > MAXIMUM_READINESS_PAGE_IDS ? undefined : stagedPageIds,
+    });
+    if (readiness.blockers.length > 0) {
+      throw new SiteAuthoringError(
+        "deploy.media_blocked",
+        `Taproot reports ${readiness.blockers.length} media blocker(s) on this candidate, starting with '${
+          readiness.blockers[0].uploadedName || readiness.blockers[0].imageId
+        }': ${readiness.blockers[0].message || readiness.blockers[0].state}.`,
+        { field: readiness.blockers[0].imageId || "blockers", status: readiness.blockers[0].state },
+      );
+    }
+    if (!readiness.hasCandidateChanges) {
+      onProgress("Taproot reports this candidate contains no changes; deploying it anyway would be a no-op.");
+    }
+
+    const created = await deploySite(client, siteId, {
+      siteId,
+      environment: DEPLOYMENT_ENVIRONMENT_STAGING,
+      ...candidate,
+    });
+    onProgress(`Staging deployment ${created.id} accepted; waiting for it to complete.`);
+    const completed = await waitForDeployment(client, {
+      siteId,
+      deploymentId: created.id,
+      environment: DEPLOYMENT_ENVIRONMENT_STAGING,
+      onProgress,
+      now,
+    });
+    await recordDeployment(config, manifest, "staging", completed);
+    const stagingPreview = await inspectStagingPreview(client, siteId, onProgress);
+    return successResult(VERB_DEPLOY, siteId, {
+      target,
+      environment: DEPLOYMENT_ENVIRONMENT_STAGING,
+      selection: {
+        stagedPageCount: stagedPageIds.length,
+        selectedSettingsTypes,
+        includeNavigation,
+      },
+      deployment: completed,
+      readiness: reportReadiness(readiness),
+      stagingPreview,
+      nextStep: "deploy --production",
+    });
+  });
+}

package/src/verbs/env.js

@@ -0,0 +1,89 @@
+import {
+  CLI_BINARY_NAME,
+  DEFAULT_API_BASE_URL,
+  ENVIRONMENT_LOCAL,
+  ENVIRONMENT_PRODUCTION,
+  VERB_ENV,
+  VERB_LOGIN,
+} from "../constants.js";
+import { credentialApiOrigin, findCredential } from "../credentials.js";
+import { SiteAuthoringError } from "../errors.js";
+import {
+  environmentNameFor,
+  readStoredApiBaseUrl,
+  resolveEnvironmentSelector,
+  settingsPath,
+  writeStoredApiBaseUrl,
+} from "../settings.js";
+import { successResult } from "../session.js";
+
+/**
+ * `taproot-site env [production|local|<url>]` — which Taproot to talk to.
+ *
+ * With no argument it reports; with one it switches. Switching writes nothing
+ * but the endpoint: credentials are stored per origin, so moving between
+ * environments and back finds the sign-in that was already there rather than
+ * discarding it.
+ */
+export async function env(invocation) {
+  const environment = invocation.environment ?? process.env;
+  const selector = typeof invocation.environmentSelector === "string"
+    ? invocation.environmentSelector.trim()
+    : undefined;
+  const onProgress = invocation.onProgress ?? (() => {});
+
+  const current = (await readStoredApiBaseUrl(environment)) ?? DEFAULT_API_BASE_URL;
+  const apiBaseUrl = selector === undefined ? current : resolveApiBaseUrl(selector);
+
+  // The credential store is read *before* the switch is written, though it is
+  // only needed for the report afterwards. A corrupt store refuses; if that
+  // refusal came after the write, the command would exit non-zero having
+  // silently repointed every later command at a different Taproot — the
+  // worst combination, a failure that changed something. Read first, nothing
+  // changes on failure.
+  const { credential } = await findCredential(environment, credentialApiOrigin(apiBaseUrl));
+
+  if (selector !== undefined && apiBaseUrl !== current) {
+    await writeStoredApiBaseUrl(environment, apiBaseUrl);
+  }
+
+  // Reported for both forms, because "which Taproot am I pointed at, and am I
+  // signed in to it" is the actual question behind running this at all — and
+  // after a switch the answer usually changes.
+  const name = environmentNameFor(apiBaseUrl);
+
+  if (selector === undefined) {
+    onProgress(`Talking to ${name} (${credentialApiOrigin(apiBaseUrl)}).`);
+  } else if (apiBaseUrl === current) {
+    onProgress(`Already talking to ${name} (${credentialApiOrigin(apiBaseUrl)}).`);
+  } else {
+    onProgress(`Now talking to ${name} (${credentialApiOrigin(apiBaseUrl)}).`);
+  }
+  onProgress(
+    credential === undefined
+      ? `Not signed in there yet — run '${CLI_BINARY_NAME} ${VERB_LOGIN}'.`
+      : `Signed in there as account ${credential.accountId}.`,
+  );
+
+  return successResult(VERB_ENV, undefined, {
+    environment: name,
+    apiOrigin: credentialApiOrigin(apiBaseUrl),
+    signedIn: credential !== undefined,
+    settingsPath: settingsPath(environment),
+    changed: selector !== undefined && apiBaseUrl !== current,
+  });
+}
+
+function resolveApiBaseUrl(selector) {
+  try {
+    return resolveEnvironmentSelector(selector);
+  } catch {
+    throw new SiteAuthoringError(
+      "env.unknown",
+      `'${selector}' is not a Taproot this CLI talks to. `
+        + `Use '${CLI_BINARY_NAME} ${VERB_ENV} ${ENVIRONMENT_PRODUCTION}', `
+        + `'${CLI_BINARY_NAME} ${VERB_ENV} ${ENVIRONMENT_LOCAL}', or an explicit loopback URL ending in '/api'.`,
+      { field: "environmentSelector", exitCode: 2 },
+    );
+  }
+}