testdossier 0.1.3 → 0.2.0

package/README.md

@@ -1,38 +1,51 @@
 # TestDossier CLI
 
 Upload a completed test report from a developer laptop, test machine, or CI
-job. Run these steps in the project containing your automated tests:
+job. Run these commands in the project containing your automated tests:
 
-1. Create `.env.testdossier`:
+1. One-time setup — creates `.env.testdossier` with owner-only permissions and
+   adds it to `.gitignore`:
 
-```dotenv
-TD_CI_TOKEN=replace_with_your_td_token
+```bash
+npx testdossier init
 ```
 
-2. Replace the placeholder with the CI-ingestion token shown once by
-   TestDossier, add the file to `.gitignore`, and protect it:
+2. 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:
 
 ```bash
-chmod 600 .env.testdossier
+npx testdossier verify
 ```
 
+`verify` makes one authenticated request with no report data. It confirms the
+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
    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
-npx testdossier upload playwright-results.json --env-file .env.testdossier
+npx testdossier upload playwright-results.json
 ```
 
 `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.
+TestDossier. Use the actual report path produced by your runner.
+
+The first successful upload writes `testdossier.json` in the directory you ran
+the CLI from — the report path, plus `--format` and `--url` when you passed
+them. Commit that file; every later publish is just:
+
+```bash
+npx testdossier
+```
+
 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 JSON reports (Playwright, Cypress,
@@ -50,77 +63,75 @@ 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 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.
+The access token is read from the first available source: an explicitly passed
+`--env-file`, the `TD_CI_TOKEN` process environment, then `.env.testdossier` in
+the current directory (the CLI announces when it uses the discovered file).
+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.
+
+`testdossier.json` is deliberately never rewritten once it exists — an upload
+with a different path never silently repoints the committed default. Edit or
+delete the file to change it.
 
 Before sending anything, inspect what the CLI detected:
 
 ```bash
-npx --yes testdossier@0.1.3 upload playwright-results.json --dry-run
+npx --yes testdossier@0.2.0 upload playwright-results.json --dry-run
 ```
 
 ## Supported reports
 
 | Runner or format | Example |
 |---|---|
-| 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` |
+| 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` |
 
 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`.
+`--format cucumber`, `--format junit`, or `--format generic`. The `upload`
+word may be omitted: `npx testdossier playwright-results.json` works too.
 
 ## Local setup
 
-Create a project access token in TestDossier with the **CI ingestion**
-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:
+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
+npx testdossier init
 ```
 
-```bash
-chmod 600 .env.testdossier
-```
-
-Upload with:
-
-```bash
-npx testdossier upload playwright-results.json --env-file .env.testdossier
-```
+`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
+`TD_CI_TOKEN=replace_with_your_td_token`, replace the placeholder, gitignore
+the file, and `chmod 600` it.
 
 For a one-off session, setting `TD_CI_TOKEN` in the process environment still
-works. An explicitly passed `--env-file` takes precedence.
+works and takes precedence over the discovered file. An explicitly passed
+`--env-file` takes precedence over both.
 
 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 --env-file .env.testdossier
+npx testdossier upload junit-results.xml --url "https://dossier.example.com"
 ```
 
+`--url` is remembered in `testdossier.json` on the first successful upload, so
+later bare runs keep targeting the same instance. `TD_URL` in the environment
+also works and overrides the saved value.
+
 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"
@@ -136,10 +147,16 @@ conflict, and server errors are retried with the same run ID.
 
 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
+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.
+
 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. 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.
+provider's encrypted secret storage instead of an env file.

package/lib/testdossier.mjs

@@ -1,9 +1,13 @@
 import { createHash, randomUUID } from "node:crypto";
-import { readFile, stat } from "node:fs/promises";
-import { basename } from "node:path";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
 
-export const VERSION = "0.1.3";
+export const VERSION = "0.2.0";
 const DEFAULT_ORIGIN = "https://testdossier.com";
+const ENV_FILE_NAME = ".env.testdossier";
+const CONFIG_FILE_NAME = "testdossier.json";
+const TOKEN_PLACEHOLDER = "replace_with_your_td_token";
+const REPORT_FORMATS = new Set(["cypress", "playwright", "cucumber", "junit", "generic"]);
 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]);
@@ -385,14 +389,134 @@ export function parseUploadArgs(args) {
     options.reportPath = arg;
   }
 
-  const formats = new Set(["auto", "cypress", "playwright", "cucumber", "junit", "generic"]);
   options.format = String(options.format).toLowerCase();
-  if (!formats.has(options.format)) {
+  if (options.format !== "auto" && !REPORT_FORMATS.has(options.format)) {
     throw new CliError("--format must be auto, cypress, playwright, cucumber, junit, or generic.");
   }
   return options;
 }
 
+export async function readProjectConfig(cwd) {
+  const path = join(cwd, CONFIG_FILE_NAME);
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if (error && error.code === "ENOENT") return null;
+    throw new CliError(`could not read ${CONFIG_FILE_NAME}: ${error.message}`);
+  }
+  let value;
+  try {
+    value = JSON.parse(text.replace(/^\uFEFF/, ""));
+  } catch (error) {
+    throw new CliError(`${CONFIG_FILE_NAME} is not valid JSON: ${error.message}`);
+  }
+  if (!isObject(value)) throw new CliError(`${CONFIG_FILE_NAME} must be a JSON object.`);
+  const config = {};
+  if (value.report !== undefined) {
+    if (typeof value.report !== "string" || !value.report.trim()) {
+      throw new CliError(`${CONFIG_FILE_NAME} "report" must be a non-empty string.`);
+    }
+    config.report = value.report;
+  }
+  if (value.format !== undefined) {
+    const format = String(value.format).toLowerCase();
+    if (!REPORT_FORMATS.has(format)) {
+      throw new CliError(`${CONFIG_FILE_NAME} "format" must be cypress, playwright, cucumber, junit, or generic.`);
+    }
+    config.format = format;
+  }
+  if (value.url !== undefined) {
+    if (typeof value.url !== "string" || !value.url.trim()) {
+      throw new CliError(`${CONFIG_FILE_NAME} "url" must be a non-empty string.`);
+    }
+    config.url = value.url;
+  }
+  return config;
+}
+
+// A committed config must work on teammates' machines and Linux CI, so only
+// a cwd-relative POSIX path is worth remembering.
+function portableReportPath(cwd, reportPath) {
+  const rel = relative(cwd, resolve(cwd, reportPath));
+  if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return null;
+  return rel.split(sep).join("/");
+}
+
+// Created only when absent: the config is a committed project default, so an
+// upload must never silently repoint it. Users edit or delete the file.
+async function saveProjectConfig(cwd, options, stdout, stderr) {
+  const report = portableReportPath(cwd, options.reportPath);
+  if (!report) {
+    stderr(
+      `Warning: not saving ${CONFIG_FILE_NAME} — the report path points outside ` +
+      "this directory; run from the project root to remember it.",
+    );
+    return;
+  }
+  const saved = { report };
+  if (options.format !== "auto") saved.format = options.format;
+  if (options.url) saved.url = options.url;
+  try {
+    await writeFile(join(cwd, CONFIG_FILE_NAME), `${JSON.stringify(saved, null, 2)}\n`, { flag: "wx" });
+    stdout(`Saved report path to ${CONFIG_FILE_NAME}; commit it, and later runs are just: npx testdossier`);
+  } catch (error) {
+    if (error && error.code !== "EEXIST") {
+      stderr(`Warning: could not write ${CONFIG_FILE_NAME}: ${error.message}`);
+    }
+  }
+}
+
+async function runInit({ cwd, stdout }) {
+  const envPath = join(cwd, ENV_FILE_NAME);
+  const contents =
+    "# Replace the placeholder with the CI-ingestion token shown once by TestDossier.\n" +
+    `TD_CI_TOKEN=${TOKEN_PLACEHOLDER}\n`;
+  let created = false;
+  try {
+    await writeFile(envPath, contents, { flag: "wx", mode: 0o600 });
+    created = true;
+  } catch (error) {
+    if (!error || error.code !== "EEXIST") {
+      throw new CliError(`could not create ${ENV_FILE_NAME}: ${error && error.message}`);
+    }
+  }
+  stdout(created
+    ? `Created ${ENV_FILE_NAME} (readable only by you).`
+    : `${ENV_FILE_NAME} already exists; left unchanged.`);
+
+  const gitignorePath = join(cwd, ".gitignore");
+  let gitignore = "";
+  try {
+    gitignore = await readFile(gitignorePath, "utf8");
+  } catch (error) {
+    if (!error || error.code !== "ENOENT") {
+      throw new CliError(`could not read .gitignore: ${error && error.message}`);
+    }
+  }
+  const ignored = gitignore.split(/\r?\n/).some((line) => {
+    const entry = line.trim();
+    return entry === ENV_FILE_NAME || entry === `/${ENV_FILE_NAME}`;
+  });
+  if (!ignored) {
+    const separator = gitignore && !gitignore.endsWith("\n") ? "\n" : "";
+    try {
+      await writeFile(gitignorePath, `${gitignore}${separator}${ENV_FILE_NAME}\n`);
+    } catch (error) {
+      throw new CliError(`could not update .gitignore: ${error && error.message}`);
+    }
+    stdout(`Added ${ENV_FILE_NAME} to .gitignore.`);
+  }
+
+  stdout([
+    `Next: paste your td_ access token into ${ENV_FILE_NAME} (TestDossier → Access tokens), then upload a report:`,
+    "  npx testdossier upload <report-file>",
+    `The first successful upload remembers the report path in ${CONFIG_FILE_NAME}; after that:`,
+    "  npx testdossier",
+  ].join("\n"));
+  return 0;
+}
+
 function normalizedHeader(value, name) {
   if (value == null || value === "") return "";
   const normalized = String(value);
@@ -435,10 +559,20 @@ function defaultRunId() {
   return `local-${Date.now()}-${randomUUID().slice(0, 8)}`;
 }
 
+function inferredProvider(env) {
+  if (env.GITHUB_ACTIONS) return "github_actions";
+  if (env.GITLAB_CI) return "gitlab_ci";
+  if (env.TF_BUILD) return "azure_devops";
+  if (env.BITBUCKET_BUILD_NUMBER) return "bitbucket_pipelines";
+  if (env.CIRCLECI) return "circleci";
+  if (env.JENKINS_URL) return "jenkins";
+  return "local";
+}
+
 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.
+  // 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
+  // answers the second upload with an idempotent replay of the first.
   const runId = boundedRunId(
     options.runId ||
     env.TD_RUN_ID ||
@@ -446,26 +580,44 @@ function inferredMetadata(options, env) {
       ? [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_BUILDID
+      ? [env.BUILD_BUILDID, env.SYSTEM_JOBID, env.SYSTEM_JOBATTEMPT].filter(Boolean).join("-")
+      : "") ||
+    (env.BITBUCKET_BUILD_NUMBER
+      ? [
+        env.BITBUCKET_BUILD_NUMBER,
+        env.BITBUCKET_STEP_UUID,
+        env.BITBUCKET_STEP_RUN_NUMBER || 1,
+      ].filter(Boolean).join("-")
+      : "") ||
+    (env.CIRCLE_WORKFLOW_ID
+      ? [env.CIRCLE_WORKFLOW_ID, env.CIRCLE_WORKFLOW_JOB_ID || env.CIRCLE_JOB].filter(Boolean).join("-")
+      : "") ||
     env.BUILD_TAG ||
     defaultRunId(),
   );
   const build = boundedHeader(
-    options.build || env.TD_BUILD || env.GITHUB_SHA || env.CI_COMMIT_SHA || env.GIT_COMMIT,
+    options.build || env.TD_BUILD || env.GITHUB_SHA || env.CI_COMMIT_SHA ||
+      env.BUILD_SOURCEVERSION || env.BITBUCKET_COMMIT || env.CIRCLE_SHA1 || 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,
+    options.branch || env.TD_BRANCH || env.GITHUB_REF_NAME || env.CI_COMMIT_REF_NAME ||
+      env.BUILD_SOURCEBRANCHNAME || env.BITBUCKET_BRANCH || env.CIRCLE_BRANCH || 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"),
+    options.provider || env.TD_PROVIDER || inferredProvider(env),
     "provider",
     80,
   );
-  const ciUrl = boundedHeader(options.ciUrl || env.TD_CI_URL || env.CI_JOB_URL || env.BUILD_URL, "CI URL", 500);
+  const ciUrl = boundedHeader(
+    options.ciUrl || env.TD_CI_URL || env.CI_JOB_URL || env.CIRCLE_BUILD_URL || env.BUILD_URL,
+    "CI URL",
+    500,
+  );
   return { runId, build, branch, provider, ciUrl };
 }
 
@@ -509,6 +661,39 @@ async function tokenFromEnvFile(path, stderr) {
   return parseTokenEnvFile(await readFile(path, "utf8"));
 }
 
+// Single token-resolution path for upload and verify: --env-file, then the
+// process environment, then the init-created file in the working directory.
+async function resolveToken(options, env, cwd, stdout, stderr) {
+  let token;
+  if (options.envFile) {
+    token = await tokenFromEnvFile(options.envFile, stderr);
+  } else if (env.TD_CI_TOKEN) {
+    token = env.TD_CI_TOKEN;
+  } else {
+    const discovered = join(cwd, ENV_FILE_NAME);
+    const discoveredStats = await stat(discovered).catch(() => null);
+    if (discoveredStats && discoveredStats.isFile()) {
+      token = await tokenFromEnvFile(discovered, stderr);
+      stdout(`Using token from ${ENV_FILE_NAME}.`);
+    }
+  }
+  if (!token) {
+    throw new CliError(
+      `TD_CI_TOKEN is not set. Run \`npx testdossier init\` to create ${ENV_FILE_NAME}, ` +
+      "then paste your td_ access token into it.",
+    );
+  }
+  if (token === TOKEN_PLACEHOLDER) {
+    throw new CliError(
+      `TD_CI_TOKEN is still the placeholder; paste your real td_ access token into ${ENV_FILE_NAME}.`,
+    );
+  }
+  if (!token.startsWith("td_")) {
+    throw new CliError("TD_CI_TOKEN must be a TestDossier td_ access token.");
+  }
+  return token;
+}
+
 function retryDelayMs(attempt, retryAfter, baseDelay) {
   if (retryAfter) {
     const seconds = Number(retryAfter);
@@ -519,13 +704,13 @@ function retryDelayMs(attempt, retryAfter, baseDelay) {
   return Math.min(baseDelay * (2 ** (attempt - 1)), 30_000);
 }
 
-function responseError(status, body) {
+function responseError(status, body, action) {
   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}`;
+  return `${action} failed (${status})${code}${message}`;
 }
 
-async function postWithRetry({ endpoint, headers, body, env, fetchImpl, stderr }) {
+async function postWithRetry({ endpoint, headers, body, env, fetchImpl, stderr, action = "upload" }) {
   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);
@@ -559,21 +744,25 @@ async function postWithRetry({ endpoint, headers, body, env, fetchImpl, stderr }
     }
     if (response.ok) return responseBody;
     if (!RETRYABLE_STATUSES.has(response.status) || attempt === attempts) {
-      throw new CliError(responseError(response.status, responseBody), 1);
+      throw new CliError(responseError(response.status, responseBody, action), 1);
     }
     const wait = retryDelayMs(attempt, response.headers.get("retry-after"), baseDelay);
-    stderr(`Upload returned ${response.status}; retrying ${attempt}/${attempts - 1} in ${wait}ms.`);
+    stderr(`Server 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);
+  throw new CliError(`${action} failed after ${attempts} attempt(s): ${lastNetworkError || "network error"}`, 1);
 }
 
 function helpText() {
   return `TestDossier report uploader ${VERSION}
 
 Usage:
+  testdossier init                  One-time setup: create ${ENV_FILE_NAME} and gitignore it
+  testdossier verify                Check the token and destination without sending a report
   testdossier upload <report-file> [options]
+  testdossier <report-file> [options]    "upload" may be omitted
+  testdossier                       Upload the report remembered in ${CONFIG_FILE_NAME}
 
 Options:
   --format <format>   auto (default), cypress, playwright, cucumber, junit, generic
@@ -589,9 +778,17 @@ Options:
   --version           Show version
 
 Authentication:
-  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.
+  The token is read from the first available source: --env-file, the
+  TD_CI_TOKEN process environment, then ${ENV_FILE_NAME} in the current
+  directory (created by "testdossier init"). Tokens are intentionally not
+  accepted as command-line arguments, keeping them out of shell history
+  and process listings.
+
+Project config:
+  The first successful upload writes ${CONFIG_FILE_NAME} (the report path,
+  plus --format and --url when passed) if the file does not exist. Commit
+  it; later runs are just "npx testdossier". Edit or delete the file to
+  change the saved defaults — uploads never rewrite an existing config.
 
 Large reports:
   JSON reports (Playwright, Cypress, Cucumber, generic) above 200 tests are
@@ -600,9 +797,12 @@ Large reports:
   split it per suite or switch the runner to a JSON reporter.
 
 Examples:
-  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`;
+  npx testdossier init
+  npx testdossier verify
+  npx testdossier upload playwright-results.json
+  npx testdossier upload junit-results.xml --build abc123
+  npx testdossier upload testdossier-ci.json --dry-run
+  npx testdossier`;
 }
 
 function outputSummary(result, stdout, stderr) {
@@ -646,6 +846,7 @@ export async function runCli(
     fetchImpl = globalThis.fetch,
     stdout = (message) => console.log(message),
     stderr = (message) => console.error(message),
+    cwd = process.cwd(),
   } = {},
 ) {
   try {
@@ -653,20 +854,65 @@ export async function runCli(
       stdout(VERSION);
       return 0;
     }
-    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    if (args[0] === "--help" || args[0] === "-h") {
       stdout(helpText());
       return 0;
     }
-    if (args[0] !== "upload") {
-      throw new CliError(`unknown command: ${args[0]}\n\n${helpText()}`);
+    if (args[0] === "init") {
+      if (args.length > 1) throw new CliError("init takes no arguments.");
+      return await runInit({ cwd, stdout });
+    }
+    if (args[0] === "verify") {
+      const options = parseUploadArgs(args.slice(1));
+      if (options.help) {
+        stdout(helpText());
+        return 0;
+      }
+      if (options.reportPath) throw new CliError("verify takes no report file.");
+      const config = await readProjectConfig(cwd);
+      const endpoint = normalizeEndpoint(options.url || env.TD_URL || (config && config.url) || DEFAULT_ORIGIN);
+      const token = await resolveToken(options, env, cwd, stdout, stderr);
+      if (typeof fetchImpl !== "function") throw new CliError("Node 18 or newer is required (global fetch is unavailable).");
+      const result = await postWithRetry({
+        endpoint,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "User-Agent": `testdossier-cli/${VERSION}`,
+          "X-CI-Verify": "1",
+        },
+        body: null,
+        env,
+        fetchImpl,
+        stderr,
+        action: "verify",
+      });
+      const name = result && 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.`);
+      return 0;
     }
 
-    const options = parseUploadArgs(args.slice(1));
+    const options = parseUploadArgs(args[0] === "upload" ? args.slice(1) : args);
     if (options.help) {
       stdout(helpText());
       return 0;
     }
-    if (!options.reportPath) throw new CliError("upload requires a report file.");
+    const config = await readProjectConfig(cwd);
+    if (!options.reportPath && config && config.report) {
+      options.reportPath = config.report;
+      stdout(`Using report ${config.report} from ${CONFIG_FILE_NAME}.`);
+    }
+    if (!options.reportPath) {
+      if (args.length === 0) {
+        stdout(helpText());
+        return 0;
+      }
+      throw new CliError(
+        `upload requires a report file (pass a path, or run one upload with a path to save it in ${CONFIG_FILE_NAME}).`,
+      );
+    }
 
     const fileStats = await stat(options.reportPath).catch((error) => {
       throw new CliError(`could not read report file: ${error.message}`);
@@ -678,11 +924,12 @@ export async function runCli(
     }
     const report = await readFile(options.reportPath);
     const reportText = report.toString("utf8");
-    const { format, document } = analyzeReport(reportText, options.format);
+    const requestedFormat = options.format !== "auto" ? options.format : (config && config.format) || "auto";
+    const { format, document } = analyzeReport(reportText, requestedFormat);
     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 endpoint = normalizeEndpoint(options.url || env.TD_URL || (config && config.url) || DEFAULT_ORIGIN);
     const destination = new URL(endpoint).origin;
     stdout(
       `Validated ${FORMAT_LABELS[format]} (${report.byteLength} bytes, ${testCount} tests` +
@@ -693,12 +940,7 @@ export async function runCli(
       return 0;
     }
 
-    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.");
-    }
+    const token = await resolveToken(options, env, cwd, stdout, stderr);
     if (typeof fetchImpl !== "function") throw new CliError("Node 18 or newer is required (global fetch is unavailable).");
 
     const metadata = inferredMetadata(options, env);
@@ -753,6 +995,7 @@ export async function runCli(
         : `Note: ${replayed} of ${pageResults.length} pages were idempotent replays of an earlier upload (run ${metadata.runId}).`);
     }
     outputSummary(aggregatePageResults(pageResults), stdout, stderr);
+    if (!config) await saveProjectConfig(cwd, options, 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.3",
+  "version": "0.2.0",
   "description": "Upload completed test reports to TestDossier from a local machine or CI.",
   "license": "MIT",
   "type": "module",