Initial qa-cli: local runner for pagerguild QA agents

Bootstrap with: uv run https://raw.githubusercontent.com/pagerguild/qa/main/qa.py --target URL --here

- qa.py: PEP 723 stdlib-only wrapper around `act`. Resolves a target repo
  (--here / --path / --repo), mints a 1-hour Doppler service token,
  overlays qa-team's scripts/.github onto the target's .qa/ tasks,
  rewrites localhost URLs to host.docker.internal, and runs the
  qa-matrix.yml workflow with the pre-baked runner image.
- Dockerfile: catthehacker/ubuntu:act-latest + Playwright chromium baked
  in; eliminates the 3-min install on every act run.
- build-image.yml: multi-arch (amd64+arm64) push to
  ghcr.io/pagerguild/qa-runner:latest on push to main.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: tylergannon

.github/workflows/build-image.yml

@@ -0,0 +1,43 @@
+# Builds and publishes the pre-baked qa-runner image to GHCR.
+#
+# Output: ghcr.io/pagerguild/qa-runner:latest (multi-arch: amd64 + arm64).
+#
+# qa.py pulls this on first run (and treats it as a cache miss on later
+# runs once it's tagged locally as pagerguild/qa-runner:local).
+
+name: Build runner image
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - Dockerfile
+      - .github/workflows/build-image.yml
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ghcr.io/pagerguild/qa-runner:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.DS_Store
+.secrets

Dockerfile

@@ -0,0 +1,35 @@
+# Pre-baked runner image for `qa.py`. Inherits catthehacker (the standard
+# act runner image — has node/npm/python/git/jq/sudo all configured the way
+# act expects), then bakes Playwright + chromium on top so we don't pay
+# the 3-minute install cost on every local act run.
+#
+# Built multi-arch (amd64 + arm64) by .github/workflows/build-image.yml in
+# this repo, published to ghcr.io/pagerguild/qa-cli/runner:latest. The wrapper
+# pins to a digest, not :latest, so cache-busting is explicit.
+#
+# Local override during dev: `docker build -t qa-cli/runner:local .` and pass
+# `--runner-image qa-cli/runner:local` to qa.py.
+
+FROM catthehacker/ubuntu:act-latest
+
+# Auto-link the published GHCR package to this repo so visibility flips
+# (private → public) appear in pagerguild/qa's package UI.
+LABEL org.opencontainers.image.source=https://github.com/pagerguild/qa
+
+# Pin Playwright to a known-good version. Bump in lockstep with whatever the
+# personas expect; the chromium binary version is tied to the Playwright
+# release. Re-bake the image when this changes.
+ARG PLAYWRIGHT_VERSION=1.49.1
+
+RUN set -eux; \
+    npx -y playwright@${PLAYWRIGHT_VERSION} install --with-deps chromium; \
+    CHROME_BIN=$(find /root/.cache/ms-playwright -path '*/chromium-*/chrome-linux*/chrome' -type f | head -1); \
+    test -n "$CHROME_BIN"; \
+    ln -sf "$CHROME_BIN" /usr/bin/chromium; \
+    test -x /usr/bin/chromium; \
+    echo "baked $CHROME_BIN → /usr/bin/chromium"
+
+# Reset to the entrypoint catthehacker expects so act's container lifecycle
+# (tail -f /dev/null then docker exec) keeps working.
+ENTRYPOINT []
+CMD ["bash"]

README.md

@@ -0,0 +1,40 @@
+# qa
+
+Local runner for pagerguild QA agents.
+
+```sh
+uv run https://raw.githubusercontent.com/pagerguild/qa/main/qa.py \
+  --target http://localhost:5173 --here
+```
+
+Runs every `.qa/<agent>/` task in your repo against any URL, in
+parallel matrix containers, using the same workflow that drives CI.
+Output streams into the team's Supabase reader at
+https://qa.guys.dev.guilde.ai.
+
+## Prereqs
+
+- `uv` — `brew install uv`
+- `gh` — `brew install gh && gh auth login`
+- `doppler` — `brew install dopplerhq/cli/doppler`, `doppler login`,
+  and `doppler setup` from a directory scoped to a Doppler config that
+  has the QA agent's secrets
+- `act` — `brew install act`
+- Docker Desktop, running
+
+## Usage
+
+```
+qa --target URL (--here | --path DIR | --repo OWNER/NAME [--branch B])
+   [--qa-dir DIR] [--verbose]
+```
+
+- `--here` runs against the current directory's checkout.
+- `--path DIR` runs against an existing checkout at `DIR`.
+- `--repo OWNER/NAME` clones the repo fresh into a temp dir and uses
+  that. Add `--branch` to pin a branch.
+
+`localhost` URLs get rewritten to `host.docker.internal` automatically
+so the agent inside the container can reach your dev server.
+
+On Apple Silicon, native arm64 containers are selected automatically.