# DBaaS UI Upstream Updates

This file is the human runbook and Agent instruction source for everything under
`build/dbaas-ui/`. The upstream production line is `tidbcloud/dbaas-ui` branch
`master`; GitHub Releases are not the CP9 release source.

## Boundaries

- `make dbaas-ui-candidate` validates locally by default. A successful local run
  does not publish or promote an image.
- ECR publication, checked-in digest promotion, and live product proof are three
  separate mutations. Before each one, show the exact plan and obtain explicit
  human approval for that mutation.
- Use a named runtime-account profile that resolves to its `cp9-developer`
  assumed role. Do not use ambient credentials, static keys, or a source-account
  publisher role.
- Keep every prior immutable image digest. Rollback selects an earlier digest;
  it does not delete images.

## Update The Reviewed Source

1. Start from a clean worktree based on current `origin/main`.
2. Run the remaining update steps in one Bash shell with fail-closed settings,
   then clone `master` once and retain the full SHA:

   ```bash
   set -euo pipefail
   upstream_checkout="$(mktemp -d)"
   gh repo clone tidbcloud/dbaas-ui "${upstream_checkout}" -- \
     --filter=blob:none --no-checkout --single-branch --branch master --depth=1
   upstream_commit="$(git -C "${upstream_checkout}" rev-parse refs/remotes/origin/master)"
   git -C "${upstream_checkout}" checkout --detach "${upstream_commit}"
   git -C "${upstream_checkout}" show --no-patch \
     --format='%H%n%cI%n%s' "${upstream_commit}"
   ```

   Completion: the SHA is 40 lowercase hexadecimal characters and the metadata
   identifies the intended upstream commit. Refresh this observation immediately
   before opening the CP9 pull request. If `master` moved, review and freeze the
   new head explicitly; do not silently change the reviewed SHA.
3. Read the previous reviewed commit from `overlay/manifest.json`, fetch it into
   the same checkout, and review the complete old-to-new range. Account for every
   changed overlay target, new `REACT_APP_*` input, absolute network origin,
   authentication or tracing change, embedded frame, package script, API
   generation change, and lockfile change. The resulting CP9 build must preserve
   the same-origin main API and disabled-by-default external integration
   contracts in `overlay/manifest.json`.

   ```bash
   previous_commit="$(
     node -p 'require(process.argv[1]).upstream.reviewed_commit' \
       build/dbaas-ui/overlay/manifest.json
   )"
   git -C "${upstream_checkout}" fetch --depth=1 origin "${previous_commit}"
   git -C "${upstream_checkout}" diff --stat \
     "${previous_commit}" "${upstream_commit}"
   git -C "${upstream_checkout}" diff --name-status \
     "${previous_commit}" "${upstream_commit}"
   ```

   Completion: the pull request records both full SHAs and an explicit disposition
   for every new input or network origin: overlay change, safe unchanged behavior,
   or blocker.
4. Hash the non-empty lockfile from that exact local checkout:

   ```bash
   reviewed_lockfile_sha256="$(
     node -e '
       const fs = require("node:fs")
       const crypto = require("node:crypto")
       const lockfile = fs.readFileSync(process.argv[1])
       if (lockfile.length === 0) throw new Error("pnpm-lock.yaml is empty")
       process.stdout.write(crypto.createHash("sha256").update(lockfile).digest("hex"))
     ' "${upstream_checkout}/pnpm-lock.yaml"
   )"
   [[ "${reviewed_lockfile_sha256}" =~ ^[0-9a-f]{64}$ ]]
   ```

   Completion: the checked-out `pnpm-lock.yaml` is larger than zero bytes and the
   digest is 64 lowercase hexadecimal characters. Set `upstream.reviewed_commit`
   and `upstream.reviewed_lockfile_sha256` in `overlay/manifest.json` to these
   exact values. Adapt `overlay/apply.mjs` only where the reviewed upstream source
   changed. Every replacement must continue to fail closed when its expected
   source shape is absent or ambiguous.

## Build The Local Candidate

Run the exact reviewed commit with a unique candidate ID:

```bash
DBAAS_UI_UPSTREAM_COMMIT="${upstream_commit}" \
DBAAS_UI_CANDIDATE_ID="review-${upstream_commit:0:12}-$(date -u +%Y%m%dT%H%M%SZ)" \
make dbaas-ui-candidate
```

The command must verify the manifest commit and lockfile digest, apply the
overlay, install the frozen dependency graph without package lifecycle scripts,
generate the API client, format the transformed files, type-check, build the
production site, and build a local static-server image. Completion is the final
`local candidate build passed` receipt for the exact SHA. Treat warnings from
upstream generators as findings to classify; do not hide them.

Before review, inspect the generated site and the actual source Git diff for
unexpected external origins or unexplained writes. `overlay/manifest.json`
defines the runtime contract; use the Git diff as the exhaustive overlay
write-set. Refresh `master` and require it to remain the reviewed SHA, then run
the repository gates:

```bash
git -C "${upstream_checkout}" fetch --depth=1 origin master
[[ "$(git -C "${upstream_checkout}" rev-parse FETCH_HEAD)" == "${upstream_commit}" ]]
```

```bash
make fmt
make lint
make test
make build
tools/render-baseline.sh check
git diff --check
```

## Publish An Immutable Candidate

Publication is optional and requires a new approval after local validation.
Present the frozen upstream SHA, manifest lockfile digest, candidate ID, runtime
AWS profile/account/role, target repository and tag, and the statement that no
checked-in runtime pin will change. After approval:

```bash
DBAAS_UI_UPSTREAM_COMMIT="${upstream_commit}" \
DBAAS_UI_CANDIDATE_ID="<approved-unique-id>" \
DBAAS_UI_PUBLISH=true \
DBAAS_UI_AWS_PROFILE="<approved-runtime-profile>" \
make dbaas-ui-candidate
```

Completion is both the published `candidate-<sha>-<id>` tag and a successful
pull of the emitted immutable digest. Record the full source SHA, candidate ID,
publisher account and assumed role, image tag, digest, and pull receipt.

## Promote An Immutable Candidate

After publication, obtain separate approval to change the immutable image
reference in `personas/app-delivery/base/dbaas-ui/deployment.yaml`. Re-run all
gates above, obtain exact-head independent review, and wait for hosted checks to
become terminal green. Promotion changes source-controlled configuration; it
does not publish, delete, or deploy registry content by itself.

## Product Proof And Rollback

Live proof requires another explicit approval and a new uniquely named Remote
Dev full session. Prove normal interactive login, the affected UI workflows,
and zero unexpected external egress. Delete every product created for the proof
exactly once, then destroy the session and record the accepted cleanup handoff;
do not wait for the asynchronous cleanup workflow or cloud-resource zero.
Preserve the scene unchanged if ownership is reassigned.

Rollback is a reviewed change that restores a previously proved immutable
digest, followed by the same render, review, hosted-check, product, and cleanup
gates appropriate to the incident. Never replace the pin with a mutable tag.