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

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

@@ -0,0 +1,440 @@
+/**
+ * The merchant Review-and-Release VIEW MODEL and its pure builder.
+ *
+ * `buildReviewReleaseViewModel` consumes the SAME `GET /api/changes` payload the
+ * admin publish surface already fetches (see `src/pages/api/changes/index.ts`) plus
+ * a small server-resolved context, and produces a fully-serializable, UI-agnostic
+ * shape a component can render directly — every string already interpolated, every
+ * decision already made. This is the props contract the downstream
+ * `review-release-workspace` unit builds its two-decision UI against; the
+ * `ChangeCardView` / `NextReleaseView` shapes ARE the props for its future
+ * change-row and release-status components.
+ *
+ * The builder is pure (no DOM, no I/O, deterministic), so it runs equally on the
+ * server (to embed the model) or the client (to re-derive it on each poll), and is
+ * exhaustively unit-testable.
+ */
+import {
+  CHANGE_STATE_COPY,
+  RELEASE_STATE_COPY,
+  ADD_TO_NEXT_RELEASE_LABEL,
+  PUBLISH_NOW_LABEL,
+  VIEW_LIVE_STORE_LABEL,
+  PUBLISH_CONFIRM_COPY,
+  WHATS_IN_RELEASE_HEADING,
+  whatsInReleaseFallback,
+} from "./copy.js";
+import { resolveChangeState, type ChangeStateFacts } from "./changeState.js";
+import { resolveReleaseState, type ReleaseStateFacts } from "./releaseState.js";
+import {
+  resolveMerchantPermissions,
+  type MerchantPermissions,
+} from "./permissions.js";
+import type {
+  InternalAggregateState,
+  InternalChangeStatus,
+  MerchantChangeActionId,
+  MerchantChangeStateId,
+  MerchantReleaseActionId,
+  MerchantReleaseStateId,
+} from "./types.js";
+
+// ── Input: the subset of GET /api/changes this model reads ───────────────────────
+// Intentionally a focused structural subset (not the full wire type) so the seam is
+// explicit and the builder never couples to fields it doesn't consume.
+
+/** One evidence check on a change row. */
+export interface ChangesPayloadEvidenceCheck {
+  status: "pass" | "fail" | string;
+}
+
+/** One change row from `payload.changes` (a built candidate or a synthetic not-built PR). */
+export interface ChangesPayloadChange {
+  changeId: string | null;
+  prNumber?: number | null;
+  status: InternalChangeStatus | string;
+  built?: boolean;
+  mergeable?: boolean;
+  liveStateConfirmed?: boolean;
+  updatedAt?: string | null;
+  evidence?: { promotable?: boolean; checks?: ChangesPayloadEvidenceCheck[] } | null;
+}
+
+/** One staged PR from `payload.aggregate.includedPrs` (carries the human title). */
+export interface ChangesPayloadIncludedPr {
+  changeId?: string | null;
+  prNumber?: number | null;
+  title?: string | null;
+}
+
+/** The aggregate card projection. */
+export interface ChangesPayloadAggregate {
+  queueState?: InternalAggregateState | string;
+  aggregateSha?: string | null;
+  includedPrs?: ChangesPayloadIncludedPr[];
+}
+
+/** The ship-plan projection (ok-plan carries the paywall verdict; a refusal does not). */
+export interface ChangesPayloadPlan {
+  ok?: boolean;
+  paywall?: { allowed?: boolean } | null;
+  alreadyShipped?: boolean;
+}
+
+/** The live-version pointer. */
+export interface ChangesPayloadCurrent {
+  versionId?: string | null;
+  createdAt?: string | null;
+}
+
+/** The `/api/changes` fields the merchant model consumes. */
+export interface ChangesPayload {
+  changes?: ChangesPayloadChange[];
+  aggregate?: ChangesPayloadAggregate | null;
+  plan?: ChangesPayloadPlan | null;
+  current?: ChangesPayloadCurrent | null;
+}
+
+/** Server-resolved context the model can't derive from the payload alone. */
+export interface ReviewReleaseContext {
+  /** Owner/admin/ship-on-behalf — mirrors the server ship gate. */
+  canShip: boolean;
+  /** This is an internal test store (publishing to a live storefront is blocked). */
+  internalTestStore?: boolean;
+  /** The store's display name, for the publish-confirm copy. */
+  storeName?: string;
+  /** A publish POST is in flight right now (client-owned transient). */
+  shipInFlight?: boolean;
+  /**
+   * After how long in "Preparing" the reassuring slow sub-line appears (contract
+   * §9.5 leaves the value to this layer; default 2 min). Compared against a
+   * change's `updatedAt`.
+   */
+  preparingSlowThresholdMs?: number;
+  /** Injectable clock for deterministic slow-threshold tests. */
+  now?: () => number;
+}
+
+// ── Output: the view model ───────────────────────────────────────────────────────
+
+/** A change's one merchant action, fully labelled. */
+export interface MerchantChangeAction {
+  id: MerchantChangeActionId;
+  label: string;
+}
+
+/** One change, ready to render. `label`/`subline` are final (interpolated) copy. */
+export interface ChangeCardView {
+  changeId: string | null;
+  prNumber: number | null;
+  /** Human title when known (from the staged summary), else null → the UI falls back to the id. */
+  title: string | null;
+  state: MerchantChangeStateId;
+  label: string;
+  subline: string;
+  /** The primary action this state carries, or null. `needs-attention` carries none —
+   *  its subline already states the developer was notified automatically. */
+  action: MerchantChangeAction | null;
+}
+
+/** The next release's one merchant action, fully labelled. */
+export interface MerchantReleaseAction {
+  id: MerchantReleaseActionId;
+  label: string;
+}
+
+/** The publish confirmation dialog copy, interpolated. */
+export interface PublishConfirmView {
+  heading: string;
+  body: string;
+  confirm: string;
+  cancel: string;
+}
+
+/** The next release, ready to render. */
+export interface NextReleaseView {
+  state: MerchantReleaseStateId;
+  heading: string;
+  body: string;
+  /** Count of staged changes (the `{n}` in the copy). */
+  changeCount: number;
+  /** "What's in this release" — a plain list of change titles (Ready to publish). */
+  contents: { heading: string; items: string[]; fallback: string };
+  /** The primary action (publish-now / view-live-store), or null. */
+  action: MerchantReleaseAction | null;
+  /** The publish confirmation copy (present iff `action` is publish-now). */
+  confirm: PublishConfirmView | null;
+}
+
+/** The whole merchant Review-and-Release surface as data. */
+export interface ReviewReleaseViewModel {
+  changes: ChangeCardView[];
+  nextRelease: NextReleaseView;
+  permissions: MerchantPermissions;
+}
+
+const DEFAULT_SLOW_MS = 120_000;
+
+// ── Builder ──────────────────────────────────────────────────────────────────────
+
+export function buildReviewReleaseViewModel(
+  payload: ChangesPayload,
+  context: ReviewReleaseContext,
+): ReviewReleaseViewModel {
+  const aggregate = payload.aggregate ?? {};
+  const includedPrs = aggregate.includedPrs ?? [];
+  const plan = payload.plan ?? null;
+  const current = payload.current ?? null;
+
+  const titleByChange = indexTitles(includedPrs);
+  const stagedKeys = stagedIdentitySet(includedPrs);
+  const now = context.now ?? Date.now;
+  const slowMs = context.preparingSlowThresholdMs ?? DEFAULT_SLOW_MS;
+
+  const changes = (payload.changes ?? []).map((c) =>
+    buildChangeCard(c, { titleByChange, stagedKeys, now, slowMs }),
+  );
+
+  const planOk = plan?.ok === true;
+  const paywalled = planOk && plan?.paywall?.allowed === false;
+  const alreadyShipped = plan?.alreadyShipped === true;
+
+  const nextRelease = buildNextRelease({
+    queueState: (aggregate.queueState as InternalAggregateState) ?? "empty",
+    aggregateSha: aggregate.aggregateSha ?? null,
+    includedPrs,
+    planOk,
+    alreadyShipped,
+    shipInFlight: context.shipInFlight === true,
+    liveVersionId: current?.versionId ?? null,
+    liveCreatedAt: current?.createdAt ?? null,
+    canPublish: context.canShip && !paywalled && !context.internalTestStore,
+    storeName: context.storeName,
+  });
+
+  const permissions = resolveMerchantPermissions({
+    canShip: context.canShip,
+    paywalled,
+    internalTestStore: context.internalTestStore === true,
+  });
+
+  return { changes, nextRelease, permissions };
+}
+
+// ── Change card ──────────────────────────────────────────────────────────────────
+
+interface ChangeBuildDeps {
+  titleByChange: (change: ChangesPayloadChange) => string | null;
+  stagedKeys: Set<string>;
+  now: () => number;
+  slowMs: number;
+}
+
+function buildChangeCard(c: ChangesPayloadChange, deps: ChangeBuildDeps): ChangeCardView {
+  const inNextRelease = isStaged(c, deps.stagedKeys);
+  const checks = c.evidence?.checks ?? [];
+  const facts: ChangeStateFacts = {
+    status: normalizeStatus(c.status),
+    promotable: c.evidence?.promotable === true,
+    // A not-built row has no settled mergeability; treat absent as not-mergeable
+    // (it isn't ready-to-add), which the precedence handles as "preparing".
+    mergeable: c.mergeable === true,
+    hasFailingChecks: checks.some((k) => k.status === "fail"),
+    liveStateConfirmed: c.liveStateConfirmed !== false,
+    inNextRelease,
+    // Merged/closed changes are filtered out of the open queue upstream, so a row
+    // in `payload.changes` is never `published`; a "Recently published" history is
+    // a separate source the workspace unit may add (contract §9.7).
+    published: false,
+  };
+  const state = resolveChangeState(facts);
+  const copy = CHANGE_STATE_COPY[state];
+
+  const subline =
+    state === "preparing" && isSlow(c.updatedAt, deps.now(), deps.slowMs) && copy.sublineSlow
+      ? copy.sublineSlow
+      : copy.subline;
+
+  const action: MerchantChangeAction | null =
+    state === "ready-to-add"
+      ? { id: "add-to-next-release", label: ADD_TO_NEXT_RELEASE_LABEL }
+      : null;
+  // `needs-attention` carries no merchant action at all — its subline already
+  // states the developer was notified (automatic, via the real backend handoff),
+  // so a "Notify developer" button would be a fake no-op duplicating that claim.
+
+  return {
+    changeId: c.changeId ?? null,
+    prNumber: c.prNumber ?? null,
+    title: deps.titleByChange(c),
+    state,
+    label: copy.label,
+    subline,
+    action,
+  };
+}
+
+function isSlow(updatedAt: string | null | undefined, nowMs: number, slowMs: number): boolean {
+  if (!updatedAt) return false;
+  const t = new Date(updatedAt).getTime();
+  if (!Number.isFinite(t)) return false;
+  return nowMs - t >= slowMs;
+}
+
+// ── Next release ─────────────────────────────────────────────────────────────────
+
+interface NextReleaseInput {
+  queueState: InternalAggregateState;
+  aggregateSha: string | null;
+  includedPrs: ChangesPayloadIncludedPr[];
+  planOk: boolean;
+  alreadyShipped: boolean;
+  shipInFlight: boolean;
+  liveVersionId: string | null;
+  liveCreatedAt: string | null;
+  canPublish: boolean;
+  storeName?: string;
+}
+
+function buildNextRelease(input: NextReleaseInput): NextReleaseView {
+  const changeCount = input.includedPrs.length;
+  const matchesLive = Boolean(
+    input.aggregateSha && input.liveVersionId && input.aggregateSha === input.liveVersionId,
+  );
+
+  const facts: ReleaseStateFacts = {
+    queueState: input.queueState,
+    // An already-shipped plan is a live/no-op, not a fresh "ready to publish".
+    planOk: input.planOk && !input.alreadyShipped,
+    shipInFlight: input.shipInFlight,
+    matchesLive,
+    hasStaged: changeCount > 0,
+  };
+  const state = resolveReleaseState(facts);
+  const copy = RELEASE_STATE_COPY[state];
+
+  const heading = copy.heading;
+  const body = interpolate(copy.body, {
+    n: String(changeCount),
+    date: formatReleaseDate(input.liveCreatedAt),
+  });
+
+  const items = input.includedPrs
+    .map((p) => (p.title ?? "").trim())
+    .filter((t) => t.length > 0);
+
+  let action: MerchantReleaseAction | null = null;
+  let confirm: PublishConfirmView | null = null;
+  if (state === "ready-to-publish" && input.canPublish) {
+    action = { id: "publish-now", label: PUBLISH_NOW_LABEL };
+    confirm = {
+      heading: PUBLISH_CONFIRM_COPY.heading,
+      body: interpolate(PUBLISH_CONFIRM_COPY.body, {
+        n: String(changeCount),
+        store: input.storeName?.trim() || "your store",
+      }),
+      confirm: PUBLISH_CONFIRM_COPY.confirm,
+      cancel: PUBLISH_CONFIRM_COPY.cancel,
+    };
+  } else if (state === "live") {
+    action = { id: "view-live-store", label: VIEW_LIVE_STORE_LABEL };
+  }
+
+  return {
+    state,
+    heading,
+    body,
+    changeCount,
+    contents: {
+      heading: WHATS_IN_RELEASE_HEADING,
+      items,
+      fallback: whatsInReleaseFallback(changeCount),
+    },
+    action,
+    confirm,
+  };
+}
+
+// ── Small pure helpers ───────────────────────────────────────────────────────────
+
+const KNOWN_STATUSES: ReadonlySet<string> = new Set<InternalChangeStatus>([
+  "queued",
+  "reconciling",
+  "ready",
+  "blocked",
+  "not-built",
+  "building",
+  "accepted",
+  "merged",
+  "closed",
+]);
+
+/** Coerce an unknown wire status to the closed vocabulary; unknowns read as "preparing". */
+function normalizeStatus(status: string): InternalChangeStatus {
+  return (KNOWN_STATUSES.has(status) ? status : "queued") as InternalChangeStatus;
+}
+
+/** Stable identity key for staged-membership matching (prefer changeId, else PR). */
+function identityKey(changeId?: string | null, prNumber?: number | null): string | null {
+  if (changeId) return "c:" + changeId;
+  if (typeof prNumber === "number") return "p:" + prNumber;
+  return null;
+}
+
+function stagedIdentitySet(includedPrs: ChangesPayloadIncludedPr[]): Set<string> {
+  const set = new Set<string>();
+  for (const p of includedPrs) {
+    const byChange = identityKey(p.changeId, null);
+    const byPr = identityKey(null, p.prNumber);
+    if (byChange) set.add(byChange);
+    if (byPr) set.add(byPr);
+  }
+  return set;
+}
+
+function isStaged(c: ChangesPayloadChange, staged: Set<string>): boolean {
+  const byChange = identityKey(c.changeId, null);
+  const byPr = identityKey(null, c.prNumber);
+  return Boolean((byChange && staged.has(byChange)) || (byPr && staged.has(byPr)));
+}
+
+function indexTitles(
+  includedPrs: ChangesPayloadIncludedPr[],
+): (change: ChangesPayloadChange) => string | null {
+  const byChange = new Map<string, string>();
+  const byPr = new Map<number, string>();
+  for (const p of includedPrs) {
+    const title = (p.title ?? "").trim();
+    if (!title) continue;
+    if (p.changeId) byChange.set(p.changeId, title);
+    if (typeof p.prNumber === "number") byPr.set(p.prNumber, title);
+  }
+  return (change) => {
+    if (change.changeId && byChange.has(change.changeId)) return byChange.get(change.changeId)!;
+    if (typeof change.prNumber === "number" && byPr.has(change.prNumber)) {
+      return byPr.get(change.prNumber)!;
+    }
+    return null;
+  };
+}
+
+/** Substitute `{token}` occurrences; unknown tokens are left intact. */
+function interpolate(template: string, values: Record<string, string>): string {
+  return template.replace(/\{(\w+)\}/g, (m: string, key: string) =>
+    key in values ? values[key]! : m,
+  );
+}
+
+const MONTHS = [
+  "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+  "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+];
+
+/** Deterministic UTC "Mon D, YYYY" for the `{date}` token; empty when unknown. */
+export function formatReleaseDate(iso: string | null | undefined): string {
+  if (!iso) return "";
+  const d = new Date(iso);
+  const t = d.getTime();
+  if (!Number.isFinite(t)) return "";
+  return `${MONTHS[d.getUTCMonth()]} ${d.getUTCDate()}, ${d.getUTCFullYear()}`;
+}

package/apps/storefront/src/lib/publish/reviewReleaseWorkspace/actions.ts

@@ -0,0 +1,161 @@
+/**
+ * The merchant's two actions, as pure functions over an injected `fetch`.
+ *
+ * These translate the internal endpoint contracts (`POST /api/changes/accept` =
+ * accept-to-preview, `POST /api/changes/ship` = go-live) into the merchant's
+ * two-decision vocabulary, collapsing every internal failure onto a state that
+ * requires NOTHING of the merchant (contract §7 "error philosophy"): an integrate
+ * conflict resolves to the change's `needs-attention`; a publish that refuses
+ * (paywall) stays put with the reason; a publish that fails after the flip resolves
+ * to the release's auto-retry `needs-attention`. There is deliberately NO retry /
+ * rebuild / resolve result — the surface offers no such control.
+ *
+ * Injected `fetch` keeps them node-testable (the storefront test env is `node`).
+ */
+
+/** The minimal fetch surface these actions use (satisfied by the global `fetch`). */
+export type FetchLike = (
+  input: string,
+  init?: { method?: string; headers?: Record<string, string>; body?: string },
+) => Promise<{ ok: boolean; status: number; json: () => Promise<unknown> }>;
+
+// ── Add to next release ──────────────────────────────────────────────────────────
+
+export interface AddDeps {
+  fetch: FetchLike;
+  /** basePath-aware `POST /api/changes/accept` URL. */
+  endpoint: string;
+}
+
+/** Which change to add — its canonical id when known, else its PR number. */
+export interface AddRef {
+  changeId: string | null;
+  prNumber: number | null;
+}
+
+export type AddResult =
+  /** The change was queued into the next release (now "In next release"). */
+  | { kind: "added" }
+  /** The change couldn't go in as-is (conflict/blocked) — now "Needs attention". */
+  | { kind: "needs-attention" }
+  /** A transport/unexpected failure — the surface re-reads; no retry control. */
+  | { kind: "error"; message: string };
+
+/**
+ * Add a ready change to the next release (accept-to-preview). The endpoint returns
+ * the honest integrate outcome (`{ ok, queueState, reason, statusMessage }`, never a
+ * bare `merged: true`): `ok` ⇒ staged; a completed-but-not-ok enqueue (conflict) ⇒
+ * needs-attention. A non-2xx or thrown transport error ⇒ `error` (the surface simply
+ * re-reads state — it never shows a retry button).
+ */
+export async function addChangeToRelease(deps: AddDeps, ref: AddRef): Promise<AddResult> {
+  const body: Record<string, unknown> = {};
+  if (ref.changeId) body.changeId = ref.changeId;
+  else if (typeof ref.prNumber === "number") body.prNumber = ref.prNumber;
+  else return { kind: "error", message: "No change reference to add." };
+
+  let res: Awaited<ReturnType<FetchLike>>;
+  try {
+    res = await deps.fetch(deps.endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    return { kind: "error", message: (err as Error).message };
+  }
+
+  if (!res.ok) {
+    const payload = await safeJson(res);
+    return { kind: "error", message: readError(payload) ?? `Request failed (${res.status}).` };
+  }
+  const payload = (await safeJson(res)) as { ok?: unknown } | null;
+  // A completed enqueue that did not go green is a conflict/blocked candidate — it is
+  // handed to a developer, so the change becomes "Needs attention" (no merchant retry).
+  return payload && payload.ok === true ? { kind: "added" } : { kind: "needs-attention" };
+}
+
+// ── Publish now ──────────────────────────────────────────────────────────────────
+
+export interface PublishDeps {
+  fetch: FetchLike;
+  /** basePath-aware `POST /api/changes/ship` URL. */
+  endpoint: string;
+}
+
+export type PublishResult =
+  /** The release went live. */
+  | { kind: "published" }
+  /** Refused at the paywall — stays Ready to publish; show the upgrade prompt. */
+  | { kind: "paywall"; message: string }
+  /** A pre-flip refusal that isn't merchant-actionable (moved/not green) — still preparing. */
+  | { kind: "not-ready" }
+  /** The flip failed after starting — Needs attention, retried automatically. */
+  | { kind: "publish-failed" }
+  /** A transport/unexpected failure — the surface re-reads; no retry control. */
+  | { kind: "error"; message: string };
+
+/**
+ * Publish the next release live. Sends the human go-live gate (`confirmGoLive: true`)
+ * — the confirm dialog IS that gate. The exact-digest pin, reviewed-digest token, and
+ * included-PR manifest stay server-side (the merchant confirmed a plain-language
+ * dialog, not a digest). Maps the orchestrator's honest terminal state onto the
+ * merchant vocabulary:
+ *   - `shipped`                       → published
+ *   - refused `paywall`               → paywall (stays Ready to publish w/ upgrade)
+ *   - refused (other, pre-flip)       → not-ready (release re-reads as Preparing)
+ *   - `promote_failed`/`record_failed`→ publish-failed (Needs attention, auto-retry)
+ */
+export async function publishNextRelease(deps: PublishDeps): Promise<PublishResult> {
+  let res: Awaited<ReturnType<FetchLike>>;
+  try {
+    res = await deps.fetch(deps.endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ confirmGoLive: true }),
+    });
+  } catch (err) {
+    return { kind: "error", message: (err as Error).message };
+  }
+
+  const payload = (await safeJson(res)) as
+    | { ok?: unknown; state?: unknown; reason?: unknown; message?: unknown }
+    | null;
+
+  if (payload && payload.ok === true) return { kind: "published" };
+
+  const state = typeof payload?.state === "string" ? payload.state : "";
+  const reason = typeof payload?.reason === "string" ? payload.reason : "";
+  const message = typeof payload?.message === "string" ? payload.message : "";
+
+  if (state === "refused") {
+    if (reason === "paywall") return { kind: "paywall", message: message || "Publishing is part of the paid plan." };
+    // not_green / no_passed_run / sha_mismatch / digest_mismatch / artifact_missing /
+    // bundle_unstaged / golive_unconfirmed: the release moved out from under the plan.
+    // Not merchant-actionable — it re-reads as Preparing and settles automatically.
+    return { kind: "not-ready" };
+  }
+  if (state === "promote_failed" || state === "record_failed") {
+    return { kind: "publish-failed" };
+  }
+  // No recognizable terminal state (e.g. a bare error body / non-2xx) — transport-ish.
+  return { kind: "error", message: message || readError(payload) || `Publish failed (${res.status}).` };
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────────
+
+async function safeJson(res: { json: () => Promise<unknown> }): Promise<unknown> {
+  try {
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+function readError(payload: unknown): string | null {
+  if (payload && typeof payload === "object" && "error" in payload) {
+    const e = (payload as { error?: unknown }).error;
+    if (typeof e === "string") return e;
+  }
+  return null;
+}