HWLAB Code Queue
98 lines
4.0 KiB
Markdown
98 lines
4.0 KiB
Markdown
# HWLAB DEV Gate Preflight
|
|
|
|
This preflight is the read-only gate before a real DEV deploy or DEV smoke on
|
|
D601. It decides whether the current `origin/main` can enter the real
|
|
`hwlab-dev` runtime path, or whether it is blocked by missing contract,
|
|
artifact, cluster, registry, edge, or safety evidence.
|
|
|
|
It does not authorize PROD, restart runtime services, read secrets or tokens,
|
|
substitute UniDesk services for HWLAB runtime, or run heavyweight/browser e2e.
|
|
|
|
## Command
|
|
|
|
Run from the repository root:
|
|
|
|
```sh
|
|
node --check scripts/dev-gate-preflight.mjs
|
|
node --check scripts/src/dev-gate-preflight.mjs
|
|
node --check scripts/refresh-artifact-catalog.mjs
|
|
node scripts/dev-gate-preflight.mjs
|
|
```
|
|
|
|
The command writes `reports/dev-gate/dev-preflight-report.json` and prints a
|
|
short JSON summary. A `blocked` conclusion means the preflight ran correctly but
|
|
found blockers; the command exits zero by default so the report can be committed
|
|
as evidence. Use `--fail-on-blocked` only in CI jobs that should fail on an open
|
|
gate.
|
|
|
|
Useful options:
|
|
|
|
```sh
|
|
node scripts/dev-gate-preflight.mjs --target-ref origin/main
|
|
node scripts/dev-gate-preflight.mjs --report reports/dev-gate/dev-preflight-report.json
|
|
node scripts/dev-gate-preflight.mjs --timeout-ms 5000
|
|
node scripts/dev-gate-preflight.mjs --no-write
|
|
```
|
|
|
|
## Read-Only Scope
|
|
|
|
The preflight checks:
|
|
|
|
- `deploy/deploy.json` and `deploy/artifact-catalog.dev.json` are internally
|
|
consistent and DEV-only.
|
|
- The deploy manifest, artifact catalog, catalog service commits, and image tags
|
|
target the selected `origin/main` source commit.
|
|
- The artifact catalog clearly separates source commit, artifact commit,
|
|
`ciPublished`, `registryVerified`, and per-service digest state.
|
|
- The artifact catalog has real publish and registry digest evidence, or stays
|
|
blocked with `not_published` digests.
|
|
- `reports/dev-gate/dev-artifacts.json`, when present, proves all frozen DEV
|
|
service artifacts were published for the selected `origin/main` commit.
|
|
- `deploy/k8s/base` and `deploy/k8s/dev` parse and remain scoped to
|
|
`hwlab-dev`.
|
|
- `hwlab-cloud-api` declares the DEV DB env contract:
|
|
`HWLAB_CLOUD_DB_URL` from Secret reference
|
|
`hwlab-cloud-api-dev-db/database-url` and
|
|
`HWLAB_CLOUD_DB_SSL_MODE=require`.
|
|
- The local cloud-api health payload reports DB env presence/missing status with
|
|
redacted values only. This is a readiness gate, not live DB evidence.
|
|
- `deploy/frp` and `deploy/master-edge` describe the D601-to-master DEV route
|
|
on port `6667`.
|
|
- The runner can perform read-only `kubectl` probes against `hwlab-dev`.
|
|
- `reports/dev-gate/dev-edge-health.json`, when present, records read-only
|
|
public edge, frps, tunnel-health, and k3s observability evidence.
|
|
- `http://74.48.78.17:6667/health/live` responds.
|
|
- GHCR manifests are visible without reading credentials.
|
|
- Deploy images do not point at UniDesk, provider-gateway, or microservice-proxy
|
|
substitutes.
|
|
|
|
## Verdict Rules
|
|
|
|
`ready` requires all checks to pass and no open blocker.
|
|
|
|
`blocked` is expected until the real DEV runtime path can be proven. Each
|
|
blocker includes a `type`, `scope`, `summary`, and `nextTask` so the next task is
|
|
the smallest repair needed before rerunning the preflight.
|
|
|
|
The DB gate has two common blocked scopes:
|
|
|
|
- `cloud-api-db-env-contract`: manifest/Kubernetes placeholders are incomplete.
|
|
- `cloud-api-db-health-gate`: runtime env presence is missing. The next task is
|
|
to configure the DEV Secret/env names, not to print or commit any secret
|
|
value.
|
|
|
|
For catalog commit mismatch, the preflight emits an
|
|
`artifactIdentity.refreshCommands.blocked` command. Use it when the source
|
|
commit changed but publish is still blocked:
|
|
|
|
```sh
|
|
node scripts/refresh-artifact-catalog.mjs --target-ref origin/main --blocked
|
|
```
|
|
|
|
Only use the published refresh path after `reports/dev-gate/dev-artifacts.json`
|
|
proves every frozen service has a registry digest for that same source commit:
|
|
|
|
```sh
|
|
node scripts/refresh-artifact-catalog.mjs --target-ref origin/main --publish-report reports/dev-gate/dev-artifacts.json
|
|
```
|