Good fix for a real problem — Set-Cookie flattening via Record<string, string> or Headers.forEach() comma-joining is a well-known footgun. The approach using getSetCookie() is correct and the tests are well-structured.

A few issues to address:

1. deploy.ts line 604 — type unsoundness: middlewareHeaders[key] is now string | string[] but is assigned to mwReqHeaders typed as Record<string, string> without a cast. Needs an as string cast to match what prod-server.ts does.
2. sendCompressed Vary header handling: now that extraHeaders values can be string[], the Vary concatenation path (existingVary + ", Accept-Encoding") can produce malformed values for array inputs. Minor since Vary is unlikely to be an array, but the type now permits it.
3. Missing edge-case test: the mwCookies = Array.isArray(existing) ? existing : [existing] branch in mergeResponseHeaders isn't exercised by any test (middleware cookie as a plain string, not an array).

None of these are blockers — the core fix is correct and well-tested. Nice work identifying both the prod-server and worker entry code paths.

Good fix for a real bug. Set-Cookie is the only HTTP header that legitimately carries multiple values and must not be comma-joined or deduplicated. Using getSetCookie() is the correct approach.

The core logic in prod-server.ts and the worker entry template in deploy.ts both look correct. I have a few observations, one of which I'd call a real issue worth addressing before merge.

Main concern: The two example worker files are exact copies of each other and both duplicate the mergeHeaders logic from deploy.ts. This is three copies of the same function that must be kept in sync manually. This isn't introduced by this PR (it was already the case), but this PR makes the duplication more painful since the function is now non-trivial. I'd suggest extracting the shared worker logic to avoid this maintenance burden — but that's a follow-up, not a blocker for this PR.

Summary of inline comments:

1. Minor type safety gap in deploy.ts template — existing in the else if branch lacks the as string cast that the example workers and prod-server.ts have.
2. Set-Cookie comparison uses lowercase string literal ("set-cookie") — this is correct since Headers.forEach() always yields lowercase keys and result.responseHeaders from the middleware runner also normalizes to lowercase, but a comment noting this assumption would help future readers.
3. The additive semantics for Set-Cookie (middleware + response cookies are both preserved, rather than response overriding middleware) is the right choice — it matches how Next.js handles this.

Review

The core fix is correct and well-targeted — Set-Cookie must never be comma-joined or deduplicated, and using getSetCookie() is the right approach. The extraction of mergeHeaders into worker-utils.ts is a good step toward reducing duplication in the example workers. Test coverage is solid.

I have one real bug to flag, one file that shouldn't be in this PR, and a couple of minor observations.

Bug: deploy.ts config headers still comma-join Set-Cookie (lines 635-651)

The generated worker template's "Apply custom headers from next.config.js" section still does:

if ((lk === "vary" || lk === "set-cookie") && middlewareHeaders[lk]) {
  middlewareHeaders[lk] += ", " + h.value;
}

This is exactly the comma-joining bug this PR is fixing! If middleware already set a Set-Cookie (now stored as ["mw=1; Path=/"]), the += will call .toString() on the array and produce "mw=1; Path=/, config=2; Path=/" — a single corrupted cookie string.

prod-server.ts correctly handles this with array accumulation (lines 899-907). The deploy.ts template needs the same treatment. The stale comment on line 638-640 also still says "Set-Cookie values are comma-joined here because middlewareHeaders is a flat Record<string, string>" which is no longer true.

Unrelated file: CLAUDE.md

This symlink is unrelated to the Set-Cookie fix. It should be dropped from this PR.

Observations

• The example workers (pages-router-cloudflare, realworld-api-rest) also don't handle config Set-Cookie as arrays in their config headers section, but that's a pre-existing issue not introduced by this PR.
• Good test coverage overall. The mergeResponseHeaders plain-string middleware cookie test (line 2810) exercises the Array.isArray(existing) ? existing : [existing] branch nicely.

Review

The core fix is correct and well-scoped. Set-Cookie is the one HTTP header that must not be comma-joined (RFC 6265), and the old Record<string, string> + Headers.forEach() patterns were silently corrupting multi-cookie responses. Using getSetCookie() and array accumulation is the right approach.

CI is all green. The extraction of mergeHeaders into worker-utils.ts is a good improvement that deduplicates the example workers. Test coverage is solid — the four new test groups cover the important code paths including the Array.isArray(existing) ? existing : [existing] branch for plain-string middleware cookies.

Two issues to flag:

1. Example workers' config headers still overwrite Set-Cookie

Both examples/pages-router-cloudflare/worker/index.ts and examples/realworld-api-rest/worker/index.ts still use a simple overwrite pattern for config headers (line 151):

middlewareHeaders[h.key.toLowerCase()] = h.value;

Now that middlewareHeaders is Record<string, string | string[]>, a config header with set-cookie will overwrite any middleware Set-Cookie array with a plain string. This is inconsistent with both prod-server.ts (lines 899-907) and the deploy.ts template (lines 644-657), which both use array accumulation. Since this PR already touched these files to fix middleware collection and import mergeHeaders, it would be good to also fix the config headers section to match.

2. Indentation inconsistency in deploy.ts template

Lines 636-659 use 7-space indent while the rest of the template uses 6-space indent. This was likely introduced when replacing the old block. Cosmetic only (affects the generated code's indentation), but worth fixing for consistency.

Review

Good fix for a real and well-known bug. Set-Cookie is the one HTTP header where comma-joining corrupts values (cookies with Expires dates contain commas), and the old Record<string, string> + Headers.forEach() patterns were silently breaking multi-cookie responses. Using getSetCookie() and array accumulation is the correct approach.

The extraction of mergeHeaders into worker-utils.ts is a solid improvement — it eliminates the duplicated inline function from both example workers. Test coverage is good: the four new test groups in features.test.ts cover the main code paths including the Array.isArray(existing) ? existing : [existing] branch for plain-string middleware cookies, and the behavioral test in deploy.test.ts properly validates the mergeHeaders function against real Response objects.

Two items to address:

1. Stale (middlewareHeaders as any) casts in prod-server.ts config headers section (lines 904, 906)

The middleware collection section was correctly updated to use middlewareHeaders[key] = [existing as string, value] (line 848), but the config headers section (lines 899-907, not in this diff) still uses the old (middlewareHeaders as any)[lk] = [existing, value] pattern. Now that middlewareHeaders is Record<string, string | string[]>, the as any cast is unnecessary and inconsistent with every other location that was updated. This should be cleaned up to match.

2. Example workers missing Vary handling in config headers

The example workers' config headers section (line 162 of both) doesn't handle Vary specially, while both prod-server.ts (line 908) and deploy.ts template (line 653) comma-join Vary values. Pre-existing issue but worth aligning since the block was already rewritten.

Otherwise the PR looks correct and ready to ship.

Review

This is a solid fix for a real and well-documented bug. Set-Cookie is the one HTTP header where comma-joining corrupts values (cookies with Expires dates contain commas), and the old Record<string, string> + Headers.forEach() patterns were silently breaking multi-cookie responses. Using getSetCookie() and array accumulation is the correct approach.

CI is all green. The core logic is correct across all three code paths (prod-server.ts, deploy.ts template, worker-utils.ts). The extraction of mergeHeaders into worker-utils.ts is a nice deduplication win for the example workers. Test coverage is good -- the four new test groups cover the important paths including the Array.isArray(existing) ? existing : [existing] branch for plain-string middleware cookies.

I have two minor nits inline but nothing blocking. Ship it.