@datadisco/qa 0.1.1 → 0.2.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
 
@@ -48,6 +54,22 @@ datadisco-qa report-preview \
   --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.
@@ -92,8 +114,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
 
-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.
+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:
+
+```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

@@ -148,7 +148,13 @@ 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));
@@ -183,6 +189,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 +224,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,
@@ -366,11 +328,15 @@ 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;
+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 +344,101 @@ 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 = resolveRunContext(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)}`);
+    return 1;
+  }
+  deps.logger.success(
+    `Preview reported for ${context.repo}#${context.prNumber} \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) {
+  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/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/commands/tunnel.ts
 var defaultTunnelDeps = {
   ...defaultDeps,
@@ -437,7 +498,13 @@ 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("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("--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) {

package/package.json

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