# 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

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