@datadisco/qa 0.1.1 → 0.3.0

package/README.md

@@ -3,9 +3,15 @@
 CI companion for [DataDisco QA](https://datadisco.com) — PR-triggered persona
 simulation ("confirmation testing for agentic teams").
 
-> **Status: pre-release.** The commands below are wired to the DataDisco QA
-> API but the package is not published to npm yet. Pin to the git repo, or
-> wait for the first tagged release.
+## Install
+
+```sh
+npm i -g @datadisco/qa     # or run ad hoc: npx @datadisco/qa <command>
+```
+
+Most teams consume it through the
+[`Data-Disco-Inc/qa-action`](https://github.com/Data-Disco-Inc/qa-action)
+GitHub Action, which wraps this CLI — see its README for the workflow snippet.
 
 ## Why this exists
 
@@ -32,29 +38,92 @@ to the hosted app and is overridable with `--api-url` / `DATADISCO_API_URL`.
 export DATADISCO_API_TOKEN=ddqa_xxx
 ```
 
+## Works in any CI
+
+`report-preview` and `wait` auto-detect the repository, PR number, and head
+SHA from whatever CI they're running in — GitHub Actions gets full support out
+of the box, and every other CI (or a bare git checkout) still works with zero
+flags in the common case:
+
+```sh
+DATADISCO_API_TOKEN=ddqa_xxx npx @datadisco/qa report-preview --url https://pr-482.preview.acme.dev
+```
+
+Each value is resolved through its own chain of fallbacks, in order, stopping
+at the first one that resolves:
+
+| Value      | Resolution order                                                                                                                         |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Repository | `--repo` → `$GITHUB_REPOSITORY` → the git checkout's github.com `origin` remote                                                          |
+| Head SHA   | `--sha` → the GitHub Actions `pull_request` event payload → `$GITHUB_SHA` → the git checkout's `HEAD`                                    |
+| PR number  | `--pr` → GitHub Actions (`GITHUB_REF` / event payload) → CircleCI, Jenkins, Buildkite, Travis CI, or Drone's PR env var → _(unresolved)_ |
+
+`--repo`, `--pr`, and `--sha` always override auto-detection when passed.
+
+Unlike the repository and head SHA, the PR number is allowed to stay
+unresolved: `report-preview` will still report the preview URL with just the
+repo + head SHA, and the DataDisco server resolves the PR from the commit
+itself. `wait` needs _either_ a PR number or a head SHA to poll by — pass
+`--sha` explicitly if neither auto-detects (e.g. a CI DataDisco doesn't
+recognize yet).
+
+| CI                | Repo                | Head SHA                              | PR number                                                         |
+| ----------------- | ------------------- | ------------------------------------- | ----------------------------------------------------------------- |
+| GitHub Actions    | `GITHUB_REPOSITORY` | `pull_request` payload / `GITHUB_SHA` | `GITHUB_REF` / `pull_request` payload                             |
+| CircleCI          | git origin remote   | git `HEAD`                            | `CIRCLE_PULL_REQUEST` / `CIRCLE_PR_NUMBER`                        |
+| Jenkins           | git origin remote   | git `HEAD`                            | `CHANGE_ID`                                                       |
+| Buildkite         | git origin remote   | git `HEAD`                            | `BUILDKITE_PULL_REQUEST`                                          |
+| Travis CI         | git origin remote   | git `HEAD`                            | `TRAVIS_PULL_REQUEST`                                             |
+| Drone             | git origin remote   | git `HEAD`                            | `DRONE_PULL_REQUEST`                                              |
+| Bare git checkout | git origin remote   | git `HEAD`                            | not auto-detected — pass `--pr` or rely on server-side resolution |
+
+The git `origin` remote fallback only recognizes github.com remotes (SSH or
+HTTPS); for anything else, pass `--repo` explicitly.
+
 ## Commands
 
 ### `report-preview`
 
 Report the deployed preview URL for a PR head SHA so its pending QA run leaves
-`PENDING_PREVIEW` and starts. In GitHub Actions, `--repo`, `--pr`, and `--sha`
-are auto-detected from the `pull_request` event.
+`PENDING_PREVIEW` and starts. `--repo`, `--pr`, and `--sha` are auto-detected —
+see [Works in any CI](#works-in-any-ci) — and the PR number is optional: if it
+can't be auto-detected, the server resolves it from the head SHA itself.
 
 ```sh
 datadisco-qa report-preview --url https://pr-482.preview.acme.dev
-# explicit outside Actions:
+# explicit, e.g. outside any auto-detected CI:
 datadisco-qa report-preview \
   --url https://pr-482.preview.acme.dev \
   --repo acme/site --pr 482 --sha "$GIT_SHA"
 ```
 
+The server debounces rapid pushes for up to 10 minutes before creating the QA
+run row, and CI often reports the preview URL before that row exists. By
+default `report-preview` handles this for you: on the server's "no QA run is
+waiting on a preview URL yet" response it retries every 30s for up to
+**12 minutes**, then fails with a hint if the run never showed up. Any other
+failure (bad token, invalid URL, repo not connected) still fails immediately —
+only the "not created yet" case is retried. The server can also mark an error
+as permanently non-retryable (e.g. the PR is closed, a draft, or the head SHA
+is stale) — those fail immediately too, with the server's error code in the
+message, instead of burning the retry window.
+
+| Flag                           | Effect                                                   |
+| ------------------------------ | -------------------------------------------------------- |
+| `--no-wait-for-run`            | Fail immediately instead of retrying (previous behavior) |
+| `--wait-run-timeout <minutes>` | Cap the retry window (default 12)                        |
+
 ### `wait`
 
 Block until the PR's QA run reaches a verdict, printing each phase transition.
-Polls every 15s; `--timeout` (minutes, default 30) caps the wait.
+Polls every 15s; `--timeout` (minutes, default 30) caps the wait. `--repo` and
+`--pr` are auto-detected the same way as `report-preview`; if the PR number
+isn't detectable, pass `--sha` to poll by head SHA instead.
 
 ```sh
 datadisco-qa wait --pr 482
+# or, when the PR number isn't auto-detected:
+datadisco-qa wait --sha "$GIT_SHA"
 ```
 
 **Exit codes** (so pipelines can branch on the outcome):
@@ -92,8 +161,31 @@ node dist/cli.js --help
 Same toolchain as [datadisco-mcp](https://github.com/Data-Disco-Inc/datadisco-mcp):
 tsup, vitest, oxlint/oxfmt, cac.
 
-## Publishing (later)
+## Releasing
+
+Publishing is automated via npm [trusted publishing](https://docs.npmjs.com/trusted-publishers)
+(OIDC — no token). Cut a release with:
+
+```sh
+npm version <patch|minor|major>   # bumps package.json + lockfile, commits, tags vX.Y.Z
+git push origin main --follow-tags
+```
+
+Pushing the `v*` tag runs [`release.yml`](.github/workflows/release.yml), which
+verifies the tag matches `package.json`, runs the tests, and `npm publish`es
+with provenance. Prerelease tags (`vX.Y.Z-beta.1`) publish under the `next`
+dist-tag so `latest` keeps pointing at the newest stable release.
+
+### Lockfile note
+
+The toolchain (rolldown/rollup/esbuild) ships platform-native binaries plus a
+wasm fallback whose `@emnapi/*` deps [npm drops from a macOS-generated
+lockfile](https://github.com/npm/cli/issues/4828) — which then fails `npm ci` on
+the Linux CI runner. A plain `npm install` locally is fine for day-to-day work
+(just don't commit the resulting lockfile). If you actually change dependencies,
+regenerate the lockfile on Linux so it stays complete:
 
-1. Bump the version and tag.
-2. `npm publish` (publishConfig is already `access: public`).
-3. Ship the companion GitHub Action (`Data-Disco-Inc/qa-action`) that wraps this CLI.
+```sh
+rm -f package-lock.json
+docker run --rm --platform linux/amd64 -v "$PWD":/app -w /app node:20 npm install
+```

package/dist/cli.js

@@ -35,60 +35,137 @@ function assertValidPreviewUrl(url) {
 
 // src/context.ts
 import { readFileSync } from "fs";
+
+// src/git.ts
+import { execFileSync } from "child_process";
+var defaultRunner = (args) => execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+function detectRepoFullName(run2 = defaultRunner) {
+  const remote = tryGit(run2, ["remote", "get-url", "origin"]);
+  return remote ? parseRepoFromRemote(remote) : void 0;
+}
+function detectHeadSha(run2 = defaultRunner) {
+  return tryGit(run2, ["rev-parse", "HEAD"]);
+}
+function parseRepoFromRemote(remote) {
+  const match = remote.match(/github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?$/);
+  return match ? match[1] : void 0;
+}
+function tryGit(run2, args) {
+  try {
+    return run2(args) || void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/context.ts
 var REPO_PATTERN = /^[^/\s]+\/[^/\s]+$/;
 var PR_REF_PATTERN = /^refs\/pull\/(\d+)\//;
-function resolvePrContext(input = {}) {
+var REPO_MISSING_MESSAGE = "Repository not set: pass --repo owner/name (auto-detected from the GitHub Actions env or a github.com origin remote on the git checkout).";
+var HEAD_SHA_MISSING_MESSAGE = "Head SHA not set: pass --sha <sha> (auto-detected from the GitHub Actions env or the git checkout's HEAD).";
+var PR_NUMBER_MISSING_MESSAGE = "Pull request number not set: pass --pr <number> (auto-detected in GitHub Actions, CircleCI, Jenkins, Buildkite, Travis CI, and Drone).";
+var PR_OR_SHA_MISSING_MESSAGE = "Neither a pull request number nor a head SHA could be resolved: pass --pr <number> or --sha <sha> (or run inside a supported CI, or a git checkout).";
+function resolveRunContext(input = {}) {
+  const context = resolveRunContextAllowingShaOnly(input);
+  if (context.prNumber === void 0) {
+    throw new ConfigError(PR_NUMBER_MISSING_MESSAGE);
+  }
+  return { ...context, prNumber: context.prNumber };
+}
+function resolveRunContextAllowingShaOnly(input = {}) {
   const env = input.env ?? process.env;
   const payload = loadEventPayload(input, env);
+  const headSha = resolveHeadSha(input, env, payload) ?? detectHeadSha(input.gitRunner);
+  if (!headSha) {
+    throw new ConfigError(HEAD_SHA_MISSING_MESSAGE);
+  }
   return {
     repo: resolveRepo(input, env),
-    prNumber: resolvePrNumber(input, env, payload)
+    prNumber: resolvePrNumber(input, env, payload),
+    headSha
   };
 }
-function resolveRunContext(input = {}) {
+function resolvePrContext(input = {}) {
   const env = input.env ?? process.env;
   const payload = loadEventPayload(input, env);
-  return {
-    repo: resolveRepo(input, env),
-    prNumber: resolvePrNumber(input, env, payload),
-    headSha: resolveHeadSha(input, env, payload)
-  };
+  const prNumber = resolvePrNumber(input, env, payload);
+  const knownHeadSha = resolveHeadSha(input, env, payload);
+  const headSha = prNumber === void 0 ? knownHeadSha ?? detectHeadSha(input.gitRunner) : knownHeadSha;
+  if (prNumber === void 0 && !headSha) {
+    throw new ConfigError(PR_OR_SHA_MISSING_MESSAGE);
+  }
+  return { repo: resolveRepo(input, env), prNumber, headSha };
 }
 function resolveRepo(input, env = {}) {
-  const repo = input.repo ?? env.GITHUB_REPOSITORY;
+  const repo = input.repo ?? env.GITHUB_REPOSITORY ?? detectRepoFullName(input.gitRunner);
   if (!repo) {
-    throw new ConfigError(
-      "Repository not set: pass --repo owner/name (auto-detected from $GITHUB_REPOSITORY in GitHub Actions)."
-    );
+    throw new ConfigError(REPO_MISSING_MESSAGE);
   }
   if (!REPO_PATTERN.test(repo)) {
     throw new ConfigError(`--repo must look like "owner/name", got "${repo}".`);
   }
   return repo;
 }
+function resolveHeadSha(input, env = {}, payload) {
+  return input.sha ?? payload.headSha ?? env.GITHUB_SHA;
+}
 function resolvePrNumber(input, env = {}, payload) {
-  const candidate = input.pr ?? parsePrFromRef(env.GITHUB_REF) ?? payload.prNumber;
-  const prNumber = Number(candidate);
-  if (candidate === void 0 || !Number.isInteger(prNumber) || prNumber <= 0) {
-    throw new ConfigError(
-      "Pull request number not set: pass --pr <number> (auto-detected from the pull_request event in GitHub Actions)."
-    );
-  }
-  return prNumber;
+  const candidate = input.pr ?? parsePrFromRef(env.GITHUB_REF) ?? payload.prNumber ?? resolvePrNumberFromCiEnv(env);
+  return toPositiveInteger(candidate);
 }
-function resolveHeadSha(input, env = {}, payload) {
-  const headSha = input.sha ?? payload.headSha ?? env.GITHUB_SHA;
-  if (!headSha) {
-    throw new ConfigError(
-      "Head SHA not set: pass --sha <sha> (the commit the preview was built from)."
-    );
-  }
-  return headSha;
+function toPositiveInteger(candidate) {
+  if (candidate === void 0) return void 0;
+  const parsed = Number(candidate);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : void 0;
 }
 function parsePrFromRef(ref) {
   const match = ref?.match(PR_REF_PATTERN);
   return match ? match[1] : void 0;
 }
+var CI_PR_ENV_SOURCES = [
+  {
+    // CircleCI: CIRCLE_PULL_REQUEST is a URL (https://github.com/o/r/pull/123);
+    // CIRCLE_PR_NUMBER is a plain number and is checked as a fallback.
+    ci: "CircleCI",
+    read: (env) => numericPrCandidate(trailingNumber(env.CIRCLE_PULL_REQUEST)) ?? numericPrCandidate(env.CIRCLE_PR_NUMBER)
+  },
+  {
+    // Jenkins (Multibranch/PR builders): CHANGE_ID is the PR number.
+    ci: "Jenkins",
+    read: (env) => numericPrCandidate(env.CHANGE_ID)
+  },
+  {
+    // Buildkite: BUILDKITE_PULL_REQUEST is "false" on non-PR builds.
+    ci: "Buildkite",
+    read: (env) => numericPrCandidate(env.BUILDKITE_PULL_REQUEST)
+  },
+  {
+    // Travis CI: TRAVIS_PULL_REQUEST is "false" on non-PR builds.
+    ci: "Travis CI",
+    read: (env) => numericPrCandidate(env.TRAVIS_PULL_REQUEST)
+  },
+  {
+    // Drone: DRONE_PULL_REQUEST is the PR number, unset outside PR builds.
+    ci: "Drone",
+    read: (env) => numericPrCandidate(env.DRONE_PULL_REQUEST)
+  }
+];
+function resolvePrNumberFromCiEnv(env) {
+  for (const source of CI_PR_ENV_SOURCES) {
+    const candidate = source.read(env);
+    if (candidate !== void 0) return candidate;
+  }
+  return void 0;
+}
+function trailingNumber(value) {
+  const match = value?.match(/(\d+)\/?$/);
+  return match?.[1];
+}
+function numericPrCandidate(value) {
+  if (!value || value === "false") return void 0;
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? value : void 0;
+}
 function loadEventPayload(input, env = {}) {
   const read = input.readEventPayload ?? (() => readEventFile(env.GITHUB_EVENT_PATH));
   const raw = safeRead(read);
@@ -120,6 +197,21 @@ function numberOrUndefined(value) {
 function stringOrUndefined(value) {
   return typeof value === "string" ? value : void 0;
 }
+function describeContextTarget(context) {
+  if (context.prNumber !== void 0) return `${context.repo}#${context.prNumber}`;
+  if (context.headSha) return `${context.repo}@${context.headSha}`;
+  return context.repo;
+}
+
+// src/legacy-server.ts
+var LEGACY_SERVER_BAD_REQUEST_STATUS = 400;
+function isUnresolvedPrOnLegacyServer(options) {
+  return !options.prNumberKnown && options.status === LEGACY_SERVER_BAD_REQUEST_STATUS && !options.code;
+}
+var LEGACY_SERVER_PR_HINT = "if this is an older DataDisco server, pass --pr <number> explicitly";
+function withLegacyServerPrHint(error) {
+  return `${error} (${LEGACY_SERVER_PR_HINT})`;
+}
 
 // src/api.ts
 var REPORT_PREVIEW_PATH = "/api/qa/report-preview";
@@ -148,12 +240,18 @@ async function reportPreview(config, params, fetchImpl) {
   if (response.ok && isString(payload.runId)) {
     return { ok: true, runId: payload.runId };
   }
-  return { ok: false, status: response.status, error: errorMessage(payload) };
+  return {
+    ok: false,
+    status: response.status,
+    error: errorMessage(payload),
+    retryable: booleanOrUndefined(payload.retryable),
+    code: stringOrUndefined2(payload.code)
+  };
 }
 async function getRunStatus(config, params, fetchImpl) {
   const url = new URL(joinUrl(config.apiUrl, RUN_STATUS_PATH));
   url.searchParams.set("repo", params.repo);
-  url.searchParams.set("prNumber", String(params.prNumber));
+  setRunLookupParam(url, params);
   const response = await fetchImpl(url.toString(), {
     headers: { authorization: `Bearer ${config.apiToken}` }
   });
@@ -161,7 +259,19 @@ async function getRunStatus(config, params, fetchImpl) {
   if (response.ok && isRunStatus(payload.run)) {
     return { ok: true, run: payload.run };
   }
-  return { ok: false, status: response.status, error: errorMessage(payload) };
+  return {
+    ok: false,
+    status: response.status,
+    error: errorMessage(payload),
+    code: stringOrUndefined2(payload.code)
+  };
+}
+function setRunLookupParam(url, params) {
+  if (params.prNumber !== void 0) {
+    url.searchParams.set("prNumber", String(params.prNumber));
+  } else if (params.headSha) {
+    url.searchParams.set("headSha", params.headSha);
+  }
 }
 function joinUrl(base, path) {
   return `${base.replace(/\/+$/, "")}${path}`;
@@ -183,6 +293,12 @@ function isRecord2(value) {
 function isString(value) {
   return typeof value === "string";
 }
+function stringOrUndefined2(value) {
+  return isString(value) ? value : void 0;
+}
+function booleanOrUndefined(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
 function isRunStatus(value) {
   return isRecord2(value) && isString(value.id) && isString(value.status) && typeof value.blockerCount === "number";
 }
@@ -212,56 +328,6 @@ var defaultDeps = {
   now: () => Date.now()
 };
 
-// src/commands/report-preview.ts
-async function runReportPreview(options, deps = defaultDeps) {
-  if (!options.url) {
-    deps.logger.error("--url is required (the deployed preview URL).");
-    return 1;
-  }
-  assertValidPreviewUrl(options.url);
-  const config = resolveConfig(options);
-  const context = resolveRunContext(options);
-  const api = deps.createApi(config);
-  const outcome = await api.reportPreview({ ...context, url: options.url });
-  if (!outcome.ok) {
-    deps.logger.error(`Could not report preview URL: ${outcome.error}`);
-    return 1;
-  }
-  deps.logger.success(
-    `Preview reported for ${context.repo}#${context.prNumber} \u2014 QA run ${outcome.runId} queued.`
-  );
-  return 0;
-}
-
-// src/git.ts
-import { execFileSync } from "child_process";
-var defaultRunner = (args) => execFileSync("git", args, { encoding: "utf8" }).trim();
-function detectRepoFullName(run2 = defaultRunner) {
-  const remote = tryGit(run2, ["remote", "get-url", "origin"]);
-  return remote ? parseRepoFromRemote(remote) : void 0;
-}
-function detectHeadSha(run2 = defaultRunner) {
-  return tryGit(run2, ["rev-parse", "HEAD"]);
-}
-function parseRepoFromRemote(remote) {
-  const match = remote.match(/github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?$/);
-  return match ? match[1] : void 0;
-}
-function tryGit(run2, args) {
-  try {
-    return run2(args) || void 0;
-  } catch {
-    return void 0;
-  }
-}
-
-// src/tunnel-provider.ts
-import localtunnel from "localtunnel";
-async function openTunnel(port) {
-  const tunnel = await localtunnel({ port });
-  return { url: tunnel.url, close: () => tunnel.close() };
-}
-
 // src/verdict.ts
 var EXIT_CODE = {
   PASSED: 0,
@@ -339,7 +405,7 @@ var POLL_INTERVAL_MS = 15e3;
 var MINUTE_MS = 6e4;
 async function waitForVerdict(api, context, deps, timeoutMs) {
   const deadline = deps.now() + timeoutMs;
-  deps.logger.info(`Waiting for QA verdict on ${context.repo}#${context.prNumber}\u2026`);
+  deps.logger.info(`Waiting for QA verdict on ${describeContextTarget(context)}\u2026`);
   let lastStatus;
   while (true) {
     const outcome = await api.getRunStatus(context);
@@ -354,7 +420,9 @@ async function waitForVerdict(api, context, deps, timeoutMs) {
         return verdict.exitCode;
       }
     } else if (outcome.status !== 404) {
-      deps.logger.error(`Could not read QA run status: ${outcome.error}`);
+      deps.logger.error(
+        `Could not read QA run status: ${describeRunStatusFailure(outcome, context)}`
+      );
       return 1;
     }
     if (deps.now() >= deadline) {
@@ -366,11 +434,25 @@ async function waitForVerdict(api, context, deps, timeoutMs) {
     await deps.sleep(POLL_INTERVAL_MS);
   }
 }
-function resolveTimeoutMs(timeout) {
-  if (timeout === void 0) return DEFAULT_TIMEOUT_MINUTES * MINUTE_MS;
+function describeRunStatusFailure(outcome, context) {
+  if (isUnresolvedPrOnLegacyServer({
+    prNumberKnown: context.prNumber !== void 0,
+    status: outcome.status,
+    code: outcome.code
+  })) {
+    return withLegacyServerPrHint(outcome.error);
+  }
+  return outcome.error;
+}
+var DEFAULT_TIMEOUT_FLAG = {
+  flag: "--timeout",
+  defaultMinutes: DEFAULT_TIMEOUT_MINUTES
+};
+function resolveTimeoutMs(timeout, spec = DEFAULT_TIMEOUT_FLAG) {
+  if (timeout === void 0) return spec.defaultMinutes * MINUTE_MS;
   const minutes = Number(timeout);
   if (!Number.isFinite(minutes) || minutes <= 0) {
-    throw new ConfigError(`--timeout must be a positive number of minutes, got "${timeout}".`);
+    throw new ConfigError(`${spec.flag} must be a positive number of minutes, got "${timeout}".`);
   }
   return minutes * MINUTE_MS;
 }
@@ -378,6 +460,86 @@ function statusLine(run2) {
   return run2.statusMessage ? `${run2.status} \u2014 ${run2.statusMessage}` : run2.status;
 }
 
+// src/commands/report-preview.ts
+var RUN_NOT_CREATED_YET_STATUS = 409;
+var RETRY_INTERVAL_MS = 3e4;
+var DEFAULT_WAIT_RUN_TIMEOUT_MINUTES = 12;
+var WAIT_RUN_TIMEOUT_SPEC = {
+  flag: "--wait-run-timeout",
+  defaultMinutes: DEFAULT_WAIT_RUN_TIMEOUT_MINUTES
+};
+async function runReportPreview(options, deps = defaultDeps) {
+  if (!options.url) {
+    deps.logger.error("--url is required (the deployed preview URL).");
+    return 1;
+  }
+  assertValidPreviewUrl(options.url);
+  const config = resolveConfig(options);
+  const context = resolveRunContextAllowingShaOnly(options);
+  const waitRunTimeoutMs = resolveTimeoutMs(options.waitRunTimeout, WAIT_RUN_TIMEOUT_SPEC);
+  const api = deps.createApi(config);
+  const outcome = await reportPreviewUntilRunExists(api, context, options.url, deps, {
+    waitForRun: options.waitForRun !== false,
+    waitRunTimeoutMs
+  });
+  if (!outcome.ok) {
+    deps.logger.error(`Could not report preview URL: ${describeFailure(outcome, context)}`);
+    return 1;
+  }
+  deps.logger.success(
+    `Preview reported for ${describeContextTarget(context)} \u2014 QA run ${outcome.runId} queued.`
+  );
+  return 0;
+}
+async function reportPreviewUntilRunExists(api, context, url, deps, policy) {
+  const firstAttempt = await api.reportPreview({ ...context, url });
+  if (firstAttempt.ok || !isRunNotCreatedYet(firstAttempt) || !policy.waitForRun) {
+    return firstAttempt;
+  }
+  return retryReportPreviewUntilRunExists(api, context, url, deps, policy.waitRunTimeoutMs);
+}
+function isRunNotCreatedYet(outcome) {
+  return !outcome.ok && outcome.status === RUN_NOT_CREATED_YET_STATUS && outcome.retryable !== false;
+}
+function describeFailure(outcome, context) {
+  if (isUnresolvedPrOnLegacyServer({
+    prNumberKnown: context.prNumber !== void 0,
+    status: outcome.status,
+    code: outcome.code
+  })) {
+    return withLegacyServerPrHint(outcome.error);
+  }
+  return outcome.code ? `${outcome.error} [${outcome.code}]` : outcome.error;
+}
+async function retryReportPreviewUntilRunExists(api, context, url, deps, waitRunTimeoutMs) {
+  const deadline = deps.now() + waitRunTimeoutMs;
+  deps.logger.info(
+    `QA run not created yet \u2014 the server may still be debouncing this push. Retrying for up to ${formatMinutes(waitRunTimeoutMs)} min\u2026`
+  );
+  while (true) {
+    await deps.sleep(Math.min(RETRY_INTERVAL_MS, deadline - deps.now()));
+    const outcome = await api.reportPreview({ ...context, url });
+    if (outcome.ok || !isRunNotCreatedYet(outcome)) return outcome;
+    if (deps.now() >= deadline) {
+      return { ...outcome, error: withRunNeverAppearedHint(outcome.error) };
+    }
+    deps.logger.info("Still waiting for the QA run to be created\u2026");
+  }
+}
+function formatMinutes(ms) {
+  return Math.round(ms / MINUTE_MS * 100) / 100;
+}
+function withRunNeverAppearedHint(error) {
+  return `${error} (gave up waiting \u2014 the QA run never appeared)`;
+}
+
+// src/tunnel-provider.ts
+import localtunnel from "localtunnel";
+async function openTunnel(port) {
+  const tunnel = await localtunnel({ port });
+  return { url: tunnel.url, close: () => tunnel.close() };
+}
+
 // src/commands/tunnel.ts
 var defaultTunnelDeps = {
   ...defaultDeps,
@@ -437,8 +599,14 @@ async function runWait(options, deps = defaultDeps) {
 
 // src/cli.ts
 var cli = cac("datadisco-qa");
-cli.command("report-preview", "Report a PR's preview-deploy URL so its pending QA run can start").option("--url <url>", "The deployed preview URL for the PR head SHA").option("--repo <owner/name>", "Repository the PR belongs to").option("--pr <number>", "Pull request number").option("--sha <sha>", "Head SHA the preview was built from").option("--api-url <url>", "DataDisco API base URL").option("--api-token <token>", "Workspace API token (or DATADISCO_API_TOKEN)").action((options) => run(() => runReportPreview(options)));
-cli.command("wait", "Block until the PR's QA run reaches a verdict").option("--repo <owner/name>", "Repository the PR belongs to").option("--pr <number>", "Pull request number").option("--timeout <minutes>", "Give up after this many minutes (default 30)").option("--api-url <url>", "DataDisco API base URL").option("--api-token <token>", "Workspace API token (or DATADISCO_API_TOKEN)").action((options) => run(() => runWait(options)));
+cli.command("report-preview", "Report a PR's preview-deploy URL so its pending QA run can start").option("--url <url>", "The deployed preview URL for the PR head SHA").option("--repo <owner/name>", "Repository the PR belongs to").option("--pr <number>", "Pull request number").option("--sha <sha>", "Head SHA the preview was built from").option("--api-url <url>", "DataDisco API base URL").option("--api-token <token>", "Workspace API token (or DATADISCO_API_TOKEN)").option(
+  "--no-wait-for-run",
+  "Fail immediately if the QA run hasn't been created yet, instead of retrying"
+).option(
+  "--wait-run-timeout <minutes>",
+  "How long to retry while the QA run hasn't been created yet (default 12)"
+).action((options) => run(() => runReportPreview(options)));
+cli.command("wait", "Block until the PR's QA run reaches a verdict").option("--repo <owner/name>", "Repository the PR belongs to").option("--pr <number>", "Pull request number").option("--sha <sha>", "Head SHA to look up the run by, if the PR number isn't known").option("--timeout <minutes>", "Give up after this many minutes (default 30)").option("--api-url <url>", "DataDisco API base URL").option("--api-token <token>", "Workspace API token (or DATADISCO_API_TOKEN)").action((options) => run(() => runWait(options)));
 cli.command("tunnel", "Expose a local build and start a QA run against it").option("--port <port>", "Local port serving the build").option("--url <url>", "Use an externally managed tunnel URL instead of --port").option("--repo <owner/name>", "Repository (defaults to the git origin remote)").option("--pr <number>", "Pull request number").option("--sha <sha>", "Head SHA (defaults to the local git HEAD)").option("--no-wait", "Queue the run and exit without waiting for a verdict").option("--timeout <minutes>", "Give up waiting after this many minutes").option("--api-url <url>", "DataDisco API base URL").option("--api-token <token>", "Workspace API token (or DATADISCO_API_TOKEN)").action((options) => run(() => runTunnel(options)));
 async function run(command) {
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datadisco/qa",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "CI companion for DataDisco QA — report preview URLs, wait on persona-simulation gates, and tunnel local builds into QA runs.",
   "keywords": [
     "ci",