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 ghcr.io/pikastech/<hwlab-service-id>:<commit>.
• The artifact catalog is contract-skeleton only. Service entries must keep publishState: "skeleton-only" and digest: "not_published" until real publish evidence exists.
• 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.

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 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 ghcr.io/pikastech/hwlab-cloud-api:<sha> is an artifact output, not a builder base image.

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.
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.

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".

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.