# tasks — react-ui-registry-deployment

## 0. Pre-flight (non-negotiable)

- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.

## 1. Registry build script (in `@suaveplan/react-ui`)

- [ ] 1.1 Create `packages/react/react-ui/scripts/build-registry.ts`.
  Walks the package's component source tree and emits one
  `registry-item` JSON per component plus a top-level
  `registry/r/index.json` listing every entry.
- [ ] 1.2 Match the shadcn `registry-item` v1 schema exactly:
  `$schema`, `name`, `type`, `dependencies`, `registryDependencies`,
  `files[]`, `tailwind`, `cssVars`. Validate the emitted JSON
  against a Zod schema before writing — the build fails on shape
  drift.
- [ ] 1.3 Emit deterministic output: stable key order, LF
  line endings, trailing newline. The CI snapshot diff in the
  package's existing test suite will catch accidental drift.
- [ ] 1.4 Co-locate `build-registry.md` per the genesis docs rule
  (≥200 words, Purpose / Features / Basic Example / Advanced
  Example / API Reference / Implementation Notes).
- [ ] 1.5 Add a smoke test
  `packages/react/react-ui/scripts/build-registry.test.ts` that
  invokes the script in a temp dir, parses every emitted JSON, and
  asserts schema conformance.

## 2. Caddy + Docker scaffolding

- [ ] 2.1 Write `ops/registry/Dockerfile` — `FROM caddy:2-alpine`,
  `COPY Caddyfile /etc/caddy/Caddyfile`, healthcheck on
  `/health`.
- [ ] 2.2 Write `ops/registry/Caddyfile` — `ui.suaveplan.com` site
  block with:
  - `root * /srv/registry`
  - `handle_path /r/*` → `file_server` with
    `Access-Control-Allow-Origin: *`
  - `handle_path /storybook/*` → `file_server` with restrictive
    CSP
  - `handle /health` → `respond 200 "ok"`
  - `tls` block pinning `protocols tls1.2 tls1.3`
  - `header` block with HSTS, `X-Content-Type-Options`,
    `Referrer-Policy`, `Permissions-Policy`
  - `encode gzip zstd`
  - explicit deny on `/.well-known/*` outside ACME
- [ ] 2.3 Write `ops/registry/docker-compose.yml` — one service
  `registry`, port `80:80` and `443:443`, named volumes
  `caddy_data` and `caddy_config`, bind-mount
  `/srv/registry:/srv/registry:ro`, `restart: unless-stopped`.
- [ ] 2.4 Write `ops/registry/.env.example` — placeholders
  `OVH_SSH_HOST=__OVH_HOST__`, `OVH_SSH_USER=deploy-registry`,
  `REGISTRY_DEPLOY_PATH=/srv/registry/r/`,
  `STORYBOOK_DEPLOY_PATH=/srv/registry/storybook/`. No real
  values.

## 3. Deployment runbook

- [ ] 3.1 Write `ops/registry/README.md` covering:
  - Architecture overview (one Caddy container, two paths)
  - First-time setup (clone, env, `docker compose up -d`, cert
    issuance check)
  - Creating the `deploy-registry` user with scoped sudoers rule
  - Installing the CI public key on OVH
  - The on-deploy flow (path-filtered GitHub Action, rsync,
    no-reload-needed-for-static)
  - Manual ad-hoc admin via `ssh root@ovh` (out-of-band; CI
    intentionally does not use root)
  - Rollback via `bash ops/registry/rollback.sh` (one-shot atomic
    swap from `/srv/registry/.previous/<timestamp>/`)
  - Cert renewal (Caddy handles automatically; how to verify and
    how to force-renew if needed)
  - GitHub Actions secret rotation steps
- [ ] 3.2 Write `ops/registry/rollback.sh` referenced from the
  runbook. Idempotent, exits non-zero with a clear message if no
  snapshot exists.

## 4. CI workflow

- [ ] 4.1 Write `.github/workflows/registry-deploy.yml` — triggers
  on push to `genesis` with path filter
  `packages/react/react-ui/**` plus `ops/registry/**`. Job steps:
  - `actions/checkout@v4`
  - Setup Bun via `oven-sh/setup-bun@v2`
  - `bun install --frozen-lockfile`
  - `bunx turbo build --filter=@suaveplan/react-ui`
  - `bun packages/react/react-ui/scripts/build-registry.ts`
  - `cd packages/react/react-ui && bun run build-storybook`
  - `webfactory/ssh-agent@v0.9.0` with the `OVH_SSH_PRIVATE_KEY`
    secret
  - `rsync -azh --delete --backup
    --backup-dir=/srv/registry/.previous/$(date -u
    +%Y%m%dT%H%M%SZ)/r/ packages/react/react-ui/registry/r/
    "$OVH_SSH_USER@$OVH_SSH_HOST:/srv/registry/r/"`
  - same for storybook with its own `--backup-dir`
  - post-deploy `curl -fsSL
    https://ui.suaveplan.com/health` smoke test
- [ ] 4.2 Add a `concurrency:` block keyed on the workflow + ref
  so back-to-back pushes serialise, never race.
- [ ] 4.3 Document the three required GitHub Actions secrets in
  the runbook (`OVH_SSH_PRIVATE_KEY`, `OVH_SSH_HOST`,
  `OVH_SSH_USER`). NEVER commit values.

## 5. Manual user steps (call out clearly)

The user MUST perform these one-time manual steps; they cannot be
scripted in this change because they involve secrets and OVH
host-side configuration.

- [ ] 5.1 **USER:** Generate a deploy SSH keypair locally
  (`ssh-keygen -t ed25519 -C "registry-deploy" -f
  ~/.ssh/registry_deploy`).
- [ ] 5.2 **USER:** Copy the public key to OVH under the
  `deploy-registry` user's `~/.ssh/authorized_keys` (after creating
  the user per the runbook).
- [ ] 5.3 **USER:** Add the private key as the
  `OVH_SSH_PRIVATE_KEY` secret in the GitHub repo settings.
- [ ] 5.4 **USER:** Add `OVH_SSH_HOST` and `OVH_SSH_USER` as
  GitHub Actions secrets (host = the OVH hostname, user =
  `deploy-registry`).
- [ ] 5.5 **USER:** Confirm `ui.suaveplan.com` A record points
  to the OVH IP (already done per change context, but re-verify
  with `dig +short ui.suaveplan.com` before first deploy).

## 6. Verification (Web App & Page Verification gate)

Per CLAUDE.md "Web App & Page Verification" — required even though
this is mostly static content.

- [ ] 6.1 Deploy from a feature branch first (NOT `genesis`)
  against a staging path or a temporary subdomain to validate the
  pipeline before pointing it at production.
- [ ] 6.2 Run a Playwright sweep: navigate to `/`, `/r/index.json`,
  `/storybook/`, plus a sampled subset of per-component manifests.
  Assert HTTPS, valid cert, expected DOM content, zero
  `console.error`, zero failed subresource requests.
- [ ] 6.3 End-to-end shadcn-add test: spin up a clean Vite + React
  project in a temp dir, point its `components.json` at the
  public registry, run `npx shadcn@latest add @suaveplan/button`,
  assert `src/components/ui/button.tsx` lands with the expected
  exports. This is the contract test.
- [ ] 6.4 Capture browser console + network during the Playwright
  sweep; any unexpected warning or 4xx/5xx fails the gate.
- [ ] 6.5 Run the rollback script once on the OVH host and verify
  the previous registry contents serve. Roll forward again before
  closing the task.
- [ ] 6.6 24 h after first production deploy, query the Caddy
  access log and confirm 5xx count is zero.

## 7. Documentation + change archive

- [ ] 7.1 Refresh root docs per AGENTS §13b: `MANIFEST.md`,
  `MISSING.yml`, `STATUS.md`, `SUMMARY.md`. The `STATUS.md` row
  for ops infrastructure should reflect that the registry deploy
  exists.
- [ ] 7.2 Run `bunx markdownlint-cli2 --fix` on every touched
  Markdown file; resolve any unfixable violations by hand.
- [ ] 7.3 Fold `specs/registry-deployment/spec.md` into the
  canonical `openspec/specs/registry-deployment/spec.md` (a new
  capability spec — first ops-tier capability on genesis).
- [ ] 7.4 Move `openspec/changes/react-ui-registry-deployment/`
  to `openspec/archive/<yyyy-mm-dd>-react-ui-registry-deployment/`.