@datadisco/qa 0.2.0 → 0.4.0

package/dist/cli.js

@@ -10,16 +10,24 @@ var API_TOKEN_ENV_KEY = "DATADISCO_API_TOKEN";
 var ConfigError = class extends Error {
 };
 function resolveConfig(input = {}) {
-  const env = input.env ?? process.env;
-  const apiUrl = input.apiUrl || env.DATADISCO_API_URL || DEFAULT_API_URL;
-  const apiToken = input.apiToken || env[API_TOKEN_ENV_KEY];
+  const apiUrl = resolveApiUrl(input);
+  const apiToken = resolveExplicitApiToken(input);
   if (!apiToken) {
     throw new ConfigError(`Missing API token: pass --api-token or set ${API_TOKEN_ENV_KEY}.`);
   }
+  return { apiUrl, apiToken };
+}
+function resolveApiUrl(input = {}) {
+  const env = input.env ?? process.env;
+  const apiUrl = input.apiUrl || env.DATADISCO_API_URL || DEFAULT_API_URL;
   if (!apiUrl.startsWith("https://")) {
     throw new ConfigError(`API url must be https, got "${apiUrl}".`);
   }
-  return { apiUrl, apiToken };
+  return apiUrl;
+}
+function resolveExplicitApiToken(input = {}) {
+  const env = input.env ?? process.env;
+  return input.apiToken || env[API_TOKEN_ENV_KEY] || void 0;
 }
 function assertValidPreviewUrl(url) {
   let parsed;
@@ -33,110 +41,562 @@ function assertValidPreviewUrl(url) {
   }
 }
 
-// src/context.ts
-import { readFileSync } from "fs";
-var REPO_PATTERN = /^[^/\s]+\/[^/\s]+$/;
-var PR_REF_PATTERN = /^refs\/pull\/(\d+)\//;
-function resolvePrContext(input = {}) {
-  const env = input.env ?? process.env;
-  const payload = loadEventPayload(input, env);
+// src/connection.ts
+function findGithubConnection(outcome) {
+  if (!outcome.ok) return void 0;
+  return outcome.connections.find((connection) => connection.kind === "GITHUB");
+}
+function connectRepoUrl(apiUrl, repo) {
+  const url = new URL("/qa/dance", apiUrl);
+  url.searchParams.set("repo", repo);
+  return url.toString();
+}
+function describeConnectionProblem(connection) {
+  if (!connection.hasInstallation) {
+    return "the DataDisco GitHub App is not installed on this repo \u2014 reinstall it from the connection page";
+  }
+  if (!connection.enabled) return "the connection is disabled \u2014 enable it from the connection page";
+  if (connection.status !== "ACTIVE") {
+    return `the connection status is ${connection.status} \u2014 check the connection page`;
+  }
+  return void 0;
+}
+
+// src/gh.ts
+function checkGh(run2) {
+  if (!run2("gh", ["--version"]).ok) return "missing";
+  return run2("gh", ["auth", "status"]).ok ? "ready" : "unauthenticated";
+}
+function setRepoSecret(run2, repo, name, value) {
+  return run2("gh", ["secret", "set", name, "--repo", repo], value);
+}
+function listRepoSecretNames(run2, repo) {
+  const result = run2("gh", [
+    "secret",
+    "list",
+    "--repo",
+    repo,
+    "--json",
+    "name",
+    "--jq",
+    ".[].name"
+  ]);
+  if (!result.ok) return void 0;
+  return result.stdout.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+}
+
+// src/host-detection.ts
+import { join } from "path";
+var DEPLOY_EVENT_HOSTS = /* @__PURE__ */ new Set(["vercel", "netlify", "amplify"]);
+var HOST_MARKERS = [
+  { host: "vercel", path: "vercel.json" },
+  { host: "vercel", path: ".vercel" },
+  { host: "netlify", path: "netlify.toml" },
+  { host: "amplify", path: "amplify.yml" },
+  { host: "fly", path: "fly.toml" },
+  { host: "render", path: "render.yaml" },
+  { host: "railway", path: "railway.json" },
+  { host: "railway", path: "railway.toml" }
+];
+var WORKFLOW_KEYWORDS = [
+  { host: "vercel", pattern: /\bvercel\b/i, label: "vercel" },
+  { host: "netlify", pattern: /\bnetlify\b/i, label: "netlify" },
+  { host: "amplify", pattern: /\bamplify\b/i, label: "amplify" },
+  { host: "fly", pattern: /\bfly(?:ctl|\.io)?\b|superfly/i, label: "fly" },
+  { host: "render", pattern: /\brender(?:\.com)?\b/i, label: "render" },
+  { host: "railway", pattern: /\brailway\b/i, label: "railway" }
+];
+var GENERIC_DEPLOY_PATTERN = /deploy/i;
+var WORKFLOWS_DIR = join(".github", "workflows");
+var WORKFLOW_FILE_PATTERN = /\.ya?ml$/;
+function isDeployEventHost(host) {
+  return DEPLOY_EVENT_HOSTS.has(host);
+}
+function detectDeployHost(repoRoot, files) {
+  const markerHits = findMarkerFiles(repoRoot, files);
+  const workflowHits2 = scanWorkflows(repoRoot, files);
+  const hosts = [...markerHits, ...workflowHits2].map((hit) => hit.host);
+  const host = hosts.find((candidate) => candidate !== void 0) ?? "unknown";
   return {
-    repo: resolveRepo(input, env),
-    prNumber: resolvePrNumber(input, env, payload)
+    host,
+    evidence: [...markerHits, ...workflowHits2].map((hit) => hit.evidence),
+    // A workflow naming Vercel/Netlify/Amplify deploys through their CLI, which creates no
+    // GitHub Deployments — only the marker files point at the Git integration.
+    deployEvents: namesDeployEventHost(markerHits) && !namesDeployEventHost(workflowHits2)
   };
 }
-function resolveRunContext(input = {}) {
-  const env = input.env ?? process.env;
-  const payload = loadEventPayload(input, env);
+function namesDeployEventHost(hits) {
+  return hits.some((hit) => hit.host !== void 0 && DEPLOY_EVENT_HOSTS.has(hit.host));
+}
+function findMarkerFiles(repoRoot, files) {
+  return HOST_MARKERS.filter((marker) => files.exists(join(repoRoot, marker.path))).map(
+    (marker) => ({ host: marker.host, evidence: marker.path })
+  );
+}
+function scanWorkflows(repoRoot, files) {
+  const workflowsDir = join(repoRoot, WORKFLOWS_DIR);
+  const workflowFiles = files.listDir(workflowsDir).filter((name) => WORKFLOW_FILE_PATTERN.test(name));
+  return workflowFiles.flatMap((name) => {
+    const content = files.readFile(join(workflowsDir, name)) ?? "";
+    return workflowHits(`${WORKFLOWS_DIR}/${name}`, content);
+  });
+}
+function workflowHits(workflowPath, content) {
+  const hostHits = WORKFLOW_KEYWORDS.filter((keyword) => keyword.pattern.test(content)).map(
+    (keyword) => ({ host: keyword.host, evidence: describeWorkflowHit(workflowPath, keyword) })
+  );
+  if (hostHits.length === 0 && GENERIC_DEPLOY_PATTERN.test(content)) {
+    return [{ host: void 0, evidence: `${workflowPath} mentions deploy` }];
+  }
+  return hostHits;
+}
+function describeWorkflowHit(workflowPath, keyword) {
+  const suffix = DEPLOY_EVENT_HOSTS.has(keyword.host) ? " (deploys from CI?)" : "";
+  return `${workflowPath} mentions ${keyword.label}${suffix}`;
+}
+
+// src/config-file.ts
+import { homedir } from "os";
+import { join as join2 } from "path";
+var CONFIG_DIR_NAME = "datadisco";
+var CONFIG_FILE_NAME = "qa.json";
+var OWNER_ONLY_FILE_MODE = 384;
+var OWNER_ONLY_DIR_MODE = 448;
+function resolveConfigFilePath(env = process.env, home = homedir()) {
+  const configHome = env.XDG_CONFIG_HOME || join2(home, ".config");
+  return join2(configHome, CONFIG_DIR_NAME, CONFIG_FILE_NAME);
+}
+function readStoredToken(apiUrl, deps) {
+  return readTokens(deps)[apiUrl];
+}
+function saveStoredToken(apiUrl, approval, deps) {
+  const tokens = readTokens(deps);
+  tokens[apiUrl] = {
+    token: approval.apiToken,
+    workspaceName: approval.workspaceName,
+    workspaceSlug: approval.workspaceSlug,
+    savedAt: new Date(deps.now()).toISOString()
+  };
+  writeTokens(tokens, deps);
+}
+function deleteStoredToken(apiUrl, deps) {
+  const tokens = readTokens(deps);
+  if (!(apiUrl in tokens)) return false;
+  delete tokens[apiUrl];
+  writeTokens(tokens, deps);
+  return true;
+}
+function readTokens(deps) {
+  const raw = deps.readFile(deps.configFilePath);
+  if (!raw) return {};
+  const parsed = parseJson(raw);
+  if (!isRecord(parsed) || !isRecord(parsed.tokens)) return {};
+  return collectStoredTokens(parsed.tokens);
+}
+function writeTokens(tokens, deps) {
+  const content = `${JSON.stringify({ tokens }, null, 2)}
+`;
+  deps.writeFile(deps.configFilePath, content, {
+    mode: OWNER_ONLY_FILE_MODE,
+    dirMode: OWNER_ONLY_DIR_MODE
+  });
+}
+function collectStoredTokens(value) {
+  const tokens = {};
+  for (const [apiUrl, entry] of Object.entries(value)) {
+    const stored = parseStoredToken(entry);
+    if (stored) tokens[apiUrl] = stored;
+  }
+  return tokens;
+}
+function parseStoredToken(value) {
+  if (!isRecord(value) || typeof value.token !== "string") return void 0;
   return {
-    repo: resolveRepo(input, env),
-    prNumber: resolvePrNumber(input, env, payload),
-    headSha: resolveHeadSha(input, env, payload)
+    token: value.token,
+    workspaceName: stringOr(value.workspaceName, ""),
+    workspaceSlug: stringOr(value.workspaceSlug, ""),
+    savedAt: stringOr(value.savedAt, "")
   };
 }
-function resolveRepo(input, env = {}) {
-  const repo = input.repo ?? env.GITHUB_REPOSITORY;
-  if (!repo) {
-    throw new ConfigError(
-      "Repository not set: pass --repo owner/name (auto-detected from $GITHUB_REPOSITORY in GitHub Actions)."
-    );
+function parseJson(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return void 0;
   }
-  if (!REPO_PATTERN.test(repo)) {
-    throw new ConfigError(`--repo must look like "owner/name", got "${repo}".`);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function stringOr(value, fallback) {
+  return typeof value === "string" ? value : fallback;
+}
+
+// src/pairing.ts
+var SECOND_MS = 1e3;
+var MIN_POLL_INTERVAL_MS = SECOND_MS;
+var MAX_BACKOFF_INTERVAL_MS = 30 * SECOND_MS;
+var TOO_MANY_REQUESTS = 429;
+var SERVER_ERROR = 500;
+var NO_RESPONSE = 0;
+async function pairDevice(api, deps, options) {
+  const started = await api.pair(deps.deviceName());
+  if (!started.ok) {
+    return { ok: false, error: describePairFailure(started.error, started.code) };
   }
-  return repo;
+  await announcePairing(started.pairing, deps, options);
+  return pollUntilResolved(api, started.pairing, deps);
 }
-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)."
-    );
+async function signIn(apiUrl, api, deps, options) {
+  const result = await pairDevice(api, deps, options);
+  if (!result.ok) return result;
+  saveStoredToken(apiUrl, result.approval, deps);
+  deps.logger.success(`Signed in to workspace ${result.approval.workspaceName}`);
+  return result;
+}
+async function announcePairing(pairing, deps, options) {
+  deps.logger.info(`Open ${pairing.verificationUrl} and confirm code ${pairing.userCode}`);
+  if (options.openBrowser) {
+    await deps.openBrowser(pairing.verificationUrl);
   }
-  return prNumber;
 }
-function resolveHeadSha(input, env = {}, payload) {
-  const headSha = input.sha ?? payload.headSha ?? env.GITHUB_SHA;
-  if (!headSha) {
+async function pollUntilResolved(api, pairing, deps) {
+  const deadline = deps.now() + pairing.expiresInSeconds * SECOND_MS;
+  let interval = Math.max(pairing.intervalSeconds * SECOND_MS, MIN_POLL_INTERVAL_MS);
+  let lastTransientError;
+  while (true) {
+    await deps.sleep(interval);
+    const outcome = await pollOnce(api, pairing.deviceCode);
+    if (isTransientFailure(outcome)) {
+      lastTransientError = outcome.error;
+      if (isRateLimited(outcome)) interval = Math.min(interval * 2, MAX_BACKOFF_INTERVAL_MS);
+    } else {
+      const resolved = resolvePoll(outcome);
+      if (resolved) return resolved;
+      lastTransientError = void 0;
+    }
+    if (deps.now() >= deadline) {
+      const detail = lastTransientError ? ` (last error: ${lastTransientError})` : "";
+      return {
+        ok: false,
+        error: `Pairing code expired before it was confirmed. Try again.${detail}`
+      };
+    }
+  }
+}
+async function pollOnce(api, deviceCode) {
+  try {
+    return await api.pollPairing(deviceCode);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, status: NO_RESPONSE, error: message };
+  }
+}
+function isTransientFailure(outcome) {
+  if (outcome.ok) return false;
+  if (outcome.code && outcome.code in POLL_FAILURE_MESSAGES) return false;
+  return outcome.status === NO_RESPONSE || outcome.status >= SERVER_ERROR || isRateLimited(outcome);
+}
+function isRateLimited(outcome) {
+  return !outcome.ok && (outcome.status === TOO_MANY_REQUESTS || outcome.code === "RATE_LIMITED");
+}
+function resolvePoll(outcome) {
+  if (!outcome.ok) {
+    return { ok: false, error: describePollFailure(outcome.error, outcome.code) };
+  }
+  return outcome.pending ? void 0 : { ok: true, approval: outcome.approval };
+}
+function describePairFailure(error, code) {
+  if (code === "RATE_LIMITED") {
+    return `Too many sign-in attempts \u2014 wait a minute and try again. (${error})`;
+  }
+  return `Could not start sign-in: ${error}`;
+}
+var POLL_FAILURE_MESSAGES = {
+  DENIED: "Sign-in was denied in the browser.",
+  EXPIRED: "Pairing code expired before it was confirmed. Try again.",
+  ALREADY_CLAIMED: "This pairing code was already used. Run the command again for a fresh code.",
+  NOT_FOUND: "The server no longer recognizes this pairing code. Run the command again."
+};
+function describePollFailure(error, code) {
+  const known = code ? POLL_FAILURE_MESSAGES[code] : void 0;
+  return known ?? `Sign-in failed: ${error}`;
+}
+
+// src/session.ts
+function findExistingToken(options, apiUrl, deps) {
+  return resolveExplicitApiToken(options) ?? readStoredToken(apiUrl, deps)?.token;
+}
+async function resolveSession(options, deps) {
+  const apiUrl = resolveApiUrl(options);
+  const existing = findExistingToken(options, apiUrl, deps);
+  if (existing) {
+    deps.logger.info(describeTokenSource(options, apiUrl, deps));
+    return {
+      ok: true,
+      session: { apiUrl, apiToken: existing, api: deps.createApi({ apiUrl, apiToken: existing }) }
+    };
+  }
+  deps.logger.info("No saved sign-in for this API \u2014 pairing this device\u2026");
+  const result = await signIn(apiUrl, deps.createApi({ apiUrl }), deps, {
+    openBrowser: options.browser !== false
+  });
+  if (!result.ok) return result;
+  const apiToken = result.approval.apiToken;
+  return { ok: true, session: { apiUrl, apiToken, api: deps.createApi({ apiUrl, apiToken }) } };
+}
+function describeTokenSource(options, apiUrl, deps) {
+  if (resolveExplicitApiToken(options)) return "Using the API token from the flag/environment.";
+  const stored = readStoredToken(apiUrl, deps);
+  return stored?.workspaceName ? `Using the saved sign-in for workspace ${stored.workspaceName}.` : "Using the saved sign-in.";
+}
+
+// src/workflow-recipe.ts
+import { join as join3 } from "path";
+var WORKFLOW_RELATIVE_PATH = join3(".github", "workflows", "datadisco-qa.yml");
+var API_TOKEN_SECRET_NAME = "DATADISCO_API_TOKEN";
+var PATTERN_PLACEHOLDER = "{number}";
+var ACTION_REF = "Data-Disco-Inc/qa-action@v1";
+var PR_NUMBER_EXPRESSION = "${{ github.event.pull_request.number }}";
+var SECRET_EXPRESSION = `\${{ secrets.${API_TOKEN_SECRET_NAME} }}`;
+var DEPLOYMENT_STATUS_TRIGGER = /^\s*deployment_status\s*:/m;
+function workflowFilePath(repoRoot) {
+  return join3(repoRoot, WORKFLOW_RELATIVE_PATH);
+}
+function assertValidPreviewUrlPattern(pattern) {
+  if (!pattern.startsWith("https://")) {
+    throw new ConfigError(`Preview URL pattern must start with https://, got "${pattern}".`);
+  }
+  if (!pattern.includes(PATTERN_PLACEHOLDER)) {
     throw new ConfigError(
-      "Head SHA not set: pass --sha <sha> (the commit the preview was built from)."
+      `Preview URL pattern must contain ${PATTERN_PLACEHOLDER}, e.g. https://pr-${PATTERN_PLACEHOLDER}.preview.example.com`
     );
   }
-  return headSha;
 }
-function parsePrFromRef(ref) {
-  const match = ref?.match(PR_REF_PATTERN);
-  return match ? match[1] : void 0;
+function describeRecipe(pattern) {
+  return `report-preview on pull_request using ${pattern}`;
 }
-function loadEventPayload(input, env = {}) {
-  const read = input.readEventPayload ?? (() => readEventFile(env.GITHUB_EVENT_PATH));
-  const raw = safeRead(read);
-  if (!isRecord(raw)) return {};
-  const pullRequest = isRecord(raw.pull_request) ? raw.pull_request : void 0;
-  const head = isRecord(pullRequest?.head) ? pullRequest.head : void 0;
-  return {
-    prNumber: numberOrUndefined(pullRequest?.number ?? raw.number),
-    headSha: stringOrUndefined(head?.sha)
-  };
+function triggersOnDeploymentStatus(workflow) {
+  return DEPLOYMENT_STATUS_TRIGGER.test(workflow);
 }
-function readEventFile(path) {
-  if (!path) return void 0;
-  return JSON.parse(readFileSync(path, "utf8"));
+function renderWorkflow(pattern) {
+  const url = pattern.split(PATTERN_PLACEHOLDER).join(PR_NUMBER_EXPRESSION);
+  return `name: DataDisco QA
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+
+jobs:
+  report-preview:
+    runs-on: ubuntu-latest
+    steps:
+      # ...wait for or deploy your preview before this step...
+      - uses: ${ACTION_REF}
+        with:
+          command: report-preview
+          url: ${url}
+          api-token: ${SECRET_EXPRESSION}
+`;
 }
-function safeRead(read) {
+
+// src/commands/setup-deps.ts
+import { hostname, userInfo } from "os";
+
+// src/files.ts
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync
+} from "fs";
+import { dirname } from "path";
+var nodeFileSystem = {
+  exists: (path) => existsSync(path),
+  readFile: (path) => tryRead(path),
+  listDir: (path) => tryList(path),
+  writeFile: (path, content, options) => {
+    mkdirSync(dirname(path), { recursive: true, mode: options?.dirMode });
+    writeFileSync(path, content, { encoding: "utf8", mode: options?.mode });
+    if (options?.mode !== void 0) chmodSync(path, options.mode);
+  }
+};
+function tryRead(path) {
   try {
-    return read();
+    return readFileSync(path, "utf8");
   } catch {
     return void 0;
   }
 }
-function isRecord(value) {
-  return typeof value === "object" && value !== null;
+function tryList(path) {
+  try {
+    return readdirSync(path);
+  } catch {
+    return [];
+  }
 }
-function numberOrUndefined(value) {
-  return typeof value === "number" ? value : void 0;
+
+// 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 stringOrUndefined(value) {
-  return typeof value === "string" ? value : 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;
+  }
+}
+function detectRepoRoot(run2 = defaultRunner) {
+  return tryGit(run2, ["rev-parse", "--show-toplevel"]);
+}
+
+// src/prompt.ts
+import { createInterface } from "readline";
+var PromptCancelledError = class extends Error {
+  constructor() {
+    super("Cancelled.");
+    this.name = "PromptCancelledError";
+  }
+};
+var YES_ANSWER = /^y(es)?$/i;
+var NO_ANSWER = /^n(o)?$/i;
+function createLinePrompt(input, output) {
+  let readline;
+  let ended = false;
+  let cancelled = false;
+  const lines = [];
+  const waiting = [];
+  const tty = input;
+  const cancel = () => {
+    cancelled = true;
+    for (const next of waiting.splice(0)) next.reject(new PromptCancelledError());
+  };
+  const open = () => {
+    if (readline) return readline;
+    readline = createInterface({ input, output });
+    readline.on("line", (line) => {
+      const next = waiting.shift();
+      if (next) next.resolve(line);
+      else lines.push(line);
+    });
+    readline.on("SIGINT", () => {
+      output.write("\n");
+      cancel();
+      readline?.close();
+    });
+    readline.on("close", () => {
+      ended = true;
+      if (tty.isTTY) cancel();
+      else for (const next of waiting.splice(0)) next.resolve(void 0);
+    });
+    return readline;
+  };
+  const nextLine = () => {
+    if (lines.length) return Promise.resolve(lines.shift());
+    if (ended) return Promise.resolve(void 0);
+    return new Promise((resolve, reject) => waiting.push({ resolve, reject }));
+  };
+  return async (question, defaultValue) => {
+    if (cancelled) throw new PromptCancelledError();
+    const reader = open();
+    const text = formatQuestion(question, defaultValue);
+    if (ended) {
+      output.write(`${text}
+`);
+    } else {
+      reader.setPrompt(text);
+      if (reader.terminal) tty.setRawMode?.(true);
+      reader.prompt();
+      reader.resume();
+    }
+    const answer = (await nextLine() ?? "").trim();
+    if (!ended) {
+      reader.pause();
+      if (reader.terminal) tty.setRawMode?.(false);
+    }
+    return answer || defaultValue || "";
+  };
+}
+var stdinPrompt;
+var terminalPrompt = (question, defaultValue) => {
+  stdinPrompt ??= createLinePrompt(process.stdin, process.stderr);
+  return stdinPrompt(question, defaultValue);
+};
+async function confirm(prompt, question, defaultYes) {
+  const answer = await prompt(`${question} (${defaultYes ? "Y/n" : "y/N"})`);
+  if (YES_ANSWER.test(answer)) return true;
+  if (NO_ANSWER.test(answer)) return false;
+  return defaultYes;
+}
+function formatQuestion(question, defaultValue) {
+  return defaultValue ? `${question} [${defaultValue}] ` : `${question} `;
+}
+
+// src/shell.ts
+import { spawn, spawnSync } from "child_process";
+import { platform } from "os";
+var runCommand = (command, args, input) => {
+  const result = spawnSync(command, args, { encoding: "utf8", input, stdio: "pipe" });
+  return {
+    ok: result.status === 0 && !result.error,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? ""
+  };
+};
+var BROWSER_OPENERS = {
+  darwin: { command: "open", args: [] },
+  win32: { command: "cmd", args: ["/c", "start", ""] }
+};
+var DEFAULT_BROWSER_OPENER = { command: "xdg-open", args: [] };
+function openBrowser(url) {
+  const opener = BROWSER_OPENERS[platform()] ?? DEFAULT_BROWSER_OPENER;
+  try {
+    const child = spawn(opener.command, [...opener.args, url], {
+      detached: true,
+      stdio: "ignore"
+    });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+  return Promise.resolve();
 }
 
 // src/api.ts
 var REPORT_PREVIEW_PATH = "/api/qa/report-preview";
 var RUN_STATUS_PATH = "/api/qa/run-status";
+var PAIR_PATH = "/api/qa/cli/pair";
+var PAIR_POLL_PATH = "/api/qa/cli/pair/poll";
+var CONNECTIONS_PATH = "/api/v1/qa/connections";
 function createApiClient(config, fetchImpl = fetch) {
   return {
     reportPreview: (params) => reportPreview(config, params, fetchImpl),
-    getRunStatus: (params) => getRunStatus(config, params, fetchImpl)
+    getRunStatus: (params) => getRunStatus(config, params, fetchImpl),
+    pair: (deviceName) => pair(config, deviceName, fetchImpl),
+    pollPairing: (deviceCode) => pollPairing(config, deviceCode, fetchImpl),
+    listConnections: (repo) => listConnections(config, repo, fetchImpl)
   };
 }
 async function reportPreview(config, params, fetchImpl) {
   const response = await fetchImpl(joinUrl(config.apiUrl, REPORT_PREVIEW_PATH), {
     method: "POST",
-    headers: {
-      authorization: `Bearer ${config.apiToken}`,
-      "content-type": "application/json"
-    },
+    headers: { ...authHeaders(config), "content-type": "application/json" },
     body: JSON.stringify({
       repo: params.repo,
       prNumber: params.prNumber,
@@ -149,25 +609,72 @@ async function reportPreview(config, params, fetchImpl) {
     return { ok: true, runId: payload.runId };
   }
   return {
-    ok: false,
-    status: response.status,
-    error: errorMessage(payload),
-    retryable: booleanOrUndefined(payload.retryable),
-    code: stringOrUndefined2(payload.code)
+    ...failure(response, payload),
+    retryable: booleanOrUndefined(payload.retryable)
   };
 }
 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));
-  const response = await fetchImpl(url.toString(), {
-    headers: { authorization: `Bearer ${config.apiToken}` }
-  });
+  setRunLookupParam(url, params);
+  const response = await fetchImpl(url.toString(), { headers: authHeaders(config) });
   const payload = await readJson(response);
   if (response.ok && isRunStatus(payload.run)) {
     return { ok: true, run: payload.run };
   }
-  return { ok: false, status: response.status, error: errorMessage(payload) };
+  return failure(response, payload);
+}
+async function pair(config, deviceName, fetchImpl) {
+  const response = await fetchImpl(joinUrl(config.apiUrl, PAIR_PATH), {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ deviceName })
+  });
+  const payload = await readJson(response);
+  const pairing = response.ok ? parsePairingStart(payload.data) : void 0;
+  if (pairing) {
+    return { ok: true, pairing };
+  }
+  return failure(response, payload);
+}
+async function pollPairing(config, deviceCode, fetchImpl) {
+  const response = await fetchImpl(joinUrl(config.apiUrl, PAIR_POLL_PATH), {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ deviceCode })
+  });
+  const payload = await readJson(response);
+  const data = response.ok && isRecord2(payload.data) ? payload.data : void 0;
+  if (data?.status === "PENDING") {
+    return { ok: true, pending: true };
+  }
+  const approval = data?.status === "APPROVED" ? parsePairingApproval(data) : void 0;
+  if (approval) {
+    return { ok: true, pending: false, approval };
+  }
+  return failure(response, payload);
+}
+async function listConnections(config, repo, fetchImpl) {
+  const url = new URL(joinUrl(config.apiUrl, CONNECTIONS_PATH));
+  url.searchParams.set("repo", repo);
+  const response = await fetchImpl(url.toString(), { headers: authHeaders(config) });
+  const payload = await readJson(response);
+  const data = response.ok && isRecord2(payload.data) ? payload.data : void 0;
+  const workspace = parseWorkspace(data?.workspace);
+  if (workspace && Array.isArray(data?.connections)) {
+    return { ok: true, workspace, connections: parseConnections(data.connections) };
+  }
+  return failure(response, payload);
+}
+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 authHeaders(config) {
+  return config.apiToken ? { authorization: `Bearer ${config.apiToken}` } : {};
 }
 function joinUrl(base, path) {
   return `${base.replace(/\/+$/, "")}${path}`;
@@ -180,6 +687,14 @@ async function readJson(response) {
     return {};
   }
 }
+function failure(response, payload) {
+  return {
+    ok: false,
+    status: response.status,
+    error: errorMessage(payload),
+    code: stringOrUndefined(payload.code)
+  };
+}
 function errorMessage(payload) {
   return isString(payload.error) ? payload.error : "Request failed.";
 }
@@ -189,15 +704,103 @@ function isRecord2(value) {
 function isString(value) {
   return typeof value === "string";
 }
-function stringOrUndefined2(value) {
+function stringOrUndefined(value) {
   return isString(value) ? value : void 0;
 }
+function stringOrNull(value) {
+  return isString(value) ? value : null;
+}
+function numberOrNull(value) {
+  return typeof value === "number" ? value : null;
+}
 function booleanOrUndefined(value) {
   return typeof value === "boolean" ? value : void 0;
 }
+function booleanOr(value, fallback) {
+  return typeof value === "boolean" ? value : fallback;
+}
 function isRunStatus(value) {
   return isRecord2(value) && isString(value.id) && isString(value.status) && typeof value.blockerCount === "number";
 }
+function parsePairingStart(value) {
+  if (!isRecord2(value) || !isString(value.deviceCode) || !isString(value.userCode) || !isString(value.verificationUrl) || typeof value.expiresInSeconds !== "number" || typeof value.intervalSeconds !== "number") {
+    return void 0;
+  }
+  return {
+    deviceCode: value.deviceCode,
+    userCode: value.userCode,
+    verificationUrl: value.verificationUrl,
+    expiresInSeconds: value.expiresInSeconds,
+    intervalSeconds: value.intervalSeconds
+  };
+}
+function parsePairingApproval(value) {
+  if (!isString(value.apiToken)) return void 0;
+  return {
+    apiToken: value.apiToken,
+    workspaceName: stringOrNull(value.workspaceName) ?? "",
+    workspaceSlug: stringOrNull(value.workspaceSlug) ?? ""
+  };
+}
+function parseWorkspace(value) {
+  if (!isRecord2(value) || !isString(value.id)) return void 0;
+  return {
+    id: value.id,
+    name: stringOrNull(value.name) ?? "",
+    slug: stringOrNull(value.slug) ?? ""
+  };
+}
+function parseConnections(values) {
+  const connections = [];
+  for (const value of values) {
+    const connection = parseConnection(value);
+    if (connection) connections.push(connection);
+  }
+  return connections;
+}
+function parseConnection(value) {
+  if (!isRecord2(value) || !isString(value.id) || !isString(value.url)) return void 0;
+  const kind = parseConnectionKind(value.kind);
+  const previewUrlSource = parsePreviewUrlSource(value.previewUrlSource);
+  if (!kind || !previewUrlSource) return void 0;
+  return {
+    id: value.id,
+    slug: stringOrNull(value.slug) ?? "",
+    kind,
+    status: stringOrNull(value.status) ?? "",
+    enabled: booleanOr(value.enabled, false),
+    repoFullName: stringOrNull(value.repoFullName),
+    hasInstallation: booleanOr(value.hasInstallation, false),
+    previewUrlSource,
+    previewUrlPattern: stringOrNull(value.previewUrlPattern),
+    deploymentEnvironment: stringOrNull(value.deploymentEnvironment),
+    waitForChecks: booleanOr(value.waitForChecks, false),
+    liveUrl: stringOrNull(value.liveUrl),
+    findingPrefix: stringOrNull(value.findingPrefix),
+    url: value.url,
+    lastRun: parseLastRun(value.lastRun)
+  };
+}
+function parseConnectionKind(value) {
+  if (value === "GITHUB" || value === "URL_ONLY") return value;
+  return void 0;
+}
+function parsePreviewUrlSource(value) {
+  if (value === "DEPLOYMENT_STATUS" || value === "URL_PATTERN") return value;
+  return void 0;
+}
+function parseLastRun(value) {
+  if (!isRecord2(value) || !isString(value.id)) return null;
+  return {
+    id: value.id,
+    status: stringOrNull(value.status) ?? "",
+    verdict: stringOrNull(value.verdict),
+    previewUrl: stringOrNull(value.previewUrl),
+    createdAt: stringOrNull(value.createdAt) ?? "",
+    prNumber: numberOrNull(value.prNumber),
+    branch: stringOrNull(value.branch)
+  };
+}
 
 // src/logger.ts
 import pc from "picocolors";
@@ -224,6 +827,605 @@ var defaultDeps = {
   now: () => Date.now()
 };
 
+// src/commands/setup-deps.ts
+var PROBE_TIMEOUT_MS = 5e3;
+var METHOD_NOT_ALLOWED = 405;
+var defaultSetupDeps = {
+  ...defaultDeps,
+  ...nodeFileSystem,
+  prompt: terminalPrompt,
+  openBrowser,
+  runCommand,
+  detectRepo: () => detectRepoFullName(),
+  repoRoot: () => detectRepoRoot() ?? process.cwd(),
+  deviceName: () => `${hostname()} (${currentUsername()})`,
+  configFilePath: resolveConfigFilePath(),
+  probeUrl: (url) => probeUrl(url)
+};
+function currentUsername(lookup = userInfo) {
+  try {
+    return lookup().username;
+  } catch {
+    return process.env.USER ?? process.env.USERNAME ?? "unknown";
+  }
+}
+async function probeUrl(url) {
+  try {
+    const head = await fetch(url, {
+      method: "HEAD",
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS)
+    });
+    if (head.status !== METHOD_NOT_ALLOWED) return { ok: head.ok, status: head.status };
+    const get = await fetch(url, { method: "GET", signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+    return { ok: get.ok, status: get.status };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+// src/commands/doctor.ts
+var MARKS = { pass: "\u2713", fail: "\u2717", skip: "\u2013" };
+var REPO_HINT = "pass --repo owner/name or run inside a checkout with a github.com origin remote";
+var INIT_HINT = "run `npx @datadisco/qa init`";
+async function runDoctor(options, deps = defaultSetupDeps) {
+  const checks = await collectChecks(options, deps);
+  for (const check of checks) printCheck(check, deps);
+  return checks.some((check) => check.state === "fail") ? 1 : 0;
+}
+async function collectChecks(options, deps) {
+  const apiUrl = resolveApiUrl(options);
+  const apiToken = findExistingToken(options, apiUrl, deps);
+  if (!apiToken) {
+    return [fail("API token", "run `datadisco-qa login`")];
+  }
+  const repo = options.repo ?? deps.detectRepo();
+  if (!repo) {
+    return [pass("API token present"), fail("Repository", REPO_HINT)];
+  }
+  return checksForRepo(deps.createApi({ apiUrl, apiToken }), apiUrl, repo, deps);
+}
+async function checksForRepo(api, apiUrl, repo, deps) {
+  const outcome = await api.listConnections(repo);
+  if (!outcome.ok) {
+    return [tokenFailure(outcome.status, outcome.error)];
+  }
+  const connection = findGithubConnection(outcome);
+  if (!connection) {
+    return [
+      pass(`API token valid for workspace ${outcome.workspace.name}`),
+      fail(`Repository ${repo} is not connected`, `connect it at ${connectRepoUrl(apiUrl, repo)}`)
+    ];
+  }
+  const detection = detectDeployHost(deps.repoRoot(), deps);
+  const workflow = readWorkflowState(deps);
+  const notNeeded = reasonCiReportNotNeeded(connection, detection, workflow);
+  return [
+    pass(`API token valid for workspace ${outcome.workspace.name}`),
+    connectionCheck(repo, connection),
+    previewSourceCheck(connection, detection, workflow),
+    notNeeded ? skip(`Workflow not needed: ${notNeeded}`) : workflowCheck(workflow),
+    notNeeded ? skip(`${API_TOKEN_SECRET_NAME} secret not needed: ${notNeeded}`) : secretCheck(repo, deps),
+    await liveUrlCheck(connection, deps),
+    lastRunCheck(connection.lastRun)
+  ];
+}
+function readWorkflowState(deps) {
+  const path = workflowFilePath(deps.repoRoot());
+  if (!deps.exists(path)) return "missing";
+  return triggersOnDeploymentStatus(deps.readFile(path) ?? "") ? "deployment-status" : "reports-previews";
+}
+function tokenFailure(status, error) {
+  if (status === 401) return fail("API token rejected", "run `datadisco-qa login`");
+  return fail(`Could not list connections (${error})`, "check --api-url and your network");
+}
+function connectionCheck(repo, connection) {
+  const problem = describeConnectionProblem(connection);
+  return problem ? fail(`Repository ${repo} is connected but unhealthy`, `${problem}: ${connection.url}`) : pass(`Repository ${repo} is connected (${connection.url})`);
+}
+function previewSourceCheck(connection, detection, workflow) {
+  if (connection.previewUrlSource === "URL_PATTERN") {
+    return pass(`Preview source: URL pattern ${connection.previewUrlPattern ?? "(unset)"}`);
+  }
+  const lastPreview = connection.lastRun?.previewUrl;
+  if (lastPreview) {
+    return pass(`Preview source: deploy events (last preview ${lastPreview})`);
+  }
+  if (detection.deployEvents) {
+    return pass(`Preview source: deploy events from ${detection.host} (no preview received yet)`);
+  }
+  if (workflow === "reports-previews") {
+    return pass(`Preview source: reported by ${WORKFLOW_RELATIVE_PATH} (no preview received yet)`);
+  }
+  if (workflow === "deployment-status") {
+    return fail(
+      `Preview source: ${WORKFLOW_RELATIVE_PATH} runs on deployment_status, and no preview URL has ever arrived`,
+      `${describeMissingDeployEvents(detection)}, so it never fires \u2014 report a URL pattern instead; ${INIT_HINT}`
+    );
+  }
+  return fail(
+    "Preview source: deploy events, but no preview URL has ever arrived",
+    `${describeMissingDeployEvents(detection)} \u2014 add a CI report or a URL pattern; ${INIT_HINT}`
+  );
+}
+function describeMissingDeployEvents(detection) {
+  if (detection.host === "unknown") return "the deploy host was not detected";
+  return isDeployEventHost(detection.host) ? `${detection.host} is deployed from CI, which emits no deploy events` : `${detection.host} does not emit deploy events`;
+}
+function reasonCiReportNotNeeded(connection, detection, workflow) {
+  if (workflow !== "missing") return void 0;
+  if (connection.previewUrlSource === "URL_PATTERN") return "previews come from the URL pattern";
+  if (detection.deployEvents) return `${detection.host} emits deploy events`;
+  if (connection.lastRun?.previewUrl) return "previews already arrive as deploy events";
+  return void 0;
+}
+function workflowCheck(workflow) {
+  return workflow !== "missing" ? pass(`${WORKFLOW_RELATIVE_PATH} present`) : fail(`${WORKFLOW_RELATIVE_PATH} missing`, INIT_HINT);
+}
+function secretCheck(repo, deps) {
+  const gh = checkGh(deps.runCommand);
+  if (gh !== "ready") {
+    return skip(
+      `${API_TOKEN_SECRET_NAME} secret not checked (gh ${gh === "missing" ? "not installed" : "not signed in"})`
+    );
+  }
+  const names = listRepoSecretNames(deps.runCommand, repo);
+  if (!names)
+    return skip(`${API_TOKEN_SECRET_NAME} secret not checked (gh could not list secrets)`);
+  return names.includes(API_TOKEN_SECRET_NAME) ? pass(`${API_TOKEN_SECRET_NAME} secret set on ${repo}`) : fail(
+    `${API_TOKEN_SECRET_NAME} secret missing on ${repo}`,
+    `gh secret set ${API_TOKEN_SECRET_NAME} --repo ${repo}`
+  );
+}
+async function liveUrlCheck(connection, deps) {
+  if (!connection.liveUrl) return skip("Live URL not set");
+  const probe = await deps.probeUrl(connection.liveUrl);
+  if (probe.ok) return pass(`Live URL reachable (${connection.liveUrl})`);
+  const detail = probe.status !== void 0 ? `HTTP ${probe.status}` : probe.error ?? "unreachable";
+  return fail(
+    `Live URL unreachable (${connection.liveUrl}: ${detail})`,
+    "check the URL on the connection page"
+  );
+}
+function lastRunCheck(lastRun) {
+  if (!lastRun) return skip("No QA runs yet");
+  const target = lastRun.prNumber !== null ? `PR #${lastRun.prNumber}` : lastRun.branch ?? "unknown ref";
+  const verdict = lastRun.verdict ? `, verdict ${lastRun.verdict}` : "";
+  return pass(`Last run: ${lastRun.status}${verdict} on ${target} at ${lastRun.createdAt}`);
+}
+function printCheck(check, deps) {
+  const line = `${MARKS[check.state]} ${check.label}`;
+  if (check.state === "pass") return deps.logger.success(line);
+  if (check.state === "skip") return deps.logger.info(line);
+  deps.logger.error(check.hint ? `${line} \u2014 ${check.hint}` : line);
+}
+function pass(label) {
+  return { state: "pass", label };
+}
+function fail(label, hint) {
+  return { state: "fail", label, hint };
+}
+function skip(label) {
+  return { state: "skip", label };
+}
+
+// src/commands/init.ts
+var INIT_EXIT_CODE = {
+  DONE: 0,
+  ERROR: 1,
+  STOPPED_WAITING: 2
+};
+var CONNECTION_POLL_INTERVAL_MS = 5e3;
+var CONNECTION_WAIT_TIMEOUT_MS = 10 * 6e4;
+var EXAMPLE_PATTERN = `https://pr-${PATTERN_PLACEHOLDER}.preview.example.com`;
+var REPO_MISSING_MESSAGE = "Repository not set: pass --repo owner/name, or run inside a git checkout with a github.com origin remote.";
+async function runInit(options, deps = defaultSetupDeps) {
+  const session = await resolveSession(options, deps);
+  if (!session.ok) {
+    deps.logger.error(session.error);
+    return INIT_EXIT_CODE.ERROR;
+  }
+  const { apiUrl, apiToken, api } = session.session;
+  const repo = resolveRepo(options, deps);
+  deps.logger.info(`Repository: ${repo}`);
+  const connection = await ensureConnection(api, apiUrl, repo, options, deps);
+  if (typeof connection === "number") return connection;
+  const detection = detectDeployHost(deps.repoRoot(), deps);
+  deps.logger.info(describeDetection(detection));
+  const written = await configurePreviewReporting(connection, detection, options, deps);
+  if (written === "needs-pattern") return INIT_EXIT_CODE.ERROR;
+  if (written === "workflow-present") {
+    await ensureSecret(repo, apiToken, options, deps);
+  }
+  printSummary(connection, written, deps);
+  return INIT_EXIT_CODE.DONE;
+}
+function resolveRepo(options, deps) {
+  const repo = options.repo ?? deps.detectRepo();
+  if (!repo) throw new ConfigError(REPO_MISSING_MESSAGE);
+  return repo;
+}
+async function ensureConnection(api, apiUrl, repo, options, deps) {
+  const outcome = await api.listConnections(repo);
+  if (!outcome.ok) {
+    deps.logger.error(describeListFailure(outcome.status, outcome.error));
+    return INIT_EXIT_CODE.ERROR;
+  }
+  const existing = findGithubConnection(outcome);
+  if (existing) {
+    deps.logger.success(`Connected to workspace ${outcome.workspace.name} (${existing.url})`);
+    return existing;
+  }
+  const connectUrl = connectRepoUrl(apiUrl, repo);
+  deps.logger.warn("This repo is not connected yet.");
+  deps.logger.info(`Connect it at ${connectUrl}`);
+  if (options.browser !== false) await deps.openBrowser(connectUrl);
+  if (options.yes) {
+    deps.logger.info("Re-run `datadisco-qa init` once the repo is connected.");
+    return INIT_EXIT_CODE.STOPPED_WAITING;
+  }
+  return waitForConnection(api, repo, deps);
+}
+async function waitForConnection(api, repo, deps) {
+  const deadline = deps.now() + CONNECTION_WAIT_TIMEOUT_MS;
+  deps.logger.info("Waiting for you to connect the repo in the browser\u2026");
+  while (deps.now() < deadline) {
+    await deps.sleep(CONNECTION_POLL_INTERVAL_MS);
+    const outcome = await pollConnections(api, repo);
+    if (!outcome.ok && isFinalListFailure(outcome.status)) {
+      deps.logger.error(describeListFailure(outcome.status, outcome.error));
+      return INIT_EXIT_CODE.ERROR;
+    }
+    const connection = findGithubConnection(outcome);
+    if (connection) {
+      deps.logger.success(`Connected: ${connection.url}`);
+      return connection;
+    }
+  }
+  deps.logger.error(
+    "Gave up waiting for the repo to be connected. Re-run `datadisco-qa init` once it is."
+  );
+  return INIT_EXIT_CODE.STOPPED_WAITING;
+}
+async function pollConnections(api, repo) {
+  try {
+    return await api.listConnections(repo);
+  } catch (error) {
+    return { ok: false, status: 0, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+function isFinalListFailure(status) {
+  return status >= 400 && status < 500 && status !== 429;
+}
+function describeListFailure(status, error) {
+  if (status === 401) {
+    return `The API token was rejected (${error}). Run \`datadisco-qa login\` to sign in again.`;
+  }
+  return `Could not look up the repo's connections: ${error}`;
+}
+function describeDetection(detection) {
+  const evidence = detection.evidence.length > 0 ? ` (${detection.evidence.join(", ")})` : "";
+  return detection.host === "unknown" ? `Deploy host: not detected${evidence}` : `Deploy host: ${detection.host}${evidence}`;
+}
+async function configurePreviewReporting(connection, detection, options, deps) {
+  if (connection.previewUrlSource === "URL_PATTERN") {
+    deps.logger.info(
+      `Nothing to add: the connection derives previews from the URL pattern ${connection.previewUrlPattern ?? ""}`.trimEnd()
+    );
+    return "nothing-to-add";
+  }
+  if (detection.deployEvents) {
+    deps.logger.info("Nothing to add: DataDisco picks previews up from deploy events.");
+    return "nothing-to-add";
+  }
+  return offerWorkflow(connection, options, deps);
+}
+async function offerWorkflow(connection, options, deps) {
+  deps.logger.info(
+    "Previews from this host don't reach GitHub as deploy events, so CI needs to report each preview URL."
+  );
+  const path = workflowFilePath(deps.repoRoot());
+  if (deps.exists(path) && !await confirmOverwrite(options, deps)) {
+    deps.logger.info(`Keeping the existing ${WORKFLOW_RELATIVE_PATH}.`);
+    return "workflow-present";
+  }
+  const pattern = await choosePattern(connection, options, deps);
+  if (!pattern) {
+    printPatternNeeded(connection, deps);
+    return "needs-pattern";
+  }
+  deps.writeFile(path, renderWorkflow(pattern));
+  deps.logger.success(`Wrote ${WORKFLOW_RELATIVE_PATH}: ${describeRecipe(pattern)}`);
+  return "workflow-present";
+}
+async function confirmOverwrite(options, deps) {
+  if (options.yes) return false;
+  return confirm(deps.prompt, `${WORKFLOW_RELATIVE_PATH} already exists. Overwrite it?`, false);
+}
+async function choosePattern(connection, options, deps) {
+  const suggested = connection.previewUrlPattern ?? void 0;
+  if (options.yes) {
+    if (suggested) assertValidPreviewUrlPattern(suggested);
+    return suggested;
+  }
+  return askPattern(suggested, deps);
+}
+async function askPattern(suggested, deps) {
+  let defaultValue = suggested;
+  for (; ; ) {
+    const pattern = await deps.prompt(
+      `Preview URL pattern with ${PATTERN_PLACEHOLDER}, e.g. ${EXAMPLE_PATTERN}`,
+      defaultValue
+    );
+    if (!pattern) return void 0;
+    try {
+      assertValidPreviewUrlPattern(pattern);
+      return pattern;
+    } catch (error) {
+      if (!(error instanceof ConfigError)) throw error;
+      deps.logger.error(error.message);
+      defaultValue = void 0;
+    }
+  }
+}
+function printPatternNeeded(connection, deps) {
+  deps.logger.error(
+    `A preview URL pattern is needed to report previews from CI, e.g. ${EXAMPLE_PATTERN}. Nothing was written.`
+  );
+  deps.logger.info(
+    `Set one on ${connection.url} or re-run \`datadisco-qa init\` and enter it when asked.`
+  );
+}
+async function ensureSecret(repo, apiToken, options, deps) {
+  const gh = checkGh(deps.runCommand);
+  if (gh !== "ready") {
+    printManualSecretSteps(repo, gh, deps);
+    return;
+  }
+  const existing = listRepoSecretNames(deps.runCommand, repo);
+  if (existing?.includes(API_TOKEN_SECRET_NAME)) {
+    await replaceExistingSecret(repo, apiToken, options, deps);
+    return;
+  }
+  const wanted = await confirmStoreSecret(repo, existing !== void 0, options, deps);
+  if (!wanted) {
+    printManualSecretSteps(repo, gh, deps);
+    return;
+  }
+  storeSecret(repo, apiToken, gh, deps);
+}
+async function replaceExistingSecret(repo, apiToken, options, deps) {
+  const replace = !options.yes && await confirm(
+    deps.prompt,
+    `${API_TOKEN_SECRET_NAME} is already set on ${repo}. Replace it with your personal sign-in token?`,
+    false
+  );
+  if (!replace) {
+    deps.logger.info(`Keeping the existing ${API_TOKEN_SECRET_NAME} secret on ${repo}.`);
+    return;
+  }
+  storeSecret(repo, apiToken, "ready", deps);
+}
+async function confirmStoreSecret(repo, listed, options, deps) {
+  const question = `Store your personal sign-in token as the ${API_TOKEN_SECRET_NAME} Actions secret on ${repo} via gh?`;
+  if (listed) return options.yes || confirm(deps.prompt, question, true);
+  deps.logger.warn(`Could not check whether ${API_TOKEN_SECRET_NAME} is already set on ${repo}.`);
+  return !options.yes && confirm(deps.prompt, `${question} It replaces the secret if set.`, false);
+}
+function storeSecret(repo, apiToken, gh, deps) {
+  const result = setRepoSecret(deps.runCommand, repo, API_TOKEN_SECRET_NAME, apiToken);
+  if (result.ok) {
+    deps.logger.success(`Set the ${API_TOKEN_SECRET_NAME} secret on ${repo}.`);
+    return;
+  }
+  deps.logger.warn(`gh could not set the secret: ${result.stderr.trim() || "unknown error"}`);
+  printManualSecretSteps(repo, gh, deps);
+}
+var MANUAL_SECRET_REASONS = {
+  missing: "gh is not installed",
+  unauthenticated: "gh is not signed in (run `gh auth login`)",
+  ready: "skipped"
+};
+function printManualSecretSteps(repo, gh, deps) {
+  deps.logger.info(
+    `Add the ${API_TOKEN_SECRET_NAME} secret manually (${MANUAL_SECRET_REASONS[gh]}):`
+  );
+  deps.logger.info(`  1. Open https://github.com/${repo}/settings/secrets/actions/new`);
+  deps.logger.info(`  2. Name: ${API_TOKEN_SECRET_NAME}`);
+  deps.logger.info(
+    "  3. Value: the workspace API token from Workspace settings \u2192 Integrations \u2192 API tokens"
+  );
+  deps.logger.info(`  (or: gh secret set ${API_TOKEN_SECRET_NAME} --repo ${repo})`);
+}
+function printSummary(connection, written, deps) {
+  deps.logger.info("");
+  deps.logger.success(`Done. QA for this repo: ${connection.url}`);
+  deps.logger.info(
+    written === "workflow-present" ? `Commit ${WORKFLOW_RELATIVE_PATH} and open a pull request to start the first run.` : "Nothing was written \u2014 open a pull request to start the first run."
+  );
+  deps.logger.info("Run `npx @datadisco/qa doctor` any time to re-check.");
+}
+
+// src/commands/login.ts
+async function runLogin(options, deps = defaultSetupDeps) {
+  const apiUrl = resolveApiUrl(options);
+  const result = await signIn(apiUrl, deps.createApi({ apiUrl }), deps, {
+    openBrowser: options.browser !== false
+  });
+  if (!result.ok) {
+    deps.logger.error(result.error);
+    return 1;
+  }
+  deps.logger.info(`Token saved to ${deps.configFilePath}`);
+  return 0;
+}
+
+// src/commands/logout.ts
+async function runLogout(options, deps = defaultSetupDeps) {
+  const apiUrl = resolveApiUrl(options);
+  if (!deleteStoredToken(apiUrl, deps)) {
+    deps.logger.info(`No saved sign-in for ${apiUrl}.`);
+    return 0;
+  }
+  deps.logger.success(`Signed out of ${apiUrl} (removed from ${deps.configFilePath}).`);
+  return 0;
+}
+
+// src/context.ts
+import { readFileSync as readFileSync2 } from "fs";
+var REPO_PATTERN = /^[^/\s]+\/[^/\s]+$/;
+var PR_REF_PATTERN = /^refs\/pull\/(\d+)\//;
+var REPO_MISSING_MESSAGE2 = "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: resolveRepo2(input, env),
+    prNumber: resolvePrNumber(input, env, payload),
+    headSha
+  };
+}
+function resolvePrContext(input = {}) {
+  const env = input.env ?? process.env;
+  const payload = loadEventPayload(input, env);
+  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: resolveRepo2(input, env), prNumber, headSha };
+}
+function resolveRepo2(input, env = {}) {
+  const repo = input.repo ?? env.GITHUB_REPOSITORY ?? detectRepoFullName(input.gitRunner);
+  if (!repo) {
+    throw new ConfigError(REPO_MISSING_MESSAGE2);
+  }
+  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 ?? resolvePrNumberFromCiEnv(env);
+  return toPositiveInteger(candidate);
+}
+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);
+  if (!isRecord3(raw)) return {};
+  const pullRequest = isRecord3(raw.pull_request) ? raw.pull_request : void 0;
+  const head = isRecord3(pullRequest?.head) ? pullRequest.head : void 0;
+  return {
+    prNumber: numberOrUndefined(pullRequest?.number ?? raw.number),
+    headSha: stringOrUndefined2(head?.sha)
+  };
+}
+function readEventFile(path) {
+  if (!path) return void 0;
+  return JSON.parse(readFileSync2(path, "utf8"));
+}
+function safeRead(read) {
+  try {
+    return read();
+  } catch {
+    return void 0;
+  }
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null;
+}
+function numberOrUndefined(value) {
+  return typeof value === "number" ? value : void 0;
+}
+function stringOrUndefined2(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/verdict.ts
 var EXIT_CODE = {
   PASSED: 0,
@@ -301,7 +1503,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);
@@ -316,7 +1518,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) {
@@ -328,6 +1532,16 @@ async function waitForVerdict(api, context, deps, timeoutMs) {
     await deps.sleep(POLL_INTERVAL_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
@@ -359,7 +1573,7 @@ async function runReportPreview(options, deps = defaultDeps) {
   }
   assertValidPreviewUrl(options.url);
   const config = resolveConfig(options);
-  const context = resolveRunContext(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, {
@@ -367,11 +1581,11 @@ async function runReportPreview(options, deps = defaultDeps) {
     waitRunTimeoutMs
   });
   if (!outcome.ok) {
-    deps.logger.error(`Could not report preview URL: ${describeFailure(outcome)}`);
+    deps.logger.error(`Could not report preview URL: ${describeFailure(outcome, context)}`);
     return 1;
   }
   deps.logger.success(
-    `Preview reported for ${context.repo}#${context.prNumber} \u2014 QA run ${outcome.runId} queued.`
+    `Preview reported for ${describeContextTarget(context)} \u2014 QA run ${outcome.runId} queued.`
   );
   return 0;
 }
@@ -385,7 +1599,14 @@ async function reportPreviewUntilRunExists(api, context, url, deps, policy) {
 function isRunNotCreatedYet(outcome) {
   return !outcome.ok && outcome.status === RUN_NOT_CREATED_YET_STATUS && outcome.retryable !== false;
 }
-function describeFailure(outcome) {
+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) {
@@ -410,28 +1631,6 @@ 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) {
@@ -498,6 +1697,16 @@ async function runWait(options, deps = defaultDeps) {
 
 // src/cli.ts
 var cli = cac("datadisco-qa");
+cli.command("init", "Sign in, connect this repo, and set up preview reporting").option("--yes", "Skip prompts: never wait, never overwrite, take the defaults").option("--repo <owner/name>", "Repository (defaults to the git origin remote)").option("--api-url <url>", "DataDisco API base URL").option(
+  "--api-token <token>",
+  "Workspace API token (or DATADISCO_API_TOKEN, or the saved sign-in)"
+).option("--no-browser", "Print URLs instead of opening them in a browser").action((options) => run(() => runInit(options)));
+cli.command("doctor", "Check the sign-in, repo connection, preview source, workflow, and secret").option("--repo <owner/name>", "Repository (defaults to the git origin remote)").option("--api-url <url>", "DataDisco API base URL").option(
+  "--api-token <token>",
+  "Workspace API token (or DATADISCO_API_TOKEN, or the saved sign-in)"
+).action((options) => run(() => runDoctor(options)));
+cli.command("login", "Sign in to DataDisco from this machine and save the token").option("--api-url <url>", "DataDisco API base URL").option("--no-browser", "Print the verification URL instead of opening it").action((options) => run(() => runLogin(options)));
+cli.command("logout", "Forget the saved sign-in for the API URL").option("--api-url <url>", "DataDisco API base URL").action((options) => run(() => runLogout(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"
@@ -505,12 +1714,16 @@ cli.command("report-preview", "Report a PR's preview-deploy URL so its pending Q
   "--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("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 {
     process.exitCode = await command();
   } catch (error) {
+    if (error instanceof PromptCancelledError) {
+      process.exitCode = 130;
+      return;
+    }
     if (error instanceof ConfigError) {
       console.error(pc2.red(error.message));
       process.exitCode = 1;