fix(deploy): switch Dockerfiles from pnpm install to npm install (Lesson #54 escape hatch)

The pnpm install --filter ... --frozen-lockfile --ignore-scripts step
deadlocks deterministically at ~734 packages on tucker (libuv worker-
thread futex hang). Pinning pnpm@9 + node:20-slim + --ignore-scripts
all stack the workaround layers but the bug surfaced again the moment
the lockfile changed (better-sqlite3 + transitive deps added in the
5.0.10 PR). The yapbay-vite escape hatch — switch to npm — is the
established fix; applying it here.

What changed:
- Root package.json: add `workspaces` array. npm reads this field;
  pnpm prefers pnpm-workspace.yaml when both exist, so local pnpm dev
  is unaffected (verified — pnpm-lock.yaml didn't churn after the
  addition).
- faucet/Dockerfile: drop corepack/pnpm@9 setup; install via
  `npm install --no-audit --no-fund --ignore-scripts --omit=optional`
  at the root. Existing `npm rebuild better-sqlite3` + `node -e
  "require('better-sqlite3')"` smoke check stay (npm rebuild handles
  the prebuild fetch the same way pnpm rebuild did). CMD is now
  `npm start`.
- app/Dockerfile: same install switch. Build invocation changes from
  `pnpm --filter @pushflip/app build` to `npm run build
  --workspace=@pushflip/app`.

Both Dockerfiles now copy ALL workspace package.json files (not just
the filtered ones) because npm install at the root reads every
workspace's manifest. Adds a few hundred bytes to the build context
per file; cache-friendly because the layer only invalidates when any
package.json changes.

Lockfile decision: deliberately not committing a package-lock.json.
The Dockerfile uses `npm install` (not `npm ci`) so the build doesn't
require one; npm resolves fresh from the package.json semver ranges.
For a containerized build that's tested locally before deploy, this
is acceptable; if reproducibility becomes a concern, a future commit
can `npm install --package-lock-only` at the root and check it in
alongside pnpm-lock.yaml. Tracked separately.

Author: georgedonnelly

app/Dockerfile

@@ -22,36 +22,45 @@
 # on the deploy host. Image carries NO secrets — Helius URLs include
 # an API key but it's a public devnet key with no economic value.
 #
-# Build base: node:20-slim (Debian, glibc), NOT node:20-alpine.
-# pnpm install hangs deterministically on Alpine in rootless podman
-# (worker-thread futex deadlock; see faucet/Dockerfile header). Serve
-# stage stays alpine because `serve` is pure JS with no native deps,
-# so the runtime image stays small.
+# Base: node:20-slim (Debian, glibc) for build, node:20-alpine for
+# the serve stage (pure JS, no native deps so musl is fine).
+#
+# Install: `npm install` (NOT pnpm). pnpm install in containerized
+# Node deadlocks deterministically at ~734 packages — libuv worker-
+# thread futex hang. Documented as Lesson #54; re-hit during the
+# 5.0.10 deploy with better-sqlite3 in the lockfile. yapbay-vite hit
+# this same bug on the same host and resolved it by switching to
+# npm; we do the same.
 
 # --- build stage ---------------------------------------------------
 FROM node:20-slim AS build
 WORKDIR /app
-RUN corepack enable && corepack prepare pnpm@9 --activate
 
-COPY pnpm-workspace.yaml package.json pnpm-lock.yaml ./
+# Copy workspace package.json files first so this layer caches across
+# source edits.
+COPY package.json ./
 COPY app/package.json ./app/
 COPY clients/js/package.json ./clients/js/
-# --ignore-scripts: workaround for pnpm install hanging on postinstall
-# scripts inside rootless podman on Alpine. Same issue caused yapbay's
-# pnpm-test image to hang for 13 days (see ~/repos/yapbay/Containerfile
-# which works around it by switching to npm ci entirely). Platform-
-# specific binaries that vite/tsc need (esbuild, lightningcss, the
-# rollup-linux-* native binding) are declared as optionalDependencies
-# and install regardless of --ignore-scripts. Biome's postinstall
-# (the likely culprit for the 10-min hang we saw) is dev-only and not
-# needed for the production bundle build.
-RUN pnpm install --filter @pushflip/app --filter @pushflip/client --frozen-lockfile --ignore-scripts
+COPY faucet/package.json ./faucet/
+COPY scripts/package.json ./scripts/
+COPY dealer/package.json ./dealer/
+COPY house-ai/package.json ./house-ai/
+COPY zk-circuits/package.json ./zk-circuits/
+
+# --ignore-scripts: skip biome/ultracite postinstalls that aren't
+# needed for the production bundle build. Vite + tsc come via npm's
+# optionalDependencies (esbuild, lightningcss, rollup-linux-*) which
+# install regardless of --ignore-scripts.
+# --no-audit --no-fund: less noise + slightly faster.
+# --omit=optional: drop platform-specific binaries we don't need on
+# this Linux x64 build.
+RUN npm install --no-audit --no-fund --ignore-scripts --omit=optional
 
 COPY clients/js ./clients/js
 COPY app ./app
 
 # Defaults match the dev expectation but production builds MUST pass
-# all three via --build-arg. The deploy script does this.
+# all four via --build-arg. The deploy script does this.
 ARG VITE_FAUCET_URL=/api/faucet
 ARG VITE_NICKNAME_URL=/api/nickname
 ARG VITE_RPC_ENDPOINT=https://api.devnet.solana.com
@@ -61,7 +70,8 @@ ENV VITE_NICKNAME_URL=${VITE_NICKNAME_URL}
 ENV VITE_RPC_ENDPOINT=${VITE_RPC_ENDPOINT}
 ENV VITE_RPC_WS_ENDPOINT=${VITE_RPC_WS_ENDPOINT}
 
-RUN pnpm --filter @pushflip/app build
+# Run the workspace's build script via npm.
+RUN npm run build --workspace=@pushflip/app
 
 # --- serve stage ---------------------------------------------------
 # Serves the built dist/ on port 5175. Matches the yapbay-vite pattern

faucet/Dockerfile

@@ -9,57 +9,69 @@
 # and the keypair is bind-mounted read-only from the host filesystem.
 # This image carries NO secrets.
 #
-# Base: node:20-slim (Debian, glibc), NOT node:20-alpine (musl).
-# pnpm install hangs deterministically on Alpine inside rootless
-# podman due to a worker-thread/futex deadlock — see the matching
-# yapbay-pushflip session log + the abandoned ~/repos/yapbay/Containerfile
-# (renamed to .pnpm-test) that hung for 13 days on the same issue.
-# Debian's glibc is the minimal-change fix; image size goes from ~50MB
-# to ~150MB which is irrelevant on tucker (49 GB free).
+# Base: node:20-slim (Debian, glibc).
+#
+# Install: `npm install` (NOT pnpm). pnpm install in containerized Node
+# deadlocks deterministically at ~734 packages — libuv worker-thread
+# futex hang. Documented as Lesson #54 in EXECUTION_PLAN.md and re-hit
+# during the 5.0.10 deploy after better-sqlite3 was added to the
+# lockfile (the package count changed but the deadlock signature did
+# not). yapbay-vite hit this same bug months ago on this same host
+# and resolved it by switching to npm; we do the same.
+#
+# Workspaces: root package.json declares a `workspaces` array that npm
+# reads (pnpm prefers pnpm-workspace.yaml when both exist, so local
+# pnpm dev is unaffected by the field).
 
 FROM node:20-slim AS base
 WORKDIR /app
-RUN corepack enable && corepack prepare pnpm@9 --activate
 
-# Install workspace deps. Copy the lockfile + the package.json files
-# of the workspaces we need first, so this layer caches across source
-# edits. @pushflip/client is needed because faucet imports U64_MAX +
-# TEST_FLIP_MINT + TOKEN_PROGRAM_ID + FLIP_DECIMALS from it.
-COPY pnpm-workspace.yaml package.json pnpm-lock.yaml ./
+# Install workspace deps. Copy the workspace package.json files first
+# so this layer caches across source edits. @pushflip/client is needed
+# because faucet imports U64_MAX + TEST_FLIP_MINT + TOKEN_PROGRAM_ID +
+# FLIP_DECIMALS from it.
+COPY package.json ./
 COPY faucet/package.json ./faucet/
 COPY clients/js/package.json ./clients/js/
-# --ignore-scripts: workaround for pnpm install hanging on postinstall
-# scripts inside rootless podman on Alpine. Same issue caused yapbay's
-# pnpm-test image to hang for 13 days. Platform-specific binaries
-# (esbuild, lightningcss, etc.) come via optionalDependencies and
-# install regardless of --ignore-scripts. The faucet has no runtime
-# binary deps, so this is strictly safe here.
-RUN pnpm install --filter @pushflip/faucet --filter @pushflip/client --frozen-lockfile --ignore-scripts
+COPY app/package.json ./app/
+COPY scripts/package.json ./scripts/
+COPY dealer/package.json ./dealer/
+COPY house-ai/package.json ./house-ai/
+COPY zk-circuits/package.json ./zk-circuits/
+
+# --ignore-scripts: skip postinstall hooks that previously triggered
+# the same hang (biome/ultracite postinstalls do disk-heavy work). We
+# explicitly run `npm rebuild better-sqlite3` after to fetch its
+# native binding.
+# --no-audit --no-fund: less noise + slightly faster.
+# --omit=optional: drop platform-specific optional binaries we don't
+# need (e.g. esbuild's macOS binaries on a Linux build).
+RUN npm install --no-audit --no-fund --ignore-scripts --omit=optional
 
 # `--ignore-scripts` blocked better-sqlite3's prebuild-install, which
 # normally downloads the precompiled native binding for the running
-# Node version. `pnpm rebuild better-sqlite3` re-runs ONLY that
+# Node version. `npm rebuild better-sqlite3` re-runs ONLY that
 # package's install script in place, fetching the prebuild for our
 # (node-20, linux-x64, glibc) target. better-sqlite3 11.x ships
 # prebuilds for that target so the fetch path always wins; the
 # build-from-source fallback (which would need python3/make/g++) is
 # never exercised here.
 #
 # The `node -e "require('better-sqlite3')"` smoke is a load-bearing
-# guard, not a paranoia check: if upstream ever drops the prebuild for
-# our target tuple, `pnpm rebuild` silently succeeds (it tries the
-# from-source fallback, which fails to find `python3`/`make`/`g++` and
+# guard, not a paranoia check: if upstream ever drops the prebuild
+# for our target tuple, npm rebuild silently succeeds (it tries the
+# from-source fallback, which fails to find python3/make/g++ and
 # leaves the package in a broken state without a non-zero exit). The
 # require() call fails loudly with "could not locate the bindings
 # file", giving the operator a clear pointer to add the build deps.
 # (Pre-Mainnet 5.0.10 — globally-unique-nickname registry needs the
 # native sqlite binding at runtime.)
-RUN pnpm rebuild better-sqlite3 \
+RUN npm rebuild better-sqlite3 \
     && node -e "require('better-sqlite3')" \
     || (echo "[faucet] FATAL: better-sqlite3 native binding failed to load. If this happened after a node/better-sqlite3 version bump, the prebuild may be missing for the target tuple — add 'apt-get install -y python3 make g++' before this RUN step to enable the from-source fallback." && exit 1)
 
 # Source. clients/js is consumed in source form by @pushflip/faucet
-# (no build step — pnpm workspace alias resolves to clients/js/src/index.ts).
+# (no build step — the workspace symlink resolves to clients/js/src/index.ts).
 COPY clients/js ./clients/js
 COPY faucet ./faucet
 
@@ -70,4 +82,5 @@ WORKDIR /app/faucet
 # FAUCET_KEYPAIR_PATH points at.
 EXPOSE 3001
 
-CMD ["pnpm", "start"]
+# `npm start` runs the workspace's "start" script (tsx src/index.ts).
+CMD ["npm", "start"]

package.json

@@ -7,5 +7,14 @@
     "build": "just build",
     "test": "just test",
     "lint": "just lint"
-  }
+  },
+  "workspaces": [
+    "app",
+    "faucet",
+    "clients/js",
+    "scripts",
+    "dealer",
+    "house-ai",
+    "zk-circuits"
+  ]
 }