mandrel-platform 0.20.1 → 0.24.0

package/templates/runner/job-cleanup.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+#
+# ACTIONS_RUNNER_HOOK_JOB_STARTED hook — generalized, runner-scoped hygiene
+# for PERSISTENT self-hosted runners (mandrel-platform runner kit).
+#
+# A persistent runner (launchd/systemd service) leaks state from a prior job
+# into the next one: the runner does not always reap the job's child process
+# tree, and some actions leave files in shared locations. Observed breakage
+# classes this hook guards against:
+#
+#   - an orphaned `pnpm`/`node` process (e.g. a hung install or lint) still
+#     mutating the pnpm shim install, corrupting the pnpm CLI for the next job;
+#   - leftover `gitleaks.tmp` / `gitleaks-*` artifacts in the shared $TMPDIR
+#     blocking the next gitleaks download.
+#
+# Running this before every job gives each job a clean slate ("fresh per job"
+# without the cost of re-registering an ephemeral runner).
+#
+# ── CONCURRENCY SAFETY (the load-bearing design constraint) ─────────────────
+#
+# Multiple runners on one host typically run as the SAME OS user, so anything
+# under $HOME (notably `~/setup-pnpm`, the pnpm/action-setup DEFAULT install
+# destination) is SHARED across all co-resident runners. A hook that reaps
+# processes matching `~/setup-pnpm` or `rm -rf`s it will destroy a pnpm
+# install a CONCURRENT runner is mid-flight on. This hook therefore:
+#
+#   1. NEVER touches `~/setup-pnpm` or any other $HOME-shared pnpm path.
+#      The pnpm shim MUST instead be runner-scoped at install time: the
+#      platform's `setup-toolchain` composite action already defaults
+#      pnpm/action-setup's `dest` to `${{ runner.temp }}/pnpm` (i.e.
+#      `<RUNNER_DIR>/_work/_temp/pnpm`, unique per runner), and
+#      `pr-quality.yml` exposes a `pnpm-dest` input for explicit overrides.
+#      See templates/runbooks/runner-provisioning.md § "pnpm scoping".
+#   2. Reaps ONLY processes whose command line resolves inside THIS runner's
+#      own work tree (`<RUNNER_DIR>/_work/...`). Every path below derives
+#      from RUNNER_DIR, which is unique per runner, so a co-resident
+#      runner's processes and files are never matched.
+#   3. Age-gates cleanup of the genuinely shared $TMPDIR gitleaks artifacts,
+#      so a fresh (in-flight) download owned by a concurrent job is never
+#      deleted — only stale leftovers are.
+#
+# ── PARAMETERIZATION ────────────────────────────────────────────────────────
+#
+# No hardcoded usernames, repo names, or runner names. All paths derive from:
+#
+#   RUNNER_DIR   — the runner's root directory. Defaults to the directory
+#                  containing this script (the kit installs the hook into the
+#                  runner root, next to config.sh / run.sh). Override via env
+#                  only if you install the hook elsewhere.
+#   RUNNER_TMP   — the runner's per-runner job temp (`runner.temp`), always
+#                  `${RUNNER_DIR}/_work/_temp`.
+#   JOB_CLEANUP_STALE_MINUTES
+#                — age threshold (minutes) for the shared-$TMPDIR gitleaks
+#                  sweep. Default 60. Artifacts younger than this are assumed
+#                  in-flight and left alone.
+#
+# Configured via `ACTIONS_RUNNER_HOOK_JOB_STARTED=<RUNNER_DIR>/job-cleanup.sh`
+# in the runner's `.env` (see .env.example in this directory).
+#
+# NEVER fails the job — best-effort cleanup, always exits 0.
+
+set +e
+
+RUNNER_DIR="${RUNNER_DIR:-$(cd "$(dirname "$0")" && pwd)}"
+RUNNER_WORK="${RUNNER_DIR}/_work"
+RUNNER_TMP="${RUNNER_WORK}/_temp"
+TMP="${TMPDIR:-/tmp}"
+STALE_MINUTES="${JOB_CLEANUP_STALE_MINUTES:-60}"
+
+# 1) Reap orphaned pnpm/node processes from prior jobs — scoped to THIS
+#    runner's work tree only. The patterns target executable paths INSIDE the
+#    runner-scoped install locations (`.../node_modules`), so they match the
+#    actual pnpm/node binaries that ran from these dirs — not a shell that
+#    merely references the path. RUNNER_TMP and RUNNER_WORK are unique per
+#    runner, so co-resident runners and unrelated user processes are never
+#    hit. The shared `~/setup-pnpm` is deliberately NOT a reap target (see
+#    the concurrency-safety header).
+pkill -9 -f "${RUNNER_TMP}/pnpm/node_modules"       2>/dev/null
+pkill -9 -f "${RUNNER_TMP}/setup-pnpm/node_modules" 2>/dev/null
+pkill -9 -f "${RUNNER_WORK}/_tool/[^ ]*node_modules" 2>/dev/null
+
+# 2) Remove stale runner-scoped pnpm shim installs so the next job's
+#    pnpm/action-setup starts from a clean slate. Only paths under THIS
+#    runner's `_work/_temp` are deleted — never `~/setup-pnpm`.
+rm -rf "${RUNNER_TMP}/pnpm"       2>/dev/null
+rm -rf "${RUNNER_TMP}/setup-pnpm" 2>/dev/null
+
+# 3) Sweep stale gitleaks artifacts from the SHARED $TMPDIR. Because this
+#    location is shared by every runner on the host, deletion is age-gated:
+#    only artifacts older than STALE_MINUTES are removed, so a concurrent
+#    runner's in-flight download is never deleted mid-job.
+find "${TMP}" -maxdepth 1 -name 'gitleaks.tmp' -mmin "+${STALE_MINUTES}" \
+  -exec rm -f  {} + 2>/dev/null
+find "${TMP}" -maxdepth 1 -name 'gitleaks-*'   -mmin "+${STALE_MINUTES}" \
+  -exec rm -rf {} + 2>/dev/null
+
+exit 0

package/templates/workflows/deploy-staging-run.yml

@@ -0,0 +1,77 @@
+name: deploy-staging-run
+
+# Canonical staging-deploy caller template — DEPLOY half (Story #272).
+#
+# > **Why this file runs on `workflow_dispatch`.** Its sibling
+# > `deploy-staging.yml` fires on CI-green (`workflow_run`) and DISPATCHES this
+# > workflow. The deploy lives here, on `workflow_dispatch`, because the shared
+# > `deploy-cloudflare.yml`'s `environment:`-gated jobs (`check-env` /
+# > `migration` / `deploy` / `boot-smoke`) are silently SKIPPED on a
+# > `workflow_run` event but run normally on `workflow_dispatch` (Story #272).
+# > Adopt this file together with `deploy-staging.yml`; `platform-sync`
+# > materializes both.
+#
+# > **Thin local caller.** The defence-in-depth deploy core lives in the shared
+# > `dsj1984/mandrel-platform` `deploy-cloudflare.yml` reusable workflow — see
+# > https://github.com/dsj1984/mandrel-platform/blob/main/docs/reusable-workflows.md#deploy-cloudflareyml.
+# > This file only holds <PROJECT_NAME>-specific values (worker names, build
+# > step, secret mapping). When the deploy PROCESS changes, that change lands
+# > upstream in mandrel-platform — not here.
+#
+# Replace every <PLACEHOLDER> with your project's real values:
+#   <MANDREL_PLATFORM_SHA>   the pinned mandrel-platform commit SHA (resolve via
+#                            `node scripts/platform-sync.mjs --ref <release-tag>`
+#                            from the consumer repo root, or `git ls-remote`).
+#   <MANDREL_PLATFORM_TAG>   the human-readable release tag matching the SHA
+#                            above (trailing `# <tag>` comment).
+#   <WORKERS_CSV>            comma-separated Worker names for this env, e.g.
+#                            "api,web".
+#   <BUILD_COMMAND>          optional build command (omit build-command /
+#                            build-artifact entirely if the deploy job's default
+#                            checkout is build-ready).
+#
+# See the full input/secret contract:
+# https://github.com/dsj1984/mandrel-platform/blob/main/docs/reusable-workflows.md#deploy-cloudflareyml
+
+on:
+  # Dispatched by deploy-staging.yml on CI-green, and available for manual
+  # on-demand deploys (UI "Run workflow" + `gh workflow run`). The optional sha
+  # input records the CI-verified commit; the deploy itself runs against the
+  # main tip (`--ref main`).
+  workflow_dispatch:
+    inputs:
+      sha:
+        description: >
+          Commit SHA that passed CI (informational — the deploy runs against
+          the current main tip). Populated automatically when dispatched by
+          deploy-staging.yml.
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+# Serialize staging deploys: only the freshest dispatch should reach the
+# staging surfaces. The shared deploy-cloudflare.yml additionally serializes
+# per-environment.
+concurrency:
+  group: deploy-staging-run
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    name: Staging deploy (shared deploy-cloudflare.yml)
+    uses: dsj1984/mandrel-platform/.github/workflows/deploy-cloudflare.yml@<MANDREL_PLATFORM_SHA> # <MANDREL_PLATFORM_TAG>
+    with:
+      environment: staging
+      gh-environment: staging
+      workers: <WORKERS_CSV>
+      migrate: true
+      # db-engine defaults to 'd1'. Set db-engine + migrate-command +
+      # snapshot-command for a non-D1 engine (e.g. Turso) — see the contract
+      # doc's "command seams" section.
+    # Frozen secret allowlist: only {CLOUDFLARE_*, TURSO_*} cross into the
+    # shared workflow. Map your project's secret NAMES onto these slots.
+    secrets:
+      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

package/templates/workflows/deploy-staging.yml

@@ -1,86 +1,91 @@
 name: deploy-staging
 
-# Canonical staging-deploy caller template (Story #175).
+# Canonical staging-deploy caller template — DISPATCHER half (Story #175,
+# reworked for Story #272).
+#
+# > **Why two files (Story #272).** A reusable workflow's `environment:`-gated
+# > jobs (`deploy-cloudflare.yml`'s `check-env` / `migration` / `deploy` /
+# > `boot-smoke`) are **silently skipped on a `workflow_run` event** — a
+# > documented GitHub limitation. The previous single-file template called
+# > `deploy-cloudflare.yml` DIRECTLY from `on: workflow_run`, so those jobs
+# > skipped and **0 workers deployed while the run reported green** (all-skipped,
+# > none failed). One consumer hid 40+ consecutive non-deploys this way.
+# >
+# > The fix: this file is now a thin **dispatcher** that fires on CI-green and
+# > re-launches the deploy via **`workflow_dispatch`** — the event on which the
+# > `environment:` jobs DO run — against its sibling `deploy-staging-run.yml`.
+# > `workflow_dispatch` and `repository_dispatch` are the two events that
+# > "always create workflow runs" even when triggered with the built-in
+# > `GITHUB_TOKEN`, so **no PAT is required** for this same-repo dispatch — just
+# > `permissions: actions: write` below. (Cross-repo dispatch, like
+# > `smoke-dispatch.yml`, still needs a PAT; same repo does not.)
 #
 # > **Thin local caller.** The defence-in-depth deploy core (secret-isolation
-# > audit -> CF env gate -> pre-migration snapshot -> migrate -> deploy ->
-# > boot-smoke + auto-rollback) AND the CI-green guard both live in the shared
+# > audit -> CF env gate -> migration (snapshot + apply) -> deploy ->
+# > boot-smoke + auto-rollback) lives in the shared
 # > `dsj1984/mandrel-platform` `deploy-cloudflare.yml` reusable workflow — see
 # > https://github.com/dsj1984/mandrel-platform/blob/main/docs/reusable-workflows.md#deploy-cloudflareyml.
-# > This file only holds <PROJECT_NAME>-specific values (worker names, build
-# > step, secret mapping). When the deploy PROCESS changes, that change lands
-# > upstream in mandrel-platform — not here.
-#
-# One paved road (operator decision 2026-07-01, D4): every consumer triggers
-# staging deploy via `workflow_run` on its own CI workflow, gated on
-# `conclusion == 'success'`. `workflow_run` fires on BOTH a successful AND a
-# failed upstream run, so a caller-side guard against a red run used to be
-# REQUIRED here — every consumer hand-copied the same `preflight` job (see
-# mandrel-platform Story #175 context). That guard is now a `require-ci-green`
-# job INSIDE `deploy-cloudflare.yml` itself (`github.event` inside a reusable
-# workflow is the CALLER's event, so the shared workflow can see and gate on
-# the `workflow_run` conclusion even though it cannot own this file's `on:`
-# block). This template needs NO caller-side preflight guard as a result —
-# copy it as-is and fill in the placeholders below.
+# > The <PROJECT_NAME>-specific values (worker names, build step, secret
+# > mapping) live in the sibling `deploy-staging-run.yml`. When the deploy
+# > PROCESS changes, that change lands upstream in mandrel-platform — not here.
 #
-# Replace every <PLACEHOLDER> with your project's real values:
-#   <CI_WORKFLOW_NAME>        the `name:` of the workflow this deploy should
-#                              gate on (e.g. "quality", "CI", "PR Quality").
-#                              Must match EXACTLY — GitHub matches
-#                              `workflow_run.workflows` by workflow name, not
-#                              file path.
-#   <MANDREL_PLATFORM_SHA>     the pinned mandrel-platform commit SHA (resolve
-#                              via `node scripts/platform-sync.mjs --ref
-#                              <release-tag>` from the consumer repo root, or
-#                              hand-resolve via `git ls-remote`).
-#   <MANDREL_PLATFORM_TAG>     the human-readable release tag matching the SHA
-#                              above (trailing `# <tag>` comment).
-#   <WORKERS_CSV>              comma-separated Worker names for this env, e.g.
-#                              "api,web".
-#   <BUILD_COMMAND>            optional build command (omit build-command /
-#                              build-artifact entirely if the deploy job's
-#                              default checkout is build-ready).
+# Adopt BOTH files together: this `deploy-staging.yml` (dispatcher) and
+# `deploy-staging-run.yml` (the actual deploy). `platform-sync` materializes
+# both. Replace every <PLACEHOLDER>:
+#   <CI_WORKFLOW_NAME>   the `name:` of the workflow this deploy gates on (e.g.
+#                        "quality", "CI"). Must match EXACTLY — GitHub matches
+#                        `workflow_run.workflows` by workflow name, not path.
 #
 # See the full input/secret contract:
 # https://github.com/dsj1984/mandrel-platform/blob/main/docs/reusable-workflows.md#deploy-cloudflareyml
 
 on:
-  # CI-green gate: fires when <CI_WORKFLOW_NAME> finishes on main. The shared
-  # deploy-cloudflare.yml's require-ci-green job skips-with-notice unless the
-  # upstream conclusion was 'success' — no caller-side guard needed.
+  # CI-green gate: fires when <CI_WORKFLOW_NAME> completes on main. Unlike the
+  # old shape, this does NOT call the deploy directly — a `workflow_run` deploy
+  # would skip every `environment:` job. It only DISPATCHES the deploy (below)
+  # on success, so the actual deploy runs on `workflow_dispatch` where those
+  # jobs execute. A red upstream run simply does not dispatch — there is no
+  # green-but-didn't-deploy run at all.
   workflow_run:
     workflows: [<CI_WORKFLOW_NAME>]
     branches: [main]
     types: [completed]
-  # Manual on-demand trigger (UI "Run workflow" + `gh workflow run`).
-  # workflow_dispatch always passes the shared workflow's CI-green guard
-  # (operator-intentional, no upstream conclusion to gate on).
-  workflow_dispatch:
 
+# actions:write lets the built-in GITHUB_TOKEN dispatch deploy-staging-run.yml
+# via the workflow_dispatch API. No PAT needed for a same-repo dispatch —
+# workflow_dispatch always creates a run even from GITHUB_TOKEN.
 permissions:
   contents: read
+  actions: write
 
-# Cancel an in-flight staging deploy when a newer commit lands on main — only
-# the freshest tip of main should reach the staging surfaces. The shared
-# deploy-cloudflare.yml additionally serializes per-environment.
+# Only the freshest tip of main should reach staging: cancel an in-flight
+# DISPATCH when a newer CI run completes. (The deploy itself is serialized
+# separately in deploy-staging-run.yml and per-environment inside the shared
+# deploy-cloudflare.yml.)
 concurrency:
-  group: deploy-staging
+  group: deploy-staging-dispatch
   cancel-in-progress: true
 
 jobs:
-  deploy:
-    name: Staging deploy (shared deploy-cloudflare.yml)
-    uses: dsj1984/mandrel-platform/.github/workflows/deploy-cloudflare.yml@<MANDREL_PLATFORM_SHA> # <MANDREL_PLATFORM_TAG>
-    with:
-      environment: staging
-      gh-environment: staging
-      workers: <WORKERS_CSV>
-      migrate: true
-      # db-engine defaults to 'd1'. Set db-engine + migrate-command +
-      # snapshot-command for a non-D1 engine (e.g. Turso) — see the contract
-      # doc's "command seams" section.
-    # Frozen secret allowlist: only {CLOUDFLARE_*, TURSO_*} cross into the
-    # shared workflow. Map your project's secret NAMES onto these slots.
-    secrets:
-      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+  dispatch:
+    name: Dispatch staging deploy on CI-green
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    # CI-green gate: dispatch the deploy ONLY when the upstream CI run
+    # concluded 'success'. `workflow_run` fires on both success and failure, so
+    # this guard is load-bearing — without it a red main would still deploy.
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - name: Dispatch deploy-staging-run.yml (workflow_dispatch)
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          SHA: ${{ github.event.workflow_run.head_sha }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          gh workflow run deploy-staging-run.yml \
+            --repo "${REPO}" \
+            --ref main \
+            -f sha="${SHA}"
+          echo "Dispatched staging deploy for ${SHA} (deploy runs on workflow_dispatch so environment: jobs execute)."