Code Queue Review
128 lines
5.3 KiB
Markdown
128 lines
5.3 KiB
Markdown
# HWLAB DEV Base Image Preflight
|
|
|
|
This preflight is the lightweight builder gate for DEV artifact publish work. It
|
|
checks whether the D601 builder has an approved local base image before any
|
|
artifact publish attempt claims readiness.
|
|
|
|
The command is local-only. It does not pull, build, push, deploy, contact DEV or
|
|
PROD, read secrets, or use UniDesk runtime services as substitutes.
|
|
|
|
## Current Repository Constraints
|
|
|
|
- No repository Dockerfile is present in the DEV skeleton.
|
|
- `deploy/deploy.json` and `deploy/artifact-catalog.dev.json` pin service image
|
|
names to the DEV registry target, by default
|
|
`127.0.0.1:5000/hwlab/<hwlab-service-id>:<commit>`.
|
|
- The artifact catalog may be either `contract-skeleton` or `published`. A
|
|
`published` catalog must be backed by `reports/dev-gate/dev-artifacts.json`
|
|
with real `sha256:<64 hex>` digests for every required service.
|
|
- The catalog and runtime boundary forbid PROD deployment, secret reads, force
|
|
push, real publish claims, and UniDesk runtime substitution.
|
|
- A builder base image is separate from HWLAB service artifact images. This
|
|
preflight only decides whether #35 may proceed to build/publish; it does not
|
|
prove that any service image was published.
|
|
|
|
Committed artifact reports may record successful base-image and publish evidence
|
|
for an older source commit. Compare their source commit with the desired-state
|
|
commit before using them for refresh or apply review. A failed catalog manifest
|
|
read from a runner process is a registry reachability question for `#66`, not
|
|
proof that the base image or publish digests are missing.
|
|
|
|
## Command
|
|
|
|
```sh
|
|
npm run --silent dev-base-image:preflight
|
|
```
|
|
|
|
Equivalent direct command:
|
|
|
|
```sh
|
|
node scripts/preflight-dev-base-image.mjs
|
|
```
|
|
|
|
The direct command always prints JSON. Use `npm run --silent` when npm is the
|
|
entry point and the output needs to be machine parsed. Exit code `0` means
|
|
`status: "ready"` and the base image can be used by #35 DEV artifact publish.
|
|
Exit code `2` means `status: "blocked"` and artifact publish must stop.
|
|
|
|
## Image Selection
|
|
|
|
Selection order is intentionally narrow:
|
|
|
|
1. If `HWLAB_DEV_BASE_IMAGE` is set, it must name an approved image that already
|
|
exists in the local Docker image cache.
|
|
2. If `HWLAB_DEV_BASE_IMAGE` is not set, the preflight looks for local
|
|
`node:20-*` images and selects the first deterministic local tag.
|
|
3. If no `node:20-*` tag exists, the preflight also accepts a local HWLAB base
|
|
tag such as `127.0.0.1:5000/hwlab/hwlab-dev-base:node20-bookworm-slim`.
|
|
4. If neither source is available, the result is a blocker.
|
|
|
|
Explicit base image values must match local `node:20-*`, `hwlab-dev-base:*`, or
|
|
`hwlab-node20-base:*` references. They must not reference UniDesk, Code Queue,
|
|
`backend-core`, `provider-gateway`, `microservice-proxy`, or an HWLAB runtime
|
|
service image. A service image such as
|
|
`127.0.0.1:5000/hwlab/hwlab-cloud-api:<sha>` is an artifact output, not a
|
|
builder base image.
|
|
|
|
The recommended D601 preload source is `node:20-bookworm-slim`. The recommended
|
|
HWLAB-specific local tag is:
|
|
|
|
```sh
|
|
127.0.0.1:5000/hwlab/hwlab-dev-base:node20-bookworm-slim
|
|
```
|
|
|
|
## Output Contract
|
|
|
|
Important fields:
|
|
|
|
| Field | Meaning |
|
|
| --- | --- |
|
|
| `status` | `ready` or `blocked`. |
|
|
| `imageSource` | `env:HWLAB_DEV_BASE_IMAGE`, `local-docker-node:20-*`, or `none`. |
|
|
| `requestedImage` | The explicit environment value, when present. |
|
|
| `localTag` | Local Docker tag selected for the builder base image. |
|
|
| `imageId` | Local Docker image ID from `docker image inspect`. |
|
|
| `candidates` | Approved local builder base images found in Docker. |
|
|
| `rejectedCandidates` | Near misses such as local non-Node-20 Node images. |
|
|
| `publishUsable` | Boolean gate for #35 artifact publish. |
|
|
| `blockers` | Deterministic reasons artifact publish must stop. |
|
|
| `nextSteps` | Operational fixes that do not require secret reads or runtime substitution. |
|
|
| `recommendation` | Machine-readable recommended source, env var, and base image tags. |
|
|
| `provision` | Copy-pasteable online, HWLAB-tag, offline import, and dry-run commands. |
|
|
| `blockedReport` | Minimal machine-readable blocked report: exact blocker, expected tag, env value, and next preload command. |
|
|
|
|
## Blocker Handling
|
|
|
|
When blocked, preload or build an approved DEV builder base image into the D601
|
|
Docker cache, set `HWLAB_DEV_BASE_IMAGE` to the exact local tag if it is not a
|
|
`node:20-*` tag, and rerun the preflight. Do not claim artifact publish success
|
|
until the preflight returns `status: "ready"`.
|
|
|
|
Online D601 preload:
|
|
|
|
```sh
|
|
docker pull node:20-bookworm-slim
|
|
HWLAB_DEV_BASE_IMAGE=node:20-bookworm-slim node scripts/preflight-dev-base-image.mjs
|
|
```
|
|
|
|
Optional HWLAB-local tag provision:
|
|
|
|
```sh
|
|
docker pull node:20-bookworm-slim
|
|
docker tag node:20-bookworm-slim 127.0.0.1:5000/hwlab/hwlab-dev-base:node20-bookworm-slim
|
|
HWLAB_DEV_BASE_IMAGE=127.0.0.1:5000/hwlab/hwlab-dev-base:node20-bookworm-slim node scripts/preflight-dev-base-image.mjs
|
|
```
|
|
|
|
Offline preload path when D601 cannot pull directly:
|
|
|
|
```sh
|
|
docker pull node:20-bookworm-slim
|
|
docker save node:20-bookworm-slim -o hwlab-node20-bookworm-slim.tar
|
|
docker load -i hwlab-node20-bookworm-slim.tar
|
|
HWLAB_DEV_BASE_IMAGE=node:20-bookworm-slim node scripts/preflight-dev-base-image.mjs
|
|
```
|
|
|
|
The preflight may use UniDesk and Code Queue as scheduling infrastructure only.
|
|
It must not use their runtime images as HWLAB service images or builder base
|
|
image substitutes.
|