testdossier 0.2.3 → 0.3.1

package/README.md

@@ -8,7 +8,7 @@ Upload a completed test report from a developer laptop, test machine, or CI
 job. Run these commands in the project containing your automated tests:
 
 1. Install the latest CLI in the project. To pin a release instead, replace
-   `@latest` with an exact version such as `@0.2.3`:
+   `@latest` with an exact version such as `@0.3.0`:
 
 ```bash
 npm install --save-dev testdossier@latest
@@ -70,9 +70,11 @@ requires Node.js 18 or newer.
 
 ## Why this is intentionally small
 
-The uploader does one thing: read a completed report and make an outbound HTTPS
-request to TestDossier. It does not run tests, accept remote commands, install a
-background service, watch files, or keep a process running.
+The upload path does one thing: read a completed report and make an outbound
+HTTPS request to TestDossier. It does not run tests, accept remote commands,
+install a background service, watch files, or keep a process running. The
+optional `setup cypress` command performs one fixed local write using the
+template already present in the installed package.
 
 The access token is read from the first available source: an explicitly passed
 `--env-file`, the `TD_CI_TOKEN` process environment, then `.env.testdossier` in
@@ -93,6 +95,74 @@ Before sending anything, inspect what the CLI detected:
 npx testdossier upload playwright-results.json --dry-run
 ```
 
+### Optional source context
+
+Source snippets are opt-in. Add this to the committed `testdossier.json` when
+the checked-out CI workspace may be read for evidence:
+
+```json
+{
+  "report": "playwright-results.json",
+  "source": {
+    "enabled": true,
+    "root": ".",
+    "before": 20,
+    "after": 80
+  }
+}
+```
+
+Only files identified by uploaded test records are considered. Paths must stay
+inside the real, non-symlink source root; binary, invalid UTF-8, symlinked,
+missing, and files over 2 MiB are skipped. Each persisted snippet is limited to
+240 lines and 16 KiB, common credential literals are masked, and the digest is
+computed after masking. Source is evidence only: the CLI never executes,
+formats, or infers test steps from it. `--dry-run` prints counts, safe relative
+paths, ranges, hashes, truncation, and redaction counts—never source contents.
+
+If a Playwright report records files relative to `testDir`, set `source.root`
+to that directory (for example `"tests/e2e"`). An unchanged CI snippet keeps
+its provenance; a new digest becomes a Review queue proposal and never silently
+overwrites an approved case or an older run snapshot.
+
+## Automatic source context (opt in once)
+
+The uploader can attach the repository source around each test declaration as
+read-only execution evidence. Enable it in the committed `testdossier.json`:
+
+```json
+{
+  "report": "playwright-results.json",
+  "source": {
+    "enabled": true,
+    "root": ".",
+    "before": 20,
+    "after": 80
+  }
+}
+```
+
+After that one-time opt-in, the same `npx testdossier` command captures source
+locally, in GitHub Actions, and in GitLab CI. No TestDossier ID is required in
+each `test()` or `it()` block: existing ID, alias, and report-signature matching
+still apply. An explicit TestDossier ID, when present, remains the strongest
+identity signal; disagreement with the report signature is quarantined for a
+reviewer instead of being attached silently.
+
+Capture is framework-neutral and best effort. It uses the source file and line
+reported by Playwright, Cypress, Cucumber, or JUnit-compatible runners. Files
+must resolve inside `source.root`; symlinks, binary files, files over 2 MiB, and
+paths outside that root are skipped. Each persisted snippet is bounded, common
+credential literals are redacted, and the CLI prints every captured path and
+digest during `--dry-run` so the upload can be inspected before it is sent.
+
+The Editor holds the current, editable source reference. Every Test Run keeps
+the source uploaded for that execution as an immutable snapshot. When a later
+upload changes a source digest, Review queue shows the incoming version for
+comparison; accepting it updates the Editor reference without rewriting the
+completed run. Editing in TestDossier never changes the repository or what CI
+executes.
+
 ## Supported reports
 
 | Runner or format | Example |
@@ -108,6 +178,43 @@ creates an ambiguous shape, pass `--format playwright`, `--format cypress`,
 `--format cucumber`, `--format junit`, or `--format generic`. The `upload`
 word may be omitted: `npx testdossier playwright-results.json` works too.
 
+For Playwright, configure `screenshot: 'only-on-failure'`. During upload the
+CLI reads one screenshot from each test whose final attempt failed and sends it
+through TestDossier's durable image path. Screenshots from passing tests and
+earlier retries are omitted, while video/trace files remain link-first. Every
+CI run stays immutable; identical images are hash-deduplicated in storage.
+
+### Generate the Cypress helper from the installed package
+
+Cypress's normal command does not write its complete Module API result to a
+file, and local screenshot paths are not enough once the runner disappears.
+After installing TestDossier in the client repository, generate the helper
+from that installed, lockfile-pinned version:
+
+```bash
+npx testdossier setup cypress
+```
+
+The command creates only `scripts/dossier-cypress.mjs`, prints its SHA-256
+digest, and never downloads code or contacts TestDossier. It is safe to run
+again when the file still matches. If the file has been edited or came from a
+different template, setup stops and leaves it untouched—there is deliberately
+no force-overwrite option.
+
+Review the generated file before committing it, then add a project script:
+
+```json
+{
+  "scripts": {
+    "cy:testdossier": "node scripts/dossier-cypress.mjs --output cypress-results.json"
+  }
+}
+```
+
+Run `npm run cy:testdossier`, then upload `cypress-results.json`. The helper
+uses the client project's own Cypress dependency; TestDossier does not bundle
+or silently install Cypress.
+
 ## Local setup
 
 For repeat use, install and pin the CLI in the test repository so its source
@@ -118,7 +225,7 @@ npm install --save-dev testdossier@latest
 npx testdossier init
 ```
 
-Use `npm install --save-dev testdossier@0.2.3` when the repository should pin
+Use `npm install --save-dev testdossier@0.3.0` when the repository should pin
 that exact release. In either case, subsequent commands remain
 `npx testdossier ...`; the version selector belongs only to installation.
 

package/assets/mark.svg

@@ -1,5 +1,5 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="TestDossier">
   <title>TestDossier</title>
-  <path fill="#006b61" fill-rule="evenodd" d="M20 6h14c17 0 28 10 28 26S51 58 34 58H20V6Zm14 14v24c9 0 14-4 14-12s-5-12-14-12Z"/>
-  <path fill="#006b61" d="M2 6h32v10H2z"/>
+  <path fill="#4335de" fill-rule="evenodd" d="M20 6h14c17 0 28 10 28 26S51 58 34 58H20V6Zm14 14v24c9 0 14-4 14-12s-5-12-14-12Z"/>
+  <path fill="#4335de" d="M2 6h32v14H2z"/>
 </svg>

package/lib/source-context.mjs

@@ -0,0 +1,212 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import { dirname, extname, isAbsolute, relative, resolve, sep } from "node:path";
+
+export const SOURCE_ENVELOPE_VERSION = 1;
+export const MAX_SOURCE_CONTEXT_BYTES = 16 * 1024;
+export const MAX_SOURCE_CONTEXT_LINES = 240;
+const MAX_SOURCE_FILE_BYTES = 2 * 1024 * 1024;
+const LANGUAGE_BY_EXTENSION = new Map([
+  [".js", "javascript"], [".jsx", "jsx"], [".mjs", "javascript"], [".cjs", "javascript"],
+  [".ts", "typescript"], [".tsx", "tsx"], [".py", "python"], [".rb", "ruby"],
+  [".java", "java"], [".kt", "kotlin"], [".kts", "kotlin"], [".cs", "csharp"],
+  [".go", "go"], [".rs", "rust"], [".php", "php"], [".feature", "gherkin"],
+  [".xml", "xml"], [".json", "json"], [".yaml", "yaml"], [".yml", "yaml"],
+  [".sh", "shell"], [".bash", "shell"], [".zsh", "shell"],
+]);
+
+function object(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function parseSourceConfig(value) {
+  if (value === undefined) return null;
+  if (!object(value)) throw new Error('testdossier.json "source" must be an object.');
+  if (value.enabled !== true && value.enabled !== false) {
+    throw new Error('testdossier.json "source.enabled" must be true or false.');
+  }
+  if (!value.enabled) return null;
+  const root = value.root === undefined ? "." : value.root;
+  if (typeof root !== "string" || !root.trim() || isAbsolute(root) || root.split(/[\\/]/).includes("..")) {
+    throw new Error('testdossier.json "source.root" must be a relative path inside the project.');
+  }
+  const integer = (field, fallback, max) => {
+    const n = value[field];
+    if (n === undefined) return fallback;
+    if (!Number.isInteger(n) || n < 0 || n > max) throw new Error(`testdossier.json "source.${field}" must be an integer from 0 to ${max}.`);
+    return n;
+  };
+  return { enabled: true, root: root.trim(), before: integer("before", 20, 200), after: integer("after", 80, 200) };
+}
+
+export function redactSourceText(value) {
+  let content = String(value);
+  let redactions = 0;
+  const replace = (pattern, replacement) => {
+    content = content.replace(pattern, (...args) => {
+      redactions += 1;
+      return typeof replacement === "function" ? replacement(...args) : replacement;
+    });
+  };
+  replace(
+    /(\b(?:password|passwd|secret|api[_-]?key|access[_-]?token|auth(?:orization)?|cookie)\b\s*[:=]\s*)(?:(["'`])[^\r\n]*?\2|[^\s,;]+)/gi,
+    (_match, prefix, quote) => `${prefix}${quote || ""}[REDACTED]${quote || ""}`,
+  );
+  replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}\b/gi, "Bearer [REDACTED]");
+  replace(/\btd_[A-Za-z0-9_-]{8,}\b/g, "td_[REDACTED]");
+  replace(/(https?:\/\/)([^\s/@:]+):([^\s/@]+)@/gi, (_match, scheme) => `${scheme}[REDACTED]@`);
+  replace(/-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g,
+    "-----BEGIN PRIVATE KEY-----\n[REDACTED]\n-----END PRIVATE KEY-----");
+  return { content, redactions };
+}
+
+function utf8Bound(value, maxBytes) {
+  const bytes = Buffer.from(value, "utf8");
+  if (bytes.byteLength <= maxBytes) return { content: value, truncated: false };
+  let content = bytes.subarray(0, maxBytes).toString("utf8").replace(/\uFFFD$/, "");
+  return { content, truncated: true };
+}
+
+function sourceTargets(format, bodyText) {
+  if (format === "junit") {
+    const targets = [];
+    const open = /<testcase\b((?:[^>"']|"[^"]*"|'[^']*')*?)(?:\/?)>/gi;
+    let match;
+    while ((match = open.exec(bodyText))) {
+      const attr = (name) => {
+        const found = match[1].match(new RegExp(`\\b${name}\\s*=\\s*("[^"]*"|'[^']*')`, "i"));
+        return found ? found[1].slice(1, -1) : "";
+      };
+      targets.push({ path: attr("file"), line: Number(attr("line")) || undefined });
+    }
+    return targets;
+  }
+  let doc;
+  try { doc = JSON.parse(bodyText.replace(/^\uFEFF/, "")); } catch { return []; }
+  if (format === "generic") return (Array.isArray(doc?.tests) ? doc.tests : []).map((test) => ({
+    path: typeof test?.file === "string" ? test.file : "",
+    line: Number(test?.line ?? test?.location?.line) || undefined,
+  }));
+  if (format === "cypress") return (Array.isArray(doc?.runs) ? doc.runs : []).flatMap((run) => {
+    const path = run?.spec?.relative || run?.spec?.name || "";
+    return (Array.isArray(run?.tests) ? run.tests : []).map((test) => ({
+      path,
+      line: Number(test?.line ?? test?.location?.line) || undefined,
+    }));
+  });
+  if (format === "cucumber") return (Array.isArray(doc) ? doc : []).flatMap((feature) =>
+    (Array.isArray(feature?.elements) ? feature.elements : [])
+      .filter((element) => String(element?.type || "scenario").toLowerCase() === "scenario")
+      .map((element) => ({ path: feature?.uri || "", line: Number(element?.line) || undefined })));
+  const targets = [];
+  const visit = (suites) => {
+    for (const suite of Array.isArray(suites) ? suites : []) {
+      for (const spec of Array.isArray(suite?.specs) ? suite.specs : []) {
+        for (const test of Array.isArray(spec?.tests) ? spec.tests : []) {
+          targets.push({ path: spec.file || "", line: Number(spec.line) || undefined });
+        }
+      }
+      visit(suite?.suites);
+    }
+  };
+  visit(doc?.suites);
+  return targets;
+}
+
+function inside(root, candidate) {
+  const rel = relative(root, candidate);
+  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+
+async function hasSymlink(root, candidate) {
+  const rel = relative(root, candidate);
+  let cursor = root;
+  for (const part of rel.split(sep).filter(Boolean)) {
+    cursor = resolve(cursor, part);
+    if ((await lstat(cursor)).isSymbolicLink()) return true;
+  }
+  return false;
+}
+
+async function readOneSource(root, target, config, commit) {
+  if (!target.path || typeof target.path !== "string") return { reason: "report has no source path" };
+  const candidate = isAbsolute(target.path) ? resolve(target.path) : resolve(root, target.path);
+  if (!inside(root, candidate)) return { reason: "path is outside source root", path: target.path };
+  try {
+    if (await hasSymlink(root, candidate)) return { reason: "symlink paths are not captured", path: target.path };
+    const candidateReal = await realpath(candidate);
+    if (!inside(root, candidateReal)) return { reason: "resolved path is outside source root", path: target.path };
+    const info = await stat(candidateReal);
+    if (!info.isFile()) return { reason: "source path is not a file", path: target.path };
+    if (info.size <= 0 || info.size > MAX_SOURCE_FILE_BYTES) return { reason: "source file is empty or over 2 MiB", path: target.path };
+    const bytes = await readFile(candidateReal);
+    if (bytes.includes(0)) return { reason: "binary source is not captured", path: target.path };
+    const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes).replace(/\r\n?/g, "\n");
+    const allLines = decoded.split("\n");
+    const focus = Number.isInteger(target.line) && target.line > 0 ? Math.min(target.line, allLines.length) : undefined;
+    const start = focus ? Math.max(1, focus - config.before) : 1;
+    const requestedEnd = focus ? Math.min(allLines.length, focus + config.after) : Math.min(allLines.length, MAX_SOURCE_CONTEXT_LINES);
+    const end = Math.min(requestedEnd, start + MAX_SOURCE_CONTEXT_LINES - 1);
+    const selected = allLines.slice(start - 1, end).join("\n");
+    const redacted = redactSourceText(selected);
+    const bounded = utf8Bound(redacted.content, MAX_SOURCE_CONTEXT_BYTES);
+    const relativePath = relative(root, candidateReal).split(sep).join("/");
+    const context = {
+      schema_version: SOURCE_ENVELOPE_VERSION,
+      origin: "ci",
+      content: bounded.content,
+      language: LANGUAGE_BY_EXTENSION.get(extname(relativePath).toLowerCase()) || "text",
+      digest: `sha256:${createHash("sha256").update(bounded.content).digest("hex")}`,
+      path: relativePath,
+      start_line: start,
+      end_line: start + bounded.content.split("\n").length - 1,
+      ...(focus ? { focus_line: focus } : {}),
+      ...(commit ? { commit: String(commit).slice(0, 80) } : {}),
+      ...((bounded.truncated || end < requestedEnd || requestedEnd < allLines.length || start > 1) ? { truncated: true } : {}),
+      ...(redacted.redactions ? { redactions: redacted.redactions } : {}),
+    };
+    return { context };
+  } catch (error) {
+    return { reason: error?.code === "ENOENT" ? "source file was not found" : "source file could not be read", path: target.path };
+  }
+}
+
+export async function collectSourceContexts({ format, body, cwd, config, commit = "" }) {
+  if (!config) return { carriers: [], captured: [], skipped: [] };
+  const configuredRoot = resolve(cwd, config.root);
+  let root;
+  try {
+    if (!inside(resolve(cwd), configuredRoot)) throw new Error("outside");
+    if (await hasSymlink(resolve(cwd), configuredRoot)) throw new Error("symlink");
+    root = await realpath(configuredRoot);
+    if (!inside(await realpath(cwd), root)) throw new Error("outside");
+  } catch {
+    throw new Error('testdossier.json "source.root" must resolve to a real, non-symlink directory inside the project.');
+  }
+  const targets = sourceTargets(format, Buffer.from(body).toString("utf8"));
+  const carriers = [];
+  const captured = [];
+  const skipped = [];
+  for (let testIndex = 0; testIndex < targets.length; testIndex += 1) {
+    const found = await readOneSource(root, targets[testIndex], config, commit);
+    if (found.context) {
+      carriers.push({ test_index: testIndex, ...found.context });
+      captured.push(found.context);
+    } else {
+      skipped.push({ test_index: testIndex, path: found.path || "", reason: found.reason });
+    }
+  }
+  return { carriers, captured, skipped };
+}
+
+export function wrapSourceEnvelope(format, body, carriers) {
+  if (!carriers?.length) return Buffer.from(body);
+  const text = Buffer.from(body).toString("utf8");
+  const report = format === "junit" ? text : JSON.parse(text.replace(/^\uFEFF/, ""));
+  return Buffer.from(JSON.stringify({
+    schema_version: SOURCE_ENVELOPE_VERSION,
+    format,
+    report,
+    source_contexts: carriers,
+  }));
+}

package/lib/testdossier.mjs

@@ -1,14 +1,21 @@
 import { createHash, randomUUID } from "node:crypto";
-import { readFile, stat, writeFile } from "node:fs/promises";
-import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { collectSourceContexts, parseSourceConfig, wrapSourceEnvelope } from "./source-context.mjs";
 
-export const VERSION = "0.2.3";
+export const VERSION = "0.3.0";
 const DEFAULT_ORIGIN = "https://testdossier.com";
 const ENV_FILE_NAME = ".env.testdossier";
 const CONFIG_FILE_NAME = "testdossier.json";
+const CYPRESS_HELPER_PATH = "scripts/dossier-cypress.mjs";
+const CYPRESS_HELPER_TEMPLATE_URL = new URL("../templates/dossier-cypress.mjs", import.meta.url);
 const TOKEN_PLACEHOLDER = "replace_with_your_td_token";
 const REPORT_FORMATS = new Set(["cypress", "playwright", "cucumber", "junit", "generic"]);
 const MAX_REPORT_BYTES = 25 * 1024 * 1024;
+// Keep encoded bodies below both the endpoint's 25 MiB request ceiling and
+// its 16 MiB decoded-evidence budget (base64 expands bytes by roughly 4/3).
+const MAX_PAGE_BYTES = 20 * 1024 * 1024;
+const MAX_FAILURE_SCREENSHOT_BYTES = 10 * 1024 * 1024;
 const MAX_TESTS_PER_PAGE = 200;
 const RETRYABLE_STATUSES = new Set([408, 409, 425, 429, 500, 502, 503, 504]);
 const FORMAT_LABELS = {
@@ -130,6 +137,86 @@ export function detectReportFormat(text) {
   return analyzeReport(text).format;
 }
 
+const SCREENSHOT_MIME = new Map([
+  [".png", "image/png"], [".jpg", "image/jpeg"],
+  [".jpeg", "image/jpeg"], [".gif", "image/gif"], [".webp", "image/webp"],
+]);
+
+function isPlaywrightScreenshot(att) {
+  if (!isObject(att)) return false;
+  const contentType = String(att.contentType || "").toLowerCase();
+  const extension = extname(String(att.path || att.name || "")).toLowerCase();
+  return contentType.startsWith("image/") || SCREENSHOT_MIME.has(extension);
+}
+
+function playwrightFinalFailure(test, result) {
+  const status = String(result && result.status || "").toLowerCase();
+  if (status === "timedout" || status === "interrupted") return true;
+  if (status !== "failed") return false;
+  return String(test && test.expectedStatus || "passed").toLowerCase() !== "failed";
+}
+
+/** Promote one screenshot from each final Playwright failure into the inline
+ * transport understood by the ingest endpoint. Earlier-retry screenshots are
+ * deliberately omitted from this upload copy to keep evidence bounded. */
+export async function hydratePlaywrightFailureScreenshots(document, reportPath) {
+  if (!isObject(document) || !Array.isArray(document.suites)) return { inlined: 0, skipped: 0 };
+  let inlined = 0;
+  let skipped = 0;
+
+  const visitSuites = async (suites) => {
+    for (const suite of suites || []) {
+      for (const spec of Array.isArray(suite && suite.specs) ? suite.specs : []) {
+        for (const test of Array.isArray(spec && spec.tests) ? spec.tests : []) {
+          const results = Array.isArray(test && test.results) ? test.results : [];
+          const ordered = results.slice().sort((a, b) => Number(a.retry || 0) - Number(b.retry || 0));
+          const finalResult = ordered[ordered.length - 1];
+          const finalAttachments = Array.isArray(finalResult && finalResult.attachments) ? finalResult.attachments : [];
+          const selected = finalResult && playwrightFinalFailure(test, finalResult)
+            ? finalAttachments.find((att) => isPlaywrightScreenshot(att) && typeof att.path === "string" && att.path.trim()) || null
+            : null;
+
+          for (const result of results) {
+            if (!Array.isArray(result.attachments)) continue;
+            const next = [];
+            for (const att of result.attachments) {
+              if (!isPlaywrightScreenshot(att)) { next.push(att); continue; }
+              if (att !== selected) continue;
+              const rawPath = String(att.path || "").trim();
+              const absolutePath = isAbsolute(rawPath) ? rawPath : resolve(dirname(reportPath), rawPath);
+              const mime = SCREENSHOT_MIME.get(extname(absolutePath).toLowerCase())
+                || (/^image\/(png|jpeg|gif|webp)$/i.test(String(att.contentType || "")) ? String(att.contentType).toLowerCase() : "");
+              try {
+                const info = await stat(absolutePath);
+                if (!mime || !info.isFile() || info.size <= 0 || info.size > MAX_FAILURE_SCREENSHOT_BYTES) {
+                  skipped += 1;
+                  continue;
+                }
+                const bytes = await readFile(absolutePath);
+                next.push({
+                  ...att,
+                  name: att.name || basename(absolutePath),
+                  contentType: mime,
+                  data_url: `data:${mime};base64,${bytes.toString("base64")}`,
+                  path: undefined,
+                });
+                inlined += 1;
+              } catch {
+                skipped += 1;
+              }
+            }
+            result.attachments = next;
+          }
+        }
+      }
+      if (Array.isArray(suite && suite.suites)) await visitSuites(suite.suites);
+    }
+  };
+
+  await visitSuites(document.suites);
+  return { inlined, skipped };
+}
+
 function playwrightTestNodes(suites, found = []) {
   for (const suite of Array.isArray(suites) ? suites : []) {
     if (!suite || typeof suite !== "object") continue;
@@ -160,6 +247,175 @@ function selectedPlaywrightSuite(suite, selectedTests) {
   return next.specs.length > 0 || next.suites.length > 0 ? next : null;
 }
 
+async function inspectPlaywrightFailureScreenshot(test, reportPath) {
+  const results = Array.isArray(test && test.results) ? test.results : [];
+  const ordered = results.slice().sort((a, b) => Number(a.retry || 0) - Number(b.retry || 0));
+  const finalResult = ordered[ordered.length - 1];
+  const attachments = Array.isArray(finalResult && finalResult.attachments) ? finalResult.attachments : [];
+  const selected = finalResult && playwrightFinalFailure(test, finalResult)
+    ? attachments.find((att) => isPlaywrightScreenshot(att) && typeof att.path === "string" && att.path.trim()) || null
+    : null;
+  if (!selected) return { selected: null, skipped: 0, dataUrlLength: 0 };
+
+  const rawPath = String(selected.path || "").trim();
+  const absolutePath = isAbsolute(rawPath) ? rawPath : resolve(dirname(reportPath), rawPath);
+  const mime = SCREENSHOT_MIME.get(extname(absolutePath).toLowerCase())
+    || (/^image\/(png|jpeg|gif|webp)$/i.test(String(selected.contentType || "")) ? String(selected.contentType).toLowerCase() : "");
+  try {
+    const info = await stat(absolutePath);
+    if (!mime || !info.isFile() || info.size <= 0 || info.size > MAX_FAILURE_SCREENSHOT_BYTES) {
+      return { selected, skipped: 1, dataUrlLength: 0 };
+    }
+    const prefix = `data:${mime};base64,`;
+    return {
+      selected,
+      absolutePath,
+      mime,
+      size: info.size,
+      skipped: 0,
+      dataUrlLength: prefix.length + 4 * Math.ceil(info.size / 3),
+    };
+  } catch {
+    return { selected, skipped: 1, dataUrlLength: 0 };
+  }
+}
+
+function playwrightUploadTest(test, evidence, dataUrl, estimate) {
+  return {
+    ...test,
+    results: (Array.isArray(test && test.results) ? test.results : []).map((result) => ({
+      ...result,
+      attachments: (Array.isArray(result && result.attachments) ? result.attachments : []).flatMap((att) => {
+        if (!isPlaywrightScreenshot(att)) return [att];
+        if (att !== evidence.selected || !evidence.absolutePath || !evidence.mime) return [];
+        if (!estimate && typeof dataUrl !== "string") return [];
+        return [{
+          ...att,
+          name: att.name || basename(evidence.absolutePath),
+          contentType: evidence.mime,
+          data_url: estimate ? "" : dataUrl,
+          path: undefined,
+        }];
+      }),
+    })),
+  };
+}
+
+function playwrightUploadPageBody(document, tests, evidenceByTest, dataUrls = null, estimate = false) {
+  const selected = new Set(tests);
+  const replacements = new Map(tests.map((test) => [
+    test,
+    playwrightUploadTest(test, evidenceByTest.get(test), dataUrls && dataUrls.get(test), estimate),
+  ]));
+  const selectSuite = (suite) => {
+    if (!suite || typeof suite !== "object") return null;
+    const next = { ...suite };
+    next.specs = (Array.isArray(suite.specs) ? suite.specs : [])
+      .filter((spec) => spec && typeof spec === "object")
+      .map((spec) => ({
+        ...spec,
+        tests: (Array.isArray(spec.tests) ? spec.tests : [])
+          .filter((test) => selected.has(test))
+          .map((test) => replacements.get(test)),
+      }))
+      .filter((spec) => spec.tests.length > 0);
+    next.suites = (Array.isArray(suite.suites) ? suite.suites : [])
+      .map(selectSuite)
+      .filter(Boolean);
+    return next.specs.length > 0 || next.suites.length > 0 ? next : null;
+  };
+  const suites = document.suites.map(selectSuite).filter(Boolean);
+  return Buffer.from(JSON.stringify({ ...document, suites }));
+}
+
+function estimatedPlaywrightUploadPageBytes(document, tests, evidenceByTest) {
+  const placeholder = playwrightUploadPageBody(document, tests, evidenceByTest, null, true);
+  return placeholder.byteLength + tests.reduce(
+    (sum, test) => sum + Number(evidenceByTest.get(test)?.dataUrlLength || 0),
+    0,
+  );
+}
+
+/** Plan Playwright pages using screenshot stat metadata only. No image bytes or
+ * base64 strings are retained here, so a failure storm cannot exhaust the Node
+ * heap before the first request is sent. */
+export async function planPlaywrightUploadPages(
+  document,
+  reportPath,
+  maxTests = MAX_TESTS_PER_PAGE,
+  maxPageBytes = MAX_PAGE_BYTES,
+) {
+  const tests = playwrightTestNodes(document.suites);
+  const evidenceByTest = new Map();
+  let inlined = 0;
+  let skipped = 0;
+  for (const test of tests) {
+    const evidence = await inspectPlaywrightFailureScreenshot(test, reportPath);
+    evidenceByTest.set(test, evidence);
+    if (evidence.dataUrlLength > 0) inlined += 1;
+    skipped += evidence.skipped;
+  }
+
+  const pages = [];
+  let current = [];
+  const pushCurrent = () => {
+    if (!current.length) return;
+    pages.push({
+      tests: current.slice(),
+      testCount: current.length,
+      estimatedBytes: estimatedPlaywrightUploadPageBytes(document, current, evidenceByTest),
+      maxPageBytes,
+    });
+  };
+  for (const test of tests) {
+    const candidate = [...current, test];
+    const estimatedBytes = estimatedPlaywrightUploadPageBytes(document, candidate, evidenceByTest);
+    if (candidate.length > maxTests || estimatedBytes > maxPageBytes) {
+      if (current.length === 0) {
+        throw new CliError("one Playwright test plus its failure screenshot exceeds the 20 MiB page limit; reduce the screenshot size.");
+      }
+      pushCurrent();
+      current = [test];
+      if (estimatedPlaywrightUploadPageBytes(document, current, evidenceByTest) > maxPageBytes) {
+        throw new CliError("one Playwright test plus its failure screenshot exceeds the 20 MiB page limit; reduce the screenshot size.");
+      }
+    } else {
+      current = candidate;
+    }
+  }
+  pushCurrent();
+  if (pages.length === 0) {
+    pages.push({ tests: [], testCount: 0, estimatedBytes: playwrightUploadPageBody(document, [], evidenceByTest).byteLength, maxPageBytes });
+  }
+  return { pages, evidenceByTest, inlined, skipped };
+}
+
+/** Read and encode only one already-planned page. The caller uploads it before
+ * materializing the next page, bounding live screenshot data to one request. */
+export async function materializePlaywrightUploadPage(document, page, evidenceByTest) {
+  const dataUrls = new Map();
+  let skipped = 0;
+  for (const test of page.tests) {
+    const evidence = evidenceByTest.get(test);
+    if (!evidence?.absolutePath || !evidence.mime) continue;
+    try {
+      const bytes = await readFile(evidence.absolutePath);
+      if (bytes.length <= 0 || bytes.length > MAX_FAILURE_SCREENSHOT_BYTES) {
+        skipped += 1;
+        continue;
+      }
+      dataUrls.set(test, `data:${evidence.mime};base64,${bytes.toString("base64")}`);
+    } catch {
+      skipped += 1;
+    }
+  }
+  const body = playwrightUploadPageBody(document, page.tests, evidenceByTest, dataUrls, false);
+  if (body.byteLength > page.maxPageBytes) {
+    throw new CliError("one Playwright page exceeds the 20 MiB page limit because its screenshot changed during upload; reduce the screenshot size.");
+  }
+  return { body, skipped };
+}
+
 // Counts <testcase> elements the way the server's parser does: real tags
 // only, so a failure message inside CDATA that happens to contain
 // "<testcase" is not counted.
@@ -231,7 +487,7 @@ function selectedCypressRun(run, selectedTests) {
   };
 }
 
-export function splitReportPages(format, report, maxTests = MAX_TESTS_PER_PAGE, document = null) {
+export function splitReportPages(format, report, maxTests = MAX_TESTS_PER_PAGE, document = null, maxPageBytes = MAX_PAGE_BYTES) {
   if (!Number.isInteger(maxTests) || maxTests < 1 || maxTests > MAX_TESTS_PER_PAGE) {
     throw new CliError(`page size must be an integer from 1 to ${MAX_TESTS_PER_PAGE}.`);
   }
@@ -259,14 +515,37 @@ export function splitReportPages(format, report, maxTests = MAX_TESTS_PER_PAGE,
 
   if (format === "playwright") {
     const tests = playwrightTestNodes(doc.suites);
-    if (tests.length <= maxTests) return [{ body: report, tests: tests.length }];
-    return pagedSlices(tests, maxTests).map((slice) => {
+    const pageBody = (slice) => {
       const selected = new Set(slice);
       const suites = doc.suites
         .map((suite) => selectedPlaywrightSuite(suite, selected))
         .filter(Boolean);
-      return { body: Buffer.from(JSON.stringify({ ...doc, suites })), tests: slice.length };
-    });
+      return Buffer.from(JSON.stringify({ ...doc, suites }));
+    };
+    if (tests.length <= maxTests && report.byteLength <= maxPageBytes) {
+      return [{ body: report, tests: tests.length }];
+    }
+    const pages = [];
+    let current = [];
+    for (const test of tests) {
+      const candidate = [...current, test];
+      const candidateBody = pageBody(candidate);
+      if (candidate.length > maxTests || candidateBody.byteLength > maxPageBytes) {
+        if (current.length === 0) {
+          throw new CliError("one Playwright test plus its failure screenshot exceeds the 20 MiB page limit; reduce the screenshot size.");
+        }
+        const body = pageBody(current);
+        pages.push({ body, tests: current.length });
+        current = [test];
+        if (pageBody(current).byteLength > maxPageBytes) {
+          throw new CliError("one Playwright test plus its failure screenshot exceeds the 20 MiB page limit; reduce the screenshot size.");
+        }
+      } else {
+        current = candidate;
+      }
+    }
+    if (current.length > 0) pages.push({ body: pageBody(current), tests: current.length });
+    return pages;
   }
 
   if (format === "cypress") {
@@ -434,6 +713,13 @@ export async function readProjectConfig(cwd) {
     }
     config.url = value.url;
   }
+  if (value.source !== undefined) {
+    try {
+      config.source = parseSourceConfig(value.source);
+    } catch (error) {
+      throw new CliError(error.message);
+    }
+  }
   return config;
 }
 
@@ -519,6 +805,57 @@ async function runInit({ cwd, stdout }) {
   return 0;
 }
 
+async function runCypressSetup({ cwd, stdout }) {
+  let template;
+  try {
+    template = await readFile(CYPRESS_HELPER_TEMPLATE_URL, "utf8");
+  } catch (error) {
+    throw new CliError(`installed Cypress helper template is unavailable: ${error && error.message}`);
+  }
+  const targetPath = join(cwd, "scripts", "dossier-cypress.mjs");
+  const digest = createHash("sha256").update(template).digest("hex");
+
+  const describeExisting = async () => {
+    let existing;
+    try {
+      existing = await readFile(targetPath, "utf8");
+    } catch (error) {
+      if (error && error.code === "ENOENT") return false;
+      throw new CliError(
+        `${CYPRESS_HELPER_PATH} already exists but could not be read; left unchanged: ${error && error.message}`,
+      );
+    }
+    if (existing !== template) {
+      throw new CliError(
+        `${CYPRESS_HELPER_PATH} already exists and differs from the testdossier ${VERSION} template; ` +
+        "left unchanged. Review or remove it before trying again.",
+      );
+    }
+    stdout(`${CYPRESS_HELPER_PATH} already matches testdossier ${VERSION}; left unchanged.`);
+    stdout(`SHA-256 ${digest}`);
+    return true;
+  };
+
+  if (await describeExisting()) return 0;
+  try {
+    await mkdir(dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, template, { flag: "wx", mode: 0o644 });
+  } catch (error) {
+    // Another process may have created the fixed target after our first read.
+    // Re-check it rather than overwriting or reporting a false failure.
+    if (error && error.code === "EEXIST" && await describeExisting()) return 0;
+    throw new CliError(`could not create ${CYPRESS_HELPER_PATH}: ${error && error.message}`);
+  }
+
+  stdout(`Created ${CYPRESS_HELPER_PATH} from installed testdossier ${VERSION}.`);
+  stdout(`SHA-256 ${digest}`);
+  stdout([
+    "Review the generated file before committing it, then add this script to package.json:",
+    '  "cy:testdossier": "node scripts/dossier-cypress.mjs --output cypress-results.json"',
+  ].join("\n"));
+  return 0;
+}
+
 function normalizedHeader(value, name) {
   if (value == null || value === "") return "";
   const normalized = String(value);
@@ -805,6 +1142,7 @@ function helpText() {
 
 Usage:
   testdossier init                  One-time setup: create ${ENV_FILE_NAME} and gitignore it
+  testdossier setup cypress         Create a reviewable Cypress helper without overwriting files
   testdossier verify                Check the token and destination without sending a report
   testdossier upload <report-file> [options]
   testdossier <report-file> [options]    "upload" may be omitted
@@ -845,6 +1183,7 @@ Large reports:
 
 Examples:
   npx testdossier init
+  npx testdossier setup cypress
   npx testdossier verify
   npx testdossier upload playwright-results.json
   npx testdossier upload junit-results.xml --build abc123
@@ -909,6 +1248,12 @@ export async function runCli(
       if (args.length > 1) throw new CliError("init takes no arguments.");
       return await runInit({ cwd, stdout });
     }
+    if (args[0] === "setup") {
+      if (args.length !== 2 || args[1] !== "cypress") {
+        throw new CliError("setup requires exactly one supported target: cypress.");
+      }
+      return await runCypressSetup({ cwd, stdout });
+    }
     if (args[0] === "verify") {
       const options = parseUploadArgs(args.slice(1));
       if (options.help) {
@@ -981,13 +1326,62 @@ export async function runCli(
     const reportText = report.toString("utf8");
     const requestedFormat = options.format !== "auto" ? options.format : (config && config.format) || "auto";
     const { format, document } = analyzeReport(reportText, requestedFormat);
-    const pages = splitReportPages(format, report, MAX_TESTS_PER_PAGE, document);
-    const testCount = pages.reduce((sum, page) => sum + page.tests, 0);
+    let playwrightUpload = null;
+    let pages;
+    if (format === "playwright" && document) {
+      playwrightUpload = await planPlaywrightUploadPages(document, options.reportPath);
+      pages = playwrightUpload.pages;
+      if (playwrightUpload.inlined || playwrightUpload.skipped) {
+        stdout(`Prepared ${playwrightUpload.inlined} failure screenshot${playwrightUpload.inlined === 1 ? "" : "s"} for durable CI evidence${playwrightUpload.skipped ? ` (${playwrightUpload.skipped} skipped)` : ""}.`);
+      }
+    } else {
+      pages = splitReportPages(format, report, MAX_TESTS_PER_PAGE, document);
+    }
+    const testCount = pages.reduce((sum, page) => sum + (page.testCount ?? page.tests), 0);
+    const metadata = inferredMetadata(options, env);
+    let sourceCaptured = 0;
+    let sourceSkipped = 0;
+    const sourcePaths = new Map();
+    if (config?.source) {
+      for (const page of pages) {
+        // The source mapper only needs the report structure. Playwright's
+        // failure screenshots remain lazily materialized at upload time.
+        const structuralBody = playwrightUpload
+          ? playwrightUploadPageBody(document, page.tests, playwrightUpload.evidenceByTest, new Map(), false)
+          : page.body;
+        const source = await collectSourceContexts({
+          format,
+          body: structuralBody,
+          cwd,
+          config: config.source,
+          commit: metadata.build,
+        });
+        page.sourceCarriers = source.carriers;
+        sourceCaptured += source.captured.length;
+        sourceSkipped += source.skipped.length;
+        for (const context of source.captured) {
+          const key = `${context.path}:${context.start_line}-${context.end_line}`;
+          if (!sourcePaths.has(key)) sourcePaths.set(key, context);
+        }
+      }
+      stdout(`Source capture: ${sourceCaptured} of ${testCount} test records captured (${sourcePaths.size} unique snippet${sourcePaths.size === 1 ? "" : "s"}); ${sourceSkipped} skipped.`);
+      const sourcePreviewLimit = 20;
+      for (const context of [...sourcePaths.values()].slice(0, sourcePreviewLimit)) {
+        stdout(`  ${context.path}:${context.start_line}-${context.end_line} · ${context.digest.slice(0, 23)}${context.truncated ? " · truncated" : ""}${context.redactions ? ` · ${context.redactions} redaction${context.redactions === 1 ? "" : "s"}` : ""}`);
+      }
+      if (sourcePaths.size > sourcePreviewLimit) {
+        stdout(`  … ${sourcePaths.size - sourcePreviewLimit} more safe snippet paths omitted from console output.`);
+      }
+      if (sourceSkipped) stderr(`Warning: ${sourceSkipped} test record${sourceSkipped === 1 ? " had" : "s had"} no safe, readable source file and will upload without source context.`);
+    }
+    const validatedBytes = playwrightUpload
+      ? pages.reduce((sum, page) => sum + page.estimatedBytes, 0)
+      : report.byteLength;
 
     const endpoint = normalizeEndpoint(options.url || env.TD_URL || (config && config.url) || DEFAULT_ORIGIN);
     const destination = new URL(endpoint).origin;
     stdout(
-      `Validated ${FORMAT_LABELS[format]} (${report.byteLength} bytes, ${testCount} tests` +
+      `Validated ${FORMAT_LABELS[format]} (${validatedBytes} bytes, ${testCount} tests` +
       `${pages.length > 1 ? ` across ${pages.length} pages` : ""}).`,
     );
     if (options.dryRun) {
@@ -998,7 +1392,6 @@ export async function runCli(
     const token = await resolveToken(options, env, cwd, stdout, stderr);
     if (typeof fetchImpl !== "function") throw new CliError("Node 18 or newer is required (global fetch is unavailable).");
 
-    const metadata = inferredMetadata(options, env);
     const baseHeaders = {
       Authorization: `Bearer ${token}`,
       "Content-Type": format === "junit" ? "application/xml" : "application/json",
@@ -1014,7 +1407,7 @@ export async function runCli(
 
     if (pages.length > 1) {
       stdout(
-        `Uploading ${pages.reduce((sum, page) => sum + (page.tests || 0), 0)} tests in ` +
+        `Uploading ${pages.reduce((sum, page) => sum + (page.testCount ?? page.tests ?? 0), 0)} tests in ` +
         `${pages.length} pages (run ${metadata.runId}).`,
       );
     }
@@ -1026,23 +1419,39 @@ export async function runCli(
     const pageResults = [];
     for (let index = 0; index < pages.length; index += 1) {
       const page = pages[index];
+      const materialized = playwrightUpload
+        ? await materializePlaywrightUploadPage(document, page, playwrightUpload.evidenceByTest)
+        : null;
+      if (materialized?.skipped) {
+        stderr(`Warning: ${materialized.skipped} failure screenshot${materialized.skipped === 1 ? " was" : "s were"} no longer readable and were skipped.`);
+      }
+      const rawBody = materialized ? materialized.body : page.body;
+      const uploadBody = wrapSourceEnvelope(format, rawBody, page.sourceCarriers);
+      if (uploadBody.byteLength > MAX_REPORT_BYTES) {
+        throw new CliError("one report page plus source context exceeds the 25 MiB request limit; reduce the source window or screenshot size.");
+      }
       const result = await postWithRetry({
         endpoint,
         headers: {
           ...baseHeaders,
+          ...(page.sourceCarriers?.length ? {
+            "Content-Type": "application/json",
+            "X-TD-Source-Envelope": "1",
+            "X-CI-Format": format,
+          } : {}),
           "X-CI-Page-Id": pages.length === 1 ? pageBase : `${pageBase}-${index + 1}`,
           "X-CI-Upload-Id": pageBase,
           "X-CI-Page-Index": String(index + 1),
           "X-CI-Page-Count": String(pages.length),
         },
-        body: page.body,
+        body: uploadBody,
         env,
         fetchImpl,
         stderr,
       });
       pageResults.push(result);
       if (pages.length > 1) {
-        stdout(`Uploaded page ${index + 1}/${pages.length} (${page.tests} tests).`);
+        stdout(`Uploaded page ${index + 1}/${pages.length} (${page.testCount ?? page.tests} tests).`);
       }
     }
     stdout(`Uploaded ${FORMAT_LABELS[format]} to ${destination} (run ${metadata.runId}).`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdossier",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "Upload Playwright, Cypress, Cucumber, JUnit, and JSON test evidence to TestDossier.",
   "license": "MIT",
   "type": "module",
@@ -10,6 +10,7 @@
   "files": [
     "bin",
     "lib",
+    "templates",
     "assets",
     "README.md",
     "LICENSE",

package/templates/dossier-cypress.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// TestDossier Cypress runner — zero dependencies beyond the project's Cypress.
+// Uses Cypress's Module API so the output is the native { runs: [...] } shape
+// accepted by X-CI-Format: cypress. Failure screenshots are embedded as data
+// URLs; /api/ci/ingest uploads them to R2 and stores only durable references.
+
+import cypress from "cypress";
+import { readFileSync, writeFileSync, existsSync, statSync } from "node:fs";
+import { extname, resolve } from "node:path";
+
+const args = process.argv.slice(2);
+const outputFlag = args.indexOf("--output");
+const output = outputFlag >= 0 && args[outputFlag + 1]
+  ? args[outputFlag + 1]
+  : "cypress-results.json";
+const cypressArgs = outputFlag >= 0
+  ? args.filter((_, i) => i !== outputFlag && i !== outputFlag + 1)
+  : args;
+
+const MIME = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+};
+const MAX_SCREENSHOTS = 20;
+const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+// Base64 adds roughly 33%; keeping raw bytes at 15 MB leaves room under the
+// ingest endpoint's 25 MB request limit for the Cypress result JSON itself.
+const MAX_TOTAL_IMAGE_BYTES = 15 * 1024 * 1024;
+
+const options = {};
+for (let i = 0; i < cypressArgs.length; i += 1) {
+  const arg = cypressArgs[i];
+  if (arg === "--browser" && cypressArgs[i + 1]) options.browser = cypressArgs[++i];
+  else if (arg === "--spec" && cypressArgs[i + 1]) options.spec = cypressArgs[++i];
+  else if (arg === "--config-file" && cypressArgs[i + 1]) options.configFile = cypressArgs[++i];
+  else if (arg === "--component") options.component = true;
+  else if (arg === "--headed") options.headed = true;
+}
+
+let result;
+try {
+  result = await cypress.run(options);
+} catch (error) {
+  console.error("Cypress could not start:", error instanceof Error ? error.message : error);
+  process.exit(2);
+}
+
+if (!result || !Array.isArray(result.runs)) {
+  console.error("Cypress did not return a test-run result:", result?.message || "unknown error");
+  process.exit(2);
+}
+
+let embedded = 0;
+let embeddedBytes = 0;
+let skipped = 0;
+for (const run of result.runs) {
+  for (const screenshot of run.screenshots || []) {
+    const path = resolve(String(screenshot.path || ""));
+    const mime = MIME[extname(path).toLowerCase()];
+    if (!path || !mime || !existsSync(path)) { skipped += 1; continue; }
+    const bytes = statSync(path).size;
+    if (
+      bytes > MAX_IMAGE_BYTES ||
+      embedded >= MAX_SCREENSHOTS ||
+      embeddedBytes + bytes > MAX_TOTAL_IMAGE_BYTES
+    ) {
+      skipped += 1;
+      continue;
+    }
+    screenshot.data_url = `data:${mime};base64,${readFileSync(path).toString("base64")}`;
+    screenshot.content_type = mime;
+    embedded += 1;
+    embeddedBytes += bytes;
+  }
+}
+
+writeFileSync(output, JSON.stringify(result));
+console.log(`Wrote ${output}: ${result.totalTests || 0} test(s), ${embedded} screenshot(s) embedded${skipped ? `, ${skipped} skipped by size/count limits` : ""}.`);
+console.warn("Review CI screenshots for secrets or personal data before sharing them externally.");
+
+const failed = Number(result.totalFailed || 0) || result.runs.reduce(
+  (sum, run) => sum + Number(run?.stats?.failures || 0),
+  0,
+);
+process.exitCode = failed > 0 ? 1 : 0;