chore: add dev deploy apply preflight

2026-05-21 16:40:59 +00:00
parent f1367da333
commit d312cd0f3f
10 changed files with 878 additions and 5 deletions
@@ -0,0 +1,63 @@
+# HWLAB DEV Deploy Apply
+
+This document records the DEV-only apply/preflight path for
+`pikasTech/HWLAB#33`. It targets only the D601 `hwlab-dev` namespace and must
+not be used for PROD.
+
+## Scope
+
+- Work from latest `origin/main`.
+- Read only HWLAB repository deploy inputs: `deploy/deploy.json`,
+  `deploy/artifact-catalog.dev.json`, and `deploy/k8s/dev`.
+- Validate artifact identity, image commit tags, Kubernetes workload/service
+  shape, DEV health, and cloud-api DB connectivity.
+- Stop before mutation when artifact publish evidence, registry digests,
+  `kubectl`, DEV health, or cloud-api DB connectivity are missing.
+
+## Commands
+
+Run a preflight that is expected to report blockers on the current skeleton:
+
+```sh
+node --check scripts/dev-deploy-apply.mjs
+node scripts/dev-deploy-apply.mjs --dry-run --expect-blocked --write-report
+node scripts/validate-dev-gate-report.mjs
+```
+
+Run the existing CLI dry-run surface:
+
+```sh
+node tools/hwlab-cli/bin/hwlab-cli.mjs test e2e --env dev --mvp --dry-run
+```
+
+Only after CI publish evidence and executor prerequisites exist, a real DEV
+apply requires explicit non-production confirmation:
+
+```sh
+node scripts/dev-deploy-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report
+```
+
+The script refuses PROD flags, secret-read flags, heavyweight e2e flags, and
+force-push flags. It also refuses to apply if the DEV artifact catalog still
+contains skeleton-only unpublished images.
+
+## Current Result
+
+The current `origin/main` deploy contract is blocked for real DEV apply:
+
+- `deploy/artifact-catalog.dev.json` says `ciPublished: false`,
+  `registryVerified: false`, `publishState: skeleton-only`, and
+  `digest: not_published`.
+- The deploy/catalog artifact commit is `24eb3bf`, which does not match the
+  current source commit validated for this apply (`1e8d009e9531`).
+- The runner does not provide `kubectl`, so it cannot read or apply the D601
+  `hwlab-dev` namespace.
+- The public DEV health probe at `http://74.48.78.17:6667/health/live` is not
+  reachable from this runner.
+- `hwlab-cloud-api` has no DEV DB connection configuration and its local health
+  payload reports `db.connected: false`.
+
+The machine-readable result is written to
+`reports/dev-gate/dev-deploy-report.json`. No PROD resource, secret value,
+UniDesk runtime substitute, browser e2e, heavyweight e2e, or force push is part
+of this flow.