fix(deploy): expand sparse checkout so microservices/ecosystem are on disk

Run #120 (v0.3.0 deploy) failed at the microservice step: every service folder
and ecosystem.config.js were "absent", and pm2 reported "File ecosystem.config.js
not found". Root cause: ~/pms on pms1 is a sparse checkout limited to App/, so
`git checkout -f $TAG` never materialised the service folders or the root
ecosystem.config.js. The app itself deployed fine (App/ is in the sparse set) and
prod stayed healthy.

- deploy.yml: before managing services, disable sparse-checkout (and clear the
  legacy core.sparseCheckout config + .git/info/sparse-checkout), then re-checkout
  the tag to materialise the full tree. Idempotent / no-op once expanded.
- Guard the pm2 call: if ecosystem.config.js is still absent, fail with a clear
  diagnostic (+ sparse-checkout list) instead of the cryptic PM2 error.
- README: note the sparse-checkout expansion.

Needs a fresh tag (e.g. v0.3.1) to re-run the deploy.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.forgejo/workflows/deploy.yml

@@ -48,6 +48,15 @@ jobs:
 
           cd "$HOME/pms"
 
+          # ~/pms has historically been a SPARSE checkout limited to App/ (only the
+          # app deployed), so the service folders + ecosystem.config.js never landed
+          # on disk. Expand the working tree to the full repo, then re-materialise
+          # the tag. Idempotent: a no-op once sparse is disabled / if never sparse.
+          git sparse-checkout disable 2>/dev/null || true
+          git config --unset core.sparseCheckout 2>/dev/null || true
+          rm -f .git/info/sparse-checkout 2>/dev/null || true
+          git checkout -f "refs/tags/${GITHUB_REF_NAME}"
+
           # Pull only the few keys the services need out of the app's .env (the
           # single source of truth on the host). Never import PORT (each service's
           # port is fixed in ecosystem.config.js) or the runner's ephemeral
@@ -69,6 +78,11 @@ jobs:
 
           # Create on first release, zero-downtime reload thereafter. The
           # ecosystem registers only services whose dirs exist.
+          if [ ! -f ecosystem.config.js ]; then
+            echo "ERROR: ecosystem.config.js absent in $(pwd) after checkout — sparse-checkout not expanded?"
+            git sparse-checkout list 2>/dev/null || true
+            exit 1
+          fi
           pm2 startOrReload ecosystem.config.js --update-env
           pm2 save
           pm2 list

automation/README.md

@@ -181,9 +181,13 @@ progress under **Actions** on the Forgejo repo, or `pm2 logs forgejo-runner` on
 ## Microservices (GstService / EpfoService / PdfService)
 
 The standalone Playwright services are deployed by the **same `v*` tag** as the app.
-After the app restart, `deploy.yml`:
+`~/pms` was historically a **sparse checkout limited to `App/`**, so the service
+folders never landed on disk; the deploy now disables sparse-checkout (idempotent)
+to materialise the whole tree before managing the services. After the app restart,
+`deploy.yml`:
 
-1. exports the few secrets the services need out of `~/pms/App/.env`
+1. expands the working tree (sparse-checkout disable) and exports the few secrets
+   the services need out of `~/pms/App/.env`
    (`PDF_SERVICE_TOKEN`, `ALLOWED_ORIGIN`, `EPFO_LIVE`) — never `PORT` or the
    runner's ephemeral `FORGEJO_TOKEN`;
 2. for each service folder present, runs `npm install` + `npx playwright install