fix(templates): build Next.js outside the deploy job that can mint a deploy token

[dawsontoth]

⊙ Problem

The Next.js templates' deploy job installed dependencies and ran next build while holding id-token: write. Any dependency's install or build script could ask GitHub for the job's identity token and trade it for the deploy user's Harper token, which can deploy any app on the cluster.

🤔 Is building in CI still right for Next.js?

Yes, for now: building on the cluster fails (HarperFast/nextjs#57, HarperFast/nextjs#58). Once those land, these templates can join the shared workflow and drop the artifact.

💡 Solution

• The test job runs next build, on pull requests too. On main it uploads .next, without .next/cache, as an artifact.
• The deploy job downloads it after checkout. Otherwise it is the shared deploy job: it no longer installs your dependencies or builds, and runs only the Harper CLI.
• The other templates' deploy job already installs only the CLI, and its checkout already sets persist-credentials: false.

⚖️ Alternatives

• A separate build job — a second dependency install, and no isolation the test job doesn't already have.
• Uploading .next/cache too — 20 of the 26 MB in a fresh scaffold, and the app serves without it.

🤔 Should the build see production-environment variables?

It no longer can: next build runs outside environment: production, so variables scoped to that environment don't reach it. The template uses none; a project that needs NEXT_PUBLIC_* values at build time can pass repository variables to the Build step with env:.

🔧 Changes

• template-nextjs/_github/workflows/deploy.yaml and template-nextjs-ts/_github/workflows/deploy.yaml are identical. The header comment says where the build runs. The test job builds and uploads it on main, with hidden files on, since upload-artifact skips .next otherwise, and overwrite so a whole-workflow re-run can upload again. The deploy job downloads it and drops its install and build. TS copy: build, upload, download.
• template-nextjs/README.md and template-nextjs-ts/README.md: pull requests now build, and the deploy section says where the build runs and why. TS copy: build, deploy.
• templates-shared/applySharedTemplates.js: the comment on why the Next.js templates keep their own workflow.

✅ Verification

• npm test: 384 pass; lint:check and format:check clean. In template.tests/deployWorkflow.test.js, a new test checks that no template's deploy job installs dependencies or builds, and new Next.js tests check the upload, the download's order and that the deploy job matches the shared one apart from the download. The scaffolded pnpm workflow keeps pnpm out of the deploy job, and the helpers moved to module scope for these. 8 of them fail on main.
• Live smoke: scaffolded nextjs, ran npm run build, copied the project without node_modules and .next, added .next without cache/, and ran harper deploy project=nextsmoke restart=true against a throwaway Harper 5.3.2. It deployed, and GET / returned 200 with the Harper-backed counter.
• Not run: the upload and download on a real Actions runner.

Related: HarperFast/documentation#731 (the same fix in the CI guide's Path B), HarperFast/skills#119 (the skill rule that quotes the guide).

_{🤖 Generated by Claude Code (Claude Opus 5.5); posted via @dawsontoth.}

Related PRs: #147 overlaps (merged; this hardens its Next.js deploy job)
Complexity: medium

_{Review-Coverage: authored=claude; ran=gemini,codex; adjudicated=domain; declined=cursor-grok,cursor-composer,cursor-kimi,cursor-muse,muse; rounds=1; full=1 @ 98f4fdc}

_{Review-Attention: read ~3m (decisions: build-env-scope, duplicated-deploy-gate, pr-builds) @ 98f4fdc}