@taprootio/site-authoring 0.22.4 → 0.23.0

package/src/verbs/plan.js

@@ -7,9 +7,9 @@ import {
   getNavigation,
   IMAGE_PROCESSING_STATE_COMPLETE,
   listSiteImages,
+  isGonePage,
   listSitePages,
   listVideos,
-  PAGE_STATUS_DELETED,
   withRefusalGuidance,
 } from "../api.js";
 import {
@@ -35,6 +35,7 @@ import { checkWorkspace } from "../workspace-check.js";
 import { enforceWorkspaceReads, ledgerDigest, recordWorkspaceReads } from "../workspace-ledger.js";
 import {
   PAGE_SOURCE_EXTENSIONS,
+  NAVIGATION_FILE_NAME,
   PAGES_DIRECTORY,
   readManifest,
   readMediaManifest,
@@ -42,6 +43,7 @@ import {
 } from "../workspace.js";
 import { footerPush } from "./footer-push.js";
 import { mediaUpload, pendingMediaFiles } from "./media-upload.js";
+import { navigationMovedRefusal, requireNavigationBaseline } from "../navigation-workspace.js";
 import { navPush, validateNavigationWorkspaceDocument } from "./nav-push.js";
 import {
   liveAuthorsRefresher,
@@ -194,7 +196,7 @@ async function preflight(session, invocation) {
         { field: "pages" },
       );
     }
-    const live = livePages.filter((summary) => summary.status !== PAGE_STATUS_DELETED);
+    const live = livePages.filter((summary) => !isGonePage(summary));
     const liveResourceIds = new Set(live.map((summary) => summary.resourceId).filter(Boolean));
 
     // The shared checks for the presentation, footer, and navigation; pages
@@ -357,8 +359,10 @@ async function preflight(session, invocation) {
     onProgress("Reading the site's navigation.");
     let liveNavigation;
     let navigationChanged = false;
+    let settlesLostPush = false;
     if (offline.navigation !== undefined) {
-      liveNavigation = await getNavigation(client, siteId);
+      const live = await getNavigation(client, siteId);
+      liveNavigation = live.navItems;
       let liveItems;
       try {
         liveItems = validateNavigationWorkspaceDocument({ siteId, navItems: liveNavigation }, siteId).navItems;
@@ -368,6 +372,24 @@ async function preflight(session, invocation) {
         liveItems = liveNavigation;
       }
       navigationChanged = stableJson(liveItems) !== stableJson(offline.navigation.navItems);
+      // A tree equal to the file under a baseline the site has moved past is a push whose answer was lost after
+      // it committed. The step runs so nav push settles the workspace, as theme push replays a lost save.
+      if (!navigationChanged) {
+        try {
+          settlesLostPush = requireNavigationBaseline(manifest) !== live.revision;
+        } catch (error) {
+          if (!(error instanceof SiteAuthoringError)) throw error;
+        }
+      }
+      // Only a navigation step that would run can be refused, as for the theme.
+      if (navigationChanged) {
+        try {
+          if (requireNavigationBaseline(manifest) !== live.revision) throw navigationMovedRefusal();
+        } catch (error) {
+          if (!(error instanceof SiteAuthoringError)) throw error;
+          problems.push(...problemsOf(error, { area: CHECK_AREA.navigation, file: NAVIGATION_FILE_NAME }));
+        }
+      }
     }
 
     const pagesItems = reportedWithin(pages.planned.map(plannedPageItem), PAGE_ITEMS_BYTES);
@@ -395,7 +417,10 @@ async function preflight(session, invocation) {
           ...(theme.replaying ? { replaysLostSave: true } : {}),
         }),
       }),
-      step(PLAN_STEP.navigation, stepStatus(problems, PLAN_STEP.navigation, navigationChanged)),
+      step(PLAN_STEP.navigation, stepStatus(problems, PLAN_STEP.navigation, navigationChanged || settlesLostPush), {
+        // The site already holds the file's tree, so the step only settles the workspace's recorded revision.
+        ...(settlesLostPush && !navigationChanged ? { settlesLostPush: true } : {}),
+      }),
     ];
     const planHash = `sha256:${createHash("sha256").update(stableJson({
       version: 1,
@@ -412,7 +437,8 @@ async function preflight(session, invocation) {
       problems,
       pendingMedia,
       planHash,
-      // The live state each step must still find, where the server has no fence.
+      // The live state each step must still find: page revisions and the navigation tree, which the steps check
+      // themselves (the theme and footer saves are fenced by the server, and the navigation save is as well).
       plannedPages: new Map(sending.map((page) => [page.file, stableJson([page.pageId ?? "", page.revision ?? "", page.action])])),
       plannedLiveNavigation: stableJson(liveNavigation ?? null),
     };

package/src/verbs/pull.js

@@ -5,8 +5,8 @@ import {
   getSitePresentation,
   getSiteRedirectMap,
   listSiteAuthors,
+  isGonePage,
   listSitePages,
-  PAGE_STATUS_DELETED,
   PAGE_STATUS_DRAFT,
   PAGE_STATUS_UNKNOWN,
   withRefusalGuidance,
@@ -22,6 +22,7 @@ import { sanitizeDiagnostic, SiteAuthoringError } from "../errors.js";
 import { appearanceManifestEntry, footerManifestEntry, presentationManifestEntry } from "../footer-workspace.js";
 import { describeJsonDifferences, reportableDifferencePaths } from "../json-path-diff.js";
 import { projectRedirectMapForWorkspace, REDIRECTS_FILE_NAME } from "../redirects-contract.js";
+import { navigationManifestEntry } from "../navigation-workspace.js";
 import { redirectsManifestEntry } from "../redirects-workspace.js";
 import { projectNavigationForWorkspace } from "./nav-push.js";
 import { boundedList, openSession, successResult } from "../session.js";
@@ -678,7 +679,7 @@ export async function pull(invocation) {
       onProgress("Listing the site's pages.");
       ({ pages, truncated } = await listSitePages(client, siteId, { onProgress }));
     }
-    const live = pages.filter((summary) => summary.status !== PAGE_STATUS_DELETED);
+    const live = pages.filter((summary) => !isGonePage(summary));
     const authorable = live.filter((summary) => isAuthorableTemplateType(summary.templateType));
     // Generated-page sources recorded apart as retired. One whose page the site
     // lists again (a bounded listing left it out last time) takes its file back
@@ -1312,9 +1313,11 @@ export async function pull(invocation) {
     }
 
     let navItems;
+    let navigation;
     if (!presentationOnly) {
       onProgress("Reading the navigation tree.");
-      navItems = await getNavigation(client, siteId);
+      navigation = await getNavigation(client, siteId);
+      navItems = navigation.navItems;
       await writeWorkspaceJson(config.workspaceDir, NAVIGATION_FILE_NAME, {
         siteId,
         navItems: projectNavigationForWorkspace(navItems),
@@ -1356,7 +1359,7 @@ export async function pull(invocation) {
       // not a partial pull.
       ...(presentationOnly ? { authoringSurface: SURFACE_DOCS_PRESENTATION } : {}),
       pagesTruncated: truncated,
-      ...(navItems === undefined ? {} : { navigation: { file: NAVIGATION_FILE_NAME, items: navItems.length } }),
+      ...(navigation === undefined ? {} : { navigation: navigationManifestEntry(navigation) }),
       ...(redirectMap === undefined ? {} : { redirects: redirectsManifestEntry(redirectMap) }),
       settings: pulledSettings,
       settingsSkipped: skippedSettings,
@@ -1409,7 +1412,7 @@ export async function pull(invocation) {
         items: reported.items,
         ...(reported.truncated ? { itemsTruncated: true } : {}),
       },
-      ...(navItems === undefined ? {} : { navigation: { file: NAVIGATION_FILE_NAME, items: navItems.length } }),
+      ...(navigation === undefined ? {} : { navigation: navigationManifestEntry(navigation) }),
       // 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/staging-review.js

@@ -1,9 +1,10 @@
 import { mintStagingPreviewHandoff, withRefusalGuidance } from "../api.js";
-import { VERB_STAGING_REVIEW } from "../constants.js";
+import { STAGING_REVIEW_SESSION_NOTE, VERB_STAGING_REVIEW } from "../constants.js";
 import { openSession, successResult } from "../session.js";
 
 export const STAGING_REVIEW_GUIDANCE = "Open the URL once in a browser, then switch the site's theme toggle between "
-  + "light and dark to review both schemes; no page draft is needed to review a presentation change.";
+  + "light and dark to review both schemes; no page draft is needed to review a presentation change. "
+  + STAGING_REVIEW_SESSION_NOTE;
 
 /**
  * `staging review` — mint a fresh single-use review handoff for the site's

package/src/verbs/theme-push.js

@@ -62,7 +62,7 @@ function fail(code, message, field) {
   throw new SiteAuthoringError(code, message, { field });
 }
 
-async function readSettingsDocument(workspaceDir, siteId, settingsType, expectedEntityId = siteId) {
+export 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);
@@ -83,6 +83,34 @@ async function readSettingsDocument(workspaceDir, siteId, settingsType, expected
   return document.settings;
 }
 
+/** The theme paths the styles document lacks, both schemes, in the order theme push reports them. */
+export function missingThemeSettings(style) {
+  const missing = [];
+  for (const scheme of ["light", "dark"]) {
+    const name = `${scheme}Theme`;
+    if (!Object.hasOwn(style, name)) missing.push(name);
+    else missing.push(...missingThemeFields(style[name], scheme));
+  }
+  return missing;
+}
+
+/** The one refusal for absent required settings keys, listing every path; `resolve` shares it with push and validate. */
+export function requireNoMissingSettings(missing) {
+  if (missing.length === 0) return;
+  throw new SiteAuthoringError(
+    "theme.settings_missing",
+    "Required settings keys are absent from this workspace. Restore them locally, or run 'taproot-site pull' if the workspace is stale; a fresh pull that still omits them means the server projection is incomplete for the listed paths.",
+    {
+      field: missing[0],
+      details: missing.map((field) => ({
+        code: "theme.setting_missing",
+        field,
+        message: MISSING_SETTING_MESSAGE,
+      })),
+    },
+  );
+}
+
 /** 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([
@@ -119,12 +147,7 @@ export async function validateThemeWorkspace(workspaceDir, siteId, knownImageIds
   // Preflight the complete required-key inventory before any value validator
   // can stop at a malformed value in an earlier group. Optional footer color
   // leaves retain their existing empty-color fallback.
-  const missing = [];
-  for (const scheme of ["light", "dark"]) {
-    const name = `${scheme}Theme`;
-    if (!Object.hasOwn(style, name)) missing.push(name);
-    else missing.push(...missingThemeFields(style[name], scheme));
-  }
+  const missing = missingThemeSettings(style);
   for (const definition of APPEARANCE_SCALAR_FIELDS) {
     if (!Object.hasOwn(documents[definition.settingsType], definition.name)) {
       missing.push(definition.path);
@@ -137,20 +160,7 @@ export async function validateThemeWorkspace(workspaceDir, siteId, knownImageIds
       if (!Object.hasOwn(publishing.footerSettings, scheme)) missing.push(`footerSettings.${scheme}`);
     }
   }
-  if (missing.length > 0) {
-    throw new SiteAuthoringError(
-      "theme.settings_missing",
-      "Required settings keys are absent from this workspace. Restore them locally, or run 'taproot-site pull' if the workspace is stale; a fresh pull that still omits them means the server projection is incomplete for the listed paths.",
-      {
-        field: missing[0],
-        details: missing.map((field) => ({
-          code: "theme.setting_missing",
-          field,
-          message: MISSING_SETTING_MESSAGE,
-        })),
-      },
-    );
-  }
+  requireNoMissingSettings(missing);
   const themes = await validateAndLintThemePair(style.lightTheme, style.darkTheme);
   const scalarOperations = buildAppearanceScalarOperations(
     documents,

package/src/verbs/theme-resolve.js

@@ -0,0 +1,98 @@
+import { getSitePresentation, withRefusalGuidance } from "../api.js";
+import { LIMITS, VERB_THEME_RESOLVE } from "../constants.js";
+import { SiteAuthoringError } from "../errors.js";
+import { CHECK_AREA, collectProblems, refuseProblems, withinByteBudget } from "../problems.js";
+import { boundedByBytes, openAnonymousSession, openSession, successResult } from "../session.js";
+import { projectSettingsGroup, SETTINGS_GROUPS, SETTINGS_TYPE_TAPROOT_STYLES } from "../settings-catalog.js";
+import { AA_LARGE_RATIO, AA_TEXT_RATIO, resolveThemePair, THEME_STYLES_FILE } from "../theme-resolve.js";
+import { missingThemeSettings, readSettingsDocument, requireNoMissingSettings } from "./theme-push.js";
+
+// A result must fit LIMITS.githubOutputBytes (64 KiB), and a theme may declare 128 contexts a scheme. The lists that
+// grow with the theme are bounded first, each by its own share; surfaces then take what is left, and the ones past
+// it are named in omittedSurfaces to be fetched with --scheme and --context.
+const RESULT_ENVELOPE_BYTES = 4 * 1024;
+const FLAG_BYTE_BUDGET = 10 * 1024;
+const NAME_LIST_BYTE_BUDGET = 6 * 1024;
+
+const STYLES_GROUP = SETTINGS_GROUPS.find((group) => group.settingsType === SETTINGS_TYPE_TAPROOT_STYLES);
+
+/** The workspace's pair, read the way theme push reads it; or the site's, projected the way pull writes it. */
+async function readThemes(invocation) {
+  if (invocation.fromSite === true) {
+    const session = await openSession(invocation);
+    const presentation = await withRefusalGuidance(session.onProgress, "theme resolve", async () =>
+      await getSitePresentation(session.client, session.siteId));
+    const projected = projectSettingsGroup(STYLES_GROUP, presentation);
+    return { siteId: session.siteId, source: "site", themes: [projected.lightTheme, projected.darkTheme] };
+  }
+  const { config } = await openAnonymousSession({ ...invocation, client: null });
+  if (config === undefined) {
+    throw new SiteAuthoringError(
+      "config.not_found",
+      "No taproot-site.json was found. theme resolve reads the pulled workspace it names; use --site to read the site instead.",
+    );
+  }
+  if (!config.siteId) {
+    throw new SiteAuthoringError(
+      "config.site_missing",
+      "No site is selected. Run 'taproot-site use <site>' to choose one, or set siteId in taproot-site.json.",
+    );
+  }
+  const style = await readSettingsDocument(config.workspaceDir, config.siteId, SETTINGS_TYPE_TAPROOT_STYLES);
+  // The same preflight push and validate run, so a stale workspace gets the same code and the full path list.
+  requireNoMissingSettings(missingThemeSettings(style));
+  return { siteId: config.siteId, source: "workspace", themes: [style.lightTheme, style.darkTheme] };
+}
+
+/**
+ * `theme resolve` — what Espalier compiles from the stored light and dark
+ * themes: every semantic color per scheme and context, and the contrast of
+ * each ink-on-surface pairing. Offline from the pulled workspace by default;
+ * `--site` reads the site's own theme instead (and needs a credential).
+ */
+export async function themeResolve(invocation) {
+  const { siteId, source, themes: [lightTheme, darkTheme] } = await readThemes(invocation);
+  const problems = [];
+  const resolution = await collectProblems(
+    problems,
+    { area: CHECK_AREA.presentation, file: THEME_STYLES_FILE },
+    async () => await resolveThemePair(lightTheme, darkTheme, {
+      scheme: invocation.themeScheme,
+      context: invocation.themeContext,
+    }),
+  );
+  refuseProblems(problems, "theme resolve");
+
+  const flags = { ...boundedByBytes(resolution.flags, FLAG_BYTE_BUDGET), count: resolution.flags.length };
+  const contexts = { ...boundedByBytes(resolution.contexts, NAME_LIST_BYTE_BUDGET), count: resolution.contexts.length };
+  const surfaceBudget = LIMITS.githubOutputBytes - RESULT_ENVELOPE_BYTES - NAME_LIST_BYTE_BUDGET
+    - Buffer.byteLength(JSON.stringify({ flags, contexts }), "utf8");
+  const entries = resolution.schemes.flatMap(({ scheme, surfaces }) => surfaces.map((surface) => ({ scheme, surface })));
+  const shown = withinByteBudget(entries, surfaceBudget);
+  const omitted = entries.slice(shown.length);
+  const schemes = resolution.schemes
+    .map(({ scheme }) => ({
+      scheme,
+      surfaces: shown.filter((entry) => entry.scheme === scheme).map((entry) => entry.surface),
+    }))
+    .filter((entry) => entry.surfaces.length > 0);
+  return successResult(VERB_THEME_RESOLVE, siteId, {
+    source,
+    thresholds: { textRatio: AA_TEXT_RATIO, largeRatio: AA_LARGE_RATIO },
+    contexts,
+    schemes,
+    contrast: resolution.contrast,
+    flags,
+    ...(omitted.length === 0
+      ? {}
+      : {
+        omittedSurfaces: {
+          ...boundedByBytes(
+            omitted.map((entry) => ({ scheme: entry.scheme, context: entry.surface.context })),
+            NAME_LIST_BYTE_BUDGET,
+          ),
+          count: omitted.length,
+        },
+      }),
+  });
+}

package/src/workspace.js

@@ -1068,9 +1068,9 @@ export async function writeWorkspaceJson(workspaceDir, relativePath, value) {
  * Removes one internal workspace file, refusing a link anywhere on the way to
  * it exactly as a read would. Returns whether anything was there.
  *
- * Only internal state is ever removed this way. Authored sources are the
- * author's, and a verb that deleted one would be doing the thing this package
- * exists to prevent.
+ * Internal state is removed this way as a matter of course. An authored source
+ * is the author's, so the one caller that removes it, `pages delete`, does so
+ * only for the page the author just asked to delete.
  */
 export async function deleteWorkspaceFile(workspaceDir, relativePath) {
   if (!await regularFileExists(workspaceDir, relativePath)) return false;