// Pure pipeline-list/detail logic for the web client. Deliberately DOM-free: // every helper here is a plain function a `node --test` can exercise without a // browser, exactly like `client.js`. The DOM wiring lives in `app.js`. // // The wording and behaviour mirror the Android app one-for-one — the same // singular/plural spelling, the same status vocabulary, the same comparator // tie-breaks and the same empty-state sentences — because the web client's goal // is feature parity, not a re-invention: // ui/Format.kt, ui/screens/ListSort.kt, ui/screens/ListFilter.kt, // ui/screens/PipelineLastRun.kt, ui/screens/PipelineDetailScreen.kt, // ui/components/RunStatus.kt. // --------------------------------------------------------------------------- // Timestamps and durations (ui/Format.kt) // --------------------------------------------------------------------------- import { pipelineScheduleState, matchesScheduleState } from "./scheduleOrigin.js"; /** * Parses an RFC3339 timestamp to epoch millis, or null when blank or * unparseable. The single parser every time-reading helper shares, so a bad * timestamp is handled the same way everywhere. */ export function parseInstant(text) { if (typeof text !== "string" || text.trim() === "") return null; const ms = Date.parse(text); return Number.isNaN(ms) ? null : ms; } /** * An RFC3339 timestamp as the app's one human, local rendering (`d MMM HH:mm`, * e.g. `17 Oct 21:26`), or null when blank/unparseable so the caller omits the * value rather than printing a blank. The day/month/hour/minute parts are * assembled from `Intl.DateTimeFormat.formatToParts`, so no locale's list comma * leaks into the string and the shape is the same everywhere. `timeZone` is * accepted for deterministic tests; `locale` defaults to a fixed English so the * month abbreviation matches the app's `d MMM` wording rather than drifting with * the host locale. */ export function formatLocalTimestamp(instant, options = {}) { const ms = parseInstant(instant); if (ms === null) return null; const { timeZone, locale = "en-GB" } = options; const parts = new Intl.DateTimeFormat(locale, { day: "numeric", month: "short", hour: "2-digit", minute: "2-digit", hourCycle: "h23", ...(timeZone ? { timeZone } : {}), }).formatToParts(new Date(ms)); const get = (type) => parts.find((part) => part.type === type)?.value ?? ""; return `${get("day")} ${get("month")} ${get("hour")}:${get("minute")}`; } /** * Human duration for a whole number of seconds: `45s`, `2m 5s`, `1h 2m`. The * single duration rule every surface shares. A negative total renders as `0s` * so a clamped value never prints a negative. */ export function formatDuration(totalSeconds) { const seconds = Math.max(0, Math.trunc(totalSeconds)); if (seconds < 60) return `${seconds}s`; if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${seconds % 60}s`; return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`; } /** * Non-negative whole seconds between two RFC3339 timestamps, or null when either * is blank/unparseable or the end precedes the start. */ export function durationSeconds(start, end) { const from = parseInstant(start); const to = parseInstant(end); if (from === null || to === null) return null; const seconds = Math.floor((to - from) / 1000); return seconds >= 0 ? seconds : null; } /** * Non-negative whole seconds from a `start` timestamp to `nowMillis`, or null * when `start` is blank/unparseable. Clamps a future/unparseable elapsed to 0 so * a live timer never prints a negative. */ export function secondsSince(start, nowMillis) { const from = parseInstant(start); if (from === null) return null; return Math.max(0, Math.floor((nowMillis - from) / 1000)); } /** * The time a run has taken so far: while it is still executing, its live elapsed * from its start to `nowMs`; once finished, its stored total duration. Null when * the needed timestamps are unusable, so the caller omits the value. */ export function runDurationText(run, nowMs) { if (run && run.executing) { const elapsed = secondsSince(run.created_at, nowMs); return elapsed === null ? null : formatDuration(elapsed); } const total = durationSeconds(run?.created_at, run?.finished_at); return total === null ? null : formatDuration(total); } /** * A compact "how long ago" for a run's start: `just now` under a minute, then * `Nm ago`/`Nh ago`/`Nd ago`. Null when the timestamp is blank/unparseable so * the caller omits the fragment instead of printing a blank. A future start * (clock skew) reads as `just now`, never a negative age. */ export function formatRanAgo(createdAt, nowMs) { const start = parseInstant(createdAt); if (start === null) return null; const seconds = Math.max(0, Math.floor((nowMs - start) / 1000)); if (seconds < 60) return "just now"; if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`; if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ago`; return `${Math.floor(seconds / 86400)}d ago`; } /** * A stage count in the app's one singular/plural spelling (`1 stage` / * `n stages`), shared by the list and the detail so a single-stage pipeline * never reads "1 stages". */ export function stageCountText(count) { const n = Number(count) || 0; return `${n} ${n === 1 ? "stage" : "stages"}`; } // --------------------------------------------------------------------------- // Run states (ui/components/RunStatus.kt) // --------------------------------------------------------------------------- const RUN_STATE_ALIASES = { running: "running", queued: "queued", waiting: "waiting", active: "active", succeeded: "succeeded", success: "succeeded", completed: "succeeded", done: "succeeded", failed: "failed", error: "failed", canceled: "canceled", cancelled: "canceled", interrupted: "interrupted", blocked: "blocked", skipped: "skipped", }; /** * Maps a server status or outcome word to the app's run-state word, accepting * the server's own vocabulary only. A blank or unrecognised value falls back to * `unknown` so a bad value never crashes the UI. */ export function runStateOf(status) { const key = String(status ?? "").trim().toLowerCase(); return RUN_STATE_ALIASES[key] ?? "unknown"; } // --------------------------------------------------------------------------- // Last-run join and badge (ui/screens/PipelineLastRun.kt) // --------------------------------------------------------------------------- /** Shown for a pipeline that has recorded no run. */ export const NO_RUNS_RECORDED = "no runs recorded"; /** * Timestamps decide recency; the higher run id breaks an exact tie (or a bad * timestamp). The one recency rule, shared by the per-pipeline last-run join * and the "most recent run" ordering. */ export function isMoreRecent(candidate, current) { const a = parseInstant(candidate.created_at); const b = parseInstant(current.created_at); if (a !== null && b !== null && a !== b) return a > b; return candidate.id > current.id; } /** * Joins the whole run history onto pipelines by pipeline id: the most recent * run per pipeline. The input order never matters — recency is decided from the * timestamps, with the higher run id breaking an exact tie — so a pipeline with * no runs is simply absent from the result (the caller renders * [NO_RUNS_RECORDED] for it). */ export function latestRunByPipeline(runs) { const latest = new Map(); for (const run of runs ?? []) { const current = latest.get(run.pipeline_id); if (current === undefined || isMoreRecent(run, current)) latest.set(run.pipeline_id, run); } return latest; } /** The display facts one pipeline row shows for `run`, anchored to `nowMs`. */ export function runBadge(run, nowMs) { return { runId: run.id, state: runStateOf(run.status), ranAgo: formatRanAgo(run.created_at, nowMs), duration: runDurationText(run, nowMs), }; } /** * The last-run secondary line, e.g. `2h ago · 1m 5s · run 42`. Missing * fragments (an unparseable start, a run still executing) are omitted so no * blank separator is ever printed; the run id is always present. */ export function runBadgeMetaLine(badge) { const fragments = [badge.ranAgo, badge.duration, `run ${badge.runId}`]; return fragments.filter((fragment) => fragment != null && fragment !== "").join(" · "); } // --------------------------------------------------------------------------- // Sorting (ui/screens/ListSort.kt) // --------------------------------------------------------------------------- /** The pipeline-list orderings offered by the sort control; Server order is the default. */ export const PIPELINE_SORTS = [ { key: "server_order", label: "Server order" }, { key: "name_asc", label: "Name A\u2013Z" }, { key: "name_desc", label: "Name Z\u2013A" }, { key: "recent_run", label: "Most recent run" }, { key: "fewest_stages", label: "Fewest stages" }, { key: "most_stages", label: "Most stages" }, ]; /** Case-insensitive string comparison, matching String.CASE_INSENSITIVE_ORDER for ASCII. */ function compareInsensitive(a, b) { const x = String(a ?? "").toUpperCase(); const y = String(b ?? "").toUpperCase(); if (x < y) return -1; if (x > y) return 1; return 0; } /** Plain (case-sensitive) string comparison for the comparator's second key. */ function compareSensitive(a, b) { const x = String(a ?? ""); const y = String(b ?? ""); if (x < y) return -1; if (x > y) return 1; return 0; } /** * The pure pipeline comparator for `sort`. Every case ends in an explicit * tie-break (`id` is unique), so pipelines that compare equal on the primary * key always order the same way rather than depending on the input order. * * `latestRuns` maps a pipeline id to that pipeline's most recent run (see * [latestRunByPipeline]); only "Most recent run" uses it but it is passed in * once so the fold is never repeated per comparison. */ export function pipelineComparator(sort, latestRuns = new Map()) { const runFor = (pipeline) => latestRuns instanceof Map ? latestRuns.get(pipeline.id) : latestRuns[pipeline.id]; switch (sort) { case "name_asc": return (a, b) => compareInsensitive(a.name, b.name) || compareSensitive(a.name, b.name) || a.id - b.id; case "name_desc": return (a, b) => -compareInsensitive(a.name, b.name) || compareSensitive(a.name, b.name) || a.id - b.id; case "recent_run": return (a, b) => { const ra = runFor(a); const rb = runFor(b); const noRunA = ra == null ? 1 : 0; const noRunB = rb == null ? 1 : 0; if (noRunA !== noRunB) return noRunA - noRunB; const ta = ra ? parseInstant(ra.created_at) : null; const tb = rb ? parseInstant(rb.created_at) : null; const na = ta == null ? -Infinity : ta; const nb = tb == null ? -Infinity : tb; if (na !== nb) return na > nb ? -1 : 1; const ia = ra ? ra.id : -Infinity; const ib = rb ? rb.id : -Infinity; if (ia !== ib) return ia > ib ? -1 : 1; return a.id - b.id; }; case "fewest_stages": return (a, b) => (Number(a.stages) || 0) - (Number(b.stages) || 0) || compareInsensitive(a.name, b.name) || a.id - b.id; case "most_stages": return (a, b) => (Number(b.stages) || 0) - (Number(a.stages) || 0) || compareInsensitive(a.name, b.name) || a.id - b.id; // Server order (and any unknown stored value): the identity comparator, so // a stable sort preserves the server's own ordering exactly. case "server_order": default: return () => 0; } } /** Orders `pipelines` by `sort` without mutating the input, folding the run history once. */ export function sortPipelines(pipelines, sort, latestRuns = new Map()) { return [...(pipelines ?? [])].sort(pipelineComparator(sort, latestRuns)); } // --------------------------------------------------------------------------- // Filtering (ui/screens/ListFilter.kt) // --------------------------------------------------------------------------- /** * The statuses a filter can select: the server's own run vocabulary. The * app-only `active` bucket, the stage-outcome words (`blocked`/`skipped`) and * the `unknown` fallback are deliberately not offered, so a status filter * always names a real run state. */ export const RUN_STATUS_FILTERS = [ "queued", "running", "waiting", "succeeded", "failed", "canceled", "interrupted", ]; /** The has/no-runs narrowing offered by the filter's Runs section. */ export const RUN_PRESENCES = [ { key: "any", label: "Any" }, { key: "has_runs", label: "Has runs" }, { key: "no_runs", label: "No runs" }, ]; export const PIPELINE_SCHEDULE_FILTERS = [ { key: "any", label: "Any schedule" }, { key: "scheduled", label: "Has schedules" }, { key: "unscheduled", label: "No schedules" }, ]; /** The default, no-narrowing pipeline filter. */ export const EMPTY_PIPELINE_FILTERS = { presence: "any", lastRunStatuses: [], name: "", scheduled: "any" }; /** Whether a run-history facet (presence or last-run status) is set. */ export function hasRunFacets(filters) { return (filters?.presence ?? "any") !== "any" || (filters?.lastRunStatuses ?? []).length > 0; } /** True when the filters actually narrow anything. */ export function pipelineFiltersActive(filters) { return hasRunFacets(filters) || String(filters?.name ?? "").trim() !== "" || ["scheduled", "unscheduled"].includes(filters?.scheduled); } /** The number of active facets, used for the control's badge. */ export function pipelineFilterCount(filters) { return ( ((filters?.presence ?? "any") !== "any" ? 1 : 0) + ((filters?.lastRunStatuses ?? []).length > 0 ? 1 : 0) + (String(filters?.name ?? "").trim() !== "" ? 1 : 0) + (["scheduled", "unscheduled"].includes(filters?.scheduled) ? 1 : 0) ); } /** True when `name` is blank, or when `pipelineName` contains it, ignoring case. */ export function pipelineMatchesName(name, pipelineName) { const needle = String(name ?? "").trim(); return needle === "" || String(pipelineName ?? "").toLowerCase().includes(needle.toLowerCase()); } /** True when `presence` is satisfied by whether the pipeline has a run. */ export function pipelineMatchesPresence(presence, hasRun) { switch (presence) { case "has_runs": return hasRun; case "no_runs": return !hasRun; case "any": default: return true; } } /** * True when `latestRun`'s status is in `statuses`; an empty set means "any * status" and a pipeline with no run never matches a selected status, so the * filter genuinely narrows. */ export function pipelineMatchesLastRunStatus(latestRun, statuses) { const wanted = statuses ?? []; if (wanted.length === 0) return true; return latestRun != null && wanted.includes(runStateOf(latestRun.status)); } /** * Narrows `pipelines` by `filters`: the name narrowing and both run facets * combined with AND. The name facet never depends on the run history, so it * applies immediately; the run facets do, so while that history is still * unknown (`runsKnown == false`) they are skipped rather than briefly hiding * every pipeline. */ export function filterPipelines(pipelines, filters, latestRuns = new Map(), runsKnown = true) { const all = pipelines ?? []; if (!pipelineFiltersActive(filters)) return all; const runFacets = hasRunFacets(filters); const getRun = (pipeline) => latestRuns instanceof Map ? latestRuns.get(pipeline.id) : latestRuns[pipeline.id]; return all.filter((pipeline) => { if (!pipelineMatchesName(filters?.name, pipeline.name)) return false; if (!matchesScheduleState(pipelineScheduleState(pipeline), filters?.scheduled)) return false; if (runFacets && runsKnown) { const latestRun = getRun(pipeline) ?? null; if (!pipelineMatchesPresence(filters.presence, latestRun != null)) return false; if (!pipelineMatchesLastRunStatus(latestRun, filters.lastRunStatuses)) return false; } return true; }); } /** * The empty-state sentence for the pipeline list plus its optional reset action. * Returns null when there is something to show. `Clear filters` is only offered * when pipelines exist (nothing exists to reveal otherwise). */ export function pipelineListEmptyState(all, items, filters) { if ((items ?? []).length > 0) return null; const every = all ?? []; if (every.length === 0) { return { message: "No pipelines are defined on this server.", clearAction: null }; } const name = String(filters?.name ?? ""); const message = name.trim() !== "" && !hasRunFacets(filters) && !["scheduled", "unscheduled"].includes(filters?.scheduled) ? `No pipelines match "${name}".` : "No pipelines match the current filters."; return { message, clearAction: "Clear filters" }; } // --------------------------------------------------------------------------- // List row and detail text // --------------------------------------------------------------------------- /** The pipeline row's secondary line: `id {id} · v{version} · {N stages}`. */ export function pipelineSubtitle(pipeline) { const stages = pipeline.stages ?? pipeline.graph?.stages?.length ?? 0; return `id ${pipeline.id} · v${pipeline.version} · ${stageCountText(stages)}`; } /** The row's `updated …` line, or null when the timestamp is unparseable. */ export function pipelineUpdatedLine(pipeline) { const formatted = formatLocalTimestamp(pipeline.updated_at); return formatted ? `updated ${formatted}` : null; } /** The pipeline-detail tabs, Summary first (the version list lives inside it). */ export const PIPELINE_DETAIL_TABS = [ { key: "summary", label: "Summary" }, { key: "graph", label: "Graph" }, { key: "source", label: "Source" }, ]; /** * The Summary tab's key/value rows, in the app's order: Content hash * (monospace), Latest version (`v{n}` or blank — never a dash), Version created, * Pipeline created, Pipeline updated. */ export function summaryFields(detail) { const latest = Number(detail?.latest_version) || 0; return [ { key: "Content hash", value: detail?.content_hash ?? "", monospace: true }, { key: "Latest version", value: latest > 0 ? `v${latest}` : "" }, { key: "Version created", value: formatLocalTimestamp(detail?.version_created_at) ?? "" }, { key: "Pipeline created", value: formatLocalTimestamp(detail?.created_at) ?? "" }, { key: "Pipeline updated", value: formatLocalTimestamp(detail?.updated_at) ?? "" }, ]; } /** One Version row: `v{n}` plus its stage count and (parseable) created time. */ export function versionRow(version) { return { versionLabel: `v${version?.version}`, stagesText: stageCountText(version?.stages), createdText: formatLocalTimestamp(version?.created_at), }; } /** * The Graph tab's guidance note, adapted for a browser: mouse-wheel zoom and * click replace the app's pinch and tap. The graph itself is the separate P6 * item. */ export const GRAPH_NOTE = "Mouse wheel to zoom, drag to pan, click a stage for details. " + "Edges are labelled with their outcome; error* is the implicit fallback."; /** The guidance note string (a function so callers need no constant import). */ export function graphNote() { return GRAPH_NOTE; }