@tokenoftrust/storefront-runner 2.0.2 → 2.0.3

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

@@ -1,439 +0,0 @@
-/**
- * Ship operations workspace — the PURE composer behind the admin
- * Publish tab's operations surface that sits ALONGSIDE the go-live core
- * (AdminPublishTab.astro's change queue + accept/reject + dispatch status).
- *
- * This module composes the operations workspace ALONGSIDE the Publish-tab core
- * (the change queue from GET /api/changes, Go-live/Reject, the live-version +
- * dispatch-status panel, and the owner-only Domain section) — the three read/act
- * surfaces woven into the same tab:
- *
- *   1. DIFF VIEW  — for one pending candidate, the artifact-level diff of what
- *      changed (its rendered immutable version vs the current live version),
- *      tied to the exact tenant Gitea head SHA, with the immutable
- *      `/<tenant>/preview/rev/<sha>/` link and the evidence AUTHORITY
- *      (authoritative / stale / missing) — never a diff a reviewer would mistake
- *      for the head when a last-good version actually renders.
- *   2. VERSIONS  — the tenant's published-version / promotion history
- *      (`listPromotions`, promotion_status), each row carrying the tenant
- *      Gitea SHA, its promotion time, a
- *      `/rev/<sha>/` link, and — marking the current live one.
- *   3. ROLLBACK  — pick a prior version and roll back THROUGH the one orchestrator
- *      (`/api/changes/rollback` → `rollbackCandidateAtomic` /
- *      `staticRollbackOrchestrator`), rendering only the HONEST terminal state
- *      (`rolled_back` when VERIFIED; `publish_pending` in flight; `publish_failed`
- *      / `blocked` fail-closed) — never a false "rolled back".
- *
- * COMPOSES, never rebuilds:
- *   - the immutable link is `reviewDashboardRevisionHref` verbatim;
- *   - the authority is `candidateEvidenceAuthority` /
- *     `classifyCandidateForRender` verbatim;
- *   - the versions come from the SAME `KVVersionStore.listPromotions` the
- *     "one step back" rollback resolution reads;
- *   - the rollback ACTION is the existing `/api/changes/rollback` seam — this
- *     module only INTERPRETS its honest response, it never re-decides a ship.
- *
- * PURE (no I/O): the endpoints inject already-read KV data, so every honest-state
- * decision is unit-tested without a Worker/KV — mirroring the reviewDashboard.ts /
- * candidatePreviewState.ts split.
- *
- * `rollbackMode` names the path a rollback is honestly driven by: a `control-plane`
- * (hosted) tenant and a `pointer` (static-publish) tenant BOTH roll back one-click
- * via the instant KV `live` pointer flip — the Worker serves whatever bundle the
- * pointer's digest names (from R2, for a static tenant), so restoring the pointer IS
- * the rollback. The `publish_pending`/`publish_failed`/`blocked` honesty model from
- * `interpretRollbackResponse` below applies identically in both modes — only the
- * digest column (surfaced for a static tenant) differs.
- */
-import { reviewDashboardRevisionHref } from "@/lib/preview/reviewDashboard";
-import { assignVersionNumbers } from "@/lib/publish/versionNumber";
-import {
-  candidateEvidenceAuthority,
-  classifyCandidateForRender,
-  defaultBlockedReason,
-  type CandidateEvidenceAuthority,
-} from "@/lib/preview/candidatePreviewState";
-import type { ReviewEnvironment, PromotionEvent } from "@tot/public-runtime";
-
-// ── Versions / promotion history ───────────────────────────────────────────
-
-/** The plain-language "what shipped in this version" model (same shape the staged
- *  release summary uses — a name + a lead sentence + one highlight per included change). */
-export interface VersionReleaseSummary {
-  /** The human-readable release name (see `deriveReleaseName`), or null. */
-  name: string | null;
-  lead: string;
-  highlights: { title: string; detail: string }[];
-}
-
-/** One change that shipped in a published version — its PR summary, for the
- *  version's openable "what shipped" list. Fields degrade to null/`PR #N` when
- *  candidate_summary didn't cover the PR (best-effort enrichment). */
-export interface WorkspaceVersionChange {
-  changeId: string;
-  prNumber: number | null;
-  headSha: string;
-  title: string | null;
-  description: string | null;
-  fileCount: number | null;
-  linesAdded: number | null;
-  linesRemoved: number | null;
-}
-
-/** Per-version release enrichment, keyed by versionId (== the promoted aggregate sha). */
-export interface VersionReleaseInfo {
-  releaseSummary: VersionReleaseSummary | null;
-  changes: WorkspaceVersionChange[];
-}
-
-/** One published version in the tenant's promotion history (promotion_status). */
-export interface WorkspaceVersion {
-  /** The tenant Gitea SHA the version serves — the content identity. */
-  versionId: string;
-  /**
-   * The merchant-facing monotonic version number ("v42") — derived from first
-   * promotion order (see `versionNumber.ts`), shared with the "Live version"
-   * metric. The human label; the SHA is demoted to a technical disclosure.
-   */
-  number: number | null;
-  /** How the version was published (a Gitea commit, or a content hash). */
-  source: "commit" | "hash" | null;
-  /** ISO time the version was PROMOTED onto `live` (the promotion event). */
-  promotedAt: string;
-  /** ISO time the version was first published (from its site-version manifest). */
-  createdAt: string | null;
-  /** Artifact count in the version manifest, or `null` when the manifest is absent. */
-  artifactCount: number | null;
-  /**
-   * The content-addressed `treeDigest`, when the console can honestly know it —
-   * i.e. ONLY the current live version of a static tenant (read back from
-   * `live/manifest.json`). `null` for every other row: a prior static version's
-   * digest lives only in the S3 archive the Worker can't enumerate. Never fabricated.
-   */
-  digest: string | null;
-  /** The immutable `/<tenant>/preview/rev/<sha>/` deep-link, or `null` without a SHA. */
-  revHref: string | null;
-  /** The version currently serving live (the one you never roll back TO). */
-  isCurrent: boolean;
-  /**
-   * The plain-language "what shipped in this version" summary, composed from the
-   * release receipt's included PRs + their candidate_summary. `null` when no
-   * receipt links this version to a PR set, or none carried summary prose.
-   */
-  releaseSummary: VersionReleaseSummary | null;
-  /**
-   * The PRs that shipped in this version (from its release receipt), each with its
-   * human summary — the version's openable "what shipped" list. Empty when no
-   * receipt links this version to a PR set.
-   */
-  changes: WorkspaceVersionChange[];
-  /** How many changes shipped in this version, or `null` when unknown (no receipt). */
-  changeCount: number | null;
-}
-
-/**
- * How a rollback is honestly driven for this tenant. `control-plane` (hosted) and
- * `pointer` (static-publish) both roll back one-click via the instant KV `live`
- * pointer flip; they render identical instant "Roll back" copy, differing only in
- * whether the static digest column is shown.
- */
-export type RollbackMode = "control-plane" | "pointer";
-
-/** The versions-panel view model. */
-export interface VersionsView {
-  /** The current live version + (static) the digest `live/` actually serves. */
-  current: { versionId: string | null; number: number | null; digest: string | null };
-  /** Promotion history, newest first, current marked. */
-  versions: WorkspaceVersion[];
-  /** Whether the tenant publishes its public site to an external static target. */
-  staticPublish: boolean;
-  /**
-   * `control-plane` (hosted) and `pointer` (static-publish) both roll back
-   * one-click via `targetVersionId` (instant KV pointer flip) and render identical
-   * instant "Roll back" copy.
-   */
-  rollbackMode: RollbackMode;
-}
-
-/** A single promoted version enriched with the manifest facts the panel shows. */
-export interface VersionManifestFacts {
-  source: "commit" | "hash" | null;
-  createdAt: string | null;
-  artifactCount: number | null;
-}
-
-export interface BuildVersionsViewInput {
-  tenantId: string;
-  /** Live-promotion history, newest first (`KVVersionStore.listPromotions`). */
-  promotions: PromotionEvent[];
-  /** The current live version id (the live-channel pointer), or `null`. */
-  currentVersionId: string | null;
-  /** The digest `live/` serves — static tenants only; `null` otherwise. */
-  currentDigest: string | null;
-  /** Per-version manifest facts, keyed by versionId (absent ⇒ unknown facts). */
-  manifests: Map<string, VersionManifestFacts>;
-  /**
-   * Per-version release enrichment, keyed by versionId (== the promoted aggregate
-   * sha on the release receipt). Absent ⇒ a version with no linked PR set (an
-   * honest empty release summary + no changes list — never fabricated).
-   */
-  releases?: Map<string, VersionReleaseInfo>;
-  staticPublish: boolean;
-}
-
-/**
- * Assemble the versions panel from the promotion history + per-version manifest
- * facts + the current-live pointer. Pure. The current live row is marked; the
- * digest is populated ONLY for the current live of a static tenant (never faked
- * for priors). `revHref` is the immutable link.
- */
-export function buildVersionsView(input: BuildVersionsViewInput): VersionsView {
-  const {
-    tenantId,
-    promotions,
-    currentVersionId,
-    currentDigest,
-    manifests,
-    releases,
-    staticPublish,
-  } = input;
-
-  // The merchant-facing "v42" counter, derived from first-promotion order — the
-  // SAME derivation `resolveLiveVersion` feeds the "Live version" metric, so the
-  // panel and the metric always agree on a version's number.
-  const numbers = assignVersionNumbers(promotions);
-
-  const versions: WorkspaceVersion[] = promotions.map((p) => {
-    const facts = manifests.get(p.versionId);
-    const release = releases?.get(p.versionId);
-    const isCurrent = currentVersionId != null && p.versionId === currentVersionId;
-    return {
-      versionId: p.versionId,
-      number: numbers.get(p.versionId) ?? null,
-      source: facts?.source ?? null,
-      promotedAt: p.at,
-      createdAt: facts?.createdAt ?? null,
-      artifactCount: facts?.artifactCount ?? null,
-      // Honest: a digest is known only for the current live of a static tenant.
-      digest: isCurrent && staticPublish ? currentDigest : null,
-      revHref: reviewDashboardRevisionHref(tenantId, p.versionId),
-      isCurrent,
-      releaseSummary: release?.releaseSummary ?? null,
-      changes: release?.changes ?? [],
-      changeCount: release ? release.changes.length : null,
-    };
-  });
-
-  return {
-    current: {
-      versionId: currentVersionId,
-      number: currentVersionId != null ? numbers.get(currentVersionId) ?? null : null,
-      digest: staticPublish ? currentDigest : null,
-    },
-    versions,
-    staticPublish,
-    rollbackMode: staticPublish ? "pointer" : "control-plane",
-  };
-}
-
-// ── Diff view ──────────────────────────────────────────────────────────────
-
-export type DiffChangeKind = "added" | "removed" | "changed";
-
-/** One artifact path that differs between the candidate and the current live version. */
-export interface DiffEntry {
-  path: string;
-  change: DiffChangeKind;
-}
-
-/** The diff-view model for one pending candidate. */
-export interface CandidateDiffView {
-  changeId: string;
-  /** The candidate's exact head SHA — the reconcile TARGET (tenant Gitea sha). */
-  headSha: string | null;
-  /** The immutable version actually rendered + diffed — the reconcile ACTUAL. */
-  versionId: string | null;
-  /** The immutable link to the exact reviewed SHA, or `null` without a head SHA. */
-  revHref: string | null;
-  /** Evidence authority: authoritative (tied to head) / stale (last-good) / missing. */
-  authority: CandidateEvidenceAuthority;
-  /** The artifact-level diff (candidate rendered version vs current live), sorted by path. */
-  files: DiffEntry[];
-  /** True when the candidate has a renderable version to diff (the `ready` classification). */
-  renderable: boolean;
-  /** When NOT renderable, the honest reason (names why) — never a fake empty diff. */
-  blockedReason: string | null;
-}
-
-export interface BuildCandidateDiffInput {
-  tenantId: string;
-  env: ReviewEnvironment;
-  /** The candidate rendered version's artifacts (path → contentHash), or `null`. */
-  candidateArtifacts: Record<string, string> | null;
-  /** The current live version's artifacts (path → contentHash), or `null` (nothing live yet). */
-  liveArtifacts: Record<string, string> | null;
-}
-
-/**
- * Diff a candidate's rendered version against the current live version, at the
- * artifact level (each path carries a content hash in its site-version manifest).
- * Composes `classifyCandidateForRender` (only a `ready` candidate has a
- * version to diff — a blocked/queued one yields an HONEST `blockedReason`, never a
- * fabricated empty diff) and `candidateEvidenceAuthority` (so a diff of a last-good
- * version that LAGS the head is flagged `stale`, not passed off as the head).
- * Pure.
- */
-export function buildCandidateDiff(input: BuildCandidateDiffInput): CandidateDiffView {
-  const { tenantId, env, candidateArtifacts, liveArtifacts } = input;
-  const classification = classifyCandidateForRender(env);
-  const authority = candidateEvidenceAuthority(env);
-  const revHref = reviewDashboardRevisionHref(tenantId, env.headSha);
-
-  if (classification.kind !== "ready") {
-    const reason =
-      classification.kind === "blocked"
-        ? classification.reason
-        : defaultBlockedReason(env.status);
-    return {
-      changeId: env.changeId,
-      headSha: env.headSha,
-      versionId: null,
-      revHref,
-      authority,
-      files: [],
-      renderable: false,
-      blockedReason: reason,
-    };
-  }
-
-  const files = diffArtifacts(candidateArtifacts ?? {}, liveArtifacts ?? {});
-  return {
-    changeId: env.changeId,
-    headSha: env.headSha,
-    versionId: classification.versionId,
-    revHref,
-    authority,
-    files,
-    renderable: true,
-    blockedReason: null,
-  };
-}
-
-/** Artifact-level diff: paths added / removed / content-changed, sorted by path. */
-export function diffArtifacts(
-  candidate: Record<string, string>,
-  live: Record<string, string>,
-): DiffEntry[] {
-  const entries: DiffEntry[] = [];
-  for (const [path, hash] of Object.entries(candidate)) {
-    if (!(path in live)) entries.push({ path, change: "added" });
-    else if (live[path] !== hash) entries.push({ path, change: "changed" });
-  }
-  for (const path of Object.keys(live)) {
-    if (!(path in candidate)) entries.push({ path, change: "removed" });
-  }
-  return entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
-}
-
-// ── Rollback response interpretation ─────────────────────────────────────────
-
-/** The normalized honest terminal state of a rollback, for the surface to render. */
-export type RollbackState =
-  | "rolled_back" // VERIFIED live on the prior version — the ONLY "rolled back" claim
-  | "publish_pending" // restored + dispatched, not yet verified — NOT "rolled back"
-  | "publish_failed" // fail-closed: unwired / dispatch failed / verification failed
-  | "blocked" // a gate refused (capability / no prior / race) — nothing moved
-  | "error"; // transport / unexpected shape
-
-export interface RollbackOutcome {
-  state: RollbackState;
-  /** True ONLY for `rolled_back` (the target is verified to serve the prior version). */
-  rolledBack: boolean;
-  /** The version restored TO, when known. */
-  toVersionId: string | null;
-  /** A human-legible message for the surface. */
-  message: string;
-}
-
-/**
- * Interpret the `/api/changes/rollback` response into ONE honest terminal state,
- * for BOTH planes without the surface having to know which it hit:
- *   - a HOSTED (control-plane) rollback returns `{ rolledBack: true, toVersionId }`
- *     on success (the pointer flip IS the rollback) or `{ error, reason }` on refusal;
- *   - a STATIC rollback returns the orchestrator's honest `{ state, ... }`.
- * The rule the surface depends on: `rolledBack` is true ONLY for a verified
- * `rolled_back` — a `publish_pending` is NEVER rendered as rolled back.
- * Pure.
- */
-export function interpretRollbackResponse(
-  httpOk: boolean,
-  body: {
-    state?: unknown;
-    rolledBack?: unknown;
-    toVersionId?: unknown;
-    message?: unknown;
-    error?: unknown;
-    reason?: unknown;
-  },
-): RollbackOutcome {
-  const toVersionId = typeof body.toVersionId === "string" ? body.toVersionId : null;
-
-  // Static plane: the orchestrator's explicit honest state wins.
-  if (typeof body.state === "string") {
-    const state = normalizeRollbackState(body.state);
-    const message =
-      typeof body.message === "string" && body.message
-        ? body.message
-        : typeof body.error === "string" && body.error
-          ? body.error
-          : rollbackStateFallbackMessage(state);
-    return { state, rolledBack: state === "rolled_back", toVersionId, message };
-  }
-
-  // Control-plane: a bare success flag, or a typed refusal.
-  if (httpOk && body.rolledBack === true) {
-    return {
-      state: "rolled_back",
-      rolledBack: true,
-      toVersionId,
-      message: toVersionId ? `Rolled back live to ${toVersionId}.` : "Rolled back live.",
-    };
-  }
-
-  const reason = typeof body.reason === "string" ? body.reason : null;
-  const message =
-    typeof body.error === "string" && body.error
-      ? body.error + (reason ? ` (${reason})` : "")
-      : "Rollback failed.";
-  // A control-plane refusal is a gate refusal (capability / no prior / conflict) —
-  // nothing moved; treat as blocked (never a false rolled-back).
-  return { state: "blocked", rolledBack: false, toVersionId, message };
-}
-
-function normalizeRollbackState(raw: string): RollbackState {
-  switch (raw) {
-    case "rolled_back":
-    case "publish_pending":
-    case "publish_failed":
-    case "blocked":
-      return raw;
-    default:
-      return "error";
-  }
-}
-
-function rollbackStateFallbackMessage(state: RollbackState): string {
-  switch (state) {
-    case "rolled_back":
-      return "Rolled back live.";
-    case "publish_pending":
-      return "Restored the pointer and dispatched the re-publish — not yet verified live. Refresh to re-check.";
-    case "publish_failed":
-      return "Rollback failed — the publish path is unwired or verification failed. Nothing false went live.";
-    case "blocked":
-      return "Rollback was refused by a gate — nothing changed.";
-    case "error":
-    default:
-      return "Rollback returned an unexpected response.";
-  }
-}

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

@@ -1,119 +0,0 @@
-/**
- * The shared "buffer-or-stream on `Accept`" plumbing for a long-running admin
- * route. ONE emit-driven work function serves BOTH transports:
- *
- *   - a non-streaming caller (the CLI, any `Accept: application/json` client) gets
- *     the buffered terminal JSON body + status the work resolved — `emit` is a no-op;
- *   - a streaming caller (`Accept: text/event-stream`, the admin Publish tab) gets
- *     each `emit(event, data)` as an SSE frame AS IT HAPPENS, then a terminal
- *     `result` event carrying the SAME payload the JSON body would have, then close.
- *
- * The work runs ONCE either way; the terminal payload + status are IDENTICAL. Only
- * the delivery differs. This is the generalized form of the pattern
- * `POST /api/preview/build` first shipped inline — extracted here so every
- * long-running route (build / integrate / rebuild / ship) streams the same way
- * without re-implementing the ReadableStream/encoder/close dance.
- */
-
-/**
- * A buffered JSON Response — the non-streaming terminal body. Inlined (not imported
- * from the change/grants controlplane) so this generic transport helper stays in the
- * `lib/publish` render layer, respecting the renderer-no-controlplane boundary.
- */
-function jsonResponse(body: unknown, status = 200): Response {
-  return new Response(JSON.stringify(body), {
-    status,
-    headers: { "content-type": "application/json", "cache-control": "no-store" },
-  });
-}
-
-/** Emit one SSE event. A no-op in buffered (JSON) mode. */
-export type SseEmit = (event: string, data: Record<string, unknown>) => void;
-
-/** The terminal outcome of the work: the HTTP status + the JSON/`result` payload. */
-export interface StreamWorkResult {
-  status: number;
-  payload: Record<string, unknown>;
-}
-
-/** True when the caller asked for an SSE stream (`Accept: text/event-stream`). */
-export function wantsEventStream(request: Request): boolean {
-  return (request.headers.get("accept") || "").includes("text/event-stream");
-}
-
-/**
- * Run `work` and deliver its terminal payload as either a buffered JSON Response
- * (default) or a streamed SSE Response (when the caller sent
- * `Accept: text/event-stream`). In stream mode each `emit` becomes an
- * `event: <name>\ndata: <json>\n\n` frame; the terminal payload is sent as a
- * `result` event and the stream closes. `onError` maps an UNEXPECTED throw (the
- * work is expected to be fail-safe and return its own error payload) to a terminal
- * result — in JSON mode it becomes the response body+status, in SSE mode the
- * `result` event.
- */
-export async function respondBufferedOrStreamed(
-  request: Request,
-  work: (emit: SseEmit) => Promise<StreamWorkResult>,
-  opts?: { onError?: (error: unknown) => StreamWorkResult },
-): Promise<Response> {
-  const onError =
-    opts?.onError ??
-    ((error: unknown): StreamWorkResult => ({
-      status: 500,
-      payload: {
-        ok: false,
-        outcome: "failed",
-        errors: [`operation failed: ${error instanceof Error ? error.message : String(error)}`],
-      },
-    }));
-
-  // Buffered JSON mode — the CLI / any non-streaming caller. `emit` is a no-op; the
-  // work's own status + payload are returned verbatim (same contract as before).
-  if (!wantsEventStream(request)) {
-    try {
-      const { status, payload } = await work(() => {});
-      return jsonResponse(payload, status);
-    } catch (error) {
-      const { status, payload } = onError(error);
-      return jsonResponse(payload, status);
-    }
-  }
-
-  // SSE mode — stream each phase as it happens, then a terminal `result` event
-  // carrying the SAME payload the JSON body would have, then close. Workers stream a
-  // ReadableStream body natively — no infra.
-  const encoder = new TextEncoder();
-  const stream = new ReadableStream<Uint8Array>({
-    start(controller) {
-      const send: SseEmit = (event, data) => {
-        try {
-          controller.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
-        } catch {
-          /* controller already closed (client disconnected) — nothing to do */
-        }
-      };
-      void (async () => {
-        try {
-          const { payload } = await work(send);
-          send("result", payload);
-        } catch (error) {
-          send("result", onError(error).payload);
-        } finally {
-          try {
-            controller.close();
-          } catch {
-            /* already closed */
-          }
-        }
-      })();
-    },
-  });
-  return new Response(stream, {
-    status: 200,
-    headers: {
-      "content-type": "text/event-stream; charset=utf-8",
-      "cache-control": "no-cache, no-transform",
-      "x-accel-buffering": "no",
-    },
-  });
-}