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

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

@@ -0,0 +1,269 @@
+/**
+ * Pure logic for the admin Publish tab's real-time build/check streaming (SSE).
+ *
+ * The build endpoint (`POST /api/preview/build` with `Accept: text/event-stream`)
+ * streams coarse lifecycle PHASES as it materializes a candidate — resolve head →
+ * read+validate tenant files → publish the immutable version → run evidence checks —
+ * then a terminal `result` event carrying the full outcome. This module is the tested
+ * source of truth for:
+ *   - parsing the raw SSE byte-frames into events (partial-chunk safe);
+ *   - mapping a phase to its human label + rail position;
+ *   - reducing the event sequence into a render-ready progress state;
+ *   - assembling the "Copy for your AI agent" prompt from a build FAILURE.
+ * The DOM wiring that drives the dialog from these is verified on a live preview, per
+ * this codebase's client-island convention (see reviewReleaseWorkspace/controller.ts).
+ */
+
+/** One decoded SSE event: its `event:` name and the concatenated `data:` payload. */
+export interface SseEvent {
+  event: string;
+  data: string;
+}
+
+/**
+ * Parse an accumulated SSE text buffer into complete events, returning any trailing
+ * INCOMPLETE frame as `rest` for the next chunk to prepend. Partial-chunk safe: a
+ * frame is complete only once its blank-line terminator (`\n\n`) has arrived.
+ * Lines with no field (`:` comments, stray blanks) are ignored; multiple `data:`
+ * lines in one frame join with `\n` (the SSE spec). A frame with no fields yields
+ * nothing.
+ */
+export function parseSseChunk(buffer: string): { events: SseEvent[]; rest: string } {
+  const normalized = buffer.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const events: SseEvent[] = [];
+  const lastSep = normalized.lastIndexOf("\n\n");
+  if (lastSep === -1) return { events, rest: normalized };
+
+  const complete = normalized.slice(0, lastSep);
+  const rest = normalized.slice(lastSep + 2);
+
+  for (const frame of complete.split("\n\n")) {
+    let eventName = "message";
+    const dataLines: string[] = [];
+    let sawField = false;
+    for (const rawLine of frame.split("\n")) {
+      if (!rawLine || rawLine.startsWith(":")) continue;
+      const colon = rawLine.indexOf(":");
+      const field = colon === -1 ? rawLine : rawLine.slice(0, colon);
+      // Per spec a single leading space after the colon is stripped.
+      let value = colon === -1 ? "" : rawLine.slice(colon + 1);
+      if (value.startsWith(" ")) value = value.slice(1);
+      if (field === "event") {
+        eventName = value;
+        sawField = true;
+      } else if (field === "data") {
+        dataLines.push(value);
+        sawField = true;
+      }
+    }
+    if (sawField) events.push({ event: eventName, data: dataLines.join("\n") });
+  }
+  return { events, rest };
+}
+
+/** The ordered build lifecycle stages the flight rail renders (mirrors the dialog). */
+export const BUILD_STAGES = ["resolve", "read", "publish", "check"] as const;
+export type BuildStage = (typeof BUILD_STAGES)[number];
+
+/** The `phase` values the server emits, in lifecycle order. */
+export type BuildPhase = "resolving" | "reading" | "publishing" | "checking";
+
+const PHASE_TO_STAGE: Record<BuildPhase, BuildStage> = {
+  resolving: "resolve",
+  reading: "read",
+  publishing: "publish",
+  checking: "check",
+};
+
+const PHASE_LABEL: Record<BuildPhase, string> = {
+  resolving: "Locating the pull request's latest commit…",
+  reading: "Reading and validating your store's files…",
+  publishing: "Publishing this version's preview…",
+  checking: "Running the checks on this version…",
+};
+
+const STAGE_LABEL: Record<BuildStage, string> = {
+  resolve: "Locate commit",
+  read: "Read & validate",
+  publish: "Publish version",
+  check: "Run checks",
+};
+
+export function buildPhaseLabel(phase: BuildPhase): string {
+  return PHASE_LABEL[phase];
+}
+
+export function buildStageLabel(stage: BuildStage): string {
+  return STAGE_LABEL[stage];
+}
+
+export function isBuildPhase(value: unknown): value is BuildPhase {
+  return value === "resolving" || value === "reading" || value === "publishing" || value === "checking";
+}
+
+/** The terminal outcome the server reports on its `result` event. */
+export type BuildOutcome = "ok" | "blocked" | "failed";
+
+/** The full terminal payload of a build (mirrors the endpoint's JSON body). */
+export interface BuildResult {
+  ok: boolean;
+  outcome: BuildOutcome;
+  tenantId?: string | null;
+  changeId?: string | null;
+  headSha?: string | null;
+  prNumber?: number | null;
+  previewUrl?: string | null;
+  errors?: string[];
+  error?: string | null;
+  findings?: BuildFinding[];
+}
+
+export interface BuildFinding {
+  id?: string;
+  label?: string;
+  detail?: string;
+  disposition?: string;
+}
+
+/** Render-ready progress the dialog reads. `stageState` is a per-stage rail map. */
+export interface BuildProgress {
+  phase: BuildPhase | null;
+  liveLabel: string;
+  stageState: Record<BuildStage, "pending" | "active" | "done" | "fail">;
+  terminal: boolean;
+  result: BuildResult | null;
+}
+
+export function initialBuildProgress(): BuildProgress {
+  return {
+    phase: null,
+    liveLabel: "Starting…",
+    stageState: { resolve: "pending", read: "pending", publish: "pending", check: "pending" },
+    terminal: false,
+    result: null,
+  };
+}
+
+/**
+ * Advance the flight rail to `stage`: everything before it is `done`, it is `active`,
+ * everything after stays `pending`. A `fail` mark is never un-done. Pure.
+ */
+function railTo(
+  prev: Record<BuildStage, "pending" | "active" | "done" | "fail">,
+  stage: BuildStage,
+): Record<BuildStage, "pending" | "active" | "done" | "fail"> {
+  const idx = BUILD_STAGES.indexOf(stage);
+  const next = { ...prev };
+  BUILD_STAGES.forEach((s, i) => {
+    if (next[s] === "fail") return;
+    next[s] = i < idx ? "done" : i === idx ? "active" : "pending";
+  });
+  return next;
+}
+
+/**
+ * Fold one SSE event into the progress state. A `phase` event advances the rail + live
+ * label; a `result` event is terminal (all reached stages `done` on success, the active
+ * stage `fail` on a blocked/failed outcome). Unknown events are ignored (state
+ * unchanged). Pure — the dialog calls this per event and re-renders from the result.
+ */
+export function reduceBuildProgress(prev: BuildProgress, ev: SseEvent): BuildProgress {
+  if (ev.event === "phase") {
+    const parsed = safeParse(ev.data);
+    const phase = parsed && (parsed as { phase?: unknown }).phase;
+    if (!isBuildPhase(phase)) return prev;
+    const stage = PHASE_TO_STAGE[phase];
+    const label =
+      (parsed && typeof (parsed as { label?: unknown }).label === "string"
+        ? (parsed as { label: string }).label
+        : "") || buildPhaseLabel(phase);
+    return {
+      ...prev,
+      phase,
+      liveLabel: label,
+      stageState: railTo(prev.stageState, stage),
+    };
+  }
+
+  if (ev.event === "result") {
+    const parsed = (safeParse(ev.data) as BuildResult | null) ?? {
+      ok: false,
+      outcome: "failed",
+      errors: ["build ended without a result"],
+    };
+    const result: BuildResult = {
+      ...parsed,
+      outcome: parsed.outcome ?? (parsed.ok ? "ok" : "failed"),
+    };
+    let stageState = prev.stageState;
+    if (result.ok) {
+      stageState = { resolve: "done", read: "done", publish: "done", check: "done" };
+    } else {
+      // Fail the stage that was active (the phase we got furthest into); if none was
+      // active yet, fail the first stage so the rail shows an honest stop point.
+      const active = BUILD_STAGES.find((s) => prev.stageState[s] === "active") ?? BUILD_STAGES[0];
+      stageState = { ...prev.stageState, [active]: "fail" };
+    }
+    return {
+      ...prev,
+      liveLabel: result.ok ? "Done." : "Stopped.",
+      stageState,
+      terminal: true,
+      result,
+    };
+  }
+
+  return prev;
+}
+
+/** The human-readable failure detail (the honest reason), joined from errors/findings. */
+export function buildFailureDetail(result: BuildResult): string {
+  const parts: string[] = [];
+  for (const e of result.errors ?? []) if (e && e.trim()) parts.push(e.trim());
+  if (result.error && result.error.trim()) parts.push(result.error.trim());
+  for (const f of result.findings ?? []) {
+    const line = [f.label || f.id, f.detail].filter(Boolean).join(": ");
+    if (line) parts.push((f.disposition === "blocking-safety" ? "[blocking] " : "") + line);
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Assemble the "Copy for your AI agent" prompt from a build FAILURE — the honest,
+ * paste-ready brief an operator hands to a coding agent to diagnose why the preview
+ * build/checks failed. Mirrors the merge-conflict copy pattern (a framed ask + the
+ * system's own words), never a bare error dump.
+ */
+export function assembleBuildFailureCopy(input: {
+  tenant: string;
+  prNumber?: number | null;
+  changeId?: string | null;
+  result: BuildResult;
+}): string {
+  const { tenant, prNumber, changeId, result } = input;
+  const pr = prNumber != null ? `PR #${prNumber}` : changeId ? `change ${changeId}` : "my open candidate PR";
+  const stage = result.outcome === "blocked" ? "was blocked by a check" : "failed to build";
+  const detail = buildFailureDetail(result) || "(no detail was reported)";
+  return [
+    `In my ${tenant} store, the preview build for ${pr} ${stage}. ` +
+      `Diagnose why from the detail below, then tell me the exact file(s) to change and the fix.`,
+    "",
+    "What the build reported:",
+    detail,
+    "",
+    result.headSha ? `Head commit: ${result.headSha}` : "",
+    "Context: this is a Token of Trust storefront tenant repo — customization files are " +
+      "mapped to artifacts and validated against the tenant-editable manifest before the " +
+      "version is published. A blocking finding or a validation error stops the build.",
+  ]
+    .filter((l) => l !== "")
+    .join("\n");
+}
+
+function safeParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,72 @@
+/**
+ * r05 — persist each Publish-tab collapsible section's open/closed state per user,
+ * scoped per store so a power user's layout survives reloads without bleeding across
+ * stores. Pure key/read/write logic, extracted from the DOM wiring in
+ * `adminPublishTab.ts` so it is unit-testable and storage-agnostic.
+ *
+ * The persisted value is the human-legible "open"/"closed" (not a boolean string).
+ * `readPersistedOpen` returns `null` when nothing is stored (or storage is
+ * unreadable) — the caller then leaves the section at its SSR default, so the
+ * default open/closed state is preserved when a user has never toggled a section.
+ */
+
+/** The slice of the Web Storage API this helper needs (localStorage satisfies it). */
+export interface CollapseStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+/** Stable identifiers for the collapsible sections on the Publish tab. */
+export type CollapseSectionId =
+  | "review-queue"
+  | "closed-changes"
+  | "next-release"
+  | "live-site"
+  | "rollback";
+
+const KEY_PREFIX = "tot.publish.collapse";
+const OPEN = "open";
+const CLOSED = "closed";
+
+/**
+ * Per-store, per-section storage key. The store scope (appDomain) keeps one store's
+ * layout from bleeding into another; an empty tenant collapses to a shared "_" scope
+ * rather than producing a dangling key.
+ */
+export function collapseStorageKey(tenant: string, sectionId: CollapseSectionId): string {
+  return `${KEY_PREFIX}.${tenant || "_"}.${sectionId}`;
+}
+
+/**
+ * The stored open/closed state, or `null` when nothing is stored, the value is
+ * unrecognized, or storage throws (private mode / disabled). Never throws.
+ */
+export function readPersistedOpen(
+  storage: CollapseStorage,
+  tenant: string,
+  sectionId: CollapseSectionId,
+): boolean | null {
+  let raw: string | null;
+  try {
+    raw = storage.getItem(collapseStorageKey(tenant, sectionId));
+  } catch {
+    return null;
+  }
+  if (raw === OPEN) return true;
+  if (raw === CLOSED) return false;
+  return null;
+}
+
+/** Persist a section's open/closed state. Swallows storage errors (never throws). */
+export function writePersistedOpen(
+  storage: CollapseStorage,
+  tenant: string,
+  sectionId: CollapseSectionId,
+  open: boolean,
+): void {
+  try {
+    storage.setItem(collapseStorageKey(tenant, sectionId), open ? OPEN : CLOSED);
+  } catch {
+    /* storage unavailable (private mode / disabled) — persistence is best-effort */
+  }
+}