@taprootio/site-authoring 0.15.0 → 0.16.0

package/README.md

@@ -124,8 +124,12 @@ with no credential, no network, and no write: every page source (metadata,
 Markdown conversion, media references, content vocabulary, section contexts),
 page paths and templates against the pages the pull recorded, navigation,
 redirects, forms, and the complete theme, appearance, header, brand, and
-footer. It reports every problem at once in `error.problems`, each with its
-file, code, and field, instead of one per run.
+footer. Navigation to a generated page (a section, tag or place page) resolves
+against the pages the pull recorded. It reports every problem at once in
+`error.problems`, each with its file, code, and field, instead of one per run.
+Warnings never refuse: `linkWarnings` names a link whose address is only
+`http(s)://` plus its own text (`content.link_autolinked`, left by older editor
+autolinking), and `pages push` reports the same for the pages it sends.
 
 `taproot-site validate <fixture-directory>` checks a complete offline fixture
 the same way: a directory laid out like a
@@ -360,6 +364,92 @@ it is created: a source for another template is refused with
 `pages.template_immutable`. `taproot-site help page <type>` gives each
 template's fields and one worked example.
 
+A `.pm.json` page's title, path, description and author live in the workspace
+manifest rather than the file. `pages meta set <path> --title <text>
+--description <text>` changes the title or description there (a Markdown page
+keeps them in its front matter; `--author` is described under *Page authors*); `pull` keeps that edit until `pages push`
+sends it, and a site edit to the same page is a `pages.pull_conflict`. A
+description over 160 characters is a warning (`descriptionWarnings`), because
+search results cut it off; over 1000 is refused with
+`pages.description_too_long`, by the CLI and by Taproot.
+
+### Page authors
+
+Pages are authorless by default: a page you create with the CLI publishes with
+no byline unless you name an author, and `pages push` lists the pages it created
+that way in `pages.authorless`, with how to credit them. An author is one of two
+kinds of person, named by one string:
+
+- a **site author without a Taproot account** — one of an imported blog's
+  authors, say — named by handle (`jane-doe`: lowercase letters, digits and
+  single hyphens, at most 64 characters, fixed when the author is created). A
+  site author's name appears on the byline and in the page's structured data;
+  there is no profile link or follow button, because there is no account;
+- a **site member who can create pages**, named by email address.
+
+`authors list` prints both and rewrites `authors.json` (`pull` writes it too).
+`authors add jane-doe --name "Jane Doe" [--email jane@example.com]` creates a
+site author; `--email` is kept private (never published, never listed) so the
+person can be linked to a Taproot account later. Adding a handle the site
+already has under the same name succeeds and reports `existing: true`, so a
+script can repeat itself; a different name for a taken handle is refused
+(`authors.handle_taken`), naming the one the site has. `authors.json` holds the
+members' email addresses, so keep it out of a public repository.
+
+A page names its author with `author: jane-doe` in its front matter (any
+template), or, for a `.pm.json` page, `pages meta set <path> --author jane-doe`.
+Only the CLI assigns authors, and only to a page that has none; people editing
+in the app are never asked to name one. `authors.json` is as old as the last
+`pull` or `authors list`, so a name missing from it is not proof the person does
+not exist. `validate` and `pages meta set` run offline: they refuse text that
+is neither a handle nor an address (`pages.author_invalid`) and otherwise only
+warn (`pages.author_unverified`, in `authorWarnings`) about a name `authors.json`
+lacks. `pages push` and `plan` settle it online: on a miss they read the site's
+current list once (`pages push` rewrites `authors.json` with it) and refuse
+(`pages.author_unknown`) only a name the site really lacks. A member who cannot
+create pages is `pages.author_unknown` as well, with the same wording.
+
+The CLI only fills a page that has no author: a page that already has a
+different one is refused (`pages.author_conflict`), by the CLI from what the
+last pull recorded and by Taproot, and naming the author a page already has
+changes nothing. The refusal says how to settle it: for a `.pm.json` page,
+`pages meta set <path> --author <the site's author>` matches the site, and
+`pages meta set <path> --author ""` drops an author that was never sent (it
+never asks the site to remove one, and is refused once the site holds an
+author); for a Markdown page, fix the `author:` line. `pull` keeps a pending
+author the site now disagrees with and says so. The author is recorded on the
+page's manifest entry (`author`, and `baseline.author` for what the site
+held), so a re-push never resends it. The site names a page's author in
+listings only while that person can still be named: a former member's page, or
+a member who can no longer create pages, reports none, and a push that names
+someone else on it is refused as a conflict.
+
+Pages Taproot generates from the site's content — a tag, the tags index, a
+published year or month, a place archive, a folder — are update-only sources.
+`pull` writes each as `pages/<name>.pm.json` with `"template": "generated"`:
+`data` holds what the page is (`kind`, `tagId`, `year`, `month`, `countryCode`,
+`regionCode`, `citySlug`, `categorySlug`, which you leave as pulled) and the four
+things that are yours to author: `customTitle`, `breadcrumbTitle`,
+`customDescription` and `introductionBody`. An empty string means "use the
+generated default"; the description then falls back to the introduction's first
+paragraph, else the system default. The manifest keeps the title and description
+the site reports, for reference. `pages meta set <path> --title/--description`
+edits `customTitle` and `customDescription` in the source (an empty value
+clears it), and `pages push` sends the page back as an unapproved draft. The
+title and description the site stores are derived from `customTitle`,
+`customDescription` and `introductionBody`, so what a push sends for them is
+ignored. A push refuses to create a generated page (`pages.generated_create`),
+move one (`pages.generated_move`) or change its kind or identity
+(`pages.generated_identity`, also when the manifest has no record of what the
+file was pulled as: run `pull`); there is no Markdown form
+(`pages.generated_markdown`). A generated page you did not edit never blocks a
+push of the whole workspace, even when Taproot moved it since the pull (a tag was
+renamed). If the site no longer has the page (its tag, month or folder is gone),
+a whole-workspace push reports the file under `pages.staleGeneratedSources` and
+sends nothing for it, and `pull` says so; delete the file. Naming that path in
+`pages push <page-path>` is refused with `pages.generated_create`. A description over 160 characters is warned about,
+since search results cut it off, and one over 1000 is refused.
+
 `pages push [page-path...]` validates and sends the selected pages, or every
 workspace page when none is named; the homepage is addressed as `/`. Every
 selected page is checked before anything is sent, and a refusal lists every
@@ -557,6 +647,25 @@ targets are refused (`content.link_rel`, `content.link_target`). The editor's
 old default, `noopener noreferrer nofollow`, reads as no choice. See
 `taproot-site help page free-form`.
 
+### Authoring feedback in 0.16.0
+
+- `pages meta set <path> --title/--description/--author` edits a `.pm.json`
+  page's title, description or author; `pull` keeps the edit until `pages push`
+  sends it. Descriptions are warned about over 160 characters and refused over
+  1000, here and by Taproot.
+- Generated pages (tags, archives, places, folders) pull as update-only sources
+  whose custom title, breadcrumb, description and introduction you can edit.
+- Pages are authorless by default. `authors list`, `authors add` and
+  `authors.json` name a member who can create pages or a site author without a
+  Taproot account; `author:` front matter or `pages meta set --author` credits
+  one on a page that has none, and an author is never replaced from the CLI.
+- `redirects check` and `deploy --staging` report `routeCheck`, `redirects` and
+  `stagingPreview` at the top level; result paths spell the home page `/`;
+  `approve` skips a page with nothing to approve instead of failing the batch.
+- `validate` checks a real pulled workspace offline (`validate --init` keeps the
+  generated pages navigation links to), and `validate` and `pages push` warn on
+  links that look made by autolinking (`content.link_autolinked`).
+
 ### Staging verification and deployment evidence
 
 `deploy --staging` selects the same changed pages, settings groups and navigation
@@ -579,13 +688,15 @@ only error class and known page/node/attribute labels, never renderer messages.
 Staging deploys check the current redirect map through the real staging edge.
 Run `taproot-site redirects check` to repeat once the deployment has completed; a redirect is a file inside the release, so it is live exactly when its release is served.
 The Node CLI consumes a separate handoff, retains its short staging cookie in
-memory, and requests each map path without following redirects. Results report
-path, HTTP status and Location; `verified` requires all entries to match and the
+memory, and requests each map path without following redirects. Both
+`redirects check` and `deploy --staging` report `routeCheck` and `redirects` at
+the top level of their result: `redirects.items` lists each path, HTTP status
+and Location, and `redirects.verified` requires all entries to match and the
 map revision to remain unchanged. A mismatch is evidence to investigate, not a
 failed deployment. Checks describe the current map, not a historical release.
 Requests have a 90-second deadline with eight concurrent requests; large JSON
-lists have explicit truncation, prioritizing failures. Human output reports each
-entry. A gate/transport failure never counts as verified.
+lists have explicit truncation, prioritizing failures. Progress output reports
+each entry. A gate/transport failure never counts as verified.
 
 `stagingPreview.url` is a fresh single-use two-minute handoff minted **after**
 checks. Opening it consumes it and establishes a five-minute staging cookie.
@@ -640,8 +751,10 @@ The destination must be new, outside the source workspace, and its parent must e
 to select another source configuration. Initialization needs no credential or
 network. It exports editable pages of every template as workspace documents with navigation,
 redirects, settings, and version-7 appearance/footer metadata, validates the
-result, and leaves the source unchanged. Excluded metadata-only pages are
-counted; unresolved references to them fail validation.
+result, and leaves the source unchanged. A metadata-only page that navigation,
+the footer or a page links to, such as a generated section page, is kept as a
+metadata-only entry (`initialized.linkedPages`); other metadata-only pages are
+left out (`initialized.skippedPages`).
 
 Exported UUIDs and HTTP(S) origins are deterministic fixture values under
 `example.test`; URL credentials, query strings and fragments are removed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Taproot site authoring CLI: sign in once in the browser, then pull, validate, push, preview, approve, and deploy a site from the terminal",
   "type": "module",
   "license": "ISC",

package/src/api.js

@@ -23,6 +23,7 @@ import {
 // would turn a successful mint into an orphaned key.
 import { KEY_PREFIX } from "./credentials.js";
 import { isCanonicalUuid, normalizePreviewDiagnostic, sanitizeDiagnostic, SiteAuthoringError } from "./errors.js";
+import { normalizeAuthorListing, parseAuthorReference } from "./authors-contract.js";
 import { docsPublicationModeFromWire, siteKindFromWire, surfaceFromWire } from "./surface.js";
 import {
   DEFAULT_REDIRECT_STATUS,
@@ -499,6 +500,14 @@ export function normalizePageSummary(value) {
     // The page's calendar date, empty when it has none. It is not part of
     // `bodyRevision`, so a typed page's push guard compares it separately.
     displayDate: typeof summary.displayDate === "string" ? summary.displayDate : "",
+    // The name the page's author goes by in a write: a site author's handle or
+    // a member's email address, folded. Empty for a page with no author, for a
+    // former member's page, and against a Taproot that predates authors
+    // (TR01196). Never the author's display name, which is not a reference.
+    authorRef: typeof summary.authorRef === "string" ? parseAuthorReference(summary.authorRef)?.value ?? "" : "",
+    // Whether the page credits anyone at all, which an empty authorRef cannot
+    // say: it is also empty for an author this credential may not name.
+    hasAuthor: typeof summary.authorDisplayName === "string" && summary.authorDisplayName.trim() !== "",
   };
 }
 
@@ -545,6 +554,62 @@ export async function updatePage(client, pageId, body) {
   );
 }
 
+/**
+ * Gives the site's two author refusals the stable codes the CLI documents
+ * (TR01196). The site answers an unknown name and one that cannot be named with
+ * the same field and wording on purpose; this keeps them one code too.
+ */
+export function translateAuthorRefusal(error, file) {
+  if (!(error instanceof ApiError)) return error;
+  for (const [field, code, fallback] of [
+    ["AuthorUnknown", "pages.author_unknown", "No site author or member who can create pages has that name."],
+    ["AuthorConflict", "pages.author_conflict", "The page already has a different author, which is never replaced."],
+  ]) {
+    if (error.hasField(field)) {
+      const detail = sanitizeDiagnostic(error.descriptionFor(field) ?? fallback, fallback);
+      // The workspace only learns who the site credits from a pull, and a
+      // conflict means someone gave the page an author after the last one.
+      const hint = field === "AuthorConflict"
+        ? " Run 'taproot-site pull' to learn who the site credits, then match it with 'pages meta set <path> --author "
+          + "<author>' (a .pm.json page) or the author: front matter line (Markdown)."
+        : "";
+      return new SiteAuthoringError(code, `'${file}': ${detail}${hint}`, { field: file });
+    }
+  }
+  return error;
+}
+
+/**
+ * Reads who a page can be credited to: the site's authors without an account
+ * and the members who can create pages (TR01196).
+ */
+export async function listSiteAuthors(client, siteId) {
+  return normalizeAuthorListing(
+    requireObject(await client.request(sitePath(siteId, "authors")), "api.authors_contract", "site authors"),
+  );
+}
+
+/** Creates a site author. The site folds the handle and the address. */
+export async function createSiteAuthor(client, siteId, { handle, displayName, email }) {
+  const created = requireObject(
+    await client.request(sitePath(siteId, "authors"), {
+      method: "POST",
+      body: { handle, displayName, ...(email === undefined ? {} : { email }) },
+    }),
+    "api.authors_contract",
+    "site author",
+  );
+  const listing = normalizeAuthorListing({ authors: [created], members: [] });
+  if (listing.authors.length !== 1) {
+    throw new SiteAuthoringError(
+      "api.authors_contract",
+      "Taproot returned a site author this CLI could not read.",
+      { field: "handle" },
+    );
+  }
+  return listing.authors[0];
+}
+
 export async function publishDrafts(client, pageIds) {
   const response = requireObject(
     await client.request("v1/pages/publish_drafts", { method: "POST", body: { pageIds } }),

package/src/authors-contract.js

@@ -0,0 +1,170 @@
+import { SiteAuthoringError } from "./errors.js";
+
+/**
+ * Who a page can be credited to (TR01196).
+ *
+ * A page's author is one of two kinds of person, named by one string:
+ *
+ * - a site member who can create pages, by email address; or
+ * - a site author without a Taproot account, by handle. Handles are a
+ *   lowercase slug the site fixes when the author is created, so a page keeps
+ *   pointing at the same person if their display name changes.
+ *
+ * The two spellings cannot collide: a handle never contains '@'. The site
+ * folds case on both (an address is stored lowercase, a handle is lowercase),
+ * so this module does too, and compares only folded values.
+ */
+
+export const AUTHORS_FILE_NAME = "authors.json";
+
+export const AUTHOR_HANDLE_MAXIMUM_LENGTH = 64;
+export const AUTHOR_DISPLAY_NAME_MAXIMUM_LENGTH = 256;
+export const AUTHOR_EMAIL_MAXIMUM_LENGTH = 320;
+
+const HANDLE = /^[a-z0-9]+(-[a-z0-9]+)*$/u;
+// Deliberately loose: the site canonicalizes and decides. This only tells an
+// address from a handle and refuses text that cannot be one.
+const EMAIL = /^[^\s@<>()]+@[^\s@<>()]+\.[^\s@<>()]+$/u;
+
+export const AUTHOR_KIND_HANDLE = "handle";
+export const AUTHOR_KIND_EMAIL = "email";
+
+/** The folded handle, or undefined when the text is not a handle. */
+export function normalizeAuthorHandle(value) {
+  if (typeof value !== "string") return undefined;
+  const handle = value.trim().toLowerCase();
+  return handle.length > 0 && handle.length <= AUTHOR_HANDLE_MAXIMUM_LENGTH && HANDLE.test(handle)
+    ? handle
+    : undefined;
+}
+
+/** The folded address, or undefined when the text is not an email address. */
+export function normalizeAuthorEmail(value) {
+  if (typeof value !== "string") return undefined;
+  const email = value.trim().toLowerCase();
+  return email.length <= AUTHOR_EMAIL_MAXIMUM_LENGTH && EMAIL.test(email) ? email : undefined;
+}
+
+/**
+ * What an `author` reference names: `{ kind, value }` with the folded value, or
+ * undefined for text that is neither a handle nor an email address.
+ */
+export function parseAuthorReference(value) {
+  if (typeof value !== "string") return undefined;
+  if (value.includes("@")) {
+    const email = normalizeAuthorEmail(value);
+    return email === undefined ? undefined : { kind: AUTHOR_KIND_EMAIL, value: email };
+  }
+  const handle = normalizeAuthorHandle(value);
+  return handle === undefined ? undefined : { kind: AUTHOR_KIND_HANDLE, value: handle };
+}
+
+/** The folded reference, or a refusal that names where it was written. */
+export function requireAuthorReference(value, field, code = "pages.author_invalid") {
+  const reference = parseAuthorReference(value);
+  if (reference === undefined) {
+    throw new SiteAuthoringError(
+      code,
+      `'${typeof value === "string" ? value.slice(0, 80) : ""}' is not an author reference. Name a site author by `
+        + "handle (lowercase letters, digits and hyphens, such as jane-doe) or a site member by email address.",
+      { field },
+    );
+  }
+  return reference.value;
+}
+
+function boundedText(value, maximum) {
+  return typeof value === "string" && value.length <= maximum ? value : undefined;
+}
+
+/**
+ * Reads the site's author listing, refusing a response that does not have the
+ * shape this CLI relies on. A member's address is only present for a caller
+ * allowed to see it; the CLI's credential is, so an absent one is dropped.
+ */
+export function normalizeAuthorListing(value) {
+  const listing = value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const authors = [];
+  for (const raw of Array.isArray(listing.authors) ? listing.authors : []) {
+    const handle = normalizeAuthorHandle(raw?.handle);
+    if (handle === undefined) continue;
+    authors.push({
+      handle,
+      displayName: boundedText(raw.displayName, AUTHOR_DISPLAY_NAME_MAXIMUM_LENGTH) ?? "",
+      hasEmail: raw.hasEmail === true || (typeof raw.email === "string" && raw.email !== ""),
+    });
+  }
+  const members = [];
+  for (const raw of Array.isArray(listing.members) ? listing.members : []) {
+    const email = normalizeAuthorEmail(raw?.email);
+    if (email === undefined) continue;
+    members.push({
+      email,
+      displayName: boundedText(raw.displayName, AUTHOR_DISPLAY_NAME_MAXIMUM_LENGTH) ?? "",
+    });
+  }
+  return { authors, members };
+}
+
+/**
+ * The workspace file `pull` and `authors list` write. Site authors carry no
+ * address: it is private to the site and nothing local needs it. Members carry
+ * theirs, because that is how a page names them.
+ */
+export function projectAuthorsForWorkspace(siteId, listing) {
+  return {
+    siteId,
+    authors: listing.authors.map(({ handle, displayName }) => ({ handle, displayName })),
+    members: listing.members.map(({ email, displayName }) => ({ email, displayName })),
+  };
+}
+
+/**
+ * Reads `authors.json` back. Anything unreadable or bound to another site is
+ * treated as absent: it can only ever make a reference unprovable offline,
+ * never turn a valid one into a refusal.
+ */
+export function readAuthorsDocument(value, siteId) {
+  if (value === null || typeof value !== "object" || Array.isArray(value) || value.siteId !== siteId) {
+    return undefined;
+  }
+  const handles = new Set();
+  for (const author of Array.isArray(value.authors) ? value.authors : []) {
+    const handle = normalizeAuthorHandle(author?.handle);
+    if (handle !== undefined) handles.add(handle);
+  }
+  const emails = new Set();
+  for (const member of Array.isArray(value.members) ? value.members : []) {
+    const email = normalizeAuthorEmail(member?.email);
+    if (email !== undefined) emails.add(email);
+  }
+  return { handles, emails };
+}
+
+/**
+ * Whether a folded reference names someone the recorded listing knows, or
+ * `undefined` when there is no listing to ask.
+ */
+export function authorKnown(authors, reference) {
+  if (authors === undefined) return undefined;
+  const parsed = parseAuthorReference(reference);
+  if (parsed === undefined) return false;
+  return parsed.kind === AUTHOR_KIND_EMAIL ? authors.emails.has(parsed.value) : authors.handles.has(parsed.value);
+}
+
+/**
+ * The refusal text for a source that names a different author than the site
+ * holds. The way out depends on where the author is written: a `.pm.json`
+ * page keeps it in the workspace manifest, edited with `pages meta set`; a
+ * Markdown page keeps it in its front matter (TR01196).
+ */
+export function authorConflictMessage({ shown, file, held, wanted, markdown }) {
+  const lead = `Page '${shown}' already has the author '${held}'`
+    + (wanted === undefined ? "" : `, and '${file}' names '${wanted}'`)
+    + ". An author is never replaced from the CLI";
+  return markdown
+    ? `${lead}: set 'author: ${held}' in the front matter, or remove the line, to match the site. To credit someone `
+      + "else, change it in the app."
+    : `${lead}: run 'taproot-site pages meta set ${shown} --author ${held}' to match the site. To credit someone `
+      + "else, change it in the app.";
+}