@taprootio/site-authoring 0.14.1 → 0.16.0

package/src/workspace.js

@@ -4,7 +4,19 @@ import { lstat, mkdir, open, readdir, unlink } from "node:fs/promises";
 import path from "node:path";
 
 import { atomicWriteFile } from "./atomic-file.js";
+import { parseAuthorReference } from "./authors-contract.js";
 import { hasAsciiControl, sanitizeDiagnostic, SiteAuthoringError } from "./errors.js";
+import {
+  noteEntry,
+  noteExists,
+  noteFileDeleted,
+  noteFileMissing,
+  noteFileRead,
+  noteFileWritten,
+  noteStreamMissing,
+  noteStreamOpened,
+  noteWalk,
+} from "./workspace-ledger.js";
 
 /**
  * The local workspace: what `pull` writes, what the push verbs read back, and
@@ -279,6 +291,9 @@ export const WORKSPACE_LIMITS = Object.freeze({
   // untouched. Generous for any real authoring workspace, and an explicit
   // refusal rather than an unbounded buffer for one that is not.
   pulledBodyBytes: 64 * 1024 * 1024,
+  // The site's authors and the members a page can name: a few hundred people
+  // at most, but written by the site and read back, so bounded by bytes.
+  authorsBytes: 1024 * 1024,
   files: 5_000,
   directoryDepth: 12,
   relativePathBytes: 1_024,
@@ -330,17 +345,31 @@ export function canonicalDocumentHash(document_) {
 
 /**
  * What a push would send for a page, as one hash: the source's bytes plus the
- * title, path and description that travel with it (for a `.pm.json` source they
- * come from the manifest, not the file). `pages push` skips a page whose key
+ * title, path, description and author that travel with it (for a `.pm.json`
+ * source they come from the manifest, not the file). `pages push` skips a page whose key
  * equals the one recorded when the workspace last agreed with the site, so an
  * unedited page is never re-sent (an update would turn an approved page back
  * into a draft). A Markdown source also folds in the hash of the document it
  * converts to, because its media references resolve through the media manifest:
  * re-uploading an image changes what is sent without changing the file.
  */
-export function pageContentKey(sourceHash, { title, path, description }, documentHash = "") {
+export function pageContentKey(sourceHash, { title, path, description, author }, documentHash = "") {
+  // The author joins the key only when there is one (TR01196). Every page
+  // without an author keeps the key it has always had, so an existing workspace
+  // does not see each of its pages as changed and resend them all, which would
+  // turn approved pages back into drafts.
   return workspaceContentHash(
-    Buffer.from(JSON.stringify([sourceHash, title ?? "", path ?? "", description ?? "", documentHash]), "utf8"),
+    Buffer.from(
+      JSON.stringify([
+        sourceHash,
+        title ?? "",
+        path ?? "",
+        description ?? "",
+        documentHash,
+        ...(typeof author === "string" && author !== "" ? [author] : []),
+      ]),
+      "utf8",
+    ),
   );
 }
 
@@ -348,6 +377,12 @@ function normalizeBaselineHash(value) {
   return typeof value === "string" && WORKSPACE_CONTENT_HASH.test(value) ? value : undefined;
 }
 
+// A folded author reference or "" (no author); anything else is a damaged member.
+function normalizeAuthorValue(value) {
+  if (value === undefined || value === "") return value;
+  return parseAuthorReference(value)?.value;
+}
+
 // A calendar date or "" (no date). Anything else is a damaged baseline member.
 function normalizeBaselineDisplayDate(value) {
   return typeof value === "string" && (value === "" || /^\d{4}-\d{2}-\d{2}$/u.test(value)) ? value : undefined;
@@ -364,7 +399,7 @@ function normalizeBaselineDisplayDate(value) {
  * dropped here instead of becoming a path refusal inside the verb that exists
  * to repair the manifest.
  */
-function isDiscoverablePageSource(file) {
+export function isDiscoverablePageSource(file) {
   if (typeof file !== "string" || !file.startsWith(`${PAGES_DIRECTORY}/`)) return false;
   const segments = file.split("/");
   return segments.length > 1
@@ -423,9 +458,10 @@ export function pageSourceRegistry(manifest) {
     const contentKey = normalizeBaselineHash(declared?.contentKey);
     const revision = normalizePageBodyRevision(declared?.revision);
     const displayDate = normalizeBaselineDisplayDate(declared?.displayDate);
+    const author = normalizeAuthorValue(declared?.author);
     const baseline =
       remoteHash === undefined && sourceHash === undefined && revision === undefined && displayDate === undefined
-        && contentKey === undefined
+        && contentKey === undefined && author === undefined
         ? undefined
         : {
           ...(remoteHash === undefined ? {} : { remoteHash }),
@@ -433,12 +469,31 @@ export function pageSourceRegistry(manifest) {
           ...(contentKey === undefined ? {} : { contentKey }),
           ...(revision === undefined ? {} : { revision }),
           ...(displayDate === undefined ? {} : { displayDate }),
+          // The author the site held for the page when this workspace last
+          // reconciled with it: what a page's own author reference is
+          // compared with before anything is sent (TR01196).
+          ...(author === undefined || author === "" ? {} : { author }),
         };
     const record = {
       pageId: entry.pageId,
       file: entry.file,
       sourceFormat,
       baseline,
+      // What a generated page was when this workspace last pulled it, kept so a
+      // pull that cannot read its body does not forget it (TR01195).
+      ...(entry.generated !== null && typeof entry.generated === "object" && !Array.isArray(entry.generated)
+        ? { generated: entry.generated }
+        : {}),
+      // What this workspace says the page's metadata is; a .pm.json page's only
+      // record of it (TR01194).
+      metadata: {
+        title: typeof entry.title === "string" ? entry.title : "",
+        path: typeof entry.path === "string" ? entry.path : "",
+        description: typeof entry.description === "string" ? entry.description : "",
+        // The author reference the site holds for the page, or the one a
+        // `pages meta set --author` is waiting to send (TR01196).
+        author: normalizeAuthorValue(entry.author) ?? "",
+      },
       baselineDiscarded: declared !== undefined && baseline === undefined,
       formatMismatch: entry.sourceFormat !== undefined && entry.sourceFormat !== sourceFormat,
       duplicateSource: false,
@@ -713,6 +768,7 @@ export async function ensureWorkspaceDirectory(workspaceDir, relativeDirectory =
 export async function readWorkspaceFile(workspaceDir, relativePath, maximumBytes) {
   const filePath = resolveWorkspacePath(workspaceDir, relativePath);
   if (!await requireRealDirectoryChain(workspaceDir, relativePath)) {
+    noteFileMissing(relativePath);
     throw new SiteAuthoringError(
       "workspace.file_missing",
       `Workspace file '${relativePath}' does not exist.`,
@@ -744,10 +800,13 @@ export async function readWorkspaceFile(workspaceDir, relativePath, maximumBytes
       if (bytesRead === 0) break;
       total += bytesRead;
     }
-    return buffer.subarray(0, total);
+    const contents = buffer.subarray(0, total);
+    noteFileRead(relativePath, contents);
+    return contents;
   } catch (error) {
     if (error instanceof SiteAuthoringError) throw error;
     if (error && typeof error === "object" && error.code === "ENOENT") {
+      noteFileMissing(relativePath);
       throw new SiteAuthoringError(
         "workspace.file_missing",
         `Workspace file '${relativePath}' does not exist.`,
@@ -778,6 +837,7 @@ const STREAM_HEADER_BYTES = 4096;
 export async function openWorkspaceFileStream(workspaceDir, relativePath, maximumBytes) {
   const filePath = resolveWorkspacePath(workspaceDir, relativePath);
   if (!await requireRealDirectoryChain(workspaceDir, relativePath)) {
+    noteStreamMissing(relativePath);
     throw new SiteAuthoringError(
       "workspace.file_missing",
       `Workspace file '${relativePath}' does not exist.`,
@@ -812,6 +872,7 @@ export async function openWorkspaceFileStream(workspaceDir, relativePath, maximu
       total += bytesRead;
     }
     const opened = handle;
+    noteStreamOpened(relativePath, byteLength, modifiedMilliseconds, header.subarray(0, total));
     return {
       byteLength,
       modifiedMilliseconds,
@@ -850,6 +911,7 @@ export async function openWorkspaceFileStream(workspaceDir, relativePath, maximu
     await handle?.close().catch(() => {});
     if (error instanceof SiteAuthoringError) throw error;
     if (error && typeof error === "object" && error.code === "ENOENT") {
+      noteStreamMissing(relativePath);
       throw new SiteAuthoringError(
         "workspace.file_missing",
         `Workspace file '${relativePath}' does not exist.`,
@@ -885,6 +947,12 @@ export async function readWorkspaceJson(workspaceDir, relativePath, maximumBytes
  * read outside the workspace.
  */
 export async function inspectWorkspaceEntry(workspaceDir, relativePath) {
+  const kind = await classifyWorkspaceEntry(workspaceDir, relativePath);
+  noteEntry(relativePath, kind);
+  return kind;
+}
+
+async function classifyWorkspaceEntry(workspaceDir, relativePath) {
   const target = resolveWorkspacePath(workspaceDir, relativePath);
   // The leaf `lstat` below refuses a linked final component; this refuses a
   // linked one anywhere above it, which is how `media/link/sub` would otherwise
@@ -929,6 +997,12 @@ export async function inspectWorkspaceEntry(workspaceDir, relativePath) {
  * missing.
  */
 export async function workspaceFileExists(workspaceDir, relativePath) {
+  const exists = await regularFileExists(workspaceDir, relativePath);
+  noteExists(relativePath, exists);
+  return exists;
+}
+
+async function regularFileExists(workspaceDir, relativePath) {
   const filePath = resolveWorkspacePath(workspaceDir, relativePath);
   if (!await requireRealDirectoryChain(workspaceDir, relativePath)) return false;
   let stats;
@@ -982,6 +1056,7 @@ export async function writeWorkspaceFile(workspaceDir, relativePath, contents, {
         ),
     },
   });
+  noteFileWritten(relativePath, contents);
   return relativePath;
 }
 
@@ -998,7 +1073,7 @@ export async function writeWorkspaceJson(workspaceDir, relativePath, value) {
  * exists to prevent.
  */
 export async function deleteWorkspaceFile(workspaceDir, relativePath) {
-  if (!await workspaceFileExists(workspaceDir, relativePath)) return false;
+  if (!await regularFileExists(workspaceDir, relativePath)) return false;
   try {
     await unlink(resolveWorkspacePath(workspaceDir, relativePath));
   } catch (error) {
@@ -1009,6 +1084,7 @@ export async function deleteWorkspaceFile(workspaceDir, relativePath) {
       { field: relativePath },
     );
   }
+  noteFileDeleted(relativePath);
   return true;
 }
 
@@ -1040,8 +1116,12 @@ export async function walkWorkspaceFiles(
   extensions,
   { segmentPattern = SAFE_SEGMENT, segmentDescription = "letters, digits, '.', '_', and '-'" } = {},
 ) {
+  const filter = `${extensions.join(",")}|${segmentPattern}`;
   const rootPath = resolveWorkspacePath(workspaceDir, relativeRoot);
-  if (!await requireRealDirectoryChain(workspaceDir, relativeRoot, { includeLeaf: true })) return [];
+  if (!await requireRealDirectoryChain(workspaceDir, relativeRoot, { includeLeaf: true })) {
+    noteWalk(relativeRoot, filter, []);
+    return [];
+  }
   const collected = [];
   const queue = [{ directory: rootPath, relative: relativeRoot, depth: 0 }];
   while (queue.length > 0) {
@@ -1088,7 +1168,9 @@ export async function walkWorkspaceFiles(
       }
     }
   }
-  return collected.sort();
+  collected.sort();
+  noteWalk(relativeRoot, filter, collected);
+  return collected;
 }
 
 /**
@@ -1112,6 +1194,14 @@ export function normalizePagePath(value) {
   return trimmed;
 }
 
+/**
+ * A page path as results show it: the home page is '/', everything else as
+ * stored. The manifest and the wire keep the empty root path.
+ */
+export function displayPagePath(value) {
+  return (normalizePagePath(value) ?? value) || "/";
+}
+
 /**
  * Chooses the workspace file name for a pulled page. The server's path is
  * preferred because it is what an author recognizes, but it is server data
@@ -1324,6 +1414,11 @@ export async function readMediaManifest(workspaceDir, expectedSiteId) {
   };
 }
 
+/** The alt text a media record keeps when its file is uploaded again: the author's own, or none. */
+export function recordedAlt(entry) {
+  return typeof entry?.alt === "string" ? entry.alt : "";
+}
+
 export async function writeMediaManifest(workspaceDir, mediaManifest) {
   return await writeWorkspaceJson(workspaceDir, MEDIA_MANIFEST_FILE_NAME, mediaManifest);
 }