testdossier 0.1.2 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TestDossier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -35,8 +35,10 @@ TestDossier. Use the actual report path produced by your runner. Repeat steps 3
 and 4 whenever you want to publish a new run.
 If tests run in multiple shards or batches, merge all shard reports before
 uploading; selecting one shard's file uploads only that shard.
-After merging, the CLI automatically sends Playwright and generic JSON reports
-larger than 200 tests as sequential pages under one stable Test Run.
+After merging, the CLI automatically sends JSON reports (Playwright, Cypress,
+Cucumber, generic) larger than 200 tests as sequential pages under one stable
+Test Run. JUnit XML larger than 200 tests is rejected before anything is sent;
+split it per suite or switch the runner to a JSON reporter.
 
 The CLI auto-detects Playwright JSON, Cypress JSON, Cucumber JSON, JUnit XML,
 and TestDossier's generic JSON format. It has zero runtime dependencies and
@@ -58,18 +60,18 @@ rejected except for localhost development.
 Before sending anything, inspect what the CLI detected:
 
 ```bash
-npx testdossier upload playwright-results.json --dry-run
+npx --yes testdossier@0.1.3 upload playwright-results.json --dry-run
 ```
 
 ## Supported reports
 
 | Runner or format | Example |
 |---|---|
-| Playwright JSON | `npx testdossier upload playwright-results.json` |
-| Cypress JSON | `npx testdossier upload cypress-results.json` |
-| Cucumber JSON | `npx testdossier upload cucumber-results.json` |
-| JUnit XML | `npx testdossier upload junit-results.xml` |
-| Generic JSON | `npx testdossier upload testdossier-ci.json` |
+| Playwright JSON | `npx --yes testdossier@0.1.3 upload playwright-results.json` |
+| Cypress JSON | `npx --yes testdossier@0.1.3 upload cypress-results.json` |
+| Cucumber JSON | `npx --yes testdossier@0.1.3 upload cucumber-results.json` |
+| JUnit XML | `npx --yes testdossier@0.1.3 upload junit-results.xml` |
+| Generic JSON | `npx --yes testdossier@0.1.3 upload testdossier-ci.json` |
 
 Detection uses the report's contents, not its filename. If a custom reporter
 creates an ambiguous shape, pass `--format playwright`, `--format cypress`,
@@ -125,12 +127,19 @@ npx testdossier upload junit-results.xml \
 ```
 
 `--run-id` is the idempotency key. Repeating the same upload with the same run
-ID returns the existing ingest result rather than creating a duplicate. Without
-one, the CLI creates a new local run ID. Transient network, rate-limit, conflict,
-and server errors are retried with the same run ID.
+ID returns the existing ingest result rather than creating a duplicate; the CLI
+prints a note when the server answers with such a replay. Different report
+files uploaded under one run ID accumulate as separate pages of that run (the
+page identity includes the report's file name and a path fingerprint). Without
+a run ID, the CLI creates a new local one. Transient network, rate-limit,
+conflict, and server errors are retried with the same run ID.
 
 Run `npx testdossier --help` for every option.
 
 If `.env.testdossier` is ever committed or shared, revoke that token in
 TestDossier immediately and create a replacement. Hosted CI should use the
-provider's encrypted secret storage instead of an env file.
+provider's encrypted secret storage instead of an env file. The Access Tokens
+dialog generates provider-specific GitHub Actions, GitLab CI, and Jenkins
+snippets that run after the test report is created. Those recipes pin the CLI,
+link back to the originating CI run, retry transient failures, and keep the
+token out of command history.

package/lib/testdossier.mjs

@@ -1,7 +1,8 @@
 import { createHash, randomUUID } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
+import { basename } from "node:path";
 
-export const VERSION = "0.1.2";
+export const VERSION = "0.1.3";
 const DEFAULT_ORIGIN = "https://testdossier.com";
 const MAX_REPORT_BYTES = 25 * 1024 * 1024;
 const MAX_TESTS_PER_PAGE = 200;
@@ -41,48 +42,88 @@ function matchingJsonFormats(value) {
   return matches;
 }
 
-function assertFormatShape(format, text) {
-  const trimmed = text.replace(/^\uFEFF/, "").trimStart();
-  if (format === "junit") {
-    if (!trimmed.startsWith("<") || !/<testsuites?\b/i.test(trimmed)) {
-      throw new CliError("JUnit reports must be XML containing a <testsuite> or <testsuites> root.");
-    }
-    return;
-  }
+function isObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
 
-  const value = parseJson(trimmed);
-  const matches = matchingJsonFormats(value);
-  if (!matches.includes(format)) {
-    const expected = {
-      cypress: "a JSON object with runs[]",
-      playwright: "a JSON object with suites[]",
-      cucumber: "a JSON array of features",
-      generic: "a JSON object with tests[]",
-    }[format];
-    throw new CliError(`${FORMAT_LABELS[format]} must be ${expected}.`);
+function validPlaywrightSuites(suites) {
+  return Array.isArray(suites) && suites.every((suite) => {
+    if (!isObject(suite)) return false;
+    if (suite.specs != null && !Array.isArray(suite.specs)) return false;
+    if (suite.suites != null && !validPlaywrightSuites(suite.suites)) return false;
+    return (suite.specs || []).every((spec) => {
+      if (!isObject(spec)) return false;
+      if (spec.tests != null && !Array.isArray(spec.tests)) return false;
+      return (spec.tests || []).every((test) =>
+        isObject(test) &&
+        (test.results == null ||
+          (Array.isArray(test.results) && test.results.every(isObject))));
+    });
+  });
+}
+
+function validJsonFormat(format, value) {
+  if (format === "generic") return isObject(value) && Array.isArray(value.tests);
+  if (format === "playwright") return isObject(value) && validPlaywrightSuites(value.suites);
+  if (format === "cypress") {
+    return isObject(value) && Array.isArray(value.runs) && value.runs.every((run) =>
+      isObject(run) &&
+      (run.tests == null ||
+        (Array.isArray(run.tests) && run.tests.every((test) =>
+          isObject(test) && (test.attempts == null || Array.isArray(test.attempts))))) &&
+      (run.screenshots == null || Array.isArray(run.screenshots)));
   }
+  return Array.isArray(value) && value.every((feature) =>
+    isObject(feature) &&
+    (feature.elements == null ||
+      (Array.isArray(feature.elements) && feature.elements.every((element) =>
+        isObject(element) && (element.steps == null || Array.isArray(element.steps))))));
 }
 
-export function detectReportFormat(text) {
+function invalidFormatMessage(format) {
+  const expected = {
+    cypress: "a JSON object with well-formed runs[]",
+    playwright: "a JSON object with well-formed suites[]",
+    cucumber: "a JSON array of features with well-formed elements[]",
+    generic: "a JSON object with tests[]",
+  }[format];
+  return `${FORMAT_LABELS[format]} must be ${expected}.`;
+}
+
+export function analyzeReport(text, requestedFormat = "auto") {
   const trimmed = text.replace(/^\uFEFF/, "").trimStart();
   if (!trimmed) throw new CliError("report file is empty.");
-  if (trimmed.startsWith("<")) {
-    assertFormatShape("junit", trimmed);
-    return "junit";
+  if (requestedFormat === "junit" || (requestedFormat === "auto" && trimmed.startsWith("<"))) {
+    if (!/^(?:<\?xml[\s\S]*?\?>\s*)?(?:<!--[\s\S]*?-->\s*)*<(?:[\w.-]+:)?testsuites?\b/i.test(trimmed)) {
+      throw new CliError("JUnit reports must be XML containing a <testsuite> or <testsuites> root.");
+    }
+    return { format: "junit", document: null };
   }
 
   const value = parseJson(trimmed);
   const matches = matchingJsonFormats(value);
-  if (matches.length === 0) {
-    throw new CliError(
-      "could not detect the report format; expected Cypress runs[], Playwright suites[], " +
-      "a Cucumber feature array, generic tests[], or JUnit XML.",
-    );
+  if (requestedFormat === "auto") {
+    if (matches.length === 0) {
+      throw new CliError(
+        "could not detect the report format; expected Cypress runs[], Playwright suites[], " +
+        "a Cucumber feature array, generic tests[], or JUnit XML.",
+      );
+    }
+    if (matches.length > 1) {
+      throw new CliError(`report shape is ambiguous (${matches.join(", ")}); pass --format explicitly.`);
+    }
+    const format = matches[0];
+    if (!validJsonFormat(format, value)) throw new CliError(invalidFormatMessage(format));
+    return { format, document: value };
   }
-  if (matches.length > 1) {
-    throw new CliError(`report shape is ambiguous (${matches.join(", ")}); pass --format explicitly.`);
+  if (!matches.includes(requestedFormat) || !validJsonFormat(requestedFormat, value)) {
+    throw new CliError(invalidFormatMessage(requestedFormat));
   }
-  return matches[0];
+  return { format: requestedFormat, document: value };
+}
+
+export function detectReportFormat(text) {
+  return analyzeReport(text).format;
 }
 
 function playwrightTestNodes(suites, found = []) {
@@ -115,44 +156,146 @@ function selectedPlaywrightSuite(suite, selectedTests) {
   return next.specs.length > 0 || next.suites.length > 0 ? next : null;
 }
 
-export function splitReportPages(format, report, maxTests = MAX_TESTS_PER_PAGE) {
+// 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.
+function countJunitTests(text) {
+  const stripped = text
+    .replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, "")
+    .replace(/<!--[\s\S]*?-->/g, "");
+  return (stripped.match(/<testcase[\s/>]/gi) || []).length;
+}
+
+function isCucumberScenario(element) {
+  return !!element && typeof element === "object" &&
+    String(element.type || "scenario").toLowerCase() === "scenario";
+}
+
+function pagedSlices(items, maxTests) {
+  const slices = [];
+  for (let start = 0; start < items.length; start += maxTests) {
+    slices.push(items.slice(start, start + maxTests));
+  }
+  return slices;
+}
+
+function cypressTestFailed(test) {
+  const attempts = Array.isArray(test.attempts) ? test.attempts : [];
+  const state = attempts[attempts.length - 1]?.state || test.state;
+  return String(state || "").toLowerCase() === "failed";
+}
+
+function normalizedCypressTitle(value) {
+  return String(value || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+
+function cypressScreenshotMatchesTest(screenshot, test) {
+  if (!isObject(screenshot)) return false;
+  const title = Array.isArray(test.title) ? test.title : [String(test.title || "")];
+  const haystack = normalizedCypressTitle(`${screenshot.name || ""} ${screenshot.path || ""}`);
+  const fullTitle = normalizedCypressTitle(title.join(" "));
+  const leafTitle = normalizedCypressTitle(title[title.length - 1] || "");
+  return !!haystack &&
+    ((fullTitle.length >= 4 && haystack.includes(fullTitle)) ||
+      (leafTitle.length >= 4 && haystack.includes(leafTitle)));
+}
+
+function selectedCypressRun(run, selectedTests) {
+  const runTests = Array.isArray(run.tests) ? run.tests : [];
+  const tests = runTests.filter((test) => selectedTests.has(test));
+  if (tests.length === 0) return null;
+
+  // The server associates run-level screenshots using the complete run's set
+  // of failures. Keep that context while paging: otherwise two failures split
+  // across pages each look like the run's sole failure and both inherit every
+  // unmatched screenshot.
+  const allFailures = runTests.filter(cypressTestFailed);
+  const pageFailures = tests.filter(cypressTestFailed);
+  let screenshots = [];
+  if (allFailures.length === 1 && pageFailures.length === 1) {
+    screenshots = Array.isArray(run.screenshots) ? run.screenshots : [];
+  } else if (allFailures.length > 1 && pageFailures.length > 0) {
+    screenshots = (Array.isArray(run.screenshots) ? run.screenshots : [])
+      .filter((screenshot) => pageFailures.some((test) => cypressScreenshotMatchesTest(screenshot, test)));
+  }
+
+  return {
+    ...run,
+    tests,
+    screenshots,
+    video: pageFailures.length > 0 ? run.video : null,
+  };
+}
+
+export function splitReportPages(format, report, maxTests = MAX_TESTS_PER_PAGE, document = null) {
   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}.`);
   }
-  if (format !== "playwright" && format !== "generic") {
-    return [{ body: report, tests: null }];
+  if (format === "junit") {
+    const count = countJunitTests(report.toString("utf8"));
+    if (count > maxTests) {
+      throw new CliError(
+        `JUnit report has ${count} tests; the server accepts at most ${maxTests} per request ` +
+        "and JUnit XML cannot be paged automatically. Split it per suite, or switch the runner " +
+        "to a JSON reporter (Playwright, Cypress, Cucumber, or generic), which the CLI pages for you.",
+      );
+    }
+    return [{ body: report, tests: count }];
   }
 
-  const document = parseJson(report.toString("utf8").replace(/^\uFEFF/, ""));
+  const doc = document ?? parseJson(report.toString("utf8").replace(/^\uFEFF/, ""));
   if (format === "generic") {
-    const tests = document.tests;
+    const tests = doc.tests;
     if (tests.length <= maxTests) return [{ body: report, tests: tests.length }];
-    const pages = [];
-    for (let start = 0; start < tests.length; start += maxTests) {
-      const slice = tests.slice(start, start + maxTests);
-      pages.push({
-        body: Buffer.from(JSON.stringify({ ...document, tests: slice })),
-        tests: slice.length,
-      });
-    }
-    return pages;
+    return pagedSlices(tests, maxTests).map((slice) => ({
+      body: Buffer.from(JSON.stringify({ ...doc, tests: slice })),
+      tests: slice.length,
+    }));
   }
 
-  const tests = playwrightTestNodes(document.suites);
-  if (tests.length <= maxTests) return [{ body: report, tests: tests.length }];
-  const pages = [];
-  for (let start = 0; start < tests.length; start += maxTests) {
-    const slice = tests.slice(start, start + maxTests);
-    const selected = new Set(slice);
-    const suites = document.suites
-      .map((suite) => selectedPlaywrightSuite(suite, selected))
-      .filter(Boolean);
-    pages.push({
-      body: Buffer.from(JSON.stringify({ ...document, suites })),
-      tests: slice.length,
+  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 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 pages;
+
+  if (format === "cypress") {
+    const runs = doc.runs;
+    const tests = runs.flatMap((run) => Array.isArray(run.tests) ? run.tests : []);
+    if (tests.length <= maxTests) return [{ body: report, tests: tests.length }];
+    return pagedSlices(tests, maxTests).map((slice) => {
+      const selected = new Set(slice);
+      const pageRuns = runs
+        .map((run) => selectedCypressRun(run, selected))
+        .filter(Boolean);
+      return { body: Buffer.from(JSON.stringify({ ...doc, runs: pageRuns })), tests: slice.length };
+    });
+  }
+
+  // cucumber: the test unit is a scenario element. Background (and other
+  // non-scenario) elements apply to every scenario in their feature, so
+  // they are replicated onto every page that carries that feature.
+  const features = (Array.isArray(doc) ? doc : []).filter((f) => f && typeof f === "object");
+  const scenarios = features.flatMap((f) =>
+    (Array.isArray(f.elements) ? f.elements : []).filter(isCucumberScenario));
+  if (scenarios.length <= maxTests) return [{ body: report, tests: scenarios.length }];
+  return pagedSlices(scenarios, maxTests).map((slice) => {
+    const selected = new Set(slice);
+    const pageFeatures = features
+      .map((f) => {
+        const elements = (Array.isArray(f.elements) ? f.elements : [])
+          .filter((el) => !isCucumberScenario(el) || selected.has(el));
+        return elements.some((el) => isCucumberScenario(el)) ? { ...f, elements } : null;
+      })
+      .filter(Boolean);
+    return { body: Buffer.from(JSON.stringify(pageFeatures)), tests: slice.length };
+  });
 }
 
 function isLoopback(hostname) {
@@ -250,29 +393,58 @@ export function parseUploadArgs(args) {
   return options;
 }
 
-function boundedHeader(value, name, maxLength) {
+function normalizedHeader(value, name) {
   if (value == null || value === "") return "";
   const normalized = String(value);
   if (/[\r\n]/.test(normalized)) throw new CliError(`${name} must not contain a newline.`);
-  return normalized.slice(0, maxLength);
+  // fetch rejects header values outside ISO-8859-1; percent-encode anything
+  // beyond printable ASCII so a Unicode branch name degrades to a readable
+  // token instead of a TypeError that looks like a network failure.
+  const ascii = normalized.replace(/[^\x20-\x7e]/gu, (char) => {
+    try { return encodeURIComponent(char); } catch { return "_"; }
+  });
+  return ascii.trim();
+}
+
+function boundedHeader(value, name, maxLength) {
+  return normalizedHeader(value, name).slice(0, maxLength).trim();
 }
 
 function boundedRunId(value) {
-  const normalized = boundedHeader(value, "run id", 1000);
+  const normalized = normalizedHeader(value, "run id");
   if (normalized.length <= 120) return normalized;
   const digest = createHash("sha256").update(normalized).digest("hex").slice(0, 20);
   return `${normalized.slice(0, 95)}-${digest}`;
 }
 
+function boundedPageBase(value) {
+  const normalized = normalizedHeader(value, "report name") || "results";
+  if (normalized.length <= 100) return normalized;
+  const digest = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  return `${normalized.slice(0, 83)}-${digest}`;
+}
+
+function reportPageBase(reportPath) {
+  const reportName = basename(reportPath);
+  const pathKey = String(reportPath).replace(/\\/g, "/");
+  const pathDigest = createHash("sha256").update(pathKey).digest("hex").slice(0, 12);
+  return boundedPageBase(`${reportName}-${pathDigest}`);
+}
+
 function defaultRunId() {
   return `local-${Date.now()}-${randomUUID().slice(0, 8)}`;
 }
 
 function inferredMetadata(options, env) {
+  // GITHUB_JOB is part of the inferred key: two jobs of one workflow run
+  // would otherwise share a run id, and the server answers the second
+  // upload with an idempotent replay of the first.
   const runId = boundedRunId(
     options.runId ||
     env.TD_RUN_ID ||
-    (env.GITHUB_RUN_ID ? `${env.GITHUB_RUN_ID}-${env.GITHUB_RUN_ATTEMPT || 1}` : "") ||
+    (env.GITHUB_RUN_ID
+      ? [env.GITHUB_RUN_ID, env.GITHUB_JOB, env.GITHUB_RUN_ATTEMPT || 1].filter(Boolean).join("-")
+      : "") ||
     (env.CI_PIPELINE_ID ? `${env.CI_PIPELINE_ID}-${env.CI_JOB_ID || 1}` : "") ||
     env.BUILD_TAG ||
     defaultRunId(),
@@ -422,8 +594,10 @@ Authentication:
   them out of shell history and process listings.
 
 Large reports:
-  Playwright and generic JSON reports above 200 tests are automatically sent
-  as sequential pages that remain grouped under one TestDossier run.
+  JSON reports (Playwright, Cypress, Cucumber, generic) above 200 tests are
+  automatically sent as sequential pages that remain grouped under one
+  TestDossier run. JUnit XML above 200 tests is rejected before upload —
+  split it per suite or switch the runner to a JSON reporter.
 
 Examples:
   npx testdossier upload playwright-results.json --env-file .env.testdossier
@@ -446,6 +620,7 @@ function outputSummary(result, stdout, stderr) {
 
 function aggregatePageResults(results) {
   const aggregate = { counts: {}, warnings: [] };
+  const seenWarnings = new Set();
   for (const result of results) {
     if (result && result.counts && typeof result.counts === "object") {
       for (const [name, value] of Object.entries(result.counts)) {
@@ -454,7 +629,12 @@ function aggregatePageResults(results) {
         }
       }
     }
-    if (Array.isArray(result && result.warnings)) aggregate.warnings.push(...result.warnings);
+    for (const warning of Array.isArray(result && result.warnings) ? result.warnings : []) {
+      const key = String(warning);
+      if (seenWarnings.has(key)) continue;
+      seenWarnings.add(key);
+      aggregate.warnings.push(warning);
+    }
   }
   return aggregate;
 }
@@ -469,7 +649,7 @@ export async function runCli(
   } = {},
 ) {
   try {
-    if (args.includes("--version")) {
+    if (args[0] === "--version") {
       stdout(VERSION);
       return 0;
     }
@@ -498,21 +678,15 @@ export async function runCli(
     }
     const report = await readFile(options.reportPath);
     const reportText = report.toString("utf8");
-    const format = options.format === "auto" ? detectReportFormat(reportText) : options.format;
-    assertFormatShape(format, reportText);
-    const pages = splitReportPages(format, report);
-    const testCount = pages.every((page) => typeof page.tests === "number")
-      ? pages.reduce((sum, page) => sum + page.tests, 0)
-      : null;
+    const { format, document } = analyzeReport(reportText, options.format);
+    const pages = splitReportPages(format, report, MAX_TESTS_PER_PAGE, document);
+    const testCount = pages.reduce((sum, page) => sum + page.tests, 0);
 
     const endpoint = normalizeEndpoint(options.url || env.TD_URL || DEFAULT_ORIGIN);
     const destination = new URL(endpoint).origin;
     stdout(
-      `Validated ${FORMAT_LABELS[format]} (${report.byteLength} bytes` +
-      (testCount == null
-        ? ""
-        : `, ${testCount} tests${pages.length > 1 ? ` across ${pages.length} pages` : ""}`) +
-      ").",
+      `Validated ${FORMAT_LABELS[format]} (${report.byteLength} bytes, ${testCount} tests` +
+      `${pages.length > 1 ? ` across ${pages.length} pages` : ""}).`,
     );
     if (options.dryRun) {
       stdout(`Dry run complete; no data was sent to ${destination}.`);
@@ -546,6 +720,11 @@ export async function runCli(
         `${pages.length} pages (run ${metadata.runId}).`,
       );
     }
+    // Page ids carry a readable file name plus a path fingerprint so two
+    // reports uploaded under one run id become distinct pages even when their
+    // base names match (for example chromium/results.json and
+    // firefox/results.json).
+    const pageBase = reportPageBase(options.reportPath);
     const pageResults = [];
     for (let index = 0; index < pages.length; index += 1) {
       const page = pages[index];
@@ -553,7 +732,7 @@ export async function runCli(
         endpoint,
         headers: {
           ...baseHeaders,
-          "X-CI-Page-Id": pages.length === 1 ? "results" : String(index + 1),
+          "X-CI-Page-Id": pages.length === 1 ? pageBase : `${pageBase}-${index + 1}`,
         },
         body: page.body,
         env,
@@ -566,6 +745,13 @@ export async function runCli(
       }
     }
     stdout(`Uploaded ${FORMAT_LABELS[format]} to ${destination} (run ${metadata.runId}).`);
+    const replayed = pageResults.filter((result) => result && result.idempotent_replay === true).length;
+    if (replayed > 0) {
+      stderr(pageResults.length === 1
+        ? `Note: the server replayed an earlier upload for run ${metadata.runId}; nothing new was ingested. ` +
+          "Pass a unique --run-id if this was not a retry."
+        : `Note: ${replayed} of ${pageResults.length} pages were idempotent replays of an earlier upload (run ${metadata.runId}).`);
+    }
     outputSummary(aggregatePageResults(pageResults), stdout, stderr);
     return 0;
   } catch (error) {

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "testdossier",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Upload completed test reports to TestDossier from a local machine or CI.",
+  "license": "MIT",
   "type": "module",
   "bin": {
     "testdossier": "bin/testdossier.mjs"
@@ -10,6 +11,7 @@
     "bin",
     "lib",
     "README.md",
+    "LICENSE",
     ".env.testdossier.example"
   ],
   "engines": {