testdossier 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# TestDossier CLI
+
+Upload a completed test report from a developer laptop, test machine, or CI job:
+
+```bash
+export TD_CI_TOKEN="td_..."
+npx testdossier upload playwright-results.json
+```
+
+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.
+
+## 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 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.
+
+Before sending anything, inspect what the CLI detected:
+
+```bash
+npx testdossier 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` |
+
+Detection uses the report's contents, not its filename. If a custom reporter
+creates an ambiguous shape, pass `--format playwright`, `--format cypress`,
+`--format cucumber`, `--format junit`, or `--format generic`.
+
+## Local setup
+
+Create a project access token in TestDossier with the **CI ingestion**
+capability, copy it once, and place it in an environment variable:
+
+```bash
+export TD_CI_TOKEN="td_..."
+```
+
+For repeat use, install and pin the CLI in the test repository so its source and
+version are captured by the lockfile:
+
+```bash
+npm install --save-dev testdossier
+npx testdossier upload playwright-results.json
+```
+
+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
+```
+
+Useful metadata options:
+
+```bash
+npx testdossier upload junit-results.xml \
+  --run-id "local-2026-07-23-1" \
+  --build "abc123" \
+  --branch "main"
+```
+
+`--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.
+
+Run `npx testdossier --help` for every option.

package/bin/testdossier.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runCli } from "../lib/testdossier.mjs";
+
+process.exitCode = await runCli(process.argv.slice(2));

package/lib/testdossier.mjs

@@ -0,0 +1,420 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+
+export const VERSION = "0.1.0";
+const DEFAULT_ORIGIN = "https://testdossier.com";
+const MAX_REPORT_BYTES = 25 * 1024 * 1024;
+const RETRYABLE_STATUSES = new Set([408, 409, 425, 429, 500, 502, 503, 504]);
+const FORMAT_LABELS = {
+  cypress: "Cypress JSON",
+  playwright: "Playwright JSON",
+  cucumber: "Cucumber JSON",
+  junit: "JUnit XML",
+  generic: "generic TestDossier JSON",
+};
+
+export class CliError extends Error {
+  constructor(message, exitCode = 2) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}
+
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new CliError(`report is not valid JSON: ${error.message}`);
+  }
+}
+
+function matchingJsonFormats(value) {
+  const matches = [];
+  if (value && !Array.isArray(value) && typeof value === "object") {
+    if (Array.isArray(value.runs)) matches.push("cypress");
+    if (Array.isArray(value.suites)) matches.push("playwright");
+    if (Array.isArray(value.tests)) matches.push("generic");
+  }
+  if (Array.isArray(value)) matches.push("cucumber");
+  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;
+  }
+
+  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}.`);
+  }
+}
+
+export function detectReportFormat(text) {
+  const trimmed = text.replace(/^\uFEFF/, "").trimStart();
+  if (!trimmed) throw new CliError("report file is empty.");
+  if (trimmed.startsWith("<")) {
+    assertFormatShape("junit", trimmed);
+    return "junit";
+  }
+
+  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 (matches.length > 1) {
+    throw new CliError(`report shape is ambiguous (${matches.join(", ")}); pass --format explicitly.`);
+  }
+  return matches[0];
+}
+
+function isLoopback(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+
+export function normalizeEndpoint(input = DEFAULT_ORIGIN) {
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new CliError(`invalid TestDossier URL: ${input}`);
+  }
+  if (url.username || url.password) {
+    throw new CliError("TestDossier URL must not contain credentials.");
+  }
+  if (url.search || url.hash) {
+    throw new CliError("TestDossier URL must not contain a query string or fragment.");
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback(url.hostname))) {
+    throw new CliError("TestDossier URL must use HTTPS (HTTP is allowed only for localhost).");
+  }
+
+  const path = url.pathname.replace(/\/+$/, "");
+  if (!path) {
+    url.pathname = "/api/ci/ingest";
+  } else if (path !== "/api/ci/ingest") {
+    throw new CliError("TestDossier URL must be an origin or end with /api/ci/ingest.");
+  }
+  return url.toString();
+}
+
+function optionValue(args, index, inlineValue, option) {
+  if (inlineValue !== undefined) return [inlineValue, index];
+  const next = args[index + 1];
+  if (!next || next.startsWith("--")) throw new CliError(`${option} requires a value.`);
+  return [next, index + 1];
+}
+
+export function parseUploadArgs(args) {
+  const options = {
+    format: "auto",
+    url: undefined,
+    runId: undefined,
+    build: undefined,
+    branch: undefined,
+    provider: undefined,
+    ciUrl: undefined,
+    dryRun: false,
+    reportPath: undefined,
+  };
+  const valueOptions = new Map([
+    ["--format", "format"],
+    ["--url", "url"],
+    ["--run-id", "runId"],
+    ["--build", "build"],
+    ["--branch", "branch"],
+    ["--provider", "provider"],
+    ["--ci-url", "ciUrl"],
+  ]);
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      const equalsAt = arg.indexOf("=");
+      const name = equalsAt === -1 ? arg : arg.slice(0, equalsAt);
+      const inlineValue = equalsAt === -1 ? undefined : arg.slice(equalsAt + 1);
+      const property = valueOptions.get(name);
+      if (!property) throw new CliError(`unknown option: ${name}`);
+      const [value, consumedIndex] = optionValue(args, i, inlineValue, name);
+      if (!value) throw new CliError(`${name} requires a non-empty value.`);
+      options[property] = value;
+      i = consumedIndex;
+      continue;
+    }
+    if (options.reportPath) throw new CliError("upload accepts exactly one report file.");
+    options.reportPath = arg;
+  }
+
+  const formats = new Set(["auto", "cypress", "playwright", "cucumber", "junit", "generic"]);
+  options.format = String(options.format).toLowerCase();
+  if (!formats.has(options.format)) {
+    throw new CliError("--format must be auto, cypress, playwright, cucumber, junit, or generic.");
+  }
+  return options;
+}
+
+function boundedHeader(value, name, maxLength) {
+  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);
+}
+
+function boundedRunId(value) {
+  const normalized = boundedHeader(value, "run id", 1000);
+  if (normalized.length <= 120) return normalized;
+  const digest = createHash("sha256").update(normalized).digest("hex").slice(0, 20);
+  return `${normalized.slice(0, 95)}-${digest}`;
+}
+
+function defaultRunId() {
+  return `local-${Date.now()}-${randomUUID().slice(0, 8)}`;
+}
+
+function inferredMetadata(options, env) {
+  const runId = boundedRunId(
+    options.runId ||
+    env.TD_RUN_ID ||
+    (env.GITHUB_RUN_ID ? `${env.GITHUB_RUN_ID}-${env.GITHUB_RUN_ATTEMPT || 1}` : "") ||
+    (env.CI_PIPELINE_ID ? `${env.CI_PIPELINE_ID}-${env.CI_JOB_ID || 1}` : "") ||
+    env.BUILD_TAG ||
+    defaultRunId(),
+  );
+  const build = boundedHeader(
+    options.build || env.TD_BUILD || env.GITHUB_SHA || env.CI_COMMIT_SHA || env.GIT_COMMIT,
+    "build",
+    80,
+  );
+  const branch = boundedHeader(
+    options.branch || env.TD_BRANCH || env.GITHUB_REF_NAME || env.CI_COMMIT_REF_NAME || env.BRANCH_NAME,
+    "branch",
+    80,
+  );
+  const provider = boundedHeader(
+    options.provider || env.TD_PROVIDER ||
+      (env.GITHUB_ACTIONS ? "github_actions" : env.GITLAB_CI ? "gitlab_ci" : env.JENKINS_URL ? "jenkins" : "local"),
+    "provider",
+    80,
+  );
+  const ciUrl = boundedHeader(options.ciUrl || env.TD_CI_URL || env.CI_JOB_URL || env.BUILD_URL, "CI URL", 500);
+  return { runId, build, branch, provider, ciUrl };
+}
+
+function integerEnv(value, fallback, min, max) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed >= min && parsed <= max ? parsed : fallback;
+}
+
+function retryDelayMs(attempt, retryAfter, baseDelay) {
+  if (retryAfter) {
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1000, 300_000);
+    const date = Date.parse(retryAfter);
+    if (Number.isFinite(date)) return Math.min(Math.max(0, date - Date.now()), 300_000);
+  }
+  return Math.min(baseDelay * (2 ** (attempt - 1)), 30_000);
+}
+
+function responseError(status, body) {
+  const code = body && typeof body.error === "string" ? ` ${body.error}` : "";
+  const message = body && typeof body.message === "string" ? `: ${body.message.slice(0, 500)}` : "";
+  return `upload failed (${status})${code}${message}`;
+}
+
+async function postWithRetry({ endpoint, headers, body, env, fetchImpl, stderr }) {
+  const attempts = integerEnv(env.TD_UPLOAD_MAX_ATTEMPTS, 5, 1, 10);
+  const baseDelay = integerEnv(env.TD_UPLOAD_BASE_DELAY_MS, 1000, 1, 30_000);
+  const timeout = integerEnv(env.TD_UPLOAD_TIMEOUT_MS, 60_000, 1000, 300_000);
+  let lastNetworkError = "";
+
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    let response;
+    try {
+      response = await fetchImpl(endpoint, {
+        method: "POST",
+        headers,
+        body,
+        redirect: "error",
+        signal: AbortSignal.timeout(timeout),
+      });
+    } catch (error) {
+      lastNetworkError = error && error.message ? error.message : String(error);
+      if (attempt === attempts) break;
+      const wait = retryDelayMs(attempt, null, baseDelay);
+      stderr(`Network error; retrying ${attempt}/${attempts - 1} in ${wait}ms.`);
+      await new Promise((resolve) => setTimeout(resolve, wait));
+      continue;
+    }
+
+    const responseText = await response.text();
+    let responseBody = {};
+    try {
+      responseBody = responseText ? JSON.parse(responseText) : {};
+    } catch {
+      responseBody = {};
+    }
+    if (response.ok) return responseBody;
+    if (!RETRYABLE_STATUSES.has(response.status) || attempt === attempts) {
+      throw new CliError(responseError(response.status, responseBody), 1);
+    }
+    const wait = retryDelayMs(attempt, response.headers.get("retry-after"), baseDelay);
+    stderr(`Upload returned ${response.status}; retrying ${attempt}/${attempts - 1} in ${wait}ms.`);
+    await new Promise((resolve) => setTimeout(resolve, wait));
+  }
+
+  throw new CliError(`upload failed after ${attempts} attempt(s): ${lastNetworkError || "network error"}`, 1);
+}
+
+function helpText() {
+  return `TestDossier report uploader ${VERSION}
+
+Usage:
+  testdossier upload <report-file> [options]
+
+Options:
+  --format <format>   auto (default), cypress, playwright, cucumber, junit, generic
+  --url <url>         TestDossier origin or /api/ci/ingest endpoint
+  --run-id <id>       Stable idempotency key for this execution
+  --build <value>     Commit, build number, or release identifier
+  --branch <value>    Branch name
+  --provider <value>  Provider label (defaults to local or detected CI)
+  --ci-url <url>      Link to the originating CI run
+  --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.
+
+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 testdossier-ci.json --dry-run`;
+}
+
+function outputSummary(result, stdout, stderr) {
+  const counts = result && result.counts && typeof result.counts === "object" ? result.counts : null;
+  if (counts) {
+    const parts = Object.entries(counts)
+      .filter(([, value]) => typeof value === "number")
+      .map(([name, value]) => `${name}=${value}`);
+    if (parts.length) stdout(`Results: ${parts.join(", ")}`);
+  }
+  if (Array.isArray(result && result.warnings)) {
+    for (const warning of result.warnings) stderr(`Warning: ${String(warning)}`);
+  }
+}
+
+export async function runCli(
+  args,
+  {
+    env = process.env,
+    fetchImpl = globalThis.fetch,
+    stdout = (message) => console.log(message),
+    stderr = (message) => console.error(message),
+  } = {},
+) {
+  try {
+    if (args.includes("--version")) {
+      stdout(VERSION);
+      return 0;
+    }
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+      stdout(helpText());
+      return 0;
+    }
+    if (args[0] !== "upload") {
+      throw new CliError(`unknown command: ${args[0]}\n\n${helpText()}`);
+    }
+
+    const options = parseUploadArgs(args.slice(1));
+    if (options.help) {
+      stdout(helpText());
+      return 0;
+    }
+    if (!options.reportPath) throw new CliError("upload requires a report file.");
+
+    const fileStats = await stat(options.reportPath).catch((error) => {
+      throw new CliError(`could not read report file: ${error.message}`);
+    });
+    if (!fileStats.isFile()) throw new CliError("report path must point to a file.");
+    if (fileStats.size === 0) throw new CliError("report file is empty.");
+    if (fileStats.size > MAX_REPORT_BYTES) {
+      throw new CliError("report exceeds the 25 MiB request limit; split it before uploading.");
+    }
+    const report = await readFile(options.reportPath);
+    const reportText = report.toString("utf8");
+    const format = options.format === "auto" ? detectReportFormat(reportText) : options.format;
+    assertFormatShape(format, reportText);
+
+    const endpoint = normalizeEndpoint(options.url || env.TD_URL || DEFAULT_ORIGIN);
+    const destination = new URL(endpoint).origin;
+    stdout(`Validated ${FORMAT_LABELS[format]} (${report.byteLength} bytes).`);
+    if (options.dryRun) {
+      stdout(`Dry run complete; no data was sent to ${destination}.`);
+      return 0;
+    }
+
+    const token = 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 = {
+      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,
+    });
+    stdout(`Uploaded ${FORMAT_LABELS[format]} to ${destination} (run ${metadata.runId}).`);
+    outputSummary(result, stdout, stderr);
+    return 0;
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    stderr(`Error: ${message}`);
+    return error instanceof CliError ? error.exitCode : 1;
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "testdossier",
+  "version": "0.1.0",
+  "description": "Upload completed test reports to TestDossier from a local machine or CI.",
+  "type": "module",
+  "bin": {
+    "testdossier": "bin/testdossier.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "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"
+  },
+  "keywords": [
+    "testing",
+    "junit",
+    "playwright",
+    "cypress",
+    "cucumber",
+    "testdossier"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}