testdossier 0.1.0 → 0.1.2

package/.env.testdossier.example

@@ -0,0 +1,3 @@
+# Copy this file to .env.testdossier, replace the placeholder, and keep the
+# resulting file out of git.
+TD_CI_TOKEN=replace_with_your_td_token

package/README.md

@@ -1,12 +1,43 @@
 # TestDossier CLI
 
-Upload a completed test report from a developer laptop, test machine, or CI job:
+Upload a completed test report from a developer laptop, test machine, or CI
+job. Run these steps in the project containing your automated tests:
+
+1. Create `.env.testdossier`:
+
+```dotenv
+TD_CI_TOKEN=replace_with_your_td_token
+```
+
+2. Replace the placeholder with the CI-ingestion token shown once by
+   TestDossier, add the file to `.gitignore`, and protect it:
+
+```bash
+chmod 600 .env.testdossier
+```
+
+3. Run your tests so they create a supported report. For example, with
+   Playwright's JSON reporter configured to write `playwright-results.json`:
+
+```bash
+npx playwright test
+test -f playwright-results.json
+```
+
+4. Upload the completed report:
 
 ```bash
-export TD_CI_TOKEN="td_..."
-npx testdossier upload playwright-results.json
+npx testdossier upload playwright-results.json --env-file .env.testdossier
 ```
 
+`playwright-results.json` is an example filename, not a file supplied by
+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.
+
 The CLI auto-detects Playwright JSON, Cypress JSON, Cucumber JSON, JUnit XML,
 and TestDossier's generic JSON format. It has zero runtime dependencies and
 requires Node.js 18 or newer.
@@ -17,10 +48,12 @@ 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 access token is read only from `TD_CI_TOKEN`. There is deliberately no
-`--token` option, so a token cannot accidentally land in shell history or a
-process listing. Redirects are rejected, and non-HTTPS destinations are rejected
-except for localhost development.
+The access token is read from an explicitly selected env file or from the
+`TD_CI_TOKEN` process environment. There is deliberately no `--token` option,
+so a token cannot accidentally land in shell history or a process listing.
+The CLI reads only `TD_CI_TOKEN` from the selected file; it does not import or
+execute other entries. Redirects are rejected, and non-HTTPS destinations are
+rejected except for localhost development.
 
 Before sending anything, inspect what the CLI detected:
 
@@ -45,31 +78,47 @@ creates an ambiguous shape, pass `--format playwright`, `--format cypress`,
 ## Local setup
 
 Create a project access token in TestDossier with the **CI ingestion**
-capability, copy it once, and place it in an environment variable:
+capability and copy it once. For repeat use, install and pin the CLI in the test
+repository so its source and version are captured by the lockfile:
 
 ```bash
-export TD_CI_TOKEN="td_..."
+npm install --save-dev testdossier
+cp node_modules/testdossier/.env.testdossier.example .env.testdossier
 ```
 
-For repeat use, install and pin the CLI in the test repository so its source and
-version are captured by the lockfile:
+Alternatively, create `.env.testdossier` yourself with the single placeholder
+line shown at the top of this guide. Replace `replace_with_your_td_token`, then
+ensure the project ignores and protects the real file:
+
+```gitignore
+.env.testdossier
+```
 
 ```bash
-npm install --save-dev testdossier
-npx testdossier upload playwright-results.json
+chmod 600 .env.testdossier
 ```
 
+Upload with:
+
+```bash
+npx testdossier upload playwright-results.json --env-file .env.testdossier
+```
+
+For a one-off session, setting `TD_CI_TOKEN` in the process environment still
+works. An explicitly passed `--env-file` takes precedence.
+
 The default destination is `https://testdossier.com`. A self-hosted or local
 instance can be selected without putting the token on the command line:
 
 ```bash
-TD_URL="https://dossier.example.com" npx testdossier upload junit-results.xml
+TD_URL="https://dossier.example.com" npx testdossier upload junit-results.xml --env-file .env.testdossier
 ```
 
 Useful metadata options:
 
 ```bash
 npx testdossier upload junit-results.xml \
+  --env-file .env.testdossier \
   --run-id "local-2026-07-23-1" \
   --build "abc123" \
   --branch "main"
@@ -81,3 +130,7 @@ one, the CLI creates a new local run ID. 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.

package/lib/testdossier.mjs

@@ -1,9 +1,10 @@
 import { createHash, randomUUID } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.2";
 const DEFAULT_ORIGIN = "https://testdossier.com";
 const MAX_REPORT_BYTES = 25 * 1024 * 1024;
+const MAX_TESTS_PER_PAGE = 200;
 const RETRYABLE_STATUSES = new Set([408, 409, 425, 429, 500, 502, 503, 504]);
 const FORMAT_LABELS = {
   cypress: "Cypress JSON",
@@ -84,6 +85,76 @@ export function detectReportFormat(text) {
   return matches[0];
 }
 
+function playwrightTestNodes(suites, found = []) {
+  for (const suite of Array.isArray(suites) ? suites : []) {
+    if (!suite || typeof suite !== "object") continue;
+    for (const spec of Array.isArray(suite.specs) ? suite.specs : []) {
+      if (!spec || typeof spec !== "object") continue;
+      for (const test of Array.isArray(spec.tests) ? spec.tests : []) {
+        found.push(test);
+      }
+    }
+    playwrightTestNodes(suite.suites, found);
+  }
+  return found;
+}
+
+function selectedPlaywrightSuite(suite, selectedTests) {
+  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) => selectedTests.has(test)),
+    }))
+    .filter((spec) => spec.tests.length > 0);
+  next.suites = (Array.isArray(suite.suites) ? suite.suites : [])
+    .map((child) => selectedPlaywrightSuite(child, selectedTests))
+    .filter(Boolean);
+  return next.specs.length > 0 || next.suites.length > 0 ? next : null;
+}
+
+export function splitReportPages(format, report, maxTests = MAX_TESTS_PER_PAGE) {
+  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 }];
+  }
+
+  const document = parseJson(report.toString("utf8").replace(/^\uFEFF/, ""));
+  if (format === "generic") {
+    const tests = document.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;
+  }
+
+  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,
+    });
+  }
+  return pages;
+}
+
 function isLoopback(hostname) {
   return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
 }
@@ -130,6 +201,7 @@ export function parseUploadArgs(args) {
     branch: undefined,
     provider: undefined,
     ciUrl: undefined,
+    envFile: undefined,
     dryRun: false,
     reportPath: undefined,
   };
@@ -141,6 +213,7 @@ export function parseUploadArgs(args) {
     ["--branch", "branch"],
     ["--provider", "provider"],
     ["--ci-url", "ciUrl"],
+    ["--env-file", "envFile"],
   ]);
 
   for (let i = 0; i < args.length; i += 1) {
@@ -229,6 +302,41 @@ function integerEnv(value, fallback, min, max) {
   return Number.isInteger(parsed) && parsed >= min && parsed <= max ? parsed : fallback;
 }
 
+export function parseTokenEnvFile(contents) {
+  let token;
+  const lines = String(contents).replace(/^\uFEFF/, "").split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index].trim();
+    if (!line || line.startsWith("#")) continue;
+    const match = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+    if (!match || match[1] !== "TD_CI_TOKEN") continue;
+    if (token !== undefined) throw new CliError("env file contains TD_CI_TOKEN more than once.");
+
+    let value = match[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    } else {
+      value = value.replace(/\s+#.*$/, "").trim();
+    }
+    if (!value) throw new CliError(`TD_CI_TOKEN is empty in the env file (line ${index + 1}).`);
+    token = value;
+  }
+  if (token === undefined) throw new CliError("env file does not define TD_CI_TOKEN.");
+  return token;
+}
+
+async function tokenFromEnvFile(path, stderr) {
+  const fileStats = await stat(path).catch((error) => {
+    throw new CliError(`could not read env file: ${error.message}`);
+  });
+  if (!fileStats.isFile()) throw new CliError("env-file path must point to a file.");
+  if (fileStats.size > 64 * 1024) throw new CliError("env file is unexpectedly large (maximum 64 KiB).");
+  if (process.platform !== "win32" && (fileStats.mode & 0o077) !== 0) {
+    stderr(`Warning: ${path} is readable by other users; run chmod 600 "${path}".`);
+  }
+  return parseTokenEnvFile(await readFile(path, "utf8"));
+}
+
 function retryDelayMs(attempt, retryAfter, baseDelay) {
   if (retryAfter) {
     const seconds = Number(retryAfter);
@@ -303,18 +411,23 @@ Options:
   --branch <value>    Branch name
   --provider <value>  Provider label (defaults to local or detected CI)
   --ci-url <url>      Link to the originating CI run
+  --env-file <path>   Read TD_CI_TOKEN from this explicit dotenv file
   --dry-run           Validate and detect only; send nothing
   -h, --help          Show help
   --version           Show version
 
 Authentication:
-  Set TD_CI_TOKEN=td_... in the environment. Tokens are intentionally not
-  accepted as command-line arguments, keeping them out of shell history and
-  process listings.
+  Set TD_CI_TOKEN in the environment or pass --env-file .env.testdossier.
+  Tokens are intentionally not accepted as command-line arguments, keeping
+  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.
 
 Examples:
-  TD_CI_TOKEN=td_... npx testdossier upload playwright-results.json
-  TD_CI_TOKEN=td_... npx testdossier upload junit-results.xml --build abc123
+  npx testdossier upload playwright-results.json --env-file .env.testdossier
+  npx testdossier upload junit-results.xml --env-file .env.testdossier --build abc123
   npx testdossier upload testdossier-ci.json --dry-run`;
 }
 
@@ -331,6 +444,21 @@ function outputSummary(result, stdout, stderr) {
   }
 }
 
+function aggregatePageResults(results) {
+  const aggregate = { counts: {}, warnings: [] };
+  for (const result of results) {
+    if (result && result.counts && typeof result.counts === "object") {
+      for (const [name, value] of Object.entries(result.counts)) {
+        if (typeof value === "number") {
+          aggregate.counts[name] = (aggregate.counts[name] || 0) + value;
+        }
+      }
+    }
+    if (Array.isArray(result && result.warnings)) aggregate.warnings.push(...result.warnings);
+  }
+  return aggregate;
+}
+
 export async function runCli(
   args,
   {
@@ -372,45 +500,73 @@ export async function runCli(
     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 endpoint = normalizeEndpoint(options.url || env.TD_URL || DEFAULT_ORIGIN);
     const destination = new URL(endpoint).origin;
-    stdout(`Validated ${FORMAT_LABELS[format]} (${report.byteLength} bytes).`);
+    stdout(
+      `Validated ${FORMAT_LABELS[format]} (${report.byteLength} bytes` +
+      (testCount == null
+        ? ""
+        : `, ${testCount} tests${pages.length > 1 ? ` across ${pages.length} pages` : ""}`) +
+      ").",
+    );
     if (options.dryRun) {
       stdout(`Dry run complete; no data was sent to ${destination}.`);
       return 0;
     }
 
-    const token = env.TD_CI_TOKEN;
+    const token = options.envFile
+      ? await tokenFromEnvFile(options.envFile, stderr)
+      : env.TD_CI_TOKEN;
     if (!token || !token.startsWith("td_")) {
       throw new CliError("TD_CI_TOKEN is required and must be a TestDossier td_ access token.");
     }
     if (typeof fetchImpl !== "function") throw new CliError("Node 18 or newer is required (global fetch is unavailable).");
 
     const metadata = inferredMetadata(options, env);
-    const headers = {
+    const baseHeaders = {
       Authorization: `Bearer ${token}`,
       "Content-Type": format === "junit" ? "application/xml" : "application/json",
       "User-Agent": `testdossier-cli/${VERSION}`,
       "X-CI-Run-Id": metadata.runId,
-      "X-CI-Page-Id": "results",
       "X-CI-Provider": metadata.provider,
     };
-    if (format !== "junit" && format !== "generic") headers["X-CI-Format"] = format;
-    if (metadata.build) headers["X-Build"] = metadata.build;
-    if (metadata.branch) headers["X-Branch"] = metadata.branch;
-    if (metadata.ciUrl) headers["X-CI-URL"] = metadata.ciUrl;
-
-    const result = await postWithRetry({
-      endpoint,
-      headers,
-      body: report,
-      env,
-      fetchImpl,
-      stderr,
-    });
+    if (format !== "junit" && format !== "generic") baseHeaders["X-CI-Format"] = format;
+    if (metadata.build) baseHeaders["X-Build"] = metadata.build;
+    if (metadata.branch) baseHeaders["X-Branch"] = metadata.branch;
+    if (metadata.ciUrl) baseHeaders["X-CI-URL"] = metadata.ciUrl;
+
+    if (pages.length > 1) {
+      stdout(
+        `Uploading ${pages.reduce((sum, page) => sum + (page.tests || 0), 0)} tests in ` +
+        `${pages.length} pages (run ${metadata.runId}).`,
+      );
+    }
+    const pageResults = [];
+    for (let index = 0; index < pages.length; index += 1) {
+      const page = pages[index];
+      const result = await postWithRetry({
+        endpoint,
+        headers: {
+          ...baseHeaders,
+          "X-CI-Page-Id": pages.length === 1 ? "results" : String(index + 1),
+        },
+        body: page.body,
+        env,
+        fetchImpl,
+        stderr,
+      });
+      pageResults.push(result);
+      if (pages.length > 1) {
+        stdout(`Uploaded page ${index + 1}/${pages.length} (${page.tests} tests).`);
+      }
+    }
     stdout(`Uploaded ${FORMAT_LABELS[format]} to ${destination} (run ${metadata.runId}).`);
-    outputSummary(result, stdout, stderr);
+    outputSummary(aggregatePageResults(pageResults), stdout, stderr);
     return 0;
   } catch (error) {
     const message = error && error.message ? error.message : String(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdossier",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Upload completed test reports to TestDossier from a local machine or CI.",
   "type": "module",
   "bin": {
@@ -9,19 +9,15 @@
   "files": [
     "bin",
     "lib",
-    "README.md"
+    "README.md",
+    ".env.testdossier.example"
   ],
   "engines": {
     "node": ">=18"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/devkalu/test-dossier.git",
-    "directory": "cli"
-  },
   "homepage": "https://testdossier.com",
   "bugs": {
-    "url": "https://github.com/devkalu/test-dossier/issues"
+    "email": "support@testdossier.com"
   },
   "keywords": [
     "testing",