@augurworks/augur 0.15.1

package/src/currency.mjs

@@ -0,0 +1,203 @@
+// What is current here, and what has been left behind.
+//
+// `F-currency-default`. Divergence is cheap in a workspace — a second version of a screen
+// costs a folder — so the shelf fills with abandoned paths fast, and a repository where the
+// live thing and the dead thing look identical has stopped being a repository. The failure
+// is quiet: nothing breaks, nothing 404s, the gallery just slowly stops meaning anything.
+//
+// The two facts that answer it were already recorded, in two different places, and neither
+// was on a card:
+//
+//   · STATUS — what a person said about this unit — is a row in the workspace overlay,
+//     written by the chip on the card and read by `/__status`. It was visible only as a
+//     20px glyph on the preview image, and only to somebody who already knew to hover it.
+//   · EDITED-AT — when this unit's bytes last actually changed — is stamped per file at
+//     COMMIT by the publish handler and carried forward untouched for every file a publish
+//     did not change. It was rendered nowhere at all.
+//
+// ⚠️ STALENESS IS DERIVED, AND MUST STAY DERIVED. The obvious shape — an "archived" flag
+// somebody sets — is the bug wearing the fix's clothes: the person who abandons a
+// prototype is by definition not coming back to tick a box, so the flag is accurate only
+// for the units that were never the problem. Everything here is computed from `editedAt`
+// and a clock. There is NO new stored field, and adding one would put the junk drawer back.
+//
+// ⚠️ ABSENT IS AN ANSWER, AND IT IS NOT "FRESH". A file published before the stamp existed
+// carries no `editedAt`, so its unit's `stale` is `null` — unknown — and it gets no
+// treatment at all. Defaulting the unknown to either end would be inventing the exact fact
+// the stamp exists to stop being invented: false-stale accuses somebody's live work, and
+// false-fresh is the junk drawer with a clean bill of health. The treatment therefore turns
+// on unit by unit as content is republished, which is slower than a flag day and true.
+//
+// The module is PURE and lives in `src/` because three callers need to agree: the worker
+// (which answers `/__currency` and `/__publish/<space>/currency`), build.js (which bakes
+// the first paint), and the suite. Same reason `src/publish-units.mjs` lives here.
+
+import { spanWords, relTime } from "./chrome/appchrome.mjs";
+import { authoredUnits } from "./publish-units.mjs";
+
+/**
+ * How long a unit may go untouched before the gallery says so, in days.
+ *
+ * NINETY, and the number is a judgement, so here is the judgement. It is a full planning
+ * quarter: a prototype somebody returns to once a cycle — the norm for anything still
+ * being argued about — never gets marked, and only something skipped for an entire cycle
+ * does. The failure directions are not symmetrical, which is what sets the floor rather
+ * than the ceiling. A false stale mark is an accusation against live work and costs the
+ * signal its credibility the first time somebody sees it on the thing they shipped
+ * yesterday; a late one costs a few weeks of a card looking ordinary. So the threshold is
+ * set where it cannot fire on ordinary working rhythm — a holiday, a re-org, a quarter
+ * spent on something else — and it is one number in one place, echoed in every answer
+ * (`staleAfterDays`) so no client and no agent ever hardcodes a second copy of it.
+ */
+export const STALE_AFTER_DAYS = 90;
+
+const DAY_MS = 86400000;
+
+/**
+ * The status vocabulary's WORDS. One table — the worker validates against its keys, build.js
+ * takes its labels, and the currency line prints them — because the whole point of this
+ * item is that a status is legible without hovering anything, and a status spelled two ways
+ * on two surfaces is not legible.
+ */
+export const STATUS_LABELS = Object.freeze({
+  "in-progress": "In progress",
+  "dev-ready": "Dev ready",
+  ignore: "Ignore",
+  reviewed: "Reviewed",
+});
+
+// A poster is a BUILD OUTPUT committed back into the folder, so a reshoot is not an edit —
+// and one reshoot touches every folder on the site at once. Counting it would move every
+// card to "edited now" in a single commit, which is not a hypothetical: it happened, to 76
+// folders, and it is why the git-derived pass carries the same exclusion. build.js imports
+// THIS test rather than keeping its own, so the stamp-derived answer and the git-derived
+// answer cannot come to disagree about what a person wrote.
+//
+// A regex LITERAL, not a `new RegExp` built from a list of basenames: the module-scope lint
+// (scripts/no-tenant-globals.mjs) can prove a literal holds no state and cannot prove it of
+// a constructor call, so the prettier version costs two allowlist entries and buys nothing.
+const GENERATED_ASSET = /(^|\/)(preview\.webp|og\.jpg)$/i;
+
+/** Is this path a build output rather than something a person wrote? */
+export const isGeneratedAsset = (p) => GENERATED_ASSET.test(String(p == null ? "" : p));
+
+const decode = (s) => { try { return decodeURIComponent(String(s)); } catch (e) { return String(s); } };
+
+/**
+ * The overlay status key for a unit path.
+ *
+ * `/checkout/flow/` is the unit; `checkout/flow` is the key the status chip has always
+ * written under (`data-status-key`). Decoded and unslashed, and nothing more — the two
+ * spellings must keep meeting, so this is the one place that converts between them.
+ */
+export const unitKey = (unitPath) => decode(unitPath).replace(/^\/+|\/+$/g, "");
+
+/**
+ * When this unit's bytes last changed, and who by, from the manifest's per-file stamps.
+ *
+ * The NEWEST stamp in the folder wins: a unit is a folder and editing any file in it is
+ * editing the unit. Files with no stamp are skipped rather than counted as old, and a unit
+ * where every file is unstamped answers `null` — see the header on why that is not "fresh".
+ */
+export function unitProvenance(manifest, unitPath) {
+  const prefix = decode(unitPath);
+  let at = 0, editedAt = null, by = null;
+  for (const [p, f] of Object.entries((manifest || {}).files || {})) {
+    if (!decode(p).startsWith(prefix)) continue;
+    if (isGeneratedAsset(p)) continue;
+    const t = f && f.editedAt ? Date.parse(f.editedAt) : NaN;
+    if (!Number.isFinite(t) || t <= at) continue;
+    at = t; editedAt = f.editedAt; by = f.by || null;
+  }
+  return { editedAt, by };
+}
+
+/**
+ * The whole of the staleness decision, in one function with no I/O.
+ *
+ * `stale` is a THREE-valued answer — true, false, or null for "no record" — because the
+ * two-valued version has to guess about unstamped content, and there is no honest guess.
+ */
+export function freshness(editedAt, now = Date.now()) {
+  const t = editedAt ? Date.parse(editedAt) : NaN;
+  if (!Number.isFinite(t)) return { ageDays: null, stale: null };
+  const ageDays = Math.max(0, Math.floor((now - t) / DAY_MS));
+  return { ageDays, stale: ageDays >= STALE_AFTER_DAYS };
+}
+
+/**
+ * The sentence a card shows for a unit's freshness.
+ *
+ * A stale unit does not get the same sentence in a different colour: "Edited 7 months ago"
+ * asks the reader to do the arithmetic and know the threshold, and most of them will do
+ * neither. "Untouched for 7 months" is the finding, stated. Both come off the same counter.
+ */
+export function whenWords(editedAt, now = Date.now()) {
+  const { stale } = freshness(editedAt, now);
+  if (stale === null) return null;
+  const t = Date.parse(editedAt);
+  return stale ? `Untouched for ${spanWords(t, now)}` : relTime(t, now);
+}
+
+/**
+ * How far back a `since` window reaches, in ms — `14d`, `2w`, `36h`, or a bare number of
+ * days. Returns 0 for anything it does not understand, so a caller refuses rather than
+ * silently answering a different question than the one asked.
+ */
+export function parseSince(raw) {
+  const m = /^\s*(\d+)\s*([hdw])?\s*$/i.exec(String(raw == null ? "" : raw));
+  if (!m) return 0;
+  const n = parseInt(m[1], 10);
+  if (!n) return 0;
+  const unit = (m[2] || "d").toLowerCase();
+  return n * (unit === "h" ? 3600000 : unit === "w" ? 7 * DAY_MS : DAY_MS);
+}
+
+/**
+ * Every authored unit in a workspace, with what is known about it. The ONE read — the
+ * gallery paints from it and an agent answers "what changed here" from it, so there is no
+ * second definition of current to drift.
+ *
+ * `spaces` is the live manifest map (`loadManifests`'s shape). `_engine` is skipped: it is
+ * shared chrome, it has no authored units, and a deploy would make the whole site look
+ * freshly edited.
+ */
+export function currencyRows(spaces, statuses, { now = Date.now(), sinceMs = 0 } = {}) {
+  const rows = [];
+  const floor = sinceMs ? now - sinceMs : 0;
+  for (const [space, manifest] of Object.entries(spaces || {})) {
+    if (space === "_engine") continue;
+    for (const path of authoredUnits(manifest)) {
+      const key = unitKey(path);
+      const { editedAt, by } = unitProvenance(manifest, path);
+      const { ageDays, stale } = freshness(editedAt, now);
+      // A `since` window asks what CHANGED. A unit with no record did not answer, and
+      // listing it would put "we don't know" in a list of things that happened.
+      if (floor && (!editedAt || Date.parse(editedAt) < floor)) continue;
+      const status = (statuses && Object.prototype.hasOwnProperty.call(statuses, key) && statuses[key]) || null;
+      rows.push({
+        key,
+        path,
+        space,
+        status,
+        statusLabel: (status && STATUS_LABELS[status]) || null,
+        editedAt: editedAt || null,
+        // The recorded author id, exactly as the manifest holds it: `personId(email)`, a
+        // one-way hash, never an address. Resolving it to a name and a face belongs at the
+        // render, against the roster — it is not this read's job to hand out who.
+        by,
+        ageDays,
+        stale,
+        when: whenWords(editedAt, now),
+      });
+    }
+  }
+  // Newest first, unstamped last, then by path — so the first screenful of an agent's
+  // answer is the answer.
+  rows.sort((a, b) => {
+    const ta = a.editedAt ? Date.parse(a.editedAt) : -Infinity;
+    const tb = b.editedAt ? Date.parse(b.editedAt) : -Infinity;
+    return tb - ta || a.path.localeCompare(b.path);
+  });
+  return rows;
+}

package/src/delete-confirmation.mjs

@@ -0,0 +1,254 @@
+/**
+ * What a person is shown BEFORE a workspace is deleted.
+ *
+ * `F-tenant-delete-ux`. A delete is the one act on a workspace that no rollback reaches, so
+ * the screen in front of it has two jobs and this module is both of them: offer the export
+ * first, and state the retention window truthfully.
+ *
+ * ⚠️ EVERY NUMBER HERE IS DERIVED, AND THAT IS THE WHOLE POINT OF THE MODULE. The window is
+ * computed from the grace the tombstone actually uses (`DELETE_GRACE_MS` in `tenant-do.js`)
+ * and from the backup rotation the deployment declares — never typed. A hand-typed "30 days"
+ * in a confirmation screen is a promise that keeps being true only for as long as nobody
+ * changes the constant, and the day somebody does, the screen is the last thing anyone
+ * thinks to check. Derived copy cannot drift: change the constant and the sentence changes
+ * with it, or the test that pins the sentence fails.
+ *
+ * ⚠️ IT NEVER INVENTS THE BACKUP NUMBER. The engine knows exactly how long a tombstone
+ * survives, because it writes that date itself. It does NOT know how long a deployment's
+ * off-site backup copies live — that is a rotation somebody configures outside this code —
+ * so `backupRetentionMs` is an input with no default, and with none supplied the copy says
+ * that a backup copy outlives the erasure WITHOUT naming a period. Two wrong answers were
+ * available and both are worse: inventing a number promises a schedule nobody runs, and
+ * saying nothing at all tells a customer their data is gone everywhere when a backup still
+ * holds it. Absent is a fact, and the copy states it as one.
+ *
+ * ⚠️ IT RENDERS NOTHING. The confirmation is CONTENT — strings and numbers — because the two
+ * surfaces that show it live in different repos and cannot import each other: a workspace's
+ * own settings here, and an operator console in the control plane. A shape that crosses the
+ * wire is the only kind both can read, which is why `GET /__control/delete` serves this and
+ * nothing hand-copies the words.
+ *
+ * No product name, no deployment name, no address: a self-hosted instance and a hosted one
+ * show the same words, and "whoever runs this service" is the honest way to name an operator
+ * this code cannot identify.
+ */
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** The command that takes a copy of everything, including what `--full` adds. */
+export const EXPORT_COMMAND = "augur export --full";
+
+/** The route that command walks, for a surface that would rather link than instruct. */
+export const EXPORT_PATH = "/__publish/_state/export";
+
+/**
+ * Whole days, rounded DOWN, and the rounding direction is deliberate.
+ *
+ * A window stated as longer than it is, is a promise the erasure breaks. Flooring can only
+ * understate — somebody is told 30 days and gets 30 days and a few hours — and understating
+ * a deadline is the safe side of this particular wrong answer.
+ */
+function wholeDays(ms) {
+  return Math.floor(ms / DAY_MS);
+}
+
+/** "1 person" / "4 people" — a count that reads as English rather than as a field. */
+function plural(n, one, many) {
+  return `${n} ${n === 1 ? one : many}`;
+}
+
+/**
+ * The retention window, as numbers.
+ *
+ * `serviceDays` is what the tombstone gives you: the data is all still there, and the
+ * erasure refuses until the date passes. `backupDays` is the day the LAST copy anywhere
+ * expires — the grace plus the rotation, not the rotation on its own, because a backup taken
+ * the day before the erasure still holds the workspace and its own clock starts then.
+ * `null` means the deployment has not declared a rotation.
+ */
+export function retentionWindow({ graceMs, backupRetentionMs = null } = {}) {
+  if (!Number.isFinite(graceMs) || graceMs < 0) {
+    throw new Error("delete-confirmation: graceMs is required and must be a finite duration");
+  }
+  const configured = Number.isFinite(backupRetentionMs) && backupRetentionMs >= 0;
+  return {
+    serviceDays: wholeDays(graceMs),
+    backupDays: configured ? wholeDays(graceMs + backupRetentionMs) : null,
+  };
+}
+
+/**
+ * The sentence the published lifecycle policy owns, rebuilt from the live numbers.
+ *
+ * ⚠️ BYTE-IDENTICAL, ON PURPOSE, to the promise a customer already read before they got
+ * here: "gone from the service in 30 days, gone from the backups within 70". A confirmation
+ * screen that paraphrases the policy is a second policy, and the second one is the one
+ * nobody updates. Lower case and no full stop, because it is a CLAUSE — the policy page
+ * lands it mid-sentence and a confirmation screen wants a capital, so both grow their own
+ * punctuation from the same words rather than each keeping a copy of the sentence.
+ *
+ * With no rotation declared the clause stops at the half this code can prove.
+ */
+export function retentionClause(window) {
+  const service = `gone from the service in ${plural(window.serviceDays, "day", "days")}`;
+  if (window.backupDays == null) return service;
+  return `${service}, gone from the backups within ${window.backupDays}`;
+}
+
+function sentence(clause) {
+  return `${clause.charAt(0).toUpperCase()}${clause.slice(1)}.`;
+}
+
+/**
+ * What this workspace holds, as counts.
+ *
+ * Straight off `status()`, so a confirmation cannot disagree with the workspace's own
+ * account of itself, and counts ONLY — the same rule `status()` keeps. A confirmation screen
+ * is read by an operator who administers somebody else's workspace, and a comment body has
+ * no business being anywhere near one.
+ *
+ * Zeroes are dropped rather than listed: "0 boards" is noise on a screen whose job is to
+ * make somebody hesitate over what is actually there.
+ */
+function holdings(status) {
+  if (!status) return { items: [], line: null };
+  const items = [
+    ["members", plural(status.members || 0, "person", "people")],
+    ["threads", plural(status.threads || 0, "comment thread", "comment threads")],
+    ["boards", plural(status.boards || 0, "board", "boards")],
+    ["images", plural(status.images || 0, "image", "images")],
+  ]
+    .filter(([k]) => Number(status[k] || 0) > 0)
+    .map(([, text]) => text);
+  if (!items.length) return { items: [], line: null };
+  const line = items.length === 1
+    ? items[0]
+    : `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+  return { items, line };
+}
+
+/**
+ * The whole confirmation, for one workspace, at one instant.
+ *
+ * `at` is passed in rather than read from the clock so the erasure date on the screen and
+ * the erasure date the delete writes are the same arithmetic on the same instant. A screen
+ * that computed its own "now" would be off by the time somebody spent reading it, which is
+ * harmless until the day it straddles midnight and the date shown is not the date written.
+ *
+ * `alreadyDeleted` is not an error case: somebody reaching this screen for a workspace that
+ * is already tombstoned needs the date it is erased on, not a second chance to delete it.
+ */
+export function deleteConfirmation({
+  workspaceId,
+  graceMs,
+  at = Date.now(),
+  backupRetentionMs = null,
+  status = null,
+} = {}) {
+  const id = String(workspaceId || "");
+  const window = retentionWindow({ graceMs, backupRetentionMs });
+  const clause = retentionClause(window);
+  const startedAt = status && status.deletedAt ? Date.parse(status.deletedAt) : NaN;
+  const already = !!(status && status.deleted);
+  // An existing tombstone keeps its own date. Re-deleting does not restart the clock
+  // (`deleteWorkspace` refuses to), so a screen offering a fresh window would be lying about
+  // arithmetic that has already happened.
+  const erasedAt = already && status.purgeAfter
+    ? Date.parse(status.purgeAfter)
+    : (Number.isFinite(startedAt) ? startedAt : Number(at)) + graceMs;
+  const erasedOn = new Date(erasedAt).toISOString();
+  const holds = holdings(status);
+
+  const timeline = [
+    {
+      when: "Immediately",
+      what: "The workspace stops being served. Its address goes dark, signing in to it "
+        + "stops, and nothing it published is reachable by anyone.",
+    },
+    {
+      when: `For ${plural(window.serviceDays, "day", "days")}`,
+      what: "The data still exists, tombstoned. Nothing has been erased, and a delete "
+        + "somebody regrets can still be undone by whoever runs this service.",
+    },
+    {
+      when: `On ${erasedOn.slice(0, 10)}`,
+      what: "Everything is erased from the live service: published content, uploads, "
+        + "comments, boards, roster, history.",
+    },
+    window.backupDays == null
+      ? {
+        when: "After that",
+        what: "A backup copy can outlive the erasure. Backups are kept on their own "
+          + "rotation and are not thinned to remove one workspace — the last copy is "
+          + "waited out rather than rewritten.",
+      }
+      : {
+        when: `Within ${plural(window.backupDays - window.serviceDays, "further day", "further days")}`,
+        what: "The last backup copy containing it expires. After that no copy exists "
+          + "anywhere, and there is nothing left for anyone to restore.",
+      },
+  ];
+
+  return {
+    workspace: id,
+    title: already ? `${id} is already deleted` : `Delete ${id}?`,
+    alreadyDeleted: already,
+    holds: holds.items,
+    holdsLine: holds.line,
+    // Two steps, in this order, and the order IS the feature. The export is offered BEFORE
+    // the confirm rather than beside it, because the only copy that survives a delete is the
+    // one somebody took first, and a nudge that shares a row with the button that deletes is
+    // a nudge nobody reads.
+    steps: [
+      {
+        id: "export",
+        title: already ? "You can still take a copy" : "Take a copy first",
+        body: already
+          ? `A full export still runs on a deleted workspace until it is erased. `
+            + `Run ‘${EXPORT_COMMAND}’ while the data is still here.`
+          : `Run ‘${EXPORT_COMMAND}’ before you confirm. It is one command, it `
+            + `takes minutes, and it is the only copy that is definitely yours.`,
+        command: EXPORT_COMMAND,
+        path: EXPORT_PATH,
+      },
+      {
+        id: "confirm",
+        title: already ? "Nothing further to confirm" : "Then confirm",
+        body: already
+          ? `This workspace is already tombstoned. Deleting it again changes nothing and `
+            + `does not move the date below.`
+          : `Type the workspace's name to confirm. There is no undo once the date below `
+            + `passes.`,
+        confirmWith: already ? null : id,
+      },
+    ],
+    timeline,
+    retention: {
+      serviceDays: window.serviceDays,
+      backupDays: window.backupDays,
+      graceMs,
+      erasedOn,
+      // The clause the published policy owns, and the sentence a screen shows. Both from
+      // the same words — see retentionClause.
+      clause,
+      summary: sentence(clause),
+    },
+  };
+}
+
+/**
+ * A deployment's declared backup rotation, in milliseconds, or `null`.
+ *
+ * ⚠️ IT FAILS TO `null`, NEVER TO A NUMBER. Unset, blank, negative, non-numeric — every one
+ * of them means "this deployment has not told me", and the copy then states the backup tail
+ * without a period rather than guessing at one. A default here would be the invented number
+ * this module exists to refuse: an operator who never configured a rotation would get a
+ * confirmation screen promising a schedule that nothing runs.
+ */
+export function backupRetentionFromEnv(env) {
+  const raw = env && env.BACKUP_RETENTION_DAYS;
+  if (raw == null || raw === "") return null;
+  const days = Number(raw);
+  if (!Number.isFinite(days) || days < 0) return null;
+  return days * DAY_MS;
+}