ci: fix Node-version drift, add composite-action schema validation

JSONbored · JSONbored · commit cc55d8cbab31 · 2026-07-20T00:16:10.000-07:00
Two independent hygiene fixes from the follow-up audit, bundled since both are small and neither conflicts with the other. Node-version drift: 13 release/publish-adjacent workflows hardcoded node-version: 24.18.0 while .nvmrc pins 22 -- every PR-facing workflow (ci.yml, ui-preview.yml, ui-deploy.yml, ui-sentry-release.yml, mcp-release-candidate.yml) already correctly used node-version-file: .nvmrc. Investigated before touching anything: none of the published packages' own engines fields (@loopover/engine, mcp, ui-kit all >=22.0.0; miner >=22.13.0) require Node 24, no comment anywhere explains the choice, and git history shows each was just whatever version was current when that particular publish workflow was first scaffolded, never reconciled against .nvmrc. Switched all 13 (18 occurrences) to node-version-file: .nvmrc for consistency. Left the two files already pinned to 22.23.1 alone (gittensor-impact.yml, visual-capture-fallback.yml) -- same major version as .nvmrc, not actually inconsistent, lower value/higher risk to touch than the real Node-24-vs-22 mismatch. Composite-action schema validation: this repo's actionlint (both the npm wrapper and the raw upstream binary, tested directly) does not support .github/actions/**/action.yml files at all -- confirmed a genuine, long-standing limitation (rhysd/actionlint#46 and #401, open since 2021), not a configuration gap. Every file passed to actionlint is parsed as a workflow regardless of shape, so it errors on runs/inputs/outputs as unexpected top-level keys rather than actually validating the composite action. scripts/lint-composite-actions.mjs is the closest available substitute: validates against GitHub's own official action-metadata JSON Schema (vendored locally at scripts/schemas/github-action.schema.json, not fetched live, so this check doesn't depend on network access in CI), plus a dedicated check for one thing the schema alone doesn't catch -- every run: step in a composite action needs an explicit shell:, unlike a top-level workflow job which defaults to bash. Verified it actually catches real problems, not just that it exists: fed it a deliberately broken action file (missing shell:, an invalid uses: type) and confirmed both classes of error surface clearly. Wired into test:ci (npm run lint:composite-actions) and a new "Lint composite actions" step in ci.yml, alongside the existing "Lint workflows" step. Also added .github/actions/** to the backend path filter -- it was missing entirely (only .github/workflows/** was covered), so a PR editing ONLY a composite action file would previously trigger neither this new check nor the existing actionlint step at all.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -79,6 +79,12 @@ jobs:
               - 'scripts/**'
               - 'migrations/**'
               - '.github/workflows/**'
+              # .github/actions/** (composite actions, e.g. setup-workspace) is workflow-adjacent
+              # infrastructure the same way .github/workflows/** above is -- without this, a PR editing
+              # ONLY a composite action file (touching nothing else backend matches) would skip both
+              # "Lint workflows" and "Lint composite actions" below entirely, with zero CI signal on a
+              # broken edit until the next push-triggered full run.
+              - '.github/actions/**'
               - 'wrangler.jsonc'
               - 'worker-configuration.d.ts'
               - '.loopover.yml'
@@ -222,6 +228,17 @@ jobs:
       - name: Lint workflows
         if: ${{ github.event_name == 'push' || needs.changes.outputs.backend == 'true' }}
         run: npm run actionlint
+      # actionlint (above) does not cover .github/actions/**/action.yml at all -- confirmed a genuine,
+      # long-standing upstream limitation (rhysd/actionlint#46 and #401, open since 2021), not something
+      # fixable by a different invocation: even the raw actionlint binary, run directly with no wrapper,
+      # treats any file it's given as a workflow and errors on runs/inputs/outputs as unexpected
+      # top-level keys. This validates composite action files against GitHub's own official
+      # action-metadata JSON Schema instead -- real structural validation, not the full expression-
+      # context linting actionlint does for workflows, which genuinely doesn't exist anywhere for
+      # action.yml files.
+      - name: Lint composite actions
+        if: ${{ github.event_name == 'push' || needs.changes.outputs.backend == 'true' }}
+        run: npm run lint:composite-actions
       - name: Check migrations
         if: ${{ github.event_name == 'push' || needs.changes.outputs.backend == 'true' }}
         run: npm run db:migrations:check
diff --git a/.github/workflows/mcp-release-please.yml b/.github/workflows/mcp-release-please.yml
@@ -236,7 +236,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
       - name: Publish any package whose committed version isn't live on npm yet
         env:
           GH_TOKEN: ${{ secrets.RELEASE_PLEASE_TOKEN }}
diff --git a/.github/workflows/mcp-release-watch.yml b/.github/workflows/mcp-release-watch.yml
@@ -27,7 +27,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
 
       - name: Check MCP release status
         env:
diff --git a/.github/workflows/mcp-ui-version-sync.yml b/.github/workflows/mcp-ui-version-sync.yml
@@ -34,7 +34,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
 
       # No npm ci -- the script only imports Node built-ins.
       - name: Sync the known-latest constant
diff --git a/.github/workflows/orb-beta-release.yml b/.github/workflows/orb-beta-release.yml
@@ -38,7 +38,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
 
       - name: Check whether an ORB beta is due
         id: report
diff --git a/.github/workflows/orb-stable-release-pr.yml b/.github/workflows/orb-stable-release-pr.yml
@@ -37,7 +37,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
 
       - name: Check whether a stable ORB release is due
         id: report
diff --git a/.github/workflows/publish-engine.yml b/.github/workflows/publish-engine.yml
@@ -59,7 +59,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
 
       - name: Resolve release version
         id: version
@@ -160,7 +160,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
           registry-url: https://registry.npmjs.org
 
       - name: Create or verify release tag
diff --git a/.github/workflows/publish-mcp.yml b/.github/workflows/publish-mcp.yml
@@ -54,7 +54,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
 
       # workflow_dispatch has no tag ref to derive a version from (unlike the old push:tags: trigger),
       # so the dispatched commit's package.json is now the single source of truth for VERSION/TAG. Pure
@@ -177,7 +177,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
           registry-url: https://registry.npmjs.org
 
       - name: Create or verify release tag
@@ -244,7 +244,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
       - name: Sync and open a PR if the known-latest copy is now stale
         env:
           # A real collaborator token, not github.token -- mirrors mcp-release-please.yml's own
diff --git a/.github/workflows/publish-miner.yml b/.github/workflows/publish-miner.yml
@@ -60,7 +60,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
 
       - name: Resolve release version
         id: version
@@ -158,7 +158,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
           registry-url: https://registry.npmjs.org
 
       - name: Create or verify release tag
diff --git a/.github/workflows/publish-ui-kit.yml b/.github/workflows/publish-ui-kit.yml
@@ -59,7 +59,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
 
       - name: Resolve release version
         id: version
@@ -159,7 +159,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
           registry-url: https://registry.npmjs.org
 
       - name: Create or verify release tag
diff --git a/.github/workflows/release-selfhost.yml b/.github/workflows/release-selfhost.yml
@@ -121,7 +121,7 @@ jobs:
       # Release jobs receive publishing/Sentry credentials, so avoid shared dependency caches here.
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: "24.18.0"
+          node-version-file: .nvmrc
 
       - name: Install deps
         run: npm ci --ignore-scripts
diff --git a/.github/workflows/selfhost.yml b/.github/workflows/selfhost.yml
@@ -78,7 +78,7 @@ jobs:
 
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: "24.18.0"
+          node-version-file: .nvmrc
           cache: "npm"
 
       - name: Install deps
diff --git a/.github/workflows/ui-preview-deploy.yml b/.github/workflows/ui-preview-deploy.yml
@@ -63,7 +63,7 @@ jobs:
         if: steps.cfg.outputs.ready == 'true'
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
 
       - name: Install trusted Wrangler
         if: steps.cfg.outputs.ready == 'true'
diff --git a/.github/workflows/upstream-contract.yml b/.github/workflows/upstream-contract.yml
@@ -25,7 +25,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 24.18.0
+          node-version-file: .nvmrc
           cache: npm
 
       - name: Install dependencies
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -46,6 +46,7 @@
     "db:migrations:check": "tsx scripts/check-migrations.mjs",
     "db:schema-drift:check": "tsx scripts/check-schema-drift.mjs",
     "actionlint": "node scripts/actionlint.mjs",
+    "lint:composite-actions": "node scripts/lint-composite-actions.mjs",
     "ui:dev": "npm run ui:preview",
     "extension:build": "node scripts/build-extension.mjs",
     "extension:lint": "npm --workspace @loopover/extension run lint",
@@ -99,7 +100,7 @@
     "test:smoke:observability:metrics": "node scripts/smoke-observability-metrics.mjs",
     "test:smoke:browser:install": "playwright install chromium",
     "test:smoke:browser": "node scripts/smoke-ui-browser.mjs",
-    "test:ci": "git diff --check && npm run actionlint && npm run db:migrations:check && npm run db:schema-drift:check && npm run selfhost:env-reference:check && npm run miner:env-reference:check && npm run selfhost:validate-observability && npm run cf-typegen:check && npm run build --workspace @loopover/engine && npm run build --workspace @loopover/discovery-index && npm run typecheck && npm run test:coverage && npm run test:engine-parity && npm run test:live-gate-parity && npm run test:driver-parity && npm run test --workspace @loopover/engine && npm run test:workers && npm run build:mcp && npm run test:mcp-pack && npm run build:miner && npm run test:miner-pack && npm run test:miner-deployment-docs-audit && npm run rees:test && npm run ui:openapi:check && npm run ui:openapi:settings-parity && npm run ui:version-audit && npm run docs:drift-check && npm run branding-drift:check && npm run manifest:drift-check && npm run engine-parity:drift-check && npm run release-manifest:sync:check && npm run command-reference:check && npm run ui:lint && npm run ui:typecheck && npm run ui:test && npm run ui:build",
+    "test:ci": "git diff --check && npm run actionlint && npm run lint:composite-actions && npm run db:migrations:check && npm run db:schema-drift:check && npm run selfhost:env-reference:check && npm run miner:env-reference:check && npm run selfhost:validate-observability && npm run cf-typegen:check && npm run build --workspace @loopover/engine && npm run build --workspace @loopover/discovery-index && npm run typecheck && npm run test:coverage && npm run test:engine-parity && npm run test:live-gate-parity && npm run test:driver-parity && npm run test --workspace @loopover/engine && npm run test:workers && npm run build:mcp && npm run test:mcp-pack && npm run build:miner && npm run test:miner-pack && npm run test:miner-deployment-docs-audit && npm run rees:test && npm run ui:openapi:check && npm run ui:openapi:settings-parity && npm run ui:version-audit && npm run docs:drift-check && npm run branding-drift:check && npm run manifest:drift-check && npm run engine-parity:drift-check && npm run release-manifest:sync:check && npm run command-reference:check && npm run ui:lint && npm run ui:typecheck && npm run ui:test && npm run ui:build",
     "test:release": "npm run test:ci && npm run changelog:check",
     "test:release:mcp": "npm run test:ci",
     "test:watch": "vitest",
@@ -139,6 +140,7 @@
     "@types/pixelmatch": "^5.2.6",
     "@types/pngjs": "^6.0.5",
     "@vitest/coverage-v8": "^4.1.9",
+    "ajv": "^8.20.0",
     "drizzle-kit": "^0.31.10",
     "gifenc": "^1.0.3",
     "git-cliff": "^2.13.1",
diff --git a/scripts/lint-composite-actions.mjs b/scripts/lint-composite-actions.mjs
@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Validates every .github/actions/*/action.yml against GitHub's official action-metadata JSON Schema,
+// plus one composite-action-specific check the schema can't express: every `run:` step needs an
+// explicit `shell:` (unlike a top-level workflow job, which defaults to bash on a Linux runner -- a
+// missing one in a composite action is a silent hard failure at actual run time, not a parse-time
+// error).
+//
+// actionlint (this repo's usual workflow linter, scripts/actionlint.mjs) does NOT support action.yml
+// files at all -- confirmed this is a genuine, long-standing upstream limitation
+// (github.com/rhysd/actionlint/issues/46 and /issues/401, open since 2021), not a configuration gap on
+// this repo's side: even the raw actionlint binary, invoked directly with no wrapper, treats any file
+// it's given as a workflow and errors on `runs`/`inputs`/`outputs` as unexpected top-level keys. This
+// script is the closest available substitute -- real structural/schema validation, not the full
+// expression-context linting actionlint does for workflows, which genuinely doesn't exist anywhere for
+// action.yml files.
+//
+// Schema vendored locally (scripts/schemas/github-action.schema.json, from
+// https://json.schemastore.org/github-action.json) rather than fetched live, so this check doesn't
+// depend on network access in CI -- consistent with how the rest of this repo's drift/lint checks work
+// offline against committed state.
+
+import Ajv from "ajv";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+
+const ACTIONS_DIR = ".github/actions";
+const SCHEMA_PATH = new URL("./schemas/github-action.schema.json", import.meta.url);
+
+const schema = JSON.parse(readFileSync(SCHEMA_PATH, "utf8"));
+const ajv = new Ajv({ allErrors: true, strict: false });
+const validateSchema = ajv.compile(schema);
+
+function findActionFiles() {
+  const results = [];
+  for (const entry of readdirSync(ACTIONS_DIR, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    for (const name of ["action.yml", "action.yaml"]) {
+      const candidate = join(ACTIONS_DIR, entry.name, name);
+      try {
+        readFileSync(candidate);
+        results.push(candidate);
+        break; // a directory has one action file, not both
+      } catch {
+        // try the other extension
+      }
+    }
+  }
+  return results;
+}
+
+const actionFiles = findActionFiles();
+if (actionFiles.length === 0) {
+  console.log(`No composite action files found under ${ACTIONS_DIR}/ -- nothing to validate.`);
+  process.exit(0);
+}
+
+let hasErrors = false;
+
+for (const path of actionFiles) {
+  const doc = parse(readFileSync(path, "utf8"));
+
+  if (!validateSchema(doc)) {
+    hasErrors = true;
+    console.error(`${path}: schema violations:`);
+    for (const err of validateSchema.errors ?? []) {
+      console.error(`  ${err.instancePath || "(root)"} ${err.message}`);
+    }
+  }
+
+  if (doc?.runs?.using === "composite") {
+    for (const [index, step] of (doc.runs.steps ?? []).entries()) {
+      if (step.run !== undefined && step.shell === undefined) {
+        hasErrors = true;
+        console.error(
+          `${path}: runs.steps[${index}] ("${step.name ?? "unnamed"}") has a run: but no shell: -- required for composite action steps, unlike a top-level workflow job which defaults to bash`,
+        );
+      }
+    }
+  }
+}
+
+if (hasErrors) {
+  process.exit(1);
+}
+console.log(`Validated ${actionFiles.length} composite action file(s) against the GitHub action-metadata schema: all clean.`);
diff --git a/scripts/schemas/github-action.schema.json b/scripts/schemas/github-action.schema.json
