@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.1

package/apps/storefront/src/lib/publish/mergeSupportEscalation.ts

@@ -0,0 +1,75 @@
+/**
+ * mergeSupportEscalation — the B3 escalation seam, sibling to
+ * {@link mergeHealthBanner} (top-of-tab summary) and {@link mergeRowFindings}
+ * (per-row chip/CTA). All three reduce the SAME `/api/changes` body through the
+ * SAME pure analyzer (`lib/preview/mergeDoctor.ts`); this one asks the analyzer's
+ * own {@link supportContext} whether ANY unresolved PLATFORM-owned fault remains
+ * (a retry didn't clear it) and, if so, pre-fills the store's EXISTING support
+ * channel — the `success@tokenoftrust.com` mailto the Publish tab already uses for
+ * its paywall upsell — with that structured payload.
+ *
+ * `supportContext()` is the ownership gate, and we TRUST it: it returns null for a
+ * fully developer-fixable queue (only `ownership:"platform"` findings escalate), so
+ * a free-text "I'm stuck" is impossible when the person could have self-served —
+ * `show` is FALSE in exactly that case. No new fetch, no new analysis pass, no
+ * re-implemented ownership check.
+ *
+ * One subtlety the sibling reducers sidestep by post-filtering (which we can't,
+ * since we must trust `supportContext` whole): a MISSING branches read makes the
+ * analyzer emit a platform-owned `BRANCH_REPORT_UNAVAILABLE`. That is an artifact
+ * of not analyzing the branch plane here, NOT a real fault, so when no
+ * `branchesBody` is supplied we present the branch report as empty-but-loaded (not
+ * "unavailable") — its absence must never manufacture an escalation.
+ */
+import {
+  analyzeMerge,
+  supportContext,
+  type ChangesInput,
+  type BranchesInput,
+} from "@/lib/preview/mergeDoctor";
+
+/** The support inbox — the SAME channel AdminPublishTab's paywall upsell mails. */
+export const SUPPORT_EMAIL = "success@tokenoftrust.com";
+
+export interface MergeSupportEscalation {
+  /** Offer escalation? True iff an unresolved platform-owned fault remains. */
+  show: boolean;
+  /** The pre-filled structured report (supportContext()); "" when `show` is false. */
+  body: string;
+  /** The escalation email subject; "" when `show` is false. */
+  subject: string;
+  /** Ready-to-use `mailto:` with subject + body pre-filled; "" when `show` is false. */
+  mailtoHref: string;
+}
+
+const HIDDEN: MergeSupportEscalation = { show: false, body: "", subject: "", mailtoHref: "" };
+
+/**
+ * Reduce a `/api/changes` body (the payload the tab already holds) to the
+ * platform-fault escalation state. `branchesBody` is optional; branch-plane
+ * platform faults (e.g. an unreachable branch classification) are also
+ * platform-owned, so passing it lets those escalate too — omit it safely when the
+ * branches panel hasn't loaded, exactly as the sibling reducers do.
+ */
+export function mergeSupportEscalation(
+  changesBody: ChangesInput["body"],
+  opts: { branchesBody?: BranchesInput["body"]; nowMs?: number } = {},
+): MergeSupportEscalation {
+  const result = analyzeMerge({
+    changes: { status: 200, body: changesBody ?? {} },
+    branches: opts.branchesBody
+      ? { status: 200, body: opts.branchesBody }
+      : { status: 200, body: { report: { rows: [] } } },
+    tenant: changesBody?.owner ?? null,
+    nowMs: opts.nowMs,
+  });
+
+  const body = supportContext(result);
+  if (body === null) return HIDDEN;
+
+  const subject = "Publish issue";
+  const mailtoHref = `mailto:${SUPPORT_EMAIL}?subject=${encodeURIComponent(
+    subject,
+  )}&body=${encodeURIComponent(body)}`;
+  return { show: true, body, subject, mailtoHref };
+}

package/apps/storefront/src/lib/publish/publish-guard.ts

@@ -0,0 +1,88 @@
+/**
+ * Publish-button hard-block + stale-build indicator (Bug 3, publish-safety half).
+ *
+ * PURE + dep-free so the branching is unit-testable in `node` — the AdminPublishTab
+ * `<script is:inline>` glue that toggles the real button/DOM is a faithful mirror of
+ * this contract (the repo's documented split: logic in a tested module, rendered output
+ * verified on preview).
+ *
+ * The incident class: a ship PLAN is computed from the aggregate read-model, but the
+ * most recent aggregate REBUILD can fail INDEPENDENTLY (a red queue state, or tot-mcp
+ * `forward_failed`) AFTER a plan was cached — leaving a stale "shippable" plan that
+ * would publish a build the rebuild never actually produced. So Publish is HARD-BLOCKED
+ * whenever the aggregate is red (`queueState === "red"`), regardless of what the plan
+ * says — belt-and-suspenders over the plan's own gate — and the operator is told their
+ * live store is serving the last good (stale) build while the rebuild is broken.
+ */
+
+export interface PublishGuardInput {
+  /** The aggregate's current queue state (`green`/`red`/`integrating`/`empty`/…). */
+  queueState: string | null | undefined;
+  /** A Publish POST is in flight (never re-enable across a mid-publish poll). */
+  aggregatePublishing: boolean;
+  /** Viewer holds ship capability. */
+  canShip: boolean;
+  /** The plan resolved to a shippable view (`Boolean(currentPlan)`). */
+  shippable: boolean;
+  /** The shippable plan is behind a paywall the viewer hasn't cleared. */
+  paywalled: boolean;
+  /** The reviewed build is already live. */
+  alreadyShipped: boolean;
+  /** Staged changes not yet published (drives the stale-build wording). */
+  aheadCount: number;
+  /**
+   * Human label for WHEN the currently-serving live build was produced (already
+   * formatted by the caller; null when unknown). Used only in the stale indicator.
+   */
+  servingBuildAtLabel: string | null;
+}
+
+export interface PublishGuardView {
+  /** Whether the Publish button must be disabled. */
+  disabled: boolean;
+  /** The Publish button's title/tooltip — the honest reason. */
+  title: string;
+  /**
+   * Non-null ⇒ render a "serving stale build" indicator with this text (the live
+   * store is serving an older build because the latest rebuild failed). Null ⇒ none.
+   */
+  staleIndicator: string | null;
+}
+
+/** Compute the Publish button's disabled/title/stale state from the aggregate + plan facts. */
+export function computePublishGuard(input: PublishGuardInput): PublishGuardView {
+  const rebuildFailed = input.queueState === "red";
+
+  const disabled =
+    input.aggregatePublishing ||
+    !input.canShip ||
+    !input.shippable ||
+    input.paywalled ||
+    input.alreadyShipped ||
+    // HARD-BLOCK: a red aggregate means the latest rebuild failed — never publish it,
+    // even if a stale plan still reads shippable.
+    rebuildFailed;
+
+  const title = !input.canShip
+    ? "Requires an owner or admin sign-in"
+    : rebuildFailed
+      ? "The latest preview rebuild failed — retry the build before publishing. Your live store is unchanged."
+      : !input.shippable
+        ? "Your next release isn't ready to publish yet"
+        : input.paywalled
+          ? "Publishing to your live store is part of the paid plan"
+          : input.alreadyShipped
+            ? "This reviewed build is already live"
+            : "Publish the exact build you reviewed to your live store";
+
+  // The stale indicator is worth showing only when a failed rebuild is actually
+  // holding NEW work back from live (there are staged changes ahead).
+  const staleIndicator =
+    rebuildFailed && input.aheadCount > 0
+      ? "Your live store is serving the last good build" +
+        (input.servingBuildAtLabel ? " from " + input.servingBuildAtLabel : "") +
+        " — the latest rebuild failed, so your newest changes aren't live yet. Retry the build to finish."
+      : null;
+
+  return { disabled, title, staleIndicator };
+}

package/apps/storefront/src/lib/publish/publishFormat.ts

@@ -0,0 +1,165 @@
+/**
+ * Pure presentational helpers for the admin Publish surface — sha/digest/age
+ * formatting and the small DOM-node builders (`chip`, `cell`, `subtle`,
+ * `linesNode`, `changeSummaryItem`). Extracted from the `adminPublishTab.ts`
+ * client island so the formatting boundary is a single, independently-testable
+ * module rather than inlined in the 3k-line controller. No closure state, no I/O —
+ * every function is a pure input → string/Node mapping.
+ *
+ * The DOM builders run in the browser (the processed client `<script>`); they touch
+ * `document` only when called, never at module load.
+ */
+
+/** First 8 chars of a sha, or an em-dash placeholder. */
+export const shortSha = (sha?: string | null): string => (sha ? String(sha).slice(0, 8) : "—");
+
+/** `sha256:` + first 12 chars + ellipsis, or an em-dash placeholder. */
+export const shortDigest = (digest?: string | null): string => {
+  const d = String(digest || "").replace(/^sha256:/, "");
+  return d ? "sha256:" + d.slice(0, 12) + "…" : "—";
+};
+
+/** A coarse relative-age label ("just now" / "5m ago" / "3h ago" / "2d ago"). */
+export const age = (iso?: string | null): string => {
+  if (!iso) return "—";
+  const ms = Date.now() - new Date(iso).getTime();
+  if (!Number.isFinite(ms) || ms < 0) return "—";
+  const mins = Math.floor(ms / 60000);
+  if (mins < 1) return "just now";
+  if (mins < 60) return mins + "m ago";
+  const hours = Math.floor(mins / 60);
+  if (hours < 48) return hours + "h ago";
+  return Math.floor(hours / 24) + "d ago";
+};
+
+/**
+ * A "+N −M" lines-changed node (added green, removed red) as ONE element, so a meta
+ * "·" separator sits before the pair rather than between the numbers. Either count
+ * may be absent.
+ */
+export const linesNode = (added?: number | null, removed?: number | null): HTMLSpanElement => {
+  const wrap = document.createElement("span");
+  wrap.className = "agg-lines";
+  if (typeof added === "number") {
+    const a = document.createElement("span");
+    a.className = "agg-add";
+    a.textContent = "+" + added;
+    wrap.append(a);
+  }
+  if (typeof removed === "number") {
+    const d = document.createElement("span");
+    d.className = "agg-del";
+    d.textContent = (typeof added === "number" ? " " : "") + "−" + removed;
+    wrap.append(d);
+  }
+  return wrap;
+};
+
+/**
+ * A status chip carrying its state WORD (never a bare colored dot) plus an optional
+ * tone class and a leading state `glyph` (✓ / ⚠ / ✕ / ●). The glyph is decorative
+ * (`aria-hidden`) — the word is the real signal — so a status chip never leans on
+ * colour alone: it reads as icon + text for a colour-blind or monochrome viewer.
+ */
+export const chip = (
+  text?: string | null,
+  tone?: string | null,
+  glyph?: string | null,
+): HTMLSpanElement => {
+  const el = document.createElement("span");
+  el.className = "chip" + (tone ? " " + tone : "");
+  if (glyph) {
+    const g = document.createElement("span");
+    g.className = "chip-glyph";
+    g.setAttribute("aria-hidden", "true");
+    g.textContent = glyph;
+    el.append(g);
+  }
+  el.append(document.createTextNode(text ?? ""));
+  return el;
+};
+
+/** A `<td>` composed from string/Node children (null/undefined children skipped). */
+export const cell = (...children: Array<Node | string | null | undefined>): HTMLTableCellElement => {
+  const td = document.createElement("td");
+  for (const child of children) {
+    if (child == null) continue;
+    td.append(typeof child === "string" ? document.createTextNode(child) : child);
+  }
+  return td;
+};
+
+/** A muted inline `<span class="subtle">`. */
+export const subtle = (text?: string | null): HTMLSpanElement => {
+  const el = document.createElement("span");
+  el.className = "subtle";
+  el.textContent = text ?? "";
+  return el;
+};
+
+/** The shape `changeSummaryItem` reads — every enrichment field is optional. */
+export interface ChangeSummaryLike {
+  prNumber?: number | null;
+  changeId?: string | null;
+  title?: string | null;
+  description?: string | null;
+  summary?: string | null;
+  headSha?: string | null;
+  fileCount?: number | null;
+  filesChanged?: number | null;
+  linesAdded?: number | null;
+  linesRemoved?: number | null;
+}
+
+/**
+ * One included-change line item (PR # + human title, a one-line description, and
+ * meta: sha / files / lines). Shared by the aggregate plan's "Included changes" and
+ * the published-versions "what shipped" list, so both read the same way. A row
+ * degrades to just "PR #N · <sha>" when the enrichment fields are absent.
+ */
+export const changeSummaryItem = (ch: ChangeSummaryLike): HTMLLIElement => {
+  const li = document.createElement("li");
+  li.className = "agg-included-item";
+
+  const top = document.createElement("div");
+  top.className = "agg-included-top";
+  const prEl = document.createElement("span");
+  prEl.className = "agg-included-pr";
+  prEl.textContent = ch.prNumber != null ? "PR #" + ch.prNumber : ch.changeId ?? "";
+  top.append(prEl);
+  if (ch.title) {
+    const t = document.createElement("span");
+    t.className = "agg-included-title";
+    t.textContent = ch.title;
+    top.append(t);
+  }
+  li.append(top);
+
+  const description = ch.description || ch.summary;
+  if (description) {
+    const desc = document.createElement("p");
+    desc.className = "agg-included-desc";
+    desc.textContent = description;
+    li.append(desc);
+  }
+
+  const meta = document.createElement("div");
+  meta.className = "agg-included-meta";
+  if (ch.headSha) {
+    const sha = document.createElement("span");
+    sha.className = "publish-mono sha-token";
+    sha.textContent = shortSha(ch.headSha);
+    meta.append(sha);
+  }
+  const fileCount = ch.fileCount != null ? ch.fileCount : ch.filesChanged;
+  if (fileCount != null) {
+    const f = document.createElement("span");
+    f.textContent = fileCount + (fileCount === 1 ? " file" : " files");
+    meta.append(f);
+  }
+  if (typeof ch.linesAdded === "number" || typeof ch.linesRemoved === "number") {
+    meta.append(linesNode(ch.linesAdded, ch.linesRemoved));
+  }
+  if (meta.childNodes.length) li.append(meta);
+  return li;
+};

package/apps/storefront/src/lib/publish/publishHero.ts

@@ -0,0 +1,177 @@
+/**
+ * publishHero — the pure state machine behind the Publish tab's single "next
+ * action" hero. It reduces the SAME `/api/changes` read the queue + aggregate
+ * already consume into ONE sentence + ONE primary call-to-action describing
+ * exactly what the operator should do next.
+ *
+ * It is the single top-of-tab state element: the two former standalone banners
+ * are folded in here, not rendered separately —
+ *   - B1 (merge-doctor health) arrives as {@link PublishHeroInput.health}
+ *     (`mergeHealthBanner` over the same payload) and becomes the hero's
+ *     blocker/warn state + the "Review the queue" action.
+ *   - B3 (platform-fault escalation) arrives as {@link PublishHeroInput.escalation}
+ *     (`mergeSupportEscalation`) and becomes the hero's most-urgent state with the
+ *     pre-filled "Report to support" mailto as its action.
+ * The DOM glue therefore toggles ONE element, never three.
+ *
+ * Precedence is ordered most-urgent → calm so the ONE sentence is always the most
+ * important true thing: a platform fault outranks a merge conflict, a merge
+ * conflict outranks a ready release, a ready release outranks unreviewed changes,
+ * and an empty queue rests calm. Total and side-effect-free.
+ */
+
+/** Tone drives the icon + non-color styling (never color alone). */
+export type PublishHeroTone = "blocker" | "warn" | "attention" | "ready" | "calm";
+
+/** The single primary action the hero offers. */
+export type PublishHeroCtaKind =
+  | "publish"
+  | "review-queue"
+  | "report-support"
+  | "goto-release"
+  | "none";
+
+export interface PublishHeroCta {
+  kind: PublishHeroCtaKind;
+  /** Button/link text; "" when kind is "none". */
+  label: string;
+  /** A ready-to-use href — set only for "report-support" (the pre-filled mailto). */
+  href?: string;
+}
+
+export interface PublishHeroView {
+  tone: PublishHeroTone;
+  /** The ONE sentence describing the current state. */
+  headline: string;
+  /** Optional supporting subtext under the headline; "" when none. */
+  detail: string;
+  cta: PublishHeroCta;
+  /**
+   * True for the two blocker states — the DOM adds an explicit "Action needed"
+   * label so urgency is conveyed by text + icon, not color alone (a11y).
+   */
+  urgent: boolean;
+}
+
+export interface PublishHeroInput {
+  /** Number of open changes in the review queue (`payload.changes.length`). */
+  changeCount: number;
+  /** The B1 merge-doctor health reduction over the same payload. */
+  health: { show: boolean; text: string; tone: "blocker" | "warn" };
+  /** The B3 platform-fault escalation reduction over the same payload. */
+  escalation: { show: boolean; mailtoHref: string };
+  /** The b09 ship plan (`payload.plan`), or null when no store is bound. */
+  plan:
+    | { ok?: boolean; alreadyShipped?: boolean; paywall?: { allowed?: boolean } | null }
+    | null;
+  /** Staged changes ahead of the live pointer (`aggregate.includedPrs.length`). */
+  aheadCount: number;
+  /** The staged aggregate sha equals the live version id — nothing to publish. */
+  matchesLive: boolean;
+  /** Whether this viewer holds ship capability (owner/admin/ship-on-behalf). */
+  canShip: boolean;
+  /** Public static hostname also advanced by this publish, when configured. */
+  publicSiteHost?: string | null;
+}
+
+const plural = (n: number, one: string, many: string): string => (n === 1 ? one : many);
+
+export function publishHeroState(input: PublishHeroInput): PublishHeroView {
+  const { changeCount, health, escalation, plan, canShip } = input;
+
+  // 1. Platform fault (absorbs B3). The rarest, most severe state — a retry
+  //    didn't clear it, so the primary action is the pre-filled support report.
+  if (escalation.show) {
+    return {
+      tone: "blocker",
+      headline: "Some of this is on our end.",
+      detail:
+        "A retry didn't clear it. Send us the pre-filled report and we'll take it from here.",
+      cta: { kind: "report-support", label: "Report to support", href: escalation.mailtoHref },
+      urgent: true,
+    };
+  }
+
+  // 2. A developer-actionable blocker (absorbs B1's red state) — a merge conflict
+  //    or similar that stops the release until it's resolved in the queue.
+  if (health.show && health.tone === "blocker") {
+    return {
+      tone: "blocker",
+      headline: health.text,
+      detail: "Resolve these in the change queue to keep your release moving.",
+      cta: { kind: "review-queue", label: "Review the queue" },
+      urgent: true,
+    };
+  }
+
+  // A reviewed, staged release exists when the plan is ok and hasn't shipped yet.
+  const releaseStaged = Boolean(plan && plan.ok && !plan.alreadyShipped);
+  const paywalled = Boolean(plan && plan.paywall && plan.paywall.allowed === false);
+
+  // 3. A release is reviewed and ready — the finish line. Publishing it is the
+  //    highest-value next action, so it leads over unreviewed queue items.
+  if (releaseStaged && canShip && !paywalled) {
+    const staged = input.aheadCount;
+    return {
+      tone: "ready",
+      headline: "Your release is reviewed and ready to publish.",
+      detail: input.publicSiteHost
+        ? `${staged || "The reviewed release"} ${staged ? plural(staged, "change is", "changes are") : "is"} staged. Publishing updates the hosted store and automatically republishes ${input.publicSiteHost}.`
+        : staged
+          ? `${staged} ${plural(staged, "change is", "changes are")} staged and waiting to go live.`
+          : "",
+      cta: {
+        kind: "publish",
+        label: input.publicSiteHost ? "Publish to both live sites" : "Publish live",
+      },
+      urgent: false,
+    };
+  }
+
+  // 4. A reviewed release is staged, but this viewer can't one-click publish it
+  //    (read-only sign-in, or the paywall gates go-live). Point them at the
+  //    release, where the existing gate explains why the button is held.
+  if (releaseStaged) {
+    return {
+      tone: "ready",
+      headline: "Your release is reviewed and ready to publish.",
+      detail: paywalled
+        ? "Publishing to your live store is part of the paid plan."
+        : "Going live needs an owner or admin sign-in for this store.",
+      cta: { kind: "goto-release", label: "Go to the release" },
+      urgent: false,
+    };
+  }
+
+  // 5. A developer-actionable warning (absorbs B1's amber state) — e.g. a change
+  //    still needs a build. Actionable, but not a hard blocker.
+  if (health.show) {
+    return {
+      tone: "warn",
+      headline: health.text,
+      detail: "Handle these in the change queue below.",
+      cta: { kind: "review-queue", label: "Review the queue" },
+      urgent: false,
+    };
+  }
+
+  // 6. Changes are waiting for review — the ordinary "you have work" state.
+  if (changeCount > 0) {
+    return {
+      tone: "attention",
+      headline: `${changeCount} ${plural(changeCount, "change is", "changes are")} ready to review.`,
+      detail: "Review them and add them to your next release.",
+      cta: { kind: "review-queue", label: "Review changes" },
+      urgent: false,
+    };
+  }
+
+  // 7. Nothing pending — calm, no alarm.
+  return {
+    tone: "calm",
+    headline: "You're all caught up.",
+    detail: "Nothing is waiting to review or publish.",
+    cta: { kind: "none", label: "" },
+    urgent: false,
+  };
+}

package/apps/storefront/src/lib/publish/reviewRelease/changeState.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure state machine: collapse a change's internal/mechanical facts onto the ONE
+ * merchant-facing state it presents (contract §2). This is the single authority
+ * for the internal→merchant mapping — no surface re-derives it. It is total and
+ * side-effect-free, so the whole mapping is exhaustively unit-testable independent
+ * of any UI or transport.
+ *
+ * The mapping absorbs all retry/reconcile churn into "Preparing" and routes every
+ * unrecoverable-by-merchant condition to "Needs attention" (a dead end for the
+ * merchant, handed to a developer). See the acceptance table's `mapsFromInternal`.
+ */
+import type { InternalChangeStatus, MerchantChangeStateId } from "./types.js";
+
+/**
+ * The facts about one change that determine its merchant state. Derived from a
+ * `/api/changes` row by the view-model builder; kept explicit (not the raw row)
+ * so the precedence logic is the readable contract, not scattered field-poking.
+ */
+export interface ChangeStateFacts {
+  /** Internal pipeline status (`queued`/`reconciling`/`ready`/`blocked`/`not-built`/…). */
+  status: InternalChangeStatus;
+  /** Evidence gate: checks passed (`evidence.promotable`). */
+  promotable: boolean;
+  /** Forge-settled mergeability against the current preview tip. */
+  mergeable: boolean;
+  /** At least one evidence check reported `fail`. */
+  hasFailingChecks: boolean;
+  /** The server could confirm this row's live state against the forge. `false` ⇒ "State unknown". */
+  liveStateConfirmed: boolean;
+  /** This change is staged into the next release (in the preview aggregate). */
+  inNextRelease: boolean;
+  /** This change's release is live — it has shipped. */
+  published: boolean;
+}
+
+/**
+ * Resolve the single merchant state. Precedence is load-bearing and ordered so a
+ * terminal/definite fact wins over a transient one:
+ *
+ *   published > in next release > needs attention > ready to add > preparing
+ *
+ * A staged change follows the release (it never independently degrades to "Needs
+ * attention" — the RELEASE does), which is why `inNextRelease` outranks the
+ * attention checks.
+ */
+export function resolveChangeState(f: ChangeStateFacts): MerchantChangeStateId {
+  if (f.published) return "published";
+  if (f.inNextRelease) return "in-next-release";
+
+  // Needs attention — the merchant dead-end (handed to a developer). Any of:
+  //  - "State unknown": the forge listing failed, the stored label is unverifiable;
+  //  - blocked;
+  //  - evidence failed (a check came back `fail`);
+  //  - a forge-settled merge conflict on an otherwise-ready change.
+  if (!f.liveStateConfirmed) return "needs-attention";
+  if (f.status === "blocked") return "needs-attention";
+  if (f.hasFailingChecks) return "needs-attention";
+  if (f.status === "ready" && f.promotable && !f.mergeable) return "needs-attention";
+
+  // Ready to add — checks passed, cleanly mergeable, not yet staged.
+  if (f.status === "ready" && f.promotable && f.mergeable) return "ready-to-add";
+
+  // Everything else is still being built/checked automatically: queued,
+  // reconciling, building, not-built, or ready-but-not-yet-promotable.
+  return "preparing";
+}