@taprootio/site-authoring 0.23.1 → 0.26.0

package/src/verbs/pages-push.js

@@ -1,5 +1,7 @@
 import {
   createPage,
+  getPage,
+  PAGE_STATUS_DRAFT,
   importVideoEmbedPoster,
   isGonePage,
   listSitePages,
@@ -38,6 +40,10 @@ import {
   COVER_IMAGE_UNUSED_MESSAGE,
   documentTemplate,
   generatedMarkdownFault,
+  legalMarkdownFault,
+  legalIdentity,
+  workspaceDocumentFromPage,
+  TEMPLATE_LEGAL,
   generatedPageDescription,
   generatedPageTitle,
   placedVideoIds,
@@ -289,6 +295,7 @@ function parseFrontMatter(source, file) {
     try {
       template = requireTemplateName(fields.get("template"), file);
       if (template === TEMPLATE_GENERATED) record(generatedMarkdownFault(file));
+      if (template === TEMPLATE_LEGAL) record(legalMarkdownFault(file));
     } catch (error) {
       record(error);
     }
@@ -1100,6 +1107,8 @@ export async function planPages({
   requestedPaths,
   getSharedThemeContexts,
   refreshAuthors,
+  legalDrafts = false,
+  readLegalPage,
   onProgress = () => {},
 }) {
   const problems = [];
@@ -1282,6 +1291,7 @@ export async function planPages({
       onProgress(`Validating '${file}'.`);
       const manifestEntry = manifestByFile.get(file);
       let observedRecord;
+      let legalRevisionGuard;
       requireCompletePageMetadata(source);
       const document_ = await convertWorkspacePageSource({ source, mediaManifest, content });
 
@@ -1298,6 +1308,9 @@ export async function planPages({
         );
       }
       const generated = documentTemplate(document_) === TEMPLATE_GENERATED;
+      if (documentTemplate(document_) === TEMPLATE_LEGAL && target === undefined && manifestEntry?.pageId !== undefined) {
+        throw documentError("pages.legal_missing", `'${file}' tracks a legal page that the site no longer lists. Pull and reconcile it before creating another page.`, file);
+      }
       if (generated && target === undefined) {
         if (targeted) {
           throw documentError(
@@ -1417,8 +1430,11 @@ export async function planPages({
             entry: manifestByPageId.get(target.pageId),
             observedRevision: observed?.revision,
           };
-          requireReconciledRevision(guard);
-          requireReconciledDisplayDate({ ...guard, document_, observed });
+          if (sourceTemplate === TEMPLATE_LEGAL) legalRevisionGuard = guard;
+          else {
+            requireReconciledRevision(guard);
+            requireReconciledDisplayDate({ ...guard, document_, observed });
+          }
         }
       }
 
@@ -1474,6 +1490,24 @@ export async function planPages({
       // An author the site no longer holds is a change to send, however the
       // source compares with the record.
       const unchanged = isUnchanged(observedRecord) && !(online && target !== undefined && authorship.sendAuthor);
+      if (documentTemplate(document_) === TEMPLATE_LEGAL && !unchanged && online) {
+        if (legalRevisionGuard !== undefined) requireReconciledRevision(legalRevisionGuard);
+        if (!legalDrafts) {
+          throw documentError("pages.legal_grant_required", "Legal draft changes require an explicit site grant. Run 'taproot-site login --legal-drafts', then 'taproot-site --legal-drafts pages push'. If TAPROOT_SITE_KEY is set, unset it first.", file);
+        }
+        if (target !== undefined) {
+          const recorded = targetEntry?.legal;
+          const livePath = normalizePagePath(target.path) ?? target.path;
+          const livePage = await readLegalPage(target);
+          const liveDocument = workspaceDocumentFromPage(livePage, target.templateType);
+          const identity = legalIdentity(document_.data);
+          const same = (other) => other !== undefined && other.documentKey === identity.documentKey && other.documentRole === identity.documentRole;
+          if (targetEntry === undefined || normalizePagePath(targetEntry.path) !== pagePath || livePath !== pagePath
+              || !same(recorded) || documentTemplate(liveDocument) !== TEMPLATE_LEGAL || !same(legalIdentity(liveDocument.data))) {
+            throw documentError("pages.legal_identity", `'${file}' changes or lacks the recorded legal document key, role or path. Pull and reconcile the page before editing.`, file);
+          }
+        }
+      }
       // Only for a page this push sends: a description stored before the limit
       // existed must not block a push that leaves it alone (TR01194). A
       // generated page's derived description is not the owner's to shorten;
@@ -1605,6 +1639,8 @@ export async function pagesPush(invocation) {
       files,
       livePages,
       online: true,
+      legalDrafts: session.legalDrafts === true,
+      readLegalPage: (target) => getPage(client, target.pageId, target.hasDraft ? PAGE_STATUS_DRAFT : target.status),
       requestedPaths,
       refreshAuthors: liveAuthorsRefresher({
         client,
@@ -1735,7 +1771,8 @@ export async function pagesPush(invocation) {
         // and a raw TypeError here would collapse to an opaque `site.failed`
         // *after* pages had already been created — the one place in this verb
         // where a crash costs more than a refusal.
-        const existing = manifest.pages.find((entry) => entry?.pageId === summary.pageId);
+        const existing = manifest.pages.find((entry) => entry?.pageId === summary.pageId)
+          ?? manifest.pages.find((entry) => entry?.pageId === undefined && entry?.file === page.file);
         const record = existing ?? {};
         // The author the site holds now: what it reports, else what was just
         // accepted, else what this workspace already knew it held.
@@ -1785,6 +1822,7 @@ export async function pagesPush(invocation) {
         });
         // What the source names, kept beside the site's own for a .pm.json
         // page, whose manifest entry is the only place it is written down.
+        if (documentTemplate(page.document) === TEMPLATE_LEGAL) record.legal = legalIdentity(page.document.data);
         if (page.author === "") delete record.author;
         else record.author = page.author;
         if (existing === undefined) manifest.pages.push(record);

package/src/verbs/plan.js

@@ -5,6 +5,8 @@ import { footerImageIds } from "../footer-contract.js";
 import { SETTINGS_TYPE_BRAND, SETTINGS_TYPE_SITE_HEADER, SETTINGS_TYPE_TAPROOT_STYLES } from "../settings-catalog.js";
 import {
   getNavigation,
+  getPage,
+  PAGE_STATUS_DRAFT,
   IMAGE_PROCESSING_STATE_COMPLETE,
   listSiteImages,
   isGonePage,
@@ -276,6 +278,8 @@ async function preflight(session, invocation) {
       files: await walkWorkspaceFiles(workspaceDir, PAGES_DIRECTORY, PAGE_SOURCE_EXTENSIONS),
       livePages,
       online: true,
+      legalDrafts: session.legalDrafts === true,
+      readLegalPage: (target) => getPage(client, target.pageId, target.hasDraft ? PAGE_STATUS_DRAFT : target.status),
       // Asked of the site but never written down: `plan` leaves the workspace as it found it.
       refreshAuthors: liveAuthorsRefresher({ client, workspaceDir, siteId, write: false, onProgress }),
       // From the theme validated above, so a broken styles file is one problem, not one per page.
@@ -550,7 +554,8 @@ export async function apply(invocation) {
 
   const ready = planned.steps.filter((entry) => entry.status === READY);
   const completed = [];
-  const stepInvocation = { ...invocation, client: session.client, resolvedConfig: session.config };
+  const stepInvocation = { ...invocation, client: session.client, resolvedConfig: session.config,
+    ...(session.legalDrafts ? { resolvedSession: session } : {}) };
   await enforceWorkspaceReads(planned.ledger, () => runSteps(ready, completed, stepInvocation, planned, onProgress));
   onProgress(
     completed.length === 0

package/src/verbs/pull.js

@@ -18,7 +18,7 @@ import {
   VERB_PULL,
 } from "../constants.js";
 import { AUTHORS_FILE_NAME, parseAuthorReference, projectAuthorsForWorkspace } from "../authors-contract.js";
-import { sanitizeDiagnostic, SiteAuthoringError } from "../errors.js";
+import { isCanonicalUuid, 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";
@@ -36,11 +36,15 @@ import {
 } from "../settings-catalog.js";
 import { ApiError } from "../transport.js";
 import { placesFormIds, readFormIndex, withFormKeys } from "../form-references.js";
+import { MARKETING_MANIFEST_KEY } from "../marketing-workspace.js";
 import {
   generatedIdentity,
+  legalIdentity,
+  isLegalTemplateType,
   isAuthorableTemplateType,
   isGeneratedTemplateType,
   sentDisplayDate,
+  TEMPLATE_LEGAL,
   workspaceDocumentFromPage,
 } from "../typed-pages.js";
 import {
@@ -450,11 +454,11 @@ async function resolveTrackedSources(workspaceDir, pages, registry, onProgress)
 }
 
 /**
- * Reads the previous manifest's source registry, tolerating everything a
- * strict read would refuse.
+ * Reads the previous manifest's source registry, tolerating damaged tracked
+ * entries but protecting unsaved drafts whose metadata has no server identity.
  *
- * `pull` is the verb that repairs a workspace, so refusing here would strand
- * one. It is also the only verb that reads a manifest it is about to replace:
+ * `pull` repairs damaged tracked entries instead of stranding the workspace.
+ * It is also the only verb that reads a manifest it is about to replace:
  * a version-4 manifest still records the `pageId → file` mapping this needs,
  * and honoring it is what repairs an existing workspace in one pull instead of
  * by hand. Every other verb keeps refusing an old manifest outright — the site
@@ -474,7 +478,22 @@ async function readSourceRegistry(workspaceDir, siteId) {
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed) || parsed.siteId !== siteId) {
     return new Map();
   }
-  const registry = pageSourceRegistry(withoutRetiredReadOnlyProjections(parsed));
+  const manifest = withoutRetiredReadOnlyProjections(parsed);
+  for (const entry of Array.isArray(manifest.pages) ? manifest.pages : []) {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry) || isCanonicalUuid(entry.pageId)) continue;
+    if (!["file", "title", "path"].some((field) => Object.hasOwn(entry, field))) continue;
+    const field = sanitizeDiagnostic(entry.file, MANIFEST_FILE_NAME);
+    const label = sanitizeDiagnostic(entry.path, field);
+    // A new source's metadata lives only here until its first save.
+    throw new SiteAuthoringError(
+      "pages.source_conflict",
+      `The pending page entry '${label}' has no server page id. Pull would discard its saved metadata. `
+        + "Save the draft with 'taproot-site pages push' first, or back up and move its source file and manifest "
+        + "entry before running 'taproot-site pull' again. Nothing was changed.",
+      { field },
+    );
+  }
+  const registry = pageSourceRegistry(manifest);
   return parsed.manifestVersion === MANIFEST_VERSION ? registry : withoutSupersededRemoteHashes(registry);
 }
 
@@ -750,6 +769,33 @@ export async function pull(invocation) {
       new Set(retiredGeneratedSources.map((source) => source.file)),
     );
 
+    // A fresh destination has no ownership baseline. Protect legal drafts even
+    // when the remote page has another template, and refuse unreadable sources.
+    for (const summary of authorable) {
+      if (tracked.has(summary.pageId)) continue;
+      const file = pageFiles.get(summary.pageId);
+      let protectedSource;
+      try {
+        if (!await workspaceFileExists(config.workspaceDir, file)) continue;
+        protectedSource = isLegalTemplateType(summary.templateType);
+        if (!protectedSource) {
+          const document = await readWorkspaceJson(config.workspaceDir, file, WORKSPACE_LIMITS.documentBytes);
+          protectedSource = document?.template === TEMPLATE_LEGAL;
+        }
+      } catch {
+        protectedSource = true;
+      }
+      if (protectedSource) {
+        throw new SiteAuthoringError(
+          "pages.source_conflict",
+          `Page ${summary.pageId} would use '${file}', but this workspace does not track that file as its source. `
+            + "The file was kept. Back up and move its source file and any manifest entry, or reconcile it before "
+            + "running 'taproot-site pull' again.",
+          { field: file },
+        );
+      }
+    }
+
     // The redirect map, with the revision a later push is fenced by (TR00702).
     // Read here, before the first workspace write, for the same reason the
     // settings groups below are: a failure must strand nothing. A Taproot that
@@ -920,6 +966,7 @@ export async function pull(invocation) {
           // The page is still the generated page it was; losing the record would
           // let the next push take an edit to its identity for the owner's.
           ...(source.generated === undefined ? {} : { generated: source.generated }),
+          ...(source.legal === undefined ? {} : { legal: source.legal }),
           description: metadataKept ? source.metadata.description : description,
           title: metadataKept ? source.metadata.title : titleFromRead(page, summary),
           path: metadataKept ? source.metadata.path : pathFromRead(page, summary),
@@ -1036,6 +1083,7 @@ export async function pull(invocation) {
       if (metadataEdited) reportPendingAuthorDisagreement(source, summary, onProgress);
       trackedPlans.set(summary.pageId, {
         ...(generatedPage ? { generated: generatedIdentity(body.data) } : {}),
+        ...(isLegalTemplateType(summary.templateType) ? { legal: legalIdentity(body.data) } : {}),
         description: metadataEdited ? source.metadata.description : description,
         title: metadataEdited ? source.metadata.title : titleFromRead(page, summary),
         path: metadataEdited ? source.metadata.path : pathFromRead(page, summary),
@@ -1252,6 +1300,7 @@ export async function pull(invocation) {
           if (plan.path !== undefined) entry.path = plan.path;
           // What a generated page is, so a push can refuse a source that changed it.
           if (plan.generated !== undefined) entry.generated = plan.generated;
+          if (plan.legal !== undefined) entry.legal = plan.legal;
           if (plan.file !== undefined) {
             entry.file = plan.file;
             entry.sourceFormat = plan.sourceFormat;
@@ -1285,6 +1334,7 @@ export async function pull(invocation) {
         } else {
           entry.file = pageFiles.get(summary.pageId);
           if (isGeneratedTemplateType(summary.templateType)) entry.generated = generatedIdentity(body.data);
+          if (isLegalTemplateType(summary.templateType)) entry.legal = legalIdentity(body.data);
           const source = Buffer.from(`${JSON.stringify(body, undefined, 2)}\n`, "utf8");
           entry.workspaceMode = PAGE_WORKSPACE_MODE_EDITABLE;
           entry.sourceFormat = pageSourceFormat(entry.file);
@@ -1346,10 +1396,13 @@ export async function pull(invocation) {
 
     // `forms pull` owns the forms baseline, and a plain pull does not read forms.
     // Carrying it forward keeps the next `forms push` fenced instead of refusing
-    // it as never pulled. An unreadable old manifest has nothing to carry.
-    const formsBaseline = (await readManifest(config.workspaceDir, siteId, { required: false }).catch(() =>
+    // it as never pulled. The marketing baseline is carried for the same reason
+    // (TR01301). An unreadable old manifest has nothing to carry.
+    const previousManifest = await readManifest(config.workspaceDir, siteId, { required: false }).catch(() =>
       undefined
-    ))?.forms;
+    );
+    const formsBaseline = previousManifest?.forms;
+    const marketingBaseline = previousManifest?.[MARKETING_MANIFEST_KEY];
     const manifest = {
       manifestVersion: MANIFEST_VERSION,
       siteId,
@@ -1371,6 +1424,7 @@ export async function pull(invocation) {
       ),
       ...(presentationRevision === undefined ? {} : { presentation: presentationManifestEntry(presentationRevision) }),
       ...(formsBaseline === undefined ? {} : { forms: formsBaseline }),
+      ...(marketingBaseline === undefined ? {} : { [MARKETING_MANIFEST_KEY]: marketingBaseline }),
       pages: manifestPages,
       ...(retiredGeneratedSources.length === 0 ? {} : { retiredGeneratedSources }),
     };

package/src/verbs/whoami.js

@@ -12,10 +12,11 @@ import {
 } from "../constants.js";
 import { isBehindLatest } from "../cli-release.js";
 import { credentialApiOrigin, findCredential } from "../credentials.js";
-import { SITE_AUTHORING_CAPABILITIES } from "../capabilities.js";
+import { CAPABILITY_CONTENT, SITE_AUTHORING_CAPABILITIES } from "../capabilities.js";
 import { openAnonymousSession, successResult } from "../session.js";
 import { environmentNameFor } from "../settings.js";
 import { describeSurface } from "../surface.js";
+import { SiteAuthoringError } from "../errors.js";
 
 /**
  * What the last exchange recorded about the platform authoring switch, dated
@@ -63,6 +64,33 @@ function cliReleaseLine(lastExchange) {
     : `Latest CLI release ${when}: ${lastExchange.latestCliVersion}. This CLI is ${CLI_VERSION}.`;
 }
 
+/**
+ * Whether the credential can manage the site's campaigns and placements (TR01301), from what is known locally.
+ *
+ * The Content capability carries both permissions those verbs need, so the answer is whether the last exchange
+ * held it. Like the rest of this verb it is a recording: `granted` is "what that exchange held", and `exchange`
+ * says no exchange has happened yet, when the next command that needs it will mint one.
+ */
+function marketingAccess(lastExchange, environmentOverride) {
+  if (environmentOverride) return { capability: CAPABILITY_CONTENT, access: "unknown" };
+  if (lastExchange === undefined) return { capability: CAPABILITY_CONTENT, access: "on_exchange" };
+  return {
+    capability: CAPABILITY_CONTENT,
+    access: lastExchange.capabilities.includes(CAPABILITY_CONTENT) ? "granted" : "not_in_last_exchange",
+  };
+}
+
+function marketingLine({ capability, access }) {
+  const verbs = "'marketing pull', 'marketing push' and 'link build'";
+  return access === "granted"
+    ? `Campaigns and placements (${verbs}): allowed; the last exchange held ${capability}.`
+    : access === "not_in_last_exchange"
+    ? `Campaigns and placements (${verbs}): the last exchange did not hold ${capability}, which the next command that needs it requests; a sign-in's ceiling includes it.`
+    : access === "on_exchange"
+    ? `Campaigns and placements (${verbs}): carried by ${capability}, which the next command that needs it requests.`
+    : `Campaigns and placements (${verbs}): needs ${capability}; ${PUBLISH_KEY_ENVIRONMENT_VARIABLE} supplies the credential, so this command cannot tell.`;
+}
+
 /**
  * `taproot-site whoami` — which Taproot, which account, which site, until when.
  *
@@ -81,7 +109,10 @@ export async function whoami(invocation) {
   const environment = invocation.environment ?? process.env;
   const { config, apiBaseUrl, onProgress } = await openAnonymousSession({ ...invocation, client: null });
   const apiOrigin = credentialApiOrigin(apiBaseUrl);
-  const { path: credentialPath, credential } = await findCredential(environment, apiOrigin);
+  if (invocation.legalDrafts && !config?.siteId) {
+    throw new SiteAuthoringError("config.site_missing", "Select a site before inspecting its legal draft grant.");
+  }
+  const { path: credentialPath, credential } = await findCredential(environment, apiOrigin, { siteId: invocation.legalDrafts ? config.siteId : undefined });
 
   // Reported, not resolved. An operator debugging a permission surprise needs
   // to know the environment override is in play; printing its value would put
@@ -92,6 +123,11 @@ export async function whoami(invocation) {
   const expired = credential?.keyExpiresAt !== undefined && Date.parse(credential.keyExpiresAt) <= now;
 
   onProgress(`Taproot: ${apiOrigin} (${environmentNameFor(apiBaseUrl)})`);
+  if (invocation.legalDrafts) {
+    onProgress(`Legal draft grant for site ${config.siteId}: ${credential ? `${credential.keyPrefix} (id ${credential.keyId}), ${expired ? "expired" : "expires"} ${credential.keyExpiresAt}` : `not found; run '${CLI_BINARY_NAME} ${VERB_LOGIN} --legal-drafts'.`}`);
+    if (environmentOverride) onProgress(`Unset ${PUBLISH_KEY_ENVIRONMENT_VARIABLE} to use this legal draft grant.`);
+    return successResult(VERB_WHOAMI, config.siteId, { apiOrigin, legalDrafts: true, signedIn: credential !== undefined, environmentOverride, ...(credential === undefined ? {} : { accountId: credential.accountId, keyId: credential.keyId, keyPrefix: credential.keyPrefix, keyExpiresAt: credential.keyExpiresAt, expired, credentialPath }) });
+  }
   if (environmentOverride) {
     onProgress(
       `${PUBLISH_KEY_ENVIRONMENT_VARIABLE} is set, so commands use that site credential and skip the sign-in.`,
@@ -146,6 +182,9 @@ export async function whoami(invocation) {
     onProgress(cliReleaseLine(lastExchange));
   }
 
+  const marketing = marketingAccess(lastExchange, environmentOverride);
+  onProgress(marketingLine(marketing));
+
   return successResult(VERB_WHOAMI, config?.siteId, {
     apiOrigin,
     // Named as well as spelled out, so "am I on local right now" is answerable
@@ -167,6 +206,7 @@ export async function whoami(invocation) {
     // Named for what each is. `capabilities` alone would conflate the ceiling
     // with the grant, which are different numbers and differently trustworthy.
     capabilityCeiling: SITE_AUTHORING_CAPABILITIES,
+    marketing,
     ...(environmentOverride || lastExchange === undefined ? {} : {
       lastExchange: {
         siteId: lastExchange.siteId,

package/src/workspace.js

@@ -484,6 +484,9 @@ export function pageSourceRegistry(manifest) {
       ...(entry.generated !== null && typeof entry.generated === "object" && !Array.isArray(entry.generated)
         ? { generated: entry.generated }
         : {}),
+      ...(entry.legal !== null && typeof entry.legal === "object" && !Array.isArray(entry.legal)
+        ? { legal: entry.legal }
+        : {}),
       // What this workspace says the page's metadata is; a .pm.json page's only
       // record of it (TR01194).
       metadata: {