# HWLAB DEV Deploy Apply

This document records the DEV-only apply/preflight path for
`pikasTech/HWLAB#33` and the apply-plan/report path for
`pikasTech/HWLAB#50`. It targets only the D601 `hwlab-dev` namespace and must
not be used for PROD.

## Scope

- Work from latest `origin/main`.
- Read only HWLAB repository deploy inputs: `deploy/deploy.json`,
  `deploy/artifact-catalog.dev.json`, and `deploy/k8s/dev`.
- Validate artifact identity, image commit tags, Kubernetes workload/service
  shape, DEV health, and cloud-api DB connectivity.
- Emit an operator-readable plan in `devDeployApply`: plan/apply boundary,
  expected artifact commit, target namespace, workloads, services, remaining
  blockers, minimal manual commands, and rollback hints.
- Stop before mutation when artifact publish evidence, registry digests,
  `kubectl`, DEV health, or cloud-api DB connectivity are missing.

## Commands

Run a preflight that is expected to report blockers on the current skeleton:

```sh
node --check scripts/dev-deploy-apply.mjs
node --check scripts/src/dev-deploy-apply.mjs
node scripts/dev-deploy-apply.mjs --dry-run --expect-blocked --write-report
node scripts/validate-dev-gate-report.mjs
```

Run the existing CLI dry-run surface:

```sh
node tools/hwlab-cli/bin/hwlab-cli.mjs test e2e --env dev --mvp --dry-run
```

Only after CI publish evidence and executor prerequisites exist, a real DEV
apply requires explicit non-production confirmation:

```sh
node scripts/dev-deploy-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report
```

The script refuses PROD flags, secret-read flags, heavyweight e2e flags, and
force-push flags. It also refuses to apply if the DEV artifact catalog still
contains skeleton-only unpublished images.

## Report Contract

The machine-readable result is written to
`reports/dev-gate/dev-deploy-report.json` when `--write-report` is used. The
report remains compatible with the #33 DEV gate validator and adds these
operator fields:

- `devDeployApply.conclusion`: `blocked` while blockers are open, otherwise
  `ready` for human approval.
- `devDeployApply.applyBoundary`: default no-write behavior, required apply
  flags, DEV-only write scope, no-write scope, and forbidden actions.
- `devDeployApply.artifactPlan`: expected artifact commit, source commit,
  deploy/catalog commit IDs, publish/registry status, and unpublished services.
- `devDeployApply.target`: DEV endpoint and `hwlab-dev` namespace.
- `devDeployApply.workloadPlan` and `servicePlan`: planned Kubernetes
  workloads, containers, images, service IDs, ports, and replica intent.
- `devDeployApply.manualCommands`: dry-run/report commands before human
  approval; the apply command is present only when the plan is ready.
- `devDeployApply.rollbackHint`: pre-apply capture commands, deployment
  rollbacks, suspended job cleanup, and post-rollback health checks.
- `devDeployApply.remainingBlockers`: open blockers with concrete unblock
  hints. These do not claim live apply happened.

When `conclusion.status` is `blocked`, operators should clear the listed
`remainingBlockers` and rerun:

```sh
node scripts/dev-deploy-apply.mjs --dry-run --expect-blocked --write-report
node scripts/validate-dev-gate-report.mjs
```

When `conclusion.status` is `ready`, run the dry-run plan and validator
immediately before human approval:

```sh
node scripts/dev-deploy-apply.mjs --dry-run --write-report
node scripts/validate-dev-gate-report.mjs
```

Only after that approval may the DEV-only apply command be used.

## Current Result

The current `origin/main` deploy contract is blocked for real DEV apply:

- `deploy/artifact-catalog.dev.json` says `ciPublished: false`,
  `registryVerified: false`, `publishState: skeleton-only`, and
  `digest: not_published`.
- The deploy/catalog artifact commit is `24eb3bf`, which does not match the
  current source commit validated for this apply (`1e8d009e9531`).
- The runner does not provide `kubectl`, so it cannot read or apply the D601
  `hwlab-dev` namespace.
- The public DEV health probe at `http://74.48.78.17:6667/health/live` is not
  reachable from this runner.
- `hwlab-cloud-api` now has a DEV DB env contract placeholder:
  `HWLAB_CLOUD_DB_URL` must come from Secret reference
  `hwlab-cloud-api-dev-db/database-url`, and
  `HWLAB_CLOUD_DB_SSL_MODE=require`. The local health gate still reports DB
  runtime config blocked when those env values are absent, and it never prints
  the connection string.

No PROD resource, secret value, UniDesk runtime substitute, browser e2e,
heavyweight e2e, or force push is part of this flow.