testdossier 0.1.0 → 0.1.1

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

@@ -2,9 +2,18 @@
 
 Upload a completed test report from a developer laptop, test machine, or CI job:
 
+Create `.env.testdossier` in the project containing the test report:
+
+```dotenv
+TD_CI_TOKEN=replace_with_your_td_token
+```
+
+Replace the placeholder with the CI-ingestion token shown once by TestDossier,
+then:
+
 ```bash
-export TD_CI_TOKEN="td_..."
-npx testdossier upload playwright-results.json
+chmod 600 .env.testdossier
+npx testdossier upload playwright-results.json --env-file .env.testdossier
 ```
 
 The CLI auto-detects Playwright JSON, Cypress JSON, Cucumber JSON, JUnit XML,
@@ -17,10 +26,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 +56,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
+npm install --save-dev testdossier
+cp node_modules/testdossier/.env.testdossier.example .env.testdossier
+```
+
+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
-export TD_CI_TOKEN="td_..."
+chmod 600 .env.testdossier
 ```
 
-For repeat use, install and pin the CLI in the test repository so its source and
-version are captured by the lockfile:
+Upload with:
 
 ```bash
-npm install --save-dev testdossier
-npx testdossier upload playwright-results.json
+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 +108,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,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.1";
 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]);
@@ -130,6 +130,7 @@ export function parseUploadArgs(args) {
     branch: undefined,
     provider: undefined,
     ciUrl: undefined,
+    envFile: undefined,
     dryRun: false,
     reportPath: undefined,
   };
@@ -141,6 +142,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 +231,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 +340,19 @@ 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.
 
 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`;
 }
 
@@ -381,7 +419,9 @@ export async function runCli(
       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.");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdossier",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Upload completed test reports to TestDossier from a local machine or CI.",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "bin",
     "lib",
-    "README.md"
+    "README.md",
+    ".env.testdossier.example"
   ],
   "engines": {
     "node": ">=18"