Files
pipelines/web/src/artifacts.js
T
alan 67120947c2 web: artifacts gallery, full-screen viewer and session export link (R8/R9)
Port the Android artifact derivation into a pure, DOM-free src/artifacts.js
(presentedArtifacts with the retired session.md hidden everywhere, grouping by
stage/visit, the header/summary/capture-note wording, kind and size formatting,
viewer paging and sessionExportArtifact) and unit-test it.

Wire it into src/app.js: a run-level artifacts gallery with per-(stage,visit)
groups, per-visit summaries and tiles, a full-screen viewer overlay (paging,
Escape/backdrop close) and the read-only session.html link. Every server string
is set with textContent; captures/ stays untracked.

Captured live against run 430 through test/ui-smoke.mjs:
captures/04-run-430-artifacts.png, 05-artifact-viewer.png,
06-session-export-link.png. PARITY.md marks R8 and R9 done.
2026-10-19 02:38:48 +01:00

391 lines
15 KiB
JavaScript

// Pure, DOM-free artifact derivation for the run detail, ported from the Android
// client so the browser says and does exactly the same thing:
// ui/ArtifactGroups.kt presentedArtifacts, runArtifactGroups, artifactsEmptyMessage
// ui/Format.kt artifactsSummary, artifactCaptureNotes, humanBytes, content-type tests
// ui/graph/ArtifactType.kt artifactKind, artifactKindLabel
// ui/graph/Artifacts.kt the gallery's group/visit/tile vocabulary
// ui/graph/ArtifactViewer.kt pagedArtifacts, viewerIndexByUrl, pagedIndex, position label
// ui/graph/SessionExport.kt sessionExportFile
// ui/screens/Timeline.kt the display visit number (control.visit, else position + 1)
// ui/ArtifactType.kt the file-kind classification vocabulary
//
// Nothing here touches the DOM or imports the app: every function is pure so the
// wording, ordering, counting and formatting can be unit-tested without a browser.
// The tile/overlay wiring lives in app.js.
import { resolveArtifactUrl } from "./serverUrl.js";
/**
* The retired markdown session export file name. Nothing writes it any more, but
* a run recorded before the HTML-only change still lists `session.md`: it is
* dated evidence that is never presented, so it is hidden from every artifact
* listing rather than shown beside the session html. Mirrors
* ArtifactGroups.kt LEGACY_SESSION_MARKDOWN_ARTIFACT.
*/
export const LEGACY_SESSION_MARKDOWN_ARTIFACT = "session.md";
/**
* The "capture pending" wording shared by a running visit's summary and the
* run-level empty state, so the two never spell it differently.
*/
export const ARTIFACT_CAPTURE_PENDING = "capture pending";
/**
* What an artifact's file type is, from the app's point of view: the two media
* kinds the gallery previews (image, video) and the file kinds it labels with a
* type glyph. Mirrors graph/ArtifactType.kt ArtifactKind.
*/
export const ArtifactKind = Object.freeze({
Image: "Image",
Video: "Video",
Audio: "Audio",
Pdf: "Pdf",
Json: "Json",
Archive: "Archive",
Spreadsheet: "Spreadsheet",
Log: "Log",
Code: "Code",
Document: "Document",
Other: "Other",
});
const ARCHIVE_EXTENSIONS = new Set([
"zip", "tar", "gz", "tgz", "bz2", "xz", "rar", "7z", "jar", "war",
]);
const ARCHIVE_MIMES = new Set([
"application/zip",
"application/gzip",
"application/x-tar",
"application/x-7z-compressed",
"application/x-rar-compressed",
"application/java-archive",
]);
const SPREADSHEET_EXTENSIONS = new Set(["csv", "tsv", "xls", "xlsx", "ods"]);
const SPREADSHEET_MIMES = new Set([
"text/csv",
"text/tab-separated-values",
"application/vnd.ms-excel",
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
]);
const CODE_EXTENSIONS = new Set([
"kt", "kts", "java", "go", "py", "rb", "php", "rs", "c", "h", "cc", "cpp",
"hpp", "cs", "js", "jsx", "ts", "tsx", "mjs", "cjs", "swift", "scala", "sh",
"bash", "zsh", "fish", "ps1", "sql", "yaml", "yml", "toml", "ini", "xml",
"gradle", "properties", "proto",
]);
const CODE_MIMES = new Set([
"application/xml",
"application/x-yaml",
"application/javascript",
"text/javascript",
"text/x-python",
"text/x-java-source",
"text/x-kotlin",
"application/x-sh",
"application/x-httpd-php",
"application/sql",
]);
const DOCUMENT_EXTENSIONS = new Set([
"txt", "md", "markdown", "rst", "doc", "docx", "odt", "rtf", "html", "htm",
]);
const DOCUMENT_MIMES = new Set([
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"application/rtf",
]);
const KIND_LABELS = Object.freeze({
[ArtifactKind.Image]: "Image",
[ArtifactKind.Video]: "Video",
[ArtifactKind.Audio]: "Audio",
[ArtifactKind.Pdf]: "PDF",
[ArtifactKind.Json]: "JSON",
[ArtifactKind.Archive]: "Archive",
[ArtifactKind.Spreadsheet]: "Spreadsheet",
[ArtifactKind.Log]: "Log",
[ArtifactKind.Code]: "Code",
[ArtifactKind.Document]: "Document",
[ArtifactKind.Other]: "File",
});
/** Whether an artifact's content type is an image the gallery can preview. */
export function isImageContentType(contentType) {
return String(contentType ?? "").startsWith("image/");
}
/**
* Whether an artifact's content type is a video. Videos are shown in the gallery
* as a poster-style tile with a play marker; they are never decoded inline and
* never autoplay.
*/
export function isVideoContentType(contentType) {
return String(contentType ?? "").startsWith("video/");
}
/**
* The artifacts of one visit as the operator sees them: the recorded files with
* the retired markdown session export filtered out. Every artifact listing
* derives from this one function, so a visit never shows a session markdown
* beside the session html and the recorded counts can never disagree with the
* tiles. Duplicate names are kept, not deduped: an artifact's identity is its
* recorded url, not its name. Mirrors ArtifactGroups.kt presentedArtifacts.
*/
export function presentedArtifacts(step) {
return (step?.artifacts ?? []).filter(
(artifact) => artifact?.name !== LEGACY_SESSION_MARKDOWN_ARTIFACT,
);
}
/** How many files the capture excluded for `step` (absent means none). */
export function artifactsSkipped(step) {
return Number(step?.artifacts_skipped ?? 0) || 0;
}
/** How many files the capture omitted for `step` (absent means none). */
export function artifactsTruncated(step) {
return Number(step?.artifacts_truncated ?? 0) || 0;
}
/** The extension of `name` (lowercased), or "" when it carries none. */
function extensionOf(name) {
const text = String(name ?? "");
const dot = text.lastIndexOf(".");
return dot === -1 ? "" : text.slice(dot + 1).toLowerCase();
}
/**
* The gallery kind of an artifact from its `contentType` (server-sniffed, may
* carry parameters) and its `name` (the extension is the fallback when the sniff
* is a generic text/plain or application/octet-stream). Image and video come
* straight from the content type; the rest match the normalised mime first, then
* the name's extension. Pure and total. Mirrors graph/ArtifactType.kt artifactKind.
*/
export function artifactKind(contentType, name) {
if (isImageContentType(contentType)) return ArtifactKind.Image;
if (isVideoContentType(contentType)) return ArtifactKind.Video;
const ct = String(contentType ?? "");
const mime = ct.split(";")[0].trim().toLowerCase();
const ext = extensionOf(name);
if (mime.startsWith("audio/")) return ArtifactKind.Audio;
if (mime === "application/pdf" || ext === "pdf") return ArtifactKind.Pdf;
if (mime.includes("json") || ext === "json") return ArtifactKind.Json;
if (ARCHIVE_MIMES.has(mime) || ARCHIVE_EXTENSIONS.has(ext)) return ArtifactKind.Archive;
if (SPREADSHEET_MIMES.has(mime) || SPREADSHEET_EXTENSIONS.has(ext)) return ArtifactKind.Spreadsheet;
if (ext === "log") return ArtifactKind.Log;
if (mime === "text/html") return ArtifactKind.Document;
if (CODE_MIMES.has(mime) || CODE_EXTENSIONS.has(ext)) return ArtifactKind.Code;
if (mime.startsWith("text/") || DOCUMENT_MIMES.has(mime) || DOCUMENT_EXTENSIONS.has(ext)) {
return ArtifactKind.Document;
}
return ArtifactKind.Other;
}
/**
* The word that names `kind` where the gallery shows its glyph but must also say
* the type in prose (a screen reader cannot read an icon). The same
* classification `artifactKind` draws from, so glyph and word never disagree.
*/
export function artifactKindLabel(kind) {
return KIND_LABELS[kind] ?? "File";
}
/**
* Human-readable byte size, matching Android Format.kt humanBytes (and the TUI):
* whole bytes under 1 KiB, otherwise one decimal with a binary unit
* (KiB/MiB/GiB/TiB/PiB/EiB).
*/
export function humanBytes(size) {
const value = Math.trunc(Number(size) || 0);
const unit = 1024;
if (value < unit) return `${value} B`;
let div = unit;
let exp = 0;
let scaled = Math.trunc(value / unit);
while (scaled >= unit) {
div *= unit;
exp++;
scaled = Math.trunc(scaled / unit);
}
return `${(value / div).toFixed(1)} ${"KMGTPE"[exp]}iB`;
}
/**
* The display visit number for a step at `index` within its stage's ordered
* visits: the recorded control visit when positive, otherwise the position
* within the stage. Mirrors Timeline.kt (`control.visit > 0 ? visit : index + 1`).
*/
export function displayVisit(step, index) {
const visit = step?.control?.visit;
return Number(visit) > 0 ? Number(visit) : index + 1;
}
/**
* Groups a run's artifacts by stage and visit. Stages keep first-appearance
* order and each stage's visits are ordered by sequence, with the display visit
* number above. Only visits that recorded at least one presented artifact
* produce a group, so an empty capture never yields an empty group and an
* artifact-less run yields an empty list. Mirrors ArtifactGroups.kt
* runArtifactGroups + Timeline.kt runTimeline.
*/
export function artifactGroups(steps) {
const list = steps ?? [];
if (list.length === 0) return [];
// groupBy(stage) keeps first-appearance order (a Map preserves insertion
// order); each stage's visits are then ordered by sequence.
const visitsByStage = new Map();
for (const step of list) {
const stage = step?.stage ?? "";
if (!visitsByStage.has(stage)) visitsByStage.set(stage, []);
visitsByStage.get(stage).push(step);
}
const groups = [];
for (const [stageKey, visits] of visitsByStage) {
const ordered = [...visits].sort((a, b) => (a?.sequence ?? 0) - (b?.sequence ?? 0));
ordered.forEach((step, index) => {
const artifacts = presentedArtifacts(step);
if (artifacts.length === 0) return;
groups.push({ stageKey, visit: displayVisit(step, index), artifacts });
});
}
return groups;
}
/**
* The explicit message shown where the run's artifacts gallery would be when
* there are none: while the run is executing it uses the same "capture pending"
* wording as a running visit, otherwise it says plainly that nothing was
* recorded. Mirrors ArtifactGroups.kt artifactsEmptyMessage.
*/
export function artifactsEmptyMessage(executing) {
return executing
? `Artifacts · ${ARTIFACT_CAPTURE_PENDING}`
: "No artifacts recorded for this run.";
}
/**
* The run summary's Artifacts section header: the title, how many artifacts the
* run recorded (the title takes its singular form for exactly one) and
* "partial capture" when any visit excluded or omitted files. It reuses the
* shared empty message, so a run with nothing recorded still gets a
* self-describing header. The recorded count is exactly the number of tiles
* `artifactGroups` yields. Mirrors ArtifactGroups.kt runArtifactsHeader.
*/
export function artifactsHeader(steps, executing) {
const list = steps ?? [];
const recorded = list.reduce((sum, step) => sum + presentedArtifacts(step).length, 0);
if (recorded === 0) return artifactsEmptyMessage(executing);
const partial = list.some((step) => artifactsSkipped(step) > 0 || artifactsTruncated(step) > 0);
let label = `${recorded === 1 ? "Artifact" : "Artifacts"} · ${recorded} recorded`;
if (partial) label += " · partial capture";
return label;
}
/**
* The per-visit artifacts summary label: "capture pending" while the visit runs,
* "not recorded for this visit" for a finished visit with no artifacts,
* otherwise the recorded count plus " · partial capture" when files were
* excluded or omitted. Mirrors Format.kt artifactsSummary.
*/
export function artifactsSummary(step) {
const artifacts = presentedArtifacts(step);
if (artifacts.length === 0) {
const state = step?.status === "running" ? ARTIFACT_CAPTURE_PENDING : "not recorded for this visit";
return `Artifacts · ${state}`;
}
let label = `Artifacts · ${artifacts.length} recorded`;
if (artifactsSkipped(step) > 0 || artifactsTruncated(step) > 0) label += " · partial capture";
return label;
}
/**
* The partial-capture notes, one line per non-zero count and nothing when the
* capture was complete. An empty artifact list yields no notes at all, so the
* notes never accompany the empty-state summary. Mirrors Format.kt
* artifactCaptureNotes.
*/
export function artifactCaptureNotes(step) {
const notes = [];
if (presentedArtifacts(step).length === 0) return notes;
const skipped = artifactsSkipped(step);
const truncated = artifactsTruncated(step);
if (skipped > 0) notes.push(`${skipped} files excluded from artifact capture.`);
if (truncated > 0) notes.push(`${truncated} files omitted by artifact capture limits.`);
return notes;
}
/**
* The media artifacts `groups` hold, in the exact order the gallery draws them
* (group by group, each group's images and videos in recorded order): the
* neighbours the full-screen viewer pages through, so a swipe visits the same
* list the grid showed. Non-media artifacts open externally and are not part of
* it. Mirrors ArtifactViewer.kt pagedArtifacts.
*/
export function pagedArtifacts(groups) {
const viewable = [];
for (const group of groups ?? []) {
for (const artifact of group?.artifacts ?? []) {
const kind = artifactKind(artifact?.content_type, artifact?.name);
if (kind === ArtifactKind.Image || kind === ArtifactKind.Video) viewable.push(artifact);
}
}
return viewable;
}
/**
* Each gallery media artifact's url mapped to its position in `pagedArtifacts`,
* the same ordered list the viewer pages through. The grid's tiles resolve their
* viewer index here, so tile and viewer derive from one source and cannot drift.
* The first occurrence of a url wins. Mirrors ArtifactViewer.kt viewerIndexByUrl.
*/
export function viewerIndexByUrl(groups) {
const indices = new Map();
pagedArtifacts(groups).forEach((artifact, index) => {
if (!indices.has(artifact.url)) indices.set(artifact.url, index);
});
return indices;
}
/**
* The index paging from `current` by `delta` within a list of `count`, clamped
* at both ends so a page never wraps (and an empty list is index 0). The one
* paging rule the viewer's buttons share. Mirrors ArtifactViewer.kt pagedIndex.
*/
export function pagedIndex(current, delta, count) {
if (count <= 0) return 0;
return Math.min(Math.max(current + delta, 0), count - 1);
}
/** The viewer's position label, e.g. `2 of 5 · image/png`. Mirrors ArtifactViewer.kt. */
export function artifactViewerPositionLabel(index, count, contentType) {
const type = String(contentType ?? "").split(";")[0].trim() || "artifact";
return `${index + 1} of ${count} · ${type}`;
}
/**
* The html session export `step` recorded, matched to the visit's recorded
* artifacts by exact name, or null when the visit has no export to open. A visit
* that recorded no export, whose export name is blank, or whose file is missing
* from a truncated listing yields null. Mirrors SessionExport.kt sessionExportFile.
*/
export function sessionExportArtifact(step) {
const html = step?.session_export?.html;
if (typeof html !== "string" || html.trim() === "") return null;
return (step?.artifacts ?? []).find((artifact) => artifact?.name === html) ?? null;
}
/**
* The absolute url a gallery artifact can be opened at, or null when it cannot
* be resolved against the configured server (blank or invalid). The one place a
* gallery artifact url is resolved, so tiles and the viewer never disagree.
* Re-exported here so callers derive tiles from this module alone.
*/
export function resolvedArtifactUrl(artifact, configuredServerUrl) {
return resolveArtifactUrl(configuredServerUrl, artifact?.url);
}