fix(deploy): stage worktree build and short .next cutover

Build install/test/migrate in a detached worktree while the live site keeps serving, then swap .next and node_modules during a brief stop. Drops nuclear rm -rf src and rolls back .next.prev on cutover failure.

Co-authored-by: Cursor <[email protected]>

src/lib/deploy-workflow-contract.test.ts

@@ -7,47 +7,63 @@ describe("production deploy workflow", () => {
 		resolve(process.cwd(), ".gitea/workflows/deploy.yaml"),
 		"utf8",
 	);
+	const deployJob = workflow.slice(workflow.indexOf("\n  deploy:"));
 
-	it("preserves the Next.js incremental build cache", () => {
-		// May clear .next/types or .next/dev, but must not wipe the whole .next tree.
-		expect(workflow).not.toMatch(/rm\s+-rf\s+\.next(?:\s|$)/);
-		expect(workflow).toContain("rm -rf .output dist .next/types .next/dev");
-		expect(workflow).toContain("pnpm install --frozen-lockfile");
-		// Production builds must validate env (AUTH_SECRET, DATABASE_URL, …).
-		expect(workflow).not.toContain("SKIP_ENV_VALIDATION=1");
+	it("builds in a stage worktree while preserving live .env and storage", () => {
+		expect(deployJob).toContain("worktree add --detach");
+		expect(deployJob).toContain("/var/tmp/atom-nexst-stage-");
+		expect(deployJob).toContain('ln -sfn "${LIVE}/.env"');
+		expect(deployJob).toContain("-e storage");
+		expect(deployJob).not.toContain("SKIP_ENV_VALIDATION=1");
+		expect(deployJob).toContain("pnpm install --frozen-lockfile");
 	});
 
-	it("reclaims ownership before git reset so www-data files can be overwritten", () => {
-		expect(workflow).toContain('sudo chown -R "$' + "{DEPLOY_USER}:" + '$' + '{DEPLOY_GROUP}"');
-		const reclaimAt = workflow.indexOf(
+	it("reclaims ownership before git operations so www-data files can be overwritten", () => {
+		expect(workflow).toContain(
 			'sudo chown -R "$' + "{DEPLOY_USER}:" + '$' + '{DEPLOY_GROUP}"',
 		);
-		const resetAt = workflow.indexOf("git reset --hard origin/main");
+		const reclaimAt = deployJob.indexOf(
+			'sudo chown -R "$' + "{DEPLOY_USER}:" + '$' + '{DEPLOY_GROUP}"',
+		);
+		const fetchAt = deployJob.indexOf("git -C \"${LIVE}\" fetch origin --prune");
 		expect(reclaimAt).toBeGreaterThan(-1);
-		expect(resetAt).toBeGreaterThan(reclaimAt);
+		expect(fetchAt).toBeGreaterThan(reclaimAt);
 	});
 
-	it("nuclear-replaces src/ and clears sticky bits without scanning every path", () => {
-		expect(workflow).toContain("rm -rf src");
-		expect(workflow).toContain("git checkout -f HEAD -- src");
-		expect(workflow).toContain("no-skip-worktree");
-		expect(workflow).toContain("no-assume-unchanged");
-		expect(workflow).toContain("Verified src/ matches HEAD");
-		expect(workflow).toContain("git ls-files -v");
-		expect(workflow).not.toContain("git ls-files -z");
-		expect(workflow).toContain("pnpm typecheck");
+	it("avoids nuclear src wipe and verifies live src after cutover reset", () => {
+		expect(deployJob).not.toContain("rm -rf src");
+		expect(deployJob).not.toContain("Nuclear-replacing src/");
+		expect(deployJob).toContain("no-skip-worktree");
+		expect(deployJob).toContain("no-assume-unchanged");
+		expect(deployJob).toContain("Verified live src/ matches HEAD");
+		expect(deployJob).toContain("ls-files -v");
+		expect(deployJob).not.toContain("git ls-files -z");
+		expect(deployJob).toContain("pnpm typecheck");
+	});
+
+	it("swaps a built .next artifact during a short service cutover", () => {
+		expect(deployJob).toContain("mv .next .next.prev");
+		expect(deployJob).toContain('mv "${STAGE}/.next" .next');
+		expect(deployJob).toContain('mv "${STAGE}/node_modules" node_modules');
+		expect(deployJob).toContain("Rolling back .next to previous artifact");
+		const buildAt = deployJob.indexOf("pnpm build");
+		const stopAt = deployJob.indexOf("sudo systemctl stop atom-nexst.service");
+		const startLabelAt = deployJob.indexOf("Starting systemd service...");
+		const startAt = deployJob.indexOf(
+			"sudo systemctl start atom-nexst.service",
+			startLabelAt,
+		);
+		expect(buildAt).toBeGreaterThan(-1);
+		expect(stopAt).toBeGreaterThan(buildAt);
+		expect(startLabelAt).toBeGreaterThan(stopAt);
+		expect(startAt).toBeGreaterThan(startLabelAt);
 	});
 
 	it("does not override onlyBuiltDependencies (uses pnpm-workspace.yaml)", () => {
 		expect(workflow).not.toContain("PNPM_CONFIG_ONLY_BUILT_DEPENDENCIES");
 	});
 
-	it("runs typecheck and tests before build", () => {
-		expect(workflow).toContain("pnpm typecheck");
-		expect(workflow).toContain("pnpm test");
-		// Scope to the deploy job: the release job's documentation body also
-		// mentions these commands, which must not affect this contract.
-		const deployJob = workflow.slice(workflow.indexOf("\n  deploy:"));
+	it("runs typecheck and tests before build in the stage", () => {
 		const typecheckAt = deployJob.indexOf("pnpm typecheck");
 		const testAt = deployJob.indexOf("pnpm test");
 		const buildAt = deployJob.indexOf("pnpm build");
@@ -57,7 +73,9 @@ describe("production deploy workflow", () => {
 	});
 
 	it("exports APP_VERSION from git for Sentry releases", () => {
-		expect(workflow).toContain('export APP_VERSION="$(git rev-parse --short HEAD)"');
+		expect(workflow).toContain(
+			'export APP_VERSION="$(git -C "${LIVE}" rev-parse --short origin/main)"',
+		);
 		expect(workflow).toContain(
 			'export NEXT_PUBLIC_APP_VERSION="$' + "{APP_VERSION}\"",
 		);
@@ -66,7 +84,6 @@ describe("production deploy workflow", () => {
 	it("runs an HTTP health check before declaring deploy success", () => {
 		expect(workflow).toContain("/api/health");
 		expect(workflow).toContain('"database":true');
-		const deployJob = workflow.slice(workflow.indexOf("\n  deploy:"));
 		const startAt = deployJob.indexOf("systemctl start atom-nexst.service");
 		const healthAt = deployJob.indexOf("/api/health");
 		const successAt = deployJob.indexOf("--- Deployed successfully ---");