@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

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

@@ -0,0 +1,141 @@
+/**
+ * Verbatim merchant microcopy for the Review-and-Release surface — the single
+ * source of truth for the exact state labels, sub-lines, headings, bodies, and
+ * action labels the two-decision UX renders. Every string here is copied
+ * verbatim from `docs/review-release-ux-contract.md` §5 and the machine-readable
+ * `docs/review-release-ux-acceptance.json`; a conformance test asserts they match.
+ *
+ * Interpolation tokens `{n}`, `{store}`, `{date}` are left in the templates and
+ * substituted by the view-model builder (see `viewModel.ts`) — never hand-mirrored
+ * at a call site, so a copy change lands in exactly one place.
+ */
+import type {
+  MerchantChangeStateId,
+  MerchantReleaseStateId,
+} from "./types.js";
+
+/** Per-state merchant change copy (contract §2/§5). `action` is the one decision the state carries. */
+export interface ChangeStateCopy {
+  id: MerchantChangeStateId;
+  /** The status chip word — always present, never a bare colored dot (a11y §8). */
+  label: string;
+  /** Helper sub-line under the status. */
+  subline: string;
+  /** The reassuring sub-line shown once preparation crosses the slow threshold. */
+  sublineSlow?: string;
+}
+
+export const CHANGE_STATE_COPY: Record<MerchantChangeStateId, ChangeStateCopy> = {
+  preparing: {
+    id: "preparing",
+    label: "Preparing",
+    subline: "We're building and checking this change. No action needed.",
+    sublineSlow: "Still working on this one — checks can take a few minutes.",
+  },
+  "ready-to-add": {
+    id: "ready-to-add",
+    label: "Ready to add",
+    subline: "Checks passed. Add it to your next release when you're ready.",
+  },
+  "in-next-release": {
+    id: "in-next-release",
+    label: "In next release",
+    subline: "Staged to go live with your next release.",
+  },
+  "needs-attention": {
+    id: "needs-attention",
+    label: "Needs attention",
+    subline: "This change needs a developer before it can go live. We've let them know.",
+  },
+  published: {
+    id: "published",
+    label: "Published",
+    // `{date}` interpolated by the builder.
+    subline: "Went live on {date}.",
+  },
+};
+
+/** Per-state next-release copy (contract §3/§5). `heading` is the panel title. */
+export interface ReleaseStateCopy {
+  id: MerchantReleaseStateId;
+  heading: string;
+  /** Body text; may carry `{n}`/`{date}` tokens the builder substitutes. */
+  body: string;
+}
+
+export const RELEASE_STATE_COPY: Record<MerchantReleaseStateId, ReleaseStateCopy> = {
+  empty: {
+    id: "empty",
+    heading: "Nothing staged yet",
+    body: "Your next release is empty. Add a ready change to start building it.",
+  },
+  "preparing-release": {
+    id: "preparing-release",
+    heading: "Preparing your next release",
+    body: "We're putting your staged changes together and checking them. This is automatic.",
+  },
+  "ready-to-publish": {
+    id: "ready-to-publish",
+    heading: "Your next release is ready",
+    body: "{n} change(s) are staged and checked. Publish now to take them live.",
+  },
+  publishing: {
+    id: "publishing",
+    heading: "Publishing…",
+    body: "Taking your release live. This usually takes a few seconds.",
+  },
+  live: {
+    id: "live",
+    heading: "Your release is live",
+    body: "Published on {date}. Your store is up to date.",
+  },
+  "needs-attention": {
+    id: "needs-attention",
+    heading: "We hit a snag with this release",
+    body: "One of the staged changes needs a developer. We're sorting it out — nothing you need to do.",
+  },
+};
+
+// ── Action labels ──────────────────────────────────────────────────────────────
+
+/** Change-row primary action (on `ready-to-add`). */
+export const ADD_TO_NEXT_RELEASE_LABEL = "Add to next release";
+/** Next-release primary action (on `ready-to-publish`). */
+export const PUBLISH_NOW_LABEL = "Publish now";
+/** Next-release action (on `live`). */
+export const VIEW_LIVE_STORE_LABEL = "View your live store";
+
+/** The single publish confirmation dialog (contract §4/§5). */
+export const PUBLISH_CONFIRM_COPY = {
+  heading: "Publish your next release?",
+  body: "This takes {n} change(s) live on {store} right away.",
+  confirm: PUBLISH_NOW_LABEL,
+  cancel: "Cancel",
+} as const;
+
+/** Post-publish success + its live-store link. */
+export const PUBLISH_SUCCESS_COPY = {
+  message: "Your release is live.",
+  link: VIEW_LIVE_STORE_LABEL,
+} as const;
+
+/** "What's in this release" summary (Ready to publish). */
+export const WHATS_IN_RELEASE_HEADING = "What's in this release";
+/** Fallback line when a change title is unavailable. */
+export const whatsInReleaseFallback = (n: number): string =>
+  `${n} change(s) ready to publish.`;
+
+/** Undo toast for "Add to next release". */
+export const UNDO_TOAST_COPY = "Added to your next release · Undo";
+
+// ── Empty / zero states (contract §5) ────────────────────────────────────────────
+
+/** Shown when there are no changes at all. */
+export const NO_CHANGES_COPY =
+  "Nothing to review right now. New changes appear here when a developer submits them.";
+/** Shown to a read-only viewer in place of the two action buttons. */
+export const READ_ONLY_NOTE =
+  "You can review changes here. Adding to a release and publishing needs an owner or admin sign-in.";
+/** Shown in place of Publish on an internal test store (contract §6). */
+export const INTERNAL_TEST_STORE_NOTE =
+  "This is a testing-only store — publishing to a live storefront is disabled here.";

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

@@ -0,0 +1,41 @@
+/**
+ * The merchant Review-and-Release model — the seam between the internal publish
+ * pipeline and the two-decision merchant surface. Import from here.
+ *
+ * `docs/review-release-ux-contract.md` is the authoritative spec; this module is
+ * its typed, tested implementation. The downstream `review-release-workspace` unit
+ * builds its UI on `buildReviewReleaseViewModel` and the `ChangeCardView` /
+ * `NextReleaseView` shapes.
+ */
+export * from "./types.js";
+export * from "./copy.js";
+export {
+  resolveChangeState,
+  type ChangeStateFacts,
+} from "./changeState.js";
+export {
+  resolveReleaseState,
+  type ReleaseStateFacts,
+} from "./releaseState.js";
+export {
+  resolveMerchantPermissions,
+  type MerchantPermissions,
+  type MerchantPermissionContext,
+} from "./permissions.js";
+export {
+  buildReviewReleaseViewModel,
+  formatReleaseDate,
+  type ReviewReleaseViewModel,
+  type ReviewReleaseContext,
+  type ChangeCardView,
+  type NextReleaseView,
+  type PublishConfirmView,
+  type MerchantChangeAction,
+  type MerchantReleaseAction,
+  type ChangesPayload,
+  type ChangesPayloadChange,
+  type ChangesPayloadAggregate,
+  type ChangesPayloadIncludedPr,
+  type ChangesPayloadPlan,
+  type ChangesPayloadCurrent,
+} from "./viewModel.js";

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

@@ -0,0 +1,47 @@
+/**
+ * Merchant-surface permission + paywall resolution (contract §6) — a UX-only
+ * MIRROR of the server-authoritative gating (`resolveViewerShipCapability`,
+ * `AggregateShipOrchestrator` paywall verdict, internal-test-store block). The
+ * server re-authorizes every action; this only decides what the merchant surface
+ * shows (and, per contract, NEVER hides an action — it shows why it's unavailable).
+ */
+import { READ_ONLY_NOTE, INTERNAL_TEST_STORE_NOTE } from "./copy.js";
+
+/** The server-resolved facts the merchant surface mirrors. */
+export interface MerchantPermissionContext {
+  /** Owner, admin, or an explicit ship-on-behalf grant (mirrors `canShip`). */
+  canShip: boolean;
+  /** The store's storefront subscription does not permit go-live (plan paywalled). */
+  paywalled: boolean;
+  /** An internal test store — blocked from publishing to a live storefront. */
+  internalTestStore: boolean;
+}
+
+/** The merchant-surface permission verdict the view model carries. */
+export interface MerchantPermissions {
+  /** May add a change to the release AND publish (owner/admin/ship-on-behalf). */
+  canAddAndPublish: boolean;
+  /** No add/publish capability — the surface shows the two actions replaced by a note. */
+  readOnly: boolean;
+  /** The read-only explanation (present iff `readOnly`), else null. */
+  readOnlyNote: string | null;
+  /** Paywall overlay on the Publish action (shown as an upgrade prompt, never hidden). */
+  paywall: { active: boolean };
+  /** Internal test store: Publish is replaced by the testing-only notice. */
+  internalTestStore: boolean;
+  /** The testing-only notice (present iff `internalTestStore`), else null. */
+  internalTestStoreNote: string | null;
+}
+
+export function resolveMerchantPermissions(
+  ctx: MerchantPermissionContext,
+): MerchantPermissions {
+  return {
+    canAddAndPublish: ctx.canShip,
+    readOnly: !ctx.canShip,
+    readOnlyNote: ctx.canShip ? null : READ_ONLY_NOTE,
+    paywall: { active: ctx.paywalled },
+    internalTestStore: ctx.internalTestStore,
+    internalTestStoreNote: ctx.internalTestStore ? INTERNAL_TEST_STORE_NOTE : null,
+  };
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Pure state machine: collapse the internal aggregate/ship-plan facts onto the ONE
+ * merchant-facing next-release state (contract §3). Single authority for the
+ * internal→merchant release mapping; total and side-effect-free.
+ *
+ * "Preparing release" absorbs `integrating` + automatic retries; a red aggregate
+ * is "Needs attention" (recovered underneath, never a merchant retry button);
+ * "Ready to publish" is the ONLY state carrying the Publish action, and only when
+ * the exact-digest plan is green (`planOk`).
+ */
+import type { InternalAggregateState, MerchantReleaseStateId } from "./types.js";
+
+/** The facts that determine the next-release state. Derived from `aggregate`/`plan`/`current`. */
+export interface ReleaseStateFacts {
+  /** The aggregate's internal queue state. */
+  queueState: InternalAggregateState;
+  /** A shippable exact-digest plan exists (green + plan `ok`). */
+  planOk: boolean;
+  /** A publish POST is in flight right now (client-owned transient — no server queueState for it). */
+  shipInFlight: boolean;
+  /** The staged aggregate sha equals the live version id — what's staged is exactly what's live. */
+  matchesLive: boolean;
+  /** At least one change is staged into the release. */
+  hasStaged: boolean;
+}
+
+/**
+ * Resolve the single merchant release state. A `shipped` aggregate is Live and
+ * outranks a stale in-flight flag; otherwise an in-flight publish shows
+ * "Publishing…". A green aggregate is "Ready to publish" only once its plan pins
+ * (until then it is still assembling → "Preparing release").
+ */
+export function resolveReleaseState(f: ReleaseStateFacts): MerchantReleaseStateId {
+  if (f.queueState === "shipped") return "live";
+  if (f.shipInFlight) return "publishing";
+  if (f.queueState === "red") return "needs-attention";
+  if (f.queueState === "green") return f.planOk ? "ready-to-publish" : "preparing-release";
+  if (f.queueState === "queued" || f.queueState === "integrating") return "preparing-release";
+  // queueState === "empty": staged-but-empty-queueState is a transient assembling
+  // window; treat any staged content as preparing, else the true empty state.
+  return f.hasStaged ? "preparing-release" : "empty";
+}

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

@@ -0,0 +1,59 @@
+/**
+ * The merchant two-decision model's type vocabulary — the seam between the
+ * internal/mechanical publish pipeline (candidate reconcile, integration runs,
+ * exact-digest ship plans) and the merchant-facing Review-and-Release surface.
+ *
+ * A merchant only ever makes two decisions: (1) add a ready change to the next
+ * release, and (2) publish the next release live. These ids/labels are the
+ * exhaustive, closed vocabulary that surface renders; they are validated against
+ * `docs/review-release-ux-acceptance.json`.
+ */
+
+/** The five merchant-facing change states (contract §2). */
+export type MerchantChangeStateId =
+  | "preparing"
+  | "ready-to-add"
+  | "in-next-release"
+  | "needs-attention"
+  | "published";
+
+/** The six merchant-facing next-release states (contract §3). */
+export type MerchantReleaseStateId =
+  | "empty"
+  | "preparing-release"
+  | "ready-to-publish"
+  | "publishing"
+  | "live"
+  | "needs-attention";
+
+/** The only action exposed on a change (contract §4). `needs-attention` carries none —
+ *  the developer handoff is fully automatic, never a merchant-triggered action. */
+export type MerchantChangeActionId = "add-to-next-release";
+
+/** The only actions exposed on the next release (contract §4). */
+export type MerchantReleaseActionId = "publish-now" | "view-live-store";
+
+/**
+ * The internal change status the pipeline carries on a `/api/changes` row, before
+ * it is collapsed onto a merchant state. `not-built` is the synthetic forge-PR
+ * entry; the merchant never sees any of these names.
+ */
+export type InternalChangeStatus =
+  | "queued"
+  | "reconciling"
+  | "ready"
+  | "blocked"
+  | "not-built"
+  | "building"
+  | "accepted"
+  | "merged"
+  | "closed";
+
+/** The internal aggregate queue state (contract §3, `adminPublishTab.ts` AGG_STATE_CHIP). */
+export type InternalAggregateState =
+  | "empty"
+  | "queued"
+  | "integrating"
+  | "green"
+  | "red"
+  | "shipped";