@taprootio/site-authoring 0.23.0 → 0.24.0

package/src/verbs/logout.js

@@ -1,6 +1,7 @@
 import { CLI_BINARY_NAME, VERB_LOGOUT } from "../constants.js";
 import { credentialApiOrigin, removeCredential } from "../credentials.js";
 import { openAnonymousSession, successResult } from "../session.js";
+import { SiteAuthoringError } from "../errors.js";
 
 /**
  * `taproot-site logout` — local discard, and nothing more.
@@ -19,11 +20,20 @@ import { openAnonymousSession, successResult } from "../session.js";
  * discards is addressed by API origin.
  */
 export async function logout(invocation) {
-  const { apiBaseUrl, onProgress } = await openAnonymousSession(invocation);
+  const { config, apiBaseUrl, onProgress } = await openAnonymousSession(invocation);
+  if (invocation.legalDrafts && !config?.siteId) {
+    throw new SiteAuthoringError("config.site_missing", "Select a site before discarding its legal draft grant.");
+  }
   const { path: credentialPath, removed } = await removeCredential(
     invocation.environment ?? process.env,
     credentialApiOrigin(apiBaseUrl),
+    { siteId: invocation.legalDrafts ? config.siteId : undefined },
   );
+  if (invocation.legalDrafts) {
+    onProgress(removed ? `Discarded the legal draft grant for site ${config.siteId} from ${credentialPath}.` : `No legal draft grant for site ${config.siteId} was found in ${credentialPath}.`);
+    if (removed) onProgress("This is a local discard; revoke the credential in Account -> Settings -> API keys.");
+    return successResult(VERB_LOGOUT, config.siteId, { removed, credentialPath, legalDrafts: true });
+  }
   onProgress(
     removed
       ? `Discarded the stored Taproot sign-in from ${credentialPath}.`
@@ -35,5 +45,9 @@ export async function logout(invocation) {
         + `Account -> Settings -> API keys; '${CLI_BINARY_NAME} ${VERB_LOGOUT}' cannot revoke it.`,
     );
   }
+  onProgress(
+    "Separate site legal draft grants, if any, remain stored. Select each site and run "
+      + `'${CLI_BINARY_NAME} --legal-drafts ${VERB_LOGOUT}' to discard its grant, or revoke the keys in Account -> Settings -> API keys.`,
+  );
   return successResult(VERB_LOGOUT, undefined, { removed, credentialPath });
 }

package/src/verbs/media-upload.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { Readable } from "node:stream";
 
 import {
@@ -624,6 +625,7 @@ export async function mediaUpload(invocation) {
           contentType,
           fileSize: bytes.byteLength,
           contentHash: hash,
+          operationKey: randomUUID(),
           width,
           height,
           ownershipScope: IMAGE_OWNERSHIP_SCOPE_SITE,

package/src/verbs/pages-delete.js

@@ -14,7 +14,7 @@ import { FOOTER_SETTINGS_FILE } from "../footer-workspace.js";
 import { afterSubmitPage, FORM_FILE_EXTENSION, FORMS_DIRECTORY, normalizePagePath as normalizeFormPagePath } from "../forms-contract.js";
 import { normalizeRedirectPath } from "../site-checks.js";
 import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
-import { isAuthorableTemplateType, isGeneratedTemplateType } from "../typed-pages.js";
+import { isAuthorableTemplateType, isGeneratedTemplateType, isLegalTemplateType } from "../typed-pages.js";
 import {
   deleteWorkspaceFile,
   displayPagePath,
@@ -194,10 +194,10 @@ function requireDeletable(manifest, entry, pagePath) {
       shown,
     );
   }
-  if (!isAuthorableTemplateType(entry.templateType)) {
+  if (isLegalTemplateType(entry.templateType) || !isAuthorableTemplateType(entry.templateType)) {
     throw refusal(
       "pages.delete_not_authorable",
-      `'${shown}' is a ${entry.templateType ?? "system-managed"} page, which this CLI does not author; delete it in the app.`,
+      `'${shown}' is a ${entry.templateType ?? "system-managed"} page, which this CLI cannot delete; delete it in the app.`,
       shown,
     );
   }
@@ -241,6 +241,9 @@ export async function pagesDelete(invocation) {
         shown,
       );
     }
+    if (live !== undefined && isLegalTemplateType(live.templateType)) {
+      throw refusal("pages.delete_not_authorable", `'${shown}' is a legal page; delete it in the app.`, shown);
+    }
     const alreadyGone = live === undefined || isGonePage(live);
     if (!alreadyGone) {
       // The fence `pages push` uses, against the revision this workspace last reconciled with.

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";
@@ -38,9 +38,12 @@ import { ApiError } from "../transport.js";
 import { placesFormIds, readFormIndex, withFormKeys } from "../form-references.js";
 import {
   generatedIdentity,
+  legalIdentity,
+  isLegalTemplateType,
   isAuthorableTemplateType,
   isGeneratedTemplateType,
   sentDisplayDate,
+  TEMPLATE_LEGAL,
   workspaceDocumentFromPage,
 } from "../typed-pages.js";
 import {
@@ -450,11 +453,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 +477,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 +768,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 +965,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 +1082,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 +1299,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 +1333,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);

package/src/verbs/whoami.js

@@ -16,6 +16,7 @@ import { 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
@@ -81,7 +82,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 +96,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.`,

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: {