@dailephd/my-dev-kit-lab 0.9.2 → 0.9.4

package/dist/src/gallery/galleryPathSafety.js

@@ -0,0 +1,111 @@
+import { open, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+// Fail-closed path and media validation for gallery source artifacts. Source artifacts are untrusted
+// filesystem inputs: a reference is accepted only when it is a safe run-root-relative POSIX path whose
+// physically resolved target is an ordinary supported file inside the verified source root.
+const SCHEME_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+// eslint-disable-next-line no-control-regex
+const CONTROL_PATTERN = /[\u0000-\u001f\u007f]/;
+export const GALLERY_MEDIA_EXTENSIONS = {
+    video: [".webm"],
+    screenshot: [".png", ".jpg", ".jpeg", ".webp"],
+    markdown: [".md"],
+    text: [".txt", ".srt", ".vtt", ".html"],
+    json: [".json"]
+};
+/** True only for a non-empty relative POSIX path with no traversal, drive, UNC, scheme, NUL or encoding tricks. */
+export function isSafeRelativeArtifactPath(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 1024)
+        return false;
+    if (CONTROL_PATTERN.test(value) || value.includes("\\") || value.includes("%"))
+        return false;
+    if (value.startsWith("/") || SCHEME_PATTERN.test(value))
+        return false;
+    return value.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+/**
+ * Validates a link value for the gallery HTML. A gallery link is output-relative, so a leading "../" run is
+ * legitimate (the artifact lives in a verified source root outside the gallery directory); any other
+ * traversal, absolute form, scheme or malformed segment is rejected. Returns the percent-encoded href or null.
+ */
+export function safeGalleryHref(value, allowedExtensions) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 2048)
+        return null;
+    if (CONTROL_PATTERN.test(value) || value.includes("\\") || value.includes("%"))
+        return null;
+    if (value.startsWith("/") || SCHEME_PATTERN.test(value))
+        return null;
+    const segments = value.split("/");
+    let index = 0;
+    while (segments[index] === "..")
+        index += 1;
+    const rest = segments.slice(index);
+    if (rest.length === 0 || rest.some((segment) => segment === "" || segment === "." || segment === ".."))
+        return null;
+    if (allowedExtensions) {
+        const ext = path.posix.extname(rest[rest.length - 1]).toLowerCase();
+        if (!allowedExtensions.includes(ext))
+            return null;
+    }
+    return [...segments.slice(0, index), ...rest.map((segment) => encodeURIComponent(segment))].join("/");
+}
+function within(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+async function sniff(file, kind, ext) {
+    if (kind === "markdown" || kind === "text" || kind === "json")
+        return true;
+    const handle = await open(file, "r");
+    try {
+        const buffer = Buffer.alloc(12);
+        const { bytesRead } = await handle.read(buffer, 0, 12, 0);
+        if (bytesRead < 4)
+            return false;
+        if (kind === "video")
+            return buffer[0] === 0x1a && buffer[1] === 0x45 && buffer[2] === 0xdf && buffer[3] === 0xa3;
+        if (ext === ".png")
+            return buffer.subarray(0, 4).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+        if (ext === ".jpg" || ext === ".jpeg")
+            return buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff;
+        if (ext === ".webp")
+            return bytesRead >= 12 && buffer.toString("latin1", 0, 4) === "RIFF" && buffer.toString("latin1", 8, 12) === "WEBP";
+        return false;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Resolves and verifies one run-root-relative artifact reference. Never throws; failure carries a reason. */
+export async function verifyArtifactFile(realRoot, reference, kind) {
+    if (!isSafeRelativeArtifactPath(reference))
+        return { ok: false, reason: "the recorded path is not a safe run-root-relative path" };
+    const ext = path.posix.extname(reference).toLowerCase();
+    if (!GALLERY_MEDIA_EXTENSIONS[kind].includes(ext))
+        return { ok: false, reason: `the file type ${ext || "(none)"} is not supported for ${kind}` };
+    try {
+        const real = await realpath(path.resolve(realRoot, ...reference.split("/")));
+        if (!within(realRoot, real))
+            return { ok: false, reason: "the file resolves outside the source root" };
+        const info = await stat(real);
+        if (!info.isFile())
+            return { ok: false, reason: "the path is not an ordinary file" };
+        if (!(await sniff(real, kind, ext)))
+            return { ok: false, reason: `the file content is not a valid ${ext.slice(1)} ${kind}` };
+        return { ok: true, absolutePath: real };
+    }
+    catch {
+        return { ok: false, reason: "the file is missing or unreadable" };
+    }
+}
+/** Output-relative POSIX link text for a verified file, or null when no relative path exists (for example another drive). */
+export function outputRelativePath(realOutDir, absoluteFile) {
+    const relative = path.relative(realOutDir, absoluteFile);
+    if (relative === "" || path.isAbsolute(relative))
+        return null;
+    return relative.split(path.sep).join("/");
+}
+/** Explicit user-supplied source text must be a local filesystem path, never a URL. */
+export function looksLikeUrl(value) {
+    return /^[a-zA-Z][a-zA-Z0-9+.-]+:/.test(value) && !/^[a-zA-Z]:[\/]/.test(value);
+}

package/dist/src/gallery/readGallerySources.js

@@ -0,0 +1,542 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { TUTORIAL_MANIFEST_SCHEMA_VERSION } from "../tutorial/tutorialManifest.js";
+import { looksLikeUrl, outputRelativePath, verifyArtifactFile } from "./galleryPathSafety.js";
+// Trusted, read-only artifact-family readers for `gallery build --source`. Each reader recognizes a family
+// from an existing producer schema/signature, reads only the bounded metadata needed to identify and display
+// it, and never executes artifact content. Gallery items only ever carry statuses the producer recorded.
+const MAX_JSON_BYTES = 8 * 1024 * 1024;
+const TUTORIAL_MANIFEST_RELATIVE = "artifacts/tutorial-manifest.json";
+const SUPPORTED_AUDIT_SCHEMA = "1.0";
+const SUPPORTED_SECURITY_SCHEMA = 1;
+const PROMPT_COMPARISON_SCHEMA = "prompt-template-comparison/1.0.0";
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function str(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function bounded(value, limit = 300) {
+    return value.length > limit ? `${value.slice(0, limit)}...` : value;
+}
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "item";
+}
+function itemId(family, identity, file) {
+    return `${family}-${slug(identity)}-${createHash("sha256").update(file).digest("hex").slice(0, 8)}`;
+}
+async function readJson(file, label) {
+    let size;
+    try {
+        size = (await stat(file)).size;
+    }
+    catch (error) {
+        throw new Error(`Gallery source ${label}: cannot read ${path.basename(file)} (${error instanceof Error ? error.message : String(error)}).`);
+    }
+    if (size > MAX_JSON_BYTES)
+        throw new Error(`Gallery source ${label}: ${path.basename(file)} exceeds the ${MAX_JSON_BYTES}-byte limit.`);
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        throw new Error(`Gallery source ${label}: ${path.basename(file)} is not valid JSON.`);
+    }
+    if (!isObject(parsed))
+        throw new Error(`Gallery source ${label}: ${path.basename(file)} is not a JSON object.`);
+    return parsed;
+}
+/** Signature tests against existing producer schemas. More than one match is an ambiguity error. */
+function matchingFamilies(data) {
+    const matches = [];
+    const plugin = data.plugin;
+    const metadata = data.metadata;
+    if (isObject(data.scenario) && isObject(data.run) && Array.isArray(data.steps) && Array.isArray(data.artifacts)) {
+        matches.push("tutorial-run");
+    }
+    if (isObject(plugin) && str(plugin.id) !== null && isObject(metadata) && str(metadata.runId) !== null && Array.isArray(data.variants)) {
+        const warm = isObject(data.warmIndexReuse) && isObject(data.warmIndexReuse.agentCampaign);
+        matches.push(warm ? "warm-index-campaign" : "plugin-experiment-report");
+    }
+    if (isObject(metadata) && metadata.reportType === "code-rot-audit" && str(data.schemaVersion) !== null)
+        matches.push("audit-report");
+    if (Array.isArray(data.checks) && Array.isArray(data.findings) && isObject(data.summary) && str(data.verdict) !== null) {
+        matches.push("security-validation-report");
+    }
+    if (str(data.executiveSummary) !== null && isObject(data.androidProjectSummary) && str(data.verdict) !== null) {
+        matches.push("android-validation-report");
+    }
+    if (num(data.totalRuns) !== null && num(data.completedRuns) !== null && Array.isArray(data.strategies))
+        matches.push("controlled-experiment");
+    if (typeof data.schemaVersion === "string" && data.schemaVersion.startsWith("prompt-template-comparison/"))
+        matches.push("prompt-template-comparison");
+    return matches;
+}
+function classify(data, label, file) {
+    const matches = matchingFamilies(data);
+    if (matches.length > 1) {
+        throw new Error(`Gallery source ${label}: ${path.basename(file)} matches more than one artifact family (${matches.join(", ")}); refusing ambiguous recognition.`);
+    }
+    return matches[0] ?? null;
+}
+const KNOWN_NAME = /(^code-rot-audit\.json$|^experiment-summary\.json$|-android-security-validation\.json$|-security-validation\.json$|^report\.json$|^tutorial-manifest\.json$|^prompt-template-comparison\.json$)/;
+async function collect(sourceArg) {
+    const label = sourceArg;
+    let real;
+    try {
+        real = await realpath(sourceArg);
+    }
+    catch {
+        throw new Error(`Gallery source ${label} does not exist or is unreadable.`);
+    }
+    const info = await stat(real);
+    const found = [];
+    const addFile = async (file, root, explicit) => {
+        const data = await readJson(file, label);
+        // The canonical tutorial manifest is recognized by its fixed name so a malformed one gets a specific error.
+        const family = path.basename(file) === "tutorial-manifest.json" ? "tutorial-run" : classify(data, label, file);
+        if (family === null) {
+            // A generic report.json that is not a plugin report is simply not ours; a named family file must match.
+            if (!explicit && path.basename(file) === "report.json")
+                return;
+            throw new Error(`Gallery source ${label}: ${path.basename(file)} is not a recognized or valid artifact family document.`);
+        }
+        found.push({ family, file, root, data });
+    };
+    if (info.isFile()) {
+        const name = path.basename(real);
+        if (!KNOWN_NAME.test(name))
+            throw new Error(`Gallery source ${label}: unsupported source type (${name}).`);
+        let root = path.dirname(real);
+        if (name === "tutorial-manifest.json") {
+            if (path.basename(root) !== "artifacts") {
+                throw new Error(`Gallery source ${label}: a tutorial manifest must be <run-root>/artifacts/tutorial-manifest.json.`);
+            }
+            root = path.dirname(root);
+        }
+        await addFile(real, root, true);
+        return found;
+    }
+    if (!info.isDirectory())
+        throw new Error(`Gallery source ${label} is neither a file nor a directory.`);
+    const tutorialManifest = path.join(real, ...TUTORIAL_MANIFEST_RELATIVE.split("/"));
+    let hasTutorial = false;
+    try {
+        hasTutorial = (await stat(tutorialManifest)).isFile();
+    }
+    catch {
+        hasTutorial = false;
+    }
+    if (hasTutorial)
+        await addFile(tutorialManifest, real, true);
+    const names = (await readdir(real)).filter((name) => name !== "tutorial-manifest.json" && KNOWN_NAME.test(name)).sort();
+    for (const name of names) {
+        const file = path.join(real, name);
+        if ((await stat(file)).isFile())
+            await addFile(file, real, false);
+    }
+    if (found.length === 0) {
+        throw new Error(`Gallery source ${label}: no supported artifact family was recognized at this root.`);
+    }
+    return found;
+}
+async function linkIfPresent(root, realOutDir, name, kind) {
+    const verified = await verifyArtifactFile(root, name, kind);
+    return verified.ok ? outputRelativePath(realOutDir, verified.absolutePath) : null;
+}
+async function readPluginFamily(found, realOutDir) {
+    const json = outputRelativePath(realOutDir, found.file);
+    if (json === null)
+        throw new Error("Gallery source report has no relative link from the gallery directory.");
+    const html = await linkIfPresent(found.root, realOutDir, "report.html", "text");
+    const text = await linkIfPresent(found.root, realOutDir, "report.txt", "text");
+    const execution = await linkIfPresent(found.root, realOutDir, "warm-index-execution.json", "json");
+    const plugin = found.data.plugin;
+    const metadata = found.data.metadata;
+    const target = isObject(found.data.target) ? found.data.target : {};
+    const runStatus = str(metadata.status) ?? "unknown";
+    const status = runStatus === "completed" ? "pass" : runStatus === "skipped" ? "skipped" : "warning";
+    const warnings = [];
+    if (status === "warning")
+        warnings.push(`Experiment run status is ${runStatus}.`);
+    if (html === null)
+        warnings.push("HTML report unavailable: report.html was not found at the source root.");
+    const metrics = [{ id: "run-status", label: "Run status", value: runStatus }];
+    if (Array.isArray(found.data.metrics))
+        metrics.push({ id: "metric-count", label: "Metric count", value: found.data.metrics.length });
+    const campaign = found.family === "warm-index-campaign";
+    const tags = [campaign ? "warm-index-campaign" : "experiment-report"];
+    if (target.privacyProjection === "external-local-redacted")
+        tags.push("external-local-redacted");
+    const artifactPaths = [text, execution].filter((value) => value !== null);
+    return {
+        id: itemId(found.family, str(metadata.runId), found.file),
+        title: `${str(plugin.name) ?? str(plugin.id)} report`,
+        description: `Plugin experiment report for run ${str(metadata.runId)} (plugin ${str(plugin.id)}).`,
+        kind: campaign ? "warm-index-campaign-report" : "plugin-experiment-report",
+        status,
+        htmlPath: html ?? "",
+        summaryPath: json,
+        ...(artifactPaths.length > 0 ? { artifactPaths } : {}),
+        sourceFamily: found.family,
+        sourceId: `${str(plugin.id)}/${str(metadata.runId)}`,
+        tags,
+        metrics,
+        warnings
+    };
+}
+function simpleItem(found, realOutDir, fields) {
+    const summary = outputRelativePath(realOutDir, found.file);
+    if (summary === null)
+        throw new Error(`Gallery source ${path.basename(found.file)} has no relative link from the gallery directory.`);
+    const { identity, ...rest } = fields;
+    return { ...rest, id: itemId(found.family, identity, found.file), htmlPath: "", summaryPath: summary, sourceFamily: found.family, sourceId: identity };
+}
+function readAudit(found, realOutDir) {
+    const data = found.data;
+    if (data.schemaVersion !== SUPPORTED_AUDIT_SCHEMA) {
+        throw new Error(`Gallery source ${path.basename(found.file)}: unsupported audit report schemaVersion ${JSON.stringify(data.schemaVersion)}.`);
+    }
+    const exit = isObject(data.exit) ? data.exit : null;
+    const summary = isObject(data.summary) ? data.summary : {};
+    const metadata = data.metadata;
+    const breached = exit?.failOnBreached;
+    const warnings = [];
+    let status = "pass";
+    if (exit === null || typeof breached !== "boolean") {
+        status = "warning";
+        warnings.push("Audit exit status is not recorded in this report.");
+    }
+    else if (breached) {
+        status = "warning";
+        warnings.push("The audit fail-on threshold was breached.");
+    }
+    const metrics = [];
+    const total = num(summary.totalIssues);
+    if (total !== null)
+        metrics.push({ id: "total-issues", label: "Total issues", value: total });
+    const label = str(exit?.finalVerdictLabel);
+    if (label)
+        metrics.push({ id: "verdict", label: "Audit verdict", value: label });
+    const types = Array.isArray(metadata.auditTypes) ? metadata.auditTypes.filter((t) => typeof t === "string").join(", ") : "audit";
+    return simpleItem(found, realOutDir, {
+        identity: `code-rot-audit/${str(metadata.generatedAt) ?? "unknown"}`,
+        title: "Code-rot audit report",
+        description: `Standalone audit report (${types}).`,
+        kind: "audit-report",
+        status,
+        tags: ["audit"],
+        metrics,
+        warnings
+    });
+}
+function verdictStatus(verdict) {
+    return verdict === "ready-for-release-preparation" ? "pass" : "warning";
+}
+function readSecurity(found, realOutDir) {
+    const data = found.data;
+    if (data.schemaVersion !== SUPPORTED_SECURITY_SCHEMA) {
+        throw new Error(`Gallery source ${path.basename(found.file)}: unsupported security report schemaVersion ${JSON.stringify(data.schemaVersion)}.`);
+    }
+    const verdict = str(data.verdict);
+    const summary = data.summary;
+    const metadata = isObject(data.metadata) ? data.metadata : {};
+    const metrics = [{ id: "verdict", label: "Verdict", value: verdict }];
+    for (const [id, label] of [["totalChecks", "Total checks"], ["failed", "Failed checks"], ["totalFindings", "Total findings"], ["blockerFindings", "Blocker findings"]]) {
+        const value = num(summary[id]);
+        if (value !== null)
+            metrics.push({ id, label, value });
+    }
+    const status = verdictStatus(verdict);
+    return simpleItem(found, realOutDir, {
+        identity: `${path.basename(found.file, ".json")}/${str(metadata.generatedAt) ?? "unknown"}`,
+        title: "Security validation report",
+        description: "Standalone security-validation report.",
+        kind: "security-validation-report",
+        status,
+        tags: ["security"],
+        metrics,
+        warnings: status === "pass" ? [] : [`Security verdict is ${verdict}.`]
+    });
+}
+function readAndroid(found, realOutDir) {
+    const data = found.data;
+    const verdict = str(data.verdict);
+    const status = verdictStatus(verdict);
+    const metadata = isObject(data.metadata) ? data.metadata : {};
+    return simpleItem(found, realOutDir, {
+        identity: `${path.basename(found.file, ".json")}/${str(metadata.generatedAt) ?? "unknown"}`,
+        title: "Android validation report",
+        description: "Static Android/mobile validation report.",
+        kind: "android-validation-report",
+        status,
+        tags: ["android", "security"],
+        metrics: [{ id: "verdict", label: "Verdict", value: verdict }],
+        warnings: status === "pass" ? [] : [`Android verdict is ${verdict}.`]
+    });
+}
+function readExperiment(found, realOutDir) {
+    const data = found.data;
+    const completed = num(data.completedRuns);
+    const total = num(data.totalRuns);
+    const problem = ["failedRuns", "skippedRuns", "unavailableRuns", "limitReachedRuns", "timeoutRuns", "invalidOutputRuns"].reduce((sum, key) => sum + (num(data[key]) ?? 0), 0);
+    const status = completed === 0 ? "skipped" : problem > 0 ? "warning" : "pass";
+    return simpleItem(found, realOutDir, {
+        identity: `experiment/${str(data.generatedAt) ?? "unknown"}`,
+        title: "Controlled experiment summary",
+        description: "Controlled experiment summary read from experiment-summary.json.",
+        kind: "controlled-experiment",
+        status,
+        tags: ["experiment"],
+        metrics: [
+            { id: "total-runs", label: "Total runs", value: total },
+            { id: "completed-runs", label: "Completed runs", value: completed }
+        ],
+        warnings: status === "pass" ? [] : [`${completed} of ${total} controlled runs completed.`]
+    });
+}
+// ---------------------------------------------------------------------------
+// Prompt-template comparison (v0.9.3)
+// ---------------------------------------------------------------------------
+async function readPromptComparison(found, realOutDir) {
+    const data = found.data;
+    const name = path.basename(found.file);
+    if (data.schemaVersion !== PROMPT_COMPARISON_SCHEMA) {
+        throw new Error(`Gallery source ${name}: unsupported prompt comparison schemaVersion ${JSON.stringify(data.schemaVersion)}.`);
+    }
+    const comparison = data.comparison;
+    const baseline = data.baseline;
+    const candidate = data.candidate;
+    const cohort = data.cohort;
+    const invalid = data.invalidOutput;
+    const improvement = data.behavioralImprovement;
+    const bad = (what) => {
+        throw new Error(`Gallery source ${name}: malformed prompt comparison (${what}).`);
+    };
+    if (!isObject(comparison) || (comparison.status !== "COMPARABLE" && comparison.status !== "INCOMPARABLE"))
+        bad("comparison");
+    if (!isObject(baseline) || !isObject(candidate))
+        bad("baseline/candidate");
+    if (!isObject(cohort) || num(cohort.matchedUnitCount) === null)
+        bad("cohort");
+    if (!isObject(invalid) || !Array.isArray(invalid.strata))
+        bad("invalidOutput");
+    if (!isObject(improvement) || (improvement.status !== "VERIFIED" && improvement.status !== "NOT_VERIFIED"))
+        bad("behavioralImprovement");
+    const comparisonObj = comparison;
+    const improvementObj = improvement;
+    const status = comparisonObj.status;
+    const base = baseline;
+    const cand = candidate;
+    const coh = cohort;
+    const overall = isObject(invalid.overall) ? invalid.overall : null;
+    const metrics = [
+        { id: "comparison-status", label: "Comparison status", value: status },
+        { id: "baseline-template", label: "Baseline template", value: str(base.templateId) ?? "unverified" },
+        { id: "candidate-template", label: "Candidate template", value: str(cand.templateId) ?? "unverified" },
+        { id: "matched-units", label: "Matched units", value: num(coh.matchedUnitCount) },
+        { id: "eligible-units", label: "Eligible matched units", value: num(coh.eligibleMatchedUnitCount) ?? 0 },
+        { id: "behavioral-improvement", label: "Behavioral improvement", value: String(improvement.status) }
+    ];
+    const rateOf = (side) => (isObject(side) ? num(side.ratePercent) : null);
+    if (overall) {
+        const b = rateOf(overall.baseline);
+        const c = rateOf(overall.candidate);
+        if (b !== null)
+            metrics.push({ id: "baseline-invalid-output-rate", label: "Baseline invalid-output rate", value: Number(b.toFixed(2)), unit: "%" });
+        if (c !== null)
+            metrics.push({ id: "candidate-invalid-output-rate", label: "Candidate invalid-output rate", value: Number(c.toFixed(2)), unit: "%" });
+        const diff = num(overall.percentagePointDifference);
+        if (diff !== null)
+            metrics.push({ id: "invalid-output-difference", label: "Invalid-output difference (baseline minus candidate)", value: Number(diff.toFixed(2)), unit: "pp" });
+    }
+    const warnings = [];
+    if (status === "INCOMPARABLE") {
+        const reasons = Array.isArray(comparisonObj.incomparabilityReasons) ? comparisonObj.incomparabilityReasons.filter((r) => typeof r === "string") : [];
+        for (const reason of reasons.slice(0, 5))
+            warnings.push(`Incomparable: ${bounded(reason)}`);
+        if (reasons.length === 0)
+            warnings.push("Incomparable: no reason recorded.");
+    }
+    if (improvementObj.status !== "VERIFIED")
+        warnings.push(`Behavioral improvement is ${String(improvementObj.status)}: ${bounded(str(improvementObj.reason) ?? "no reason recorded")}`);
+    if (Array.isArray(data.limitations)) {
+        for (const limitation of data.limitations.filter((l) => typeof l === "string").slice(0, 3))
+            warnings.push(`Limitation: ${bounded(limitation)}`);
+    }
+    const html = await linkIfPresent(found.root, realOutDir, "prompt-template-comparison.html", "text");
+    const text = await linkIfPresent(found.root, realOutDir, "prompt-template-comparison.txt", "text");
+    if (html === null)
+        warnings.push("HTML comparison report unavailable: prompt-template-comparison.html was not found.");
+    const json = outputRelativePath(realOutDir, found.file);
+    if (json === null)
+        throw new Error(`Gallery source ${name} has no relative link from the gallery directory.`);
+    const identity = `${str(base.runId) ?? "baseline"}-vs-${str(cand.runId) ?? "candidate"}`;
+    return {
+        id: itemId("prompt-template-comparison", identity, found.file),
+        title: "Prompt template comparison",
+        description: `Baseline ${str(base.templateId) ?? "unverified"} versus candidate ${str(cand.templateId) ?? "unverified"} (${status}).`,
+        kind: "prompt-template-comparison",
+        status: status === "COMPARABLE" ? "pass" : "warning",
+        htmlPath: html ?? "",
+        summaryPath: json,
+        ...(text ? { artifactPaths: [text] } : {}),
+        sourceFamily: "prompt-template-comparison",
+        sourceId: identity,
+        tags: ["prompt-comparison"],
+        metrics,
+        warnings
+    };
+}
+// ---------------------------------------------------------------------------
+// Tutorial runs
+// ---------------------------------------------------------------------------
+function validateTutorialManifest(data, label) {
+    if (data.schemaVersion !== TUTORIAL_MANIFEST_SCHEMA_VERSION) {
+        throw new Error(`Gallery source ${label}: unsupported tutorial manifest schemaVersion ${JSON.stringify(data.schemaVersion)}.`);
+    }
+    const bad = (what) => {
+        throw new Error(`Gallery source ${label}: malformed tutorial manifest (${what}).`);
+    };
+    const scenario = data.scenario;
+    const run = data.run;
+    if (!isObject(scenario) || !str(scenario.id) || !str(scenario.title))
+        bad("scenario");
+    if (!isObject(run) || !str(run.id) || !str(run.status) || !str(run.startedAt) || !str(run.endedAt))
+        bad("run");
+    if (!Array.isArray(data.steps))
+        bad("steps");
+    if (!Array.isArray(data.artifacts))
+        bad("artifacts");
+    for (const key of ["warnings", "cleanupErrors"]) {
+        const value = data[key];
+        if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string"))
+            bad(key);
+    }
+    return data;
+}
+async function readTutorial(found, realOutDir) {
+    const manifest = validateTutorialManifest(found.data, path.basename(found.root));
+    const warnings = [
+        ...manifest.warnings.map((warning) => bounded(warning)),
+        ...manifest.cleanupErrors.map((error) => `Cleanup error: ${bounded(error)}`)
+    ];
+    const records = manifest.artifacts.filter(isObject);
+    const resolveKind = async (kind, media, human) => {
+        const matching = records.filter((record) => record.kind === kind);
+        if (matching.length === 0) {
+            warnings.push(`${human} unavailable: not recorded in the tutorial manifest.`);
+            return [];
+        }
+        const links = [];
+        for (const record of matching) {
+            if (record.status !== "written") {
+                warnings.push(`${human} unavailable: artifact status is ${record.status ?? "unknown"}${record.error ? ` (${bounded(record.error)})` : ""}.`);
+                if (record.status === "failed")
+                    degraded = true;
+                continue;
+            }
+            const verified = await verifyArtifactFile(found.root, record.path, media);
+            if (!verified.ok) {
+                warnings.push(`${human} unavailable: ${verified.reason}.`);
+                degraded = true;
+                continue;
+            }
+            const link = outputRelativePath(realOutDir, verified.absolutePath);
+            if (link === null) {
+                warnings.push(`${human} unavailable: no relative link exists from the gallery directory.`);
+                degraded = true;
+            }
+            else
+                links.push(link);
+        }
+        return links;
+    };
+    let degraded = false;
+    const videos = await resolveKind("video", "video", "Video");
+    const screenshots = await resolveKind("screenshot", "screenshot", "Screenshot");
+    const markdown = await resolveKind("markdown", "markdown", "Markdown");
+    const subtitles = [...(await resolveKind("srt", "text", "SRT subtitles")), ...(await resolveKind("vtt", "text", "VTT subtitles"))];
+    const runStatus = manifest.run.status;
+    // Media the manifest truthfully records as absent does not downgrade a passed run; a recorded artifact that
+    // failed or cannot be verified does.
+    const status = runStatus === "passed" && !degraded && manifest.cleanupErrors.length === 0 ? "pass" : "warning";
+    if (runStatus !== "passed")
+        warnings.unshift(`Tutorial run status is ${runStatus}; the run did not pass.`);
+    const summary = outputRelativePath(realOutDir, found.file);
+    const duration = num(manifest.run.durationMs);
+    return {
+        id: itemId("tutorial-run", `${manifest.scenario.id}-${manifest.run.id}`, found.file),
+        title: manifest.scenario.title,
+        description: manifest.scenario.description ?? `Tutorial run ${manifest.run.id}.`,
+        kind: "tutorial-run",
+        status,
+        htmlPath: "",
+        ...(summary === null ? {} : { summaryPath: summary }),
+        ...(screenshots[0] ? { screenshotPath: screenshots[0] } : {}),
+        artifactPaths: subtitles,
+        sourceFamily: "tutorial-run",
+        sourceId: `${manifest.scenario.id}/${manifest.run.id}`,
+        ...(videos[0] ? { videoPath: videos[0] } : {}),
+        ...(markdown[0] ? { markdownPath: markdown[0] } : {}),
+        ...(screenshots.length > 0 ? { screenshotPaths: screenshots } : {}),
+        tags: ["tutorial"],
+        metrics: [
+            { id: "run-status", label: "Run status", value: runStatus },
+            { id: "step-count", label: "Step count", value: manifest.steps.length },
+            ...(duration !== null ? [{ id: "duration-ms", label: "Duration", value: duration, unit: "ms" }] : [])
+        ],
+        warnings
+    };
+}
+// ---------------------------------------------------------------------------
+/**
+ * Reads every explicitly supplied source, in the supplied order. Repeated sources and repeated artifacts
+ * (same physical file and family) produce one item. Any unreadable, malformed, unsupported or ambiguous
+ * source fails the whole build; no placeholder success item is ever produced.
+ */
+export async function readGallerySources(options) {
+    const items = [];
+    const seen = new Set();
+    for (const source of options.sources) {
+        if (source.trim() === "")
+            throw new Error("Gallery source path must not be empty.");
+        if (looksLikeUrl(source))
+            throw new Error(`Gallery source ${source}: URLs are not supported; supply a local path.`);
+        for (const entry of await collect(source)) {
+            const key = `${entry.family}|${await realpath(entry.file)}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            switch (entry.family) {
+                case "tutorial-run":
+                    items.push(await readTutorial(entry, options.realOutDir));
+                    break;
+                case "plugin-experiment-report":
+                case "warm-index-campaign":
+                    items.push(await readPluginFamily(entry, options.realOutDir));
+                    break;
+                case "audit-report":
+                    items.push(readAudit(entry, options.realOutDir));
+                    break;
+                case "security-validation-report":
+                    items.push(readSecurity(entry, options.realOutDir));
+                    break;
+                case "android-validation-report":
+                    items.push(readAndroid(entry, options.realOutDir));
+                    break;
+                case "controlled-experiment":
+                    items.push(readExperiment(entry, options.realOutDir));
+                    break;
+                case "prompt-template-comparison":
+                    items.push(await readPromptComparison(entry, options.realOutDir));
+                    break;
+            }
+        }
+    }
+    return { items };
+}