testdossier 0.2.0 → 0.2.2

package/README.md

@@ -3,14 +3,21 @@
 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. One-time setup — creates `.env.testdossier` with owner-only permissions and
+1. Install the latest CLI in the project. To pin a release instead, replace
+   `@latest` with an exact version such as `@0.2.2`:
+
+```bash
+npm install --save-dev testdossier@latest
+```
+
+2. One-time setup — creates `.env.testdossier` with owner-only permissions and
    adds it to `.gitignore`:
 
 ```bash
 npx testdossier init
 ```
 
-2. Paste the CI-ingestion token shown once by TestDossier into
+3. Paste the CI-ingestion token shown once by TestDossier into
    `.env.testdossier`, replacing the placeholder, then prove the wiring in
    seconds instead of after a full CI round-trip:
 
@@ -22,14 +29,14 @@ npx testdossier verify
 token is valid, has the CI-ingestion capability, and reaches the right
 project — and prints that project's name.
 
-3. Run your tests so they create a supported report. For example, with
+4. 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
 ```
 
-4. Upload the completed report:
+5. Upload the completed report:
 
 ```bash
 npx testdossier upload playwright-results.json
@@ -79,18 +86,18 @@ delete the file to change it.
 Before sending anything, inspect what the CLI detected:
 
 ```bash
-npx --yes testdossier@0.2.0 upload playwright-results.json --dry-run
+npx testdossier upload playwright-results.json --dry-run
 ```
 
 ## Supported reports
 
 | Runner or format | Example |
 |---|---|
-| Playwright JSON | `npx --yes testdossier@0.2.0 upload playwright-results.json` |
-| Cypress JSON | `npx --yes testdossier@0.2.0 upload cypress-results.json` |
-| Cucumber JSON | `npx --yes testdossier@0.2.0 upload cucumber-results.json` |
-| JUnit XML | `npx --yes testdossier@0.2.0 upload junit-results.xml` |
-| Generic JSON | `npx --yes testdossier@0.2.0 upload testdossier-ci.json` |
+| 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`,
@@ -103,10 +110,14 @@ 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
+npm install --save-dev testdossier@latest
 npx testdossier init
 ```
 
+Use `npm install --save-dev testdossier@0.2.2` when the repository should pin
+that exact release. In either case, subsequent commands remain
+`npx testdossier ...`; the version selector belongs only to installation.
+
 `init` is idempotent: it never overwrites an existing `.env.testdossier` and
 never duplicates the `.gitignore` entry. If you prefer manual setup, create
 `.env.testdossier` yourself with the single line
@@ -134,7 +145,8 @@ Useful metadata options:
 npx testdossier upload junit-results.xml \
   --run-id "local-2026-07-23-1" \
   --build "abc123" \
-  --branch "main"
+  --branch "main" \
+  --pipeline-id "github:acme/storefront:e2e"
 ```
 
 `--run-id` is the idempotency key. Repeating the same upload with the same run
@@ -145,18 +157,30 @@ 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.
 
+`--pipeline-id` identifies the stable repository/workflow/job that produced the
+run. It is inferred on supported CI providers and can also be set with
+`TD_PIPELINE_ID`. Keep it stable across access-token rotation: Insights uses it
+to let the latest completed result replace an earlier result from the same
+pipeline without allowing another repository's result to be overwritten.
+
 Run `npx testdossier --help` for every option.
 
 ## Using the same flow in CI
 
 Commit `testdossier.json` and set `TD_CI_TOKEN` in the provider's encrypted
-secret storage; the pipeline step is then `npx --yes testdossier@0.2.0` with
+secret storage; after the dependency install, the pipeline step is
+`npx testdossier` with
 no arguments. Run identity, build, branch, and provider metadata are inferred
 automatically on GitHub Actions, GitLab CI, Jenkins, Azure DevOps, Bitbucket
 Pipelines, and CircleCI. The Access Tokens dialog still generates
 provider-specific snippets that pass the report path explicitly — either style
 works; the explicit one fails louder when the report artifact is missing.
 
+Use `@latest` only when adding/updating the dependency. The lockfile then keeps
+CI reproducible, and normal invocations use the installed command without a
+version selector. Update or pin the dependency through your normal dependency
+update process.
+
 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

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { readFile, stat, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
 
-export const VERSION = "0.2.0";
+export const VERSION = "0.2.2";
 const DEFAULT_ORIGIN = "https://testdossier.com";
 const ENV_FILE_NAME = ".env.testdossier";
 const CONFIG_FILE_NAME = "testdossier.json";
@@ -326,8 +326,8 @@ export function normalizeEndpoint(input = DEFAULT_ORIGIN) {
   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.");
+  } else if (path !== "/api/ci/ingest" && path !== "/api/v1/ci/ingest") {
+    throw new CliError("TestDossier URL must be an origin or end with /api/ci/ingest (or its /api/v1 alias).");
   }
   return url.toString();
 }
@@ -347,6 +347,7 @@ export function parseUploadArgs(args) {
     build: undefined,
     branch: undefined,
     provider: undefined,
+    pipelineId: undefined,
     ciUrl: undefined,
     envFile: undefined,
     dryRun: false,
@@ -359,6 +360,7 @@ export function parseUploadArgs(args) {
     ["--build", "build"],
     ["--branch", "branch"],
     ["--provider", "provider"],
+    ["--pipeline-id", "pipelineId"],
     ["--ci-url", "ciUrl"],
     ["--env-file", "envFile"],
   ]);
@@ -569,6 +571,46 @@ function inferredProvider(env) {
   return "local";
 }
 
+function boundedPipelineId(value) {
+  const normalized = normalizedHeader(value, "pipeline id");
+  if (normalized.length <= 200) return normalized;
+  const digest = createHash("sha256").update(normalized).digest("hex").slice(0, 20);
+  return `${normalized.slice(0, 175)}-${digest}`;
+}
+
+function inferredPipelineId(env, provider) {
+  if (provider === "github_actions") {
+    const repository = env.GITHUB_REPOSITORY || "unknown-repository";
+    const refPrefix = `${repository}/`;
+    const workflowRef = String(env.GITHUB_WORKFLOW_REF || "").split("@")[0];
+    const workflow = workflowRef.startsWith(refPrefix)
+      ? workflowRef.slice(refPrefix.length)
+      : workflowRef || env.GITHUB_WORKFLOW || "workflow";
+    return [provider, repository, workflow, env.GITHUB_JOB || "job"].join(":");
+  }
+  if (provider === "gitlab_ci") {
+    return [provider, env.CI_PROJECT_PATH || "unknown-project", env.CI_JOB_NAME || "job"].join(":");
+  }
+  if (provider === "azure_devops") {
+    return [
+      provider,
+      env.SYSTEM_TEAMPROJECT || "unknown-project",
+      env.BUILD_REPOSITORY_NAME || env.BUILD_REPOSITORY_ID || "repository",
+      env.SYSTEM_DEFINITIONID || env.BUILD_DEFINITIONNAME || "pipeline",
+      env.SYSTEM_JOBDISPLAYNAME || env.SYSTEM_JOBID || "job",
+    ].join(":");
+  }
+  if (provider === "bitbucket_pipelines") {
+    return [provider, env.BITBUCKET_REPO_FULL_NAME || "unknown-repository"].join(":");
+  }
+  if (provider === "circleci") {
+    const repository = [env.CIRCLE_PROJECT_USERNAME, env.CIRCLE_PROJECT_REPONAME].filter(Boolean).join("/") || "unknown-repository";
+    return [provider, repository, env.CIRCLE_JOB || "job"].join(":");
+  }
+  if (provider === "jenkins") return [provider, env.JOB_NAME || "job"].join(":");
+  return `${provider || "local"}:local`;
+}
+
 function inferredMetadata(options, env) {
   // The job identifier is part of every inferred key: two jobs of one
   // workflow/pipeline run would otherwise share a run id, and the server
@@ -618,7 +660,10 @@ function inferredMetadata(options, env) {
     "CI URL",
     500,
   );
-  return { runId, build, branch, provider, ciUrl };
+  const pipelineId = boundedPipelineId(
+    options.pipelineId || env.TD_PIPELINE_ID || inferredPipelineId(env, provider),
+  );
+  return { runId, build, branch, provider, ciUrl, pipelineId };
 }
 
 function integerEnv(value, fallback, min, max) {
@@ -766,11 +811,12 @@ Usage:
 
 Options:
   --format <format>   auto (default), cypress, playwright, cucumber, junit, generic
-  --url <url>         TestDossier origin or /api/ci/ingest endpoint
+  --url <url>         TestDossier origin or ingest endpoint (/api/ci/ingest or /api/v1/ci/ingest)
   --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)
+  --pipeline-id <id>  Stable repository/workflow/job identity (normally inferred)
   --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
@@ -886,11 +932,19 @@ export async function runCli(
         stderr,
         action: "verify",
       });
-      const name = result && typeof result.project_name === "string" && result.project_name
+      // A 200 alone is not proof: a mis-pointed URL can hit an HTML page,
+      // which the response parser degrades to {}. Only the ingest handler's
+      // explicit verify marker + project identity count as success.
+      if (!result || result.verify !== true || !result.project_id) {
+        throw new CliError(
+          `verify got a successful response from ${new URL(endpoint).origin} that is not the TestDossier ingest API — check the --url / TD_URL destination.`,
+          1,
+        );
+      }
+      const name = typeof result.project_name === "string" && result.project_name
         ? ` "${result.project_name}"`
         : "";
-      const id = result && result.project_id ? ` (${result.project_id})` : "";
-      stdout(`Token verified for project${name}${id} at ${new URL(endpoint).origin} — CI ingestion enabled.`);
+      stdout(`Token verified for project${name} (${result.project_id}) at ${new URL(endpoint).origin} — CI ingestion enabled.`);
       return 0;
     }
 
@@ -950,6 +1004,7 @@ export async function runCli(
       "User-Agent": `testdossier-cli/${VERSION}`,
       "X-CI-Run-Id": metadata.runId,
       "X-CI-Provider": metadata.provider,
+      "X-CI-Pipeline-Id": metadata.pipelineId,
     };
     if (format !== "junit" && format !== "generic") baseHeaders["X-CI-Format"] = format;
     if (metadata.build) baseHeaders["X-Build"] = metadata.build;
@@ -975,6 +1030,9 @@ export async function runCli(
         headers: {
           ...baseHeaders,
           "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,
         env,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdossier",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Upload completed test reports to TestDossier from a local machine or CI.",
   "license": "MIT",
   "type": "module",