# 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

```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:*`,
`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:

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

Optional dependency runtime base provision:

```sh
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:

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