From db64f2fdae2b3fd0d7d0c2abc38c8b904c98819d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 16 Apr 2026 10:11:34 +0000
Subject: [PATCH] =?UTF-8?q?fix:=20address=20review=20=E2=80=94=20rename=20?=
 =?UTF-8?q?forgejo.nomad.hcl=20+=20wire=20nomad=20job=20validate=20CI?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two blockers from the #844 review:

1. Rename nomad/jobs/forgejo.hcl → nomad/jobs/forgejo.nomad.hcl to match
   the convention documented in nomad/AGENTS.md:38 (*.nomad.hcl suffix).
   First jobspec sets the pattern for all future ones; keeps any glob-
   based tooling over nomad/jobs/*.nomad.hcl working.
2. Add a dedicated `nomad-job-validate` step to .woodpecker/nomad-validate.yml.
   `nomad config validate` (step 1) parses agent configs only — it rejects
   jobspec HCL as "unknown block 'job'". `nomad job validate` is the
   correct offline validator for jobspec HCL. Per the Hashicorp docs it
   does not require a running agent (exit 0 clean, 1 on syntax/semantic
   error). New jobspecs will add an explicit line alongside forgejo's,
   matching step 1's enumeration pattern and this file's "no-ad-hoc-steps"
   principle.

Also updated the file header comment and the pipeline's top-of-file step
index to reflect the new step ordering (2. nomad-job-validate inserted;
old 2-4 renumbered to 3-5).

Refs: #840 (S1.1), PR #844
---
 .woodpecker/nomad-validate.yml                | 30 +++++++++++++++----
 nomad/jobs/{forgejo.hcl => forgejo.nomad.hcl} |  2 +-
 2 files changed, 25 insertions(+), 7 deletions(-)
 rename nomad/jobs/{forgejo.hcl => forgejo.nomad.hcl} (98%)

diff --git a/.woodpecker/nomad-validate.yml b/.woodpecker/nomad-validate.yml
index 6cd616f..83946c3 100644
--- a/.woodpecker/nomad-validate.yml
+++ b/.woodpecker/nomad-validate.yml
@@ -15,9 +15,10 @@
 #
 # Steps (all fail-closed — any error blocks merge):
 #   1. nomad-config-validate  — `nomad config validate` on server + client HCL
-#   2. vault-operator-diagnose — `vault operator diagnose` syntax check on vault.hcl
-#   3. shellcheck-nomad        — shellcheck the cluster-up + install scripts + disinto
-#   4. bats-init-nomad         — `disinto init --backend=nomad --dry-run` smoke tests
+#   2. nomad-job-validate      — `nomad job validate` on every nomad/jobs/*.nomad.hcl
+#   3. vault-operator-diagnose — `vault operator diagnose` syntax check on vault.hcl
+#   4. shellcheck-nomad        — shellcheck the cluster-up + install scripts + disinto
+#   5. bats-init-nomad         — `disinto init --backend=nomad --dry-run` smoke tests
 #
 # Pinned image versions match lib/init/nomad/install.sh (nomad 1.9.5 /
 # vault 1.18.5). Bump there AND here together — drift = CI passing on
@@ -56,7 +57,24 @@ steps:
     commands:
       - nomad config validate nomad/server.hcl nomad/client.hcl
 
-  # ── 2. Vault HCL syntax check ────────────────────────────────────────────
+  # ── 2. Nomad jobspec HCL syntax check ────────────────────────────────────
+  # `nomad job validate` is a *different* tool from `nomad config validate` —
+  # the former parses jobspec HCL (job/group/task blocks, driver config,
+  # volume refs, network ports), the latter parses agent config HCL
+  # (server/client blocks). Running step 1 on a jobspec would reject it
+  # with "unknown block 'job'", and vice versa. Hence two separate steps.
+  #
+  # Validation is offline: no running Nomad server is required (exit 0 on
+  # valid HCL, 1 on syntax/semantic error). One invocation per file — the
+  # CLI takes a single path argument. New jobspecs get explicit lines here
+  # so bringing one up is a conscious CI edit, matching step 1's pattern
+  # and this file's "no-ad-hoc-steps" principle.
+  - name: nomad-job-validate
+    image: hashicorp/nomad:1.9.5
+    commands:
+      - nomad job validate nomad/jobs/forgejo.nomad.hcl
+
+  # ── 3. Vault HCL syntax check ────────────────────────────────────────────
   # `vault operator diagnose` loads the config and runs a suite of checks.
   # Exit codes:
   #   0 — all checks green
@@ -81,7 +99,7 @@ steps:
           *) echo "vault config: hard failure (rc=$rc)" >&2; exit "$rc" ;;
         esac
 
-  # ── 3. Shellcheck ────────────────────────────────────────────────────────
+  # ── 4. Shellcheck ────────────────────────────────────────────────────────
   # Covers the new lib/init/nomad/*.sh scripts plus bin/disinto (which owns
   # the backend dispatcher). bin/disinto has no .sh extension so the
   # repo-wide shellcheck in .woodpecker/ci.yml skips it — this step is the
@@ -91,7 +109,7 @@ steps:
     commands:
       - shellcheck --severity=warning lib/init/nomad/*.sh bin/disinto
 
-  # ── 4. bats: `disinto init --backend=nomad --dry-run` ────────────────────
+  # ── 5. bats: `disinto init --backend=nomad --dry-run` ────────────────────
   # Smoke-tests the CLI dispatcher: both --backend=nomad variants exit 0
   # with the expected step list, and --backend=docker stays on the docker
   # path (regression guard). Pure dry-run — no sudo, no network.
diff --git a/nomad/jobs/forgejo.hcl b/nomad/jobs/forgejo.nomad.hcl
similarity index 98%
rename from nomad/jobs/forgejo.hcl
rename to nomad/jobs/forgejo.nomad.hcl
index b2c057f..c7a0326 100644
--- a/nomad/jobs/forgejo.hcl
+++ b/nomad/jobs/forgejo.nomad.hcl
@@ -1,5 +1,5 @@
 # =============================================================================
-# nomad/jobs/forgejo.hcl — Forgejo git server (Nomad service job)
+# nomad/jobs/forgejo.nomad.hcl — Forgejo git server (Nomad service job)
 #
 # Part of the Nomad+Vault migration (S1.1, issue #840). First jobspec to
 # land under nomad/jobs/ — proves the docker driver + host_volume plumbing