pikasTech-HWLAB/docs/dev-base-image-preflight.md

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 /tmp/hwlab-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

npm run --silent dev-base-image:preflight

Equivalent direct command:

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:*, hwlab-node20-base:*, or hwlab-node-runtime-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:

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:

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:

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

Optional dependency runtime base provision:

node scripts/dev-runtime-base-image.mjs --dry-run
node scripts/dev-runtime-base-image.mjs
HWLAB_DEV_BASE_IMAGE=127.0.0.1:5000/hwlab/hwlab-node-runtime-base:deps-<hash> node scripts/preflight-dev-base-image.mjs

This runtime base caches package.json / package-lock.json dependencies in /opt/hwlab-node-runtime-base/node_modules. Service artifact builds copy that directory when present, which avoids repeating the same npm ci layer for each service.

Offline preload path when D601 cannot pull directly:

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.