pikasTech-HWLAB/docs/dev-gate-preflight.md

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:

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:

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:16667/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:

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:

node scripts/refresh-artifact-catalog.mjs --target-ref origin/main --publish-report reports/dev-gate/dev-artifacts.json