@taprootio/site-authoring 0.1.0

package/src/verbs/sites.js

@@ -0,0 +1,57 @@
+import { listAuthorableSites, withRefusalGuidance } from "../api.js";
+import { CLI_BINARY_NAME, VERB_SITES, VERB_USE } from "../constants.js";
+import { sanitizeDiagnostic } from "../errors.js";
+import { boundedList, openAccountSession, successResult } from "../session.js";
+
+/**
+ * `taproot-site sites` — the sites this sign-in may author.
+ *
+ * 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.
+ */
+
+/**
+ * More than a terminal can usefully read at once, and well inside the result
+ * size bound. A studio account with more sites than this gets a reported
+ * truncation rather than a failed command.
+ */
+const MAXIMUM_SITES = 200;
+
+export async function sites(invocation) {
+  const { client, signIn, onProgress } = await openAccountSession(invocation);
+
+  return await withRefusalGuidance(onProgress, "site list", async () => {
+    const authorable = await listAuthorableSites(client);
+    const reported = boundedList(authorable, MAXIMUM_SITES);
+
+    if (authorable.length === 0) {
+      onProgress("This account has no sites that can be authored from the CLI.");
+    } 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.
+        const name = sanitizeDiagnostic(site.name, site.siteId);
+        const domain = site.primaryDomain ? `  ${sanitizeDiagnostic(site.primaryDomain, "")}` : "";
+        onProgress(`${site.siteId}  ${name}${domain}`);
+      }
+      onProgress(`Select one with '${CLI_BINARY_NAME} ${VERB_USE} <name or id>'.`);
+    }
+
+    return successResult(VERB_SITES, undefined, {
+      accountId: signIn.accountId,
+      sites: {
+        total: authorable.length,
+        items: reported.items,
+        ...(reported.truncated ? { itemsTruncated: true } : {}),
+      },
+    });
+  });
+}

package/src/verbs/status.js

@@ -0,0 +1,94 @@
+import {
+  getPublishingReadiness,
+  IMAGE_PROCESSING_STATE_COMPLETE,
+  IMAGE_PROCESSING_STATE_FAILED,
+  listDeployments,
+  listSiteImages,
+  withRefusalGuidance,
+} from "../api.js";
+import { VERB_STATUS } from "../constants.js";
+import { boundedList, openSession, successResult } from "../session.js";
+
+/**
+ * `status` — deployments, publishing readiness, and image processing.
+ *
+ * Broken references are deliberately absent. `GetSiteBrokenReferences` is
+ * session-only under TR00602's read list, and TR00604 adds no server surface,
+ * so there is no key-authorized way to read them. The verb says that out loud —
+ * on the human channel and as a field in the JSON result — rather than
+ * reporting a clean site and implying a coverage it does not have.
+ */
+
+const MAXIMUM_DEPLOYMENTS = 20;
+const MAXIMUM_FAILED_IMAGES = 50;
+const MAXIMUM_BLOCKERS = 50;
+
+const BROKEN_REFERENCES_NOTE =
+  "GetSiteBrokenReferences is session-only on the shipped contract, so a key-authorized CLI cannot read it.";
+
+export async function status(invocation) {
+  const { client, siteId, onProgress } = await openSession(invocation);
+
+  return await withRefusalGuidance(onProgress, "status check", async () => {
+    onProgress("Reading publishing readiness.");
+    const readiness = await getPublishingReadiness(client, siteId);
+    onProgress("Reading the deployment log.");
+    const {
+      deployments,
+      truncated: deploymentsTruncated,
+    } = await listDeployments(client, siteId, { pageSize: MAXIMUM_DEPLOYMENTS });
+    onProgress("Reading image processing state.");
+    const { images, summary, truncated } = await listSiteImages(client, siteId);
+
+    const byState = {};
+    for (const image of images) {
+      byState[image.processingState] = (byState[image.processingState] ?? 0) + 1;
+    }
+    const failedImages = boundedList(
+      images
+        .filter((image) => image.processingState === IMAGE_PROCESSING_STATE_FAILED)
+        .map((image) => ({
+          imageId: image.imageId,
+          uploadedName: image.uploadedName,
+          reason: image.processingFailureReason,
+        })),
+      MAXIMUM_FAILED_IMAGES,
+    );
+    const reportedDeployments = boundedList(deployments, MAXIMUM_DEPLOYMENTS);
+    const blockers = boundedList(readiness.blockers, MAXIMUM_BLOCKERS);
+
+    onProgress(`Broken references are not reported: ${BROKEN_REFERENCES_NOTE}`);
+
+    return successResult(VERB_STATUS, siteId, {
+      readiness: {
+        state: readiness.state,
+        approvedPageCount: readiness.approvedPageCount,
+        blockedPageCount: readiness.blockedPageCount,
+        hasCandidateChanges: readiness.hasCandidateChanges,
+        hasSuccessfulStagingDeployment: readiness.hasSuccessfulStagingDeployment,
+        blockers: blockers.items,
+        ...(blockers.truncated ? { blockersTruncated: true } : {}),
+      },
+      deployments: {
+        // One page of the log, not the site's history. `listTruncated` says so
+        // rather than letting `total` read as a count of every deployment the
+        // site has ever had.
+        total: deployments.length,
+        items: reportedDeployments.items,
+        ...(reportedDeployments.truncated ? { itemsTruncated: true } : {}),
+        ...(deploymentsTruncated ? { listTruncated: true } : {}),
+      },
+      images: {
+        total: summary.totalImages,
+        processing: summary.processingImages,
+        complete: byState[IMAGE_PROCESSING_STATE_COMPLETE] ?? 0,
+        failed: byState[IMAGE_PROCESSING_STATE_FAILED] ?? 0,
+        byState,
+        failedItems: failedImages.items,
+        ...(failedImages.truncated ? { failedItemsTruncated: true } : {}),
+        ...(truncated ? { listTruncated: true } : {}),
+      },
+      brokenReferences: { covered: false, reason: BROKEN_REFERENCES_NOTE },
+    });
+  });
+}

package/src/verbs/theme-push.js

@@ -0,0 +1,197 @@
+import { getSettingsGroup, saveSiteFooterSettings, setSetting, withRefusalGuidance } from "../api.js";
+import {
+  applyFooterColors,
+  buildAppearanceScalarOperations,
+  footerColorOverlay,
+} from "../appearance-contract.js";
+import { VERB_THEME_PUSH } from "../constants.js";
+import { SiteAuthoringError } from "../errors.js";
+import { computeFooterDraftHash } from "../footer-draft-hash.js";
+import { projectFooterSettingsForWorkspace } from "../footer-contract.js";
+import {
+  advanceFooterManifest,
+  readAppearanceWorkspaceContext,
+  requireFooterContentPushed,
+} from "../footer-workspace.js";
+import { boundedList, openSession, successResult } from "../session.js";
+import {
+  SETTINGS_TYPE_BRAND,
+  SETTINGS_TYPE_SITE_HEADER,
+  SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES,
+  SETTINGS_TYPE_TAPROOT_STYLES,
+} from "../settings-catalog.js";
+import {
+  validateAndEncodeThemePair,
+} from "../theme-validation.js";
+import {
+  readWorkspaceJson,
+  SETTINGS_DIRECTORY,
+  WORKSPACE_LIMITS,
+  workspaceFileExists,
+  writeWorkspaceJson,
+} from "../workspace.js";
+
+const SETTINGS_FILES = Object.freeze({
+  [SETTINGS_TYPE_TAPROOT_STYLES]: "taproot-styles.json",
+  [SETTINGS_TYPE_BRAND]: "brand.json",
+  [SETTINGS_TYPE_SITE_HEADER]: "site-header.json",
+  [SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES]: "site-publishing-preferences.json",
+});
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function fail(code, message, field) {
+  throw new SiteAuthoringError(code, message, { field });
+}
+
+async function readSettingsDocument(workspaceDir, siteId, settingsType, expectedEntityId = siteId) {
+  const file = `${SETTINGS_DIRECTORY}/${SETTINGS_FILES[settingsType]}`;
+  if (!await workspaceFileExists(workspaceDir, file)) {
+    fail("theme.settings_missing", `Workspace file '${file}' is missing. Run 'taproot-site pull' first.`, file);
+  }
+  const document = await readWorkspaceJson(workspaceDir, file, WORKSPACE_LIMITS.settingsBytes);
+  if (!isPlainObject(document) || !isPlainObject(document.settings)) {
+    fail("theme.settings_invalid", `${file} must be the settings document written by pull.`, file);
+  }
+  if (document.entityId !== expectedEntityId || document.settingsType !== settingsType) {
+    const binding = expectedEntityId === siteId ? "site" : "fixture entity";
+    const guidance = expectedEntityId === siteId ? " Run pull into this workspace again." : "";
+    fail(
+      "theme.settings_site_mismatch",
+      `${file} is not bound to ${binding} ${expectedEntityId} and settings group ${settingsType}.${guidance}`,
+      file,
+    );
+  }
+  return document.settings;
+}
+
+/** The complete local validation phase shared by live push and offline fixtures. */
+export async function validateThemeWorkspace(workspaceDir, siteId, knownImageIds, expectedEntityIds) {
+  const [style, brand, header, publishing] = await Promise.all([
+    readSettingsDocument(
+      workspaceDir,
+      siteId,
+      SETTINGS_TYPE_TAPROOT_STYLES,
+      expectedEntityIds?.get(SETTINGS_TYPE_TAPROOT_STYLES),
+    ),
+    readSettingsDocument(
+      workspaceDir,
+      siteId,
+      SETTINGS_TYPE_BRAND,
+      expectedEntityIds?.get(SETTINGS_TYPE_BRAND),
+    ),
+    readSettingsDocument(
+      workspaceDir,
+      siteId,
+      SETTINGS_TYPE_SITE_HEADER,
+      expectedEntityIds?.get(SETTINGS_TYPE_SITE_HEADER),
+    ),
+    readSettingsDocument(
+      workspaceDir,
+      siteId,
+      SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES,
+      expectedEntityIds?.get(SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES),
+    ),
+  ]);
+  const themes = validateAndEncodeThemePair(style.lightTheme, style.darkTheme);
+  const scalarOperations = buildAppearanceScalarOperations(
+    {
+      [SETTINGS_TYPE_TAPROOT_STYLES]: style,
+      [SETTINGS_TYPE_BRAND]: brand,
+      [SETTINGS_TYPE_SITE_HEADER]: header,
+    },
+    knownImageIds,
+  );
+  const footerColors = footerColorOverlay(publishing.footerSettings);
+  return { style, brand, header, publishing, themes, scalarOperations, footerColors };
+}
+
+export async function themePush(invocation) {
+  const { client, config, siteId, onProgress } = await openSession(invocation);
+  const appearanceContext = await readAppearanceWorkspaceContext(config.workspaceDir, siteId);
+  const { publishing, themes, scalarOperations, footerColors } = await validateThemeWorkspace(
+    config.workspaceDir,
+    siteId,
+    appearanceContext.knownImageIds,
+  );
+  // The fresh footer read below replaces the workspace document, so refuse
+  // while it still carries footer-content edits that footer push has not
+  // saved. Colour-only differences are theme push's own to write.
+  requireFooterContentPushed(appearanceContext.footer, publishing.footerSettings);
+  onProgress(`Validated the complete light/dark theme pair and ${scalarOperations.length} appearance settings.`);
+  for (const warning of themes.warnings) onProgress(`Espalier warning: ${warning}`);
+
+  const written = [];
+  try {
+    await withRefusalGuidance(onProgress, "theme push", async () => {
+      // Re-read immediately before the concurrency-protected save and carry only
+      // the ten workspace color values across. Footer prose, links, and images
+      // always come from this fresh server document, never the pull snapshot.
+      const currentPublishing = await getSettingsGroup(
+        client,
+        siteId,
+        SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES,
+      );
+      const currentFooter = currentPublishing.sitePublishingPreferences?.footerSettings ?? {};
+      const nextFooter = applyFooterColors(currentFooter, footerColors);
+      const footerResponse = await saveSiteFooterSettings(
+        client,
+        siteId,
+        nextFooter,
+        computeFooterDraftHash(currentFooter),
+      );
+      written.push("footerSettings.light/dark colors");
+      if (!isPlainObject(footerResponse.footerSettings)) {
+        throw new SiteAuthoringError(
+          "api.footer_settings_contract",
+          "Taproot returned no normalized footer document after saving the color overlay.",
+          { field: "footerSettings" },
+        );
+      }
+      const savedFooter = footerResponse.footerSettings;
+      const projectedFooter = projectFooterSettingsForWorkspace(savedFooter);
+      await writeWorkspaceJson(
+        config.workspaceDir,
+        `${SETTINGS_DIRECTORY}/${SETTINGS_FILES[SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES]}`,
+        {
+          entityId: siteId,
+          settingsType: SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES,
+          settings: { ...publishing, footerSettings: projectedFooter },
+        },
+      );
+      await advanceFooterManifest(config.workspaceDir, siteId, projectedFooter);
+      onProgress("Saved the light and dark footer scheme colors over the current footer document.");
+
+      for (const operation of scalarOperations) {
+        await setSetting(client, siteId, operation.settingsType, operation.setting, operation.value);
+        written.push(`${operation.settingsType}.${operation.setting}`);
+        onProgress(`Saved ${operation.setting}.`);
+      }
+
+      // The pair is locally valid and complete before either mutation starts.
+      // These writes are last so the first one is also the point at which the
+      // server marks the theme externally managed and the visual editor adopts
+      // its guarded mode.
+      await setSetting(client, siteId, SETTINGS_TYPE_TAPROOT_STYLES, "lightTheme", themes.light);
+      written.push(`${SETTINGS_TYPE_TAPROOT_STYLES}.lightTheme`);
+      await setSetting(client, siteId, SETTINGS_TYPE_TAPROOT_STYLES, "darkTheme", themes.dark);
+      written.push(`${SETTINGS_TYPE_TAPROOT_STYLES}.darkTheme`);
+      onProgress("Saved both complete themes; Brand & Style now treats the color model as externally managed.");
+    });
+  } catch (error) {
+    if (error instanceof SiteAuthoringError && written.length > 0) {
+      throw error.withCompletedWrites(written);
+    }
+    throw error;
+  }
+
+  return successResult(VERB_THEME_PUSH, siteId, {
+    written: boundedList(written, 100),
+    warnings: {
+      items: themes.warnings,
+      count: themes.warningCount,
+      ...(themes.warningsTruncated ? { truncated: true } : {}),
+    },
+  });
+}

package/src/verbs/use.js

@@ -0,0 +1,129 @@
+import path from "node:path";
+
+import { listAuthorableSites, withRefusalGuidance } from "../api.js";
+import { atomicWriteFile } from "../atomic-file.js";
+import {
+  CLI_BINARY_NAME,
+  CONFIG_FILE_NAME,
+  CONFIG_VERSION,
+  DEFAULT_WORKSPACE_DIR,
+  VERB_SITES,
+  VERB_USE,
+} from "../constants.js";
+import { isCanonicalUuid, sanitizeDiagnostic, SiteAuthoringError } from "../errors.js";
+import { openAccountSession, successResult } from "../session.js";
+
+/**
+ * `taproot-site use <site>` — choose the site the next command writes to.
+ *
+ * The half of TR00645's onboarding fix that `sites` sets up: rather than
+ * hand-writing a site id into JSON, an operator names a site and this records
+ * the choice. Resolution accepts an id, an exact name, or an unambiguous
+ * case-insensitive name, because the id is the thing a human is least able to
+ * type from memory and most likely to get subtly wrong.
+ *
+ * An ambiguous name is refused rather than guessed. Two sites called "Blog" on
+ * one account is a real situation, and picking one of them silently would point
+ * every subsequent write at a site the operator did not choose.
+ */
+
+function selectSite(authorable, selector) {
+  if (isCanonicalUuid(selector)) {
+    return authorable.filter((site) => site.siteId === selector);
+  }
+  const exact = authorable.filter((site) => site.name === selector);
+  if (exact.length > 0) return exact;
+  const folded = selector.toLocaleLowerCase();
+  return authorable.filter((site) => site.name.toLocaleLowerCase() === folded);
+}
+
+export async function use(invocation) {
+  const selector = typeof invocation.siteSelector === "string" ? invocation.siteSelector.trim() : "";
+  if (selector.length === 0) {
+    throw new SiteAuthoringError(
+      "use.selector_missing",
+      `Name the site to use: '${CLI_BINARY_NAME} ${VERB_USE} <name or id>'. `
+        + `'${CLI_BINARY_NAME} ${VERB_SITES}' lists them.`,
+      { field: "selector", exitCode: 2 },
+    );
+  }
+
+  const { client, config, signIn, onProgress } = await openAccountSession(invocation);
+  // With no configuration yet, this is the command that creates one, in the
+  // directory the operator ran it from.
+  const configPath = config?.configPath
+    ?? path.join(path.resolve(invocation.cwd ?? process.cwd()), CONFIG_FILE_NAME);
+
+  return await withRefusalGuidance(onProgress, "site selection", async () => {
+    const authorable = await listAuthorableSites(client);
+    const matches = selectSite(authorable, selector);
+
+    if (matches.length === 0) {
+      throw new SiteAuthoringError(
+        "use.site_unknown",
+        `No site on this account matches '${selector}'. `
+          + `Run '${CLI_BINARY_NAME} ${VERB_SITES}' to see what is available.`,
+        { field: "selector" },
+      );
+    }
+    if (matches.length > 1) {
+      throw new SiteAuthoringError(
+        "use.site_ambiguous",
+        `More than one site is named '${selector}': ${matches.map((site) => site.siteId).join(", ")}. `
+          + "Use the site id instead.",
+        { field: "selector" },
+      );
+    }
+
+    const [site] = matches;
+    // An existing configuration keeps its workspace; a new one gets a real
+    // child directory. Never "." — `validateWorkspaceDirectoryText` rejects a
+    // "." segment outright, so writing it would produce a configuration the
+    // very next command refuses to load.
+    const workspaceDir = config === undefined
+      ? DEFAULT_WORKSPACE_DIR
+      : path.relative(config.configDirectory, config.workspaceDir) || DEFAULT_WORKSPACE_DIR;
+    const contents = `${
+      JSON.stringify(
+        {
+          configVersion: CONFIG_VERSION,
+          siteId: site.siteId,
+          workspaceDir,
+          // No endpoint. Which Taproot this is talking to lives with the
+          // credential, per machine — writing it here would pin a project to
+          // whichever environment happened to be selected when someone ran
+          // `use`, which is how a repository ends up authoring against local
+          // in CI.
+        },
+        undefined,
+        2,
+      )
+    }\n`;
+
+    // The configuration is not a secret, so 0644 rather than the credential
+    // store's 0600 — but the write is the same atomic one, because a
+    // half-written config would leave the next command pointed at nothing.
+    await atomicWriteFile(configPath, contents, {
+      mode: 0o644,
+      failures: {
+        inspect: () =>
+          new SiteAuthoringError("use.config_unwritable", `Could not inspect '${configPath}' before writing.`),
+        notRegular: () =>
+          new SiteAuthoringError("use.config_not_regular", `'${configPath}' is not a regular file.`),
+        write: () =>
+          new SiteAuthoringError("use.config_unwritable", `Could not write '${configPath}'.`),
+      },
+    });
+
+    // 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}).`);
+    onProgress(`Recorded in ${configPath}.`);
+
+    return successResult(VERB_USE, site.siteId, {
+      accountId: signIn.accountId,
+      site: { siteId: site.siteId, name: site.name, primaryDomain: site.primaryDomain },
+      configPath: configPath,
+    });
+  });
+}