fix: serialize next build across worker threads (#52)

[dawsontoth]

Fixes #52.

Problem

On a multi-threaded Harper cluster, a deployed Next.js app (no prebuilt) fails to serve — every route 404s — and system.log shows the on-startup build failing in a worker thread:

Error building Next.js application <app>: Error: ENOENT: no such file or directory,
  ... path: '.../components/<app>/.next/BUILD_ID'

handleApplication runs in every worker thread, but build() only did a post-hoc dedup check — it never claimed the build before compiling. On a fresh deploy/restart there is no (or a >5s stale) build-info record, so every worker fell through and ran next build concurrently into the same .next. next build clears and rewrites .next at the start, so one worker deletes .next/BUILD_ID while another reads it → ENOENT → the build worker exits → nothing serves.

Fix

Port the claim-then-wait lock from @harperfast/vite's buildLock:

• A worker claims the shared nextjs_build_info record with status building before compiling.
• Sibling workers observe the fresh claim and poll-wait, then skip — only one worker ever builds.
• A stale-claim timeout (5 min) reclaims the build if the holder crashed (the issue notes a build worker's process.exit(1) is swallowed to keep Harper alive).
• The existing behavior is preserved: reuse a fresh (<5s) successful build when the on-disk BUILD_ID matches, and skip when a fresh failure is recorded.

Coordination is extracted into a testable src/buildLock.ts (withBuildLock), mirroring vite. build() now supplies a runBuild closure holding the Next-version-specific next build call; on success withBuildLock records the resulting BUILD_ID, on throw it records a failure and rethrows.

Changes

• src/buildLock.ts — new withBuildLock(scope, { getBuildId, runBuild }) coordination module.
• src/plugin.ts — build() delegates to withBuildLock; extracted runNextBuild(). Also normalizes the stored BUILD_ID with .trim() so it matches getBuildId() in the reuse check.
• src/buildLock.test.ts — node --test unit tests for the claim / wait / stale-reclaim / fresh-reuse / mismatch-rebuild / fresh-failure-skip / build-throws paths.
• package.json — test script (node --test), and files allowlist now ships dist/** minus dist/**/*.test.*.
• .npmignore — belt-and-suspenders *.test.* backstop (matches vite).
• schema.graphql — document the building claim status on NextBuildInfo.

Testing

npm test          # 9/9 buildLock unit tests pass (the wait test exercises a real poll cycle)
npm run build     # tsc clean
npx tsc -p tsconfig.json --noEmit   # type-check clean

The unit tests deterministically cover the coordination logic. I did not add a multi-thread integration test: @harperfast/integration-testing hardcodes --THREADS_COUNT=1, so the harness can't exercise the race, and a timing-based reproduction would be flaky.

Notes / follow-ups

• Like vite's lock, the check-then-claim has a small residual TOCTOU window (two workers both reading "no claim" within the same DB round-trip). In practice worker startup is staggered well beyond that window, so the first worker claims before the others check — this is the endorsed vite behavior. A future hardening could add a per-build heartbeat so STALE_CLAIM_MS tracks liveness rather than a fixed budget.
• Pre-existing (unchanged) quirk: on a genuine build failure, the worker that built declines to serve while sibling workers that observed the fresh failure record still fall through to serve(). Out of scope here; worth a separate look.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a build lock mechanism (withBuildLock) to coordinate Next.js production builds across Harper worker threads, preventing concurrent builds into the same .next directory. It also adds comprehensive unit tests for this lock mechanism, updates package configurations to exclude test files from the published package, and adds a test script. The reviewer suggested increasing the build timeout (STALE_CLAIM_MS and CLAIM_WAIT_TIMEOUT_MS) from 5 minutes to 10 minutes to accommodate larger Next.js applications or resource-constrained environments, preventing premature timeouts that could lead to concurrent builds.

[gemini-code-assist]

For larger Next.js applications or resource-constrained server environments, a 5-minute build timeout (STALE_CLAIM_MS and CLAIM_WAIT_TIMEOUT_MS) can sometimes be exceeded. If a build takes longer than 5 minutes, waiting workers will time out and start building concurrently, which defeats the lock and causes the ENOENT crash. Increasing this timeout to 10 minutes provides a safer margin.

Suggested change

	const STALE_CLAIM_MS = 5 * 60 * 1000;
	// How often a waiting worker re-checks the claim, and how long it waits before building anyway.
	const CLAIM_POLL_MS = 150;
	const CLAIM_WAIT_TIMEOUT_MS = 5 * 60 * 1000;
	const STALE_CLAIM_MS = 10 * 60 * 1000;
	// How often a waiting worker re-checks the claim, and how long it waits before building anyway.
	const CLAIM_POLL_MS = 150;
	const CLAIM_WAIT_TIMEOUT_MS = 10 * 60 * 1000;

[Ethan-Arrowood]

lgtm

[github-actions]

🎉 This PR is included in version 2.2.2 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀