@datadisco/qa 0.3.0 → 0.4.0

package/README.md

@@ -9,9 +9,21 @@ simulation ("confirmation testing for agentic teams").
 npm i -g @datadisco/qa     # or run ad hoc: npx @datadisco/qa <command>
 ```
 
-Most teams consume it through the
+### Quick start
+
+```sh
+npx @datadisco/qa init
+```
+
+`init` signs you in from the browser, connects the current repo to your
+DataDisco workspace, works out how your previews get deployed, and — only when
+your host doesn't emit GitHub deploy events — writes a `report-preview`
+workflow and stores the API token as an Actions secret. Run
+`npx @datadisco/qa doctor` afterwards (or any time) to re-check the setup.
+
+Most teams' CI consumes the CLI 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.
+GitHub Action, which wraps this CLI — `init` writes that workflow for you.
 
 ## Why this exists
 
@@ -23,21 +35,42 @@ App can't see:
 
 | Command                                   | For teams that…                                                                                              |
 | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `datadisco-qa init`                       | want the whole setup — sign-in, repo connection, preview reporting, secret — done from one prompt            |
+| `datadisco-qa doctor`                     | want to know why a run isn't starting: checks the token, connection, preview source, workflow, and secret    |
 | `datadisco-qa report-preview --url <url>` | deploy previews without emitting GitHub Deployment events — report the URL from CI so the pending run starts |
 | `datadisco-qa wait --pr <n>`              | want a pipeline step to block on the QA verdict instead of relying on branch protection                      |
 | `datadisco-qa tunnel --port <port>`       | want to run personas against a build served on their own machine                                             |
 
 ## Authentication
 
-Every command needs a **workspace API token** (create one under
-_Workspace settings → Integrations → API tokens_). Pass it with
-`--api-token` or the `DATADISCO_API_TOKEN` env var. The API base URL defaults
-to the hosted app and is overridable with `--api-url` / `DATADISCO_API_URL`.
+Every command needs a **workspace API token**. In CI, pass it with
+`--api-token` or the `DATADISCO_API_TOKEN` env var (create one under
+_Workspace settings → Integrations → API tokens_):
 
 ```sh
 export DATADISCO_API_TOKEN=ddqa_xxx
 ```
 
+On your own machine, `datadisco-qa login` (or the first `init`) signs you in
+from the browser instead: it shows a short pairing code, you confirm it in
+DataDisco, and the resulting token is saved to the CLI config file.
+`init` and `doctor` look for a token in this order: `--api-token`,
+`DATADISCO_API_TOKEN`, then the saved sign-in for the API URL in use.
+`report-preview`, `wait`, and `tunnel` only read the flag and env var.
+
+The API base URL defaults to the hosted app and is overridable with
+`--api-url` / `DATADISCO_API_URL`; saved sign-ins are keyed by it, so a
+staging server gets its own entry.
+
+### Config file
+
+| Location                                                                 | Contents                                                                                 |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `$XDG_CONFIG_HOME/datadisco/qa.json`, else `~/.config/datadisco/qa.json` | `{ "tokens": { "<apiUrl>": { "token", "workspaceName", "workspaceSlug", "savedAt" } } }` |
+
+The file is written with mode `0600`. `datadisco-qa logout` removes the entry
+for the current API URL.
+
 ## Works in any CI
 
 `report-preview` and `wait` auto-detect the repository, PR number, and head
@@ -82,6 +115,88 @@ HTTPS); for anything else, pass `--repo` explicitly.
 
 ## Commands
 
+### `init`
+
+Interactive, idempotent setup for the current repo:
+
+1. **Token** — uses `--api-token` / `DATADISCO_API_TOKEN` / the saved
+   sign-in, or pairs this machine from the browser and saves the token.
+2. **Repo** — `--repo owner/name` or the git `origin` remote.
+3. **Connection** — looks the repo up in the workspace. If it isn't connected
+   yet, prints (and opens) the connect page and waits up to 10 minutes for
+   you to finish in the browser.
+4. **Host detection** — purely local: looks for `vercel.json` / `.vercel/`,
+   `netlify.toml`, `amplify.yml`, `fly.toml`, `render.yaml`,
+   `railway.json` / `railway.toml`, and scans `.github/workflows/*.yml` for
+   host names.
+5. **Preview reporting** — Vercel, Netlify, and Amplify's Git integrations
+   emit GitHub deploy events, so when one of their marker files is present
+   nothing is written (likewise when the connection already uses a URL
+   pattern). A workflow that mentions one of them is taken to deploy through
+   its CLI, which emits no deploy events. In every other case it writes
+   `.github/workflows/datadisco-qa.yml` using `Data-Disco-Inc/qa-action@v1`:
+   a `pull_request` recipe with your preview URL pattern
+   (`https://pr-{number}.example.dev`, defaulting to the pattern configured in
+   DataDisco). Without a pattern nothing is written and `init` exits `1`. An
+   existing file is never overwritten without confirmation. It then offers to
+   store your sign-in token — a personal token, so CI acts as you — as the
+   `DATADISCO_API_TOKEN` Actions secret via `gh secret set` when `gh` is
+   installed and signed in, or prints the manual steps. An existing secret is
+   kept unless you explicitly agree to replace it (never under `--yes`).
+6. **Summary** — the repo's DataDisco URL and what was written.
+
+```sh
+datadisco-qa init
+datadisco-qa init --yes --repo acme/site   # non-interactive: never waits, never overwrites
+datadisco-qa init --no-browser             # print URLs instead of opening them
+```
+
+| Flag           | Effect                                                                                                                             |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `--yes`        | Skip prompts: take the server's pattern (exit `1` when it has none), never overwrite, exit `2` instead of waiting for a connection |
+| `--repo`       | Repository, when the git remote isn't the one you mean                                                                             |
+| `--no-browser` | Don't try to open the pairing / connect pages                                                                                      |
+
+**Exit codes:** `0` done, `1` error, `2` stopped waiting for you (re-run once
+the repo is connected).
+
+### `doctor`
+
+Re-checks the setup and prints one line per check — `✓` pass, `✗` fail with a
+fix hint, `–` skipped:
+
+- the API token is present and accepted by the server,
+- the repo is resolved and has a healthy GitHub connection (App installed,
+  enabled, `ACTIVE`),
+- the preview source: the configured URL pattern, or whether a preview URL has
+  ever arrived via deploy events (warning when it hasn't and the local host
+  doesn't emit them),
+- the `datadisco-qa.yml` workflow is present when CI needs to report previews
+  (one that only runs on `deployment_status` doesn't count as a preview
+  source),
+- the `DATADISCO_API_TOKEN` Actions secret exists (via `gh secret list`;
+  skipped without `gh`). Both this and the workflow check are skipped when
+  `init` would write neither: the connection uses a URL pattern, the host
+  emits deploy events, or previews already arrive without the workflow,
+- the connection's live URL responds (5 s timeout) when one is set,
+- the last run's status, verdict, and time.
+
+```sh
+datadisco-qa doctor
+```
+
+Exits `1` if any check fails, `0` otherwise.
+
+### `login` / `logout`
+
+```sh
+datadisco-qa login             # pair this machine and save the token
+datadisco-qa login --no-browser
+datadisco-qa logout            # forget the saved token for the API URL
+```
+
+`login` always pairs afresh, replacing any saved token for that API URL.
+
 ### `report-preview`
 
 Report the deployed preview URL for a PR head SHA so its pending QA run leaves