pikasTech-HWLAB/docs/dev-artifact-publish.md

HWLAB DEV Artifact Publish

scripts/dev-artifact-publish.mjs is the DEV-only build and publish path for D601 local/internal registry artifacts. It does not deploy workloads, read secrets, enable PROD, or push to GHCR/Docker Hub/other third-party registries.

Scope

• Environment: dev.
• Namespace: hwlab-dev.
• Default registry prefix: 127.0.0.1:5000/hwlab.
• Base image: resolved by scripts/preflight-dev-base-image.mjs from HWLAB_DEV_BASE_IMAGE, a local node:20-* Docker image, or a local HWLAB base tag such as 127.0.0.1:5000/hwlab/hwlab-dev-base:node20-bookworm-slim. There is no network pull or third-party fallback during publish; the build runs with --pull=false.
• Image tag: first seven characters of the Git commit used as build source.
• Required image labels:
  • hwlab.pikastech.local/repo
  • hwlab.pikastech.local/commit
  • hwlab.pikastech.local/service-id
  • hwlab.pikastech.local/environment=dev

Commands

Static check:

node --check scripts/preflight-dev-base-image.mjs
node --check scripts/src/dev-base-image-preflight.mjs
node --check scripts/dev-artifact-publish.mjs

Base image preflight:

node scripts/preflight-dev-base-image.mjs

Preflight and report generation:

node scripts/dev-artifact-publish.mjs --preflight

Build only:

node scripts/dev-artifact-publish.mjs --build

Build and publish to the D601 local/internal registry:

node scripts/dev-artifact-publish.mjs --publish

Use --registry-prefix only for another localhost/private/internal D601 registry prefix. The script rejects third-party registry hosts and any prefix that names PROD. Use --base-image only to override HWLAB_DEV_BASE_IMAGE with an approved local image for that run.

Report

The script writes reports/dev-gate/dev-artifacts.json. The file is kept in the existing DEV gate report envelope for compatibility with scripts/validate-dev-gate-report.mjs, while the artifactPublish object is the HWLAB#35-specific publish record.

Each service record contains:

• serviceId
• image
• imageTag
• digest
• runtimeKind
• implementationState
• entrypoint

digest is only set to a registry digest after docker push succeeds and the push output contains a digest. The script records blockers instead of claiming a publish when build, push, base image, registry, contract, or safety checks fail.

The report also includes artifactPublish.baseImagePreflight with the image source, local tag, local image ID, publishUsable gate, blockers, and next steps. It also carries recommendation, provision, and blockedReport objects so the blocked report includes the exact blocker, expected image tag, recommended HWLAB_DEV_BASE_IMAGE value, and preload commands. When that preflight is blocked, artifact publish is blocked and no build or push is attempted.

Known Implementation States

• repo-entrypoint: the repository has cmd/<serviceId>/main.mjs.
• static-web-wrapper: the cloud web static files are packaged behind a small health/static-file wrapper.
• repo-bundle: the image packages repository-owned skill artifacts.
• library-only: the repository has library code but no executable package bin.
• missing-runtime-entrypoint: the image is only a health placeholder and is not a real service implementation.

Runtime implementation blockers do not fake a service implementation. They are recorded as the next minimum work needed after artifact publication.