fix(arkenv): prevent in-place mutation of config objects during coercion

[yamcodes]

Description

This PR refactors applyCoercion to perform non-mutating updates on environment configuration data by recursively cloning/structurally sharing objects and arrays along the validation target path instead of modifying the existing ones in-place.

This fixes:

1. Runtime crashes when parsing frozen or read-only configuration objects (such as Nuxt's runtimeConfig).
2. Silent side-effects caused by in-place mutations on reused configuration objects.
3. Restores configuration safety when using Record<string, unknown> environments.

Testing Done

Added comprehensive unit tests in packages/arkenv/src/coercion/shared.test.ts to assert:

• Successful coercion of frozen/read-only objects without crashes.
• Reference integrity (non-mutation) of original objects.
• Correct structural sharing on unmodified sibling/nested paths.
• Clean array coercion without in-place mutation.

All 69 test files (701 tests) in the workspace pass successfully.

[pullfrog]

Run failed. View the logs →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[changeset-bot]

🦋 Changeset detected

Latest commit: e8bc799

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
arkenv	Patch
@arkenv/nuxt	Patch
@arkenv/cli	Patch
@arkenv/build	Patch
@arkenv/nextjs	Minor
@arkenv/bun-plugin	Patch
@arkenv/vite-plugin	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[arkenv-bot]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (Asia/Almaty)
arkenv	Ready	Preview, Comment	Jun 15 2026, 9:59 AM (Asia/Almaty)

[pkg-pr-new]

Open in StackBlitz

arkenv

npm i https://pkg.pr.new/yamcodes/arkenv@1206

@arkenv/build

npm i https://pkg.pr.new/yamcodes/arkenv/@arkenv/build@1206

@arkenv/bun-plugin

npm i https://pkg.pr.new/yamcodes/arkenv/@arkenv/bun-plugin@1206

@arkenv/cli

npm i https://pkg.pr.new/yamcodes/arkenv/@arkenv/cli@1206

@arkenv/fumadocs-ui

npm i https://pkg.pr.new/yamcodes/arkenv/@arkenv/fumadocs-ui@1206

@arkenv/nextjs

npm i https://pkg.pr.new/yamcodes/arkenv/@arkenv/nextjs@1206

@arkenv/nuxt

npm i https://pkg.pr.new/yamcodes/arkenv/@arkenv/nuxt@1206

@arkenv/vite-plugin

npm i https://pkg.pr.new/yamcodes/arkenv/@arkenv/vite-plugin@1206

commit: e8bc799

[arkenv-bot]

📦 Bundle Size Report

Package	Size	Limit	Diff	Status
arkenv	2.02 kB	2.05 kB	+3.6%	✅
arkenv/standard	2.19 kB	2.25 kB	+3.3%	✅
arkenv/core	441 B	500 B	0.0%	✅
@arkenv/nextjs	1002 B	2.93 kB	<0.1%	✅
@arkenv/nextjs/shared	1018 B	1.46 kB	-0.4%	✅
@arkenv/nextjs/server	1.05 kB	1.95 kB	-0.9%	✅
@arkenv/nextjs/client	1.04 kB	1.95 kB	-1.0%	✅
@arkenv/nextjs/config	2.42 kB	2.93 kB	0.0%	✅

✅ All size limits passed!

[pullfrog]

Important

Object.hasOwn breaks TypeScript compilation at the current es2020 target. The old code explicitly handled this with the prototype-based call and a biome suppression comment noting the limitation.

Reviewed changes — this PR refactors applyCoercion from in-place mutation to a non-mutating functional pattern, preventing crashes on frozen/read-only config objects and eliminating side-effects on reusable configs.

• Replace walk with updateAtPath — the new pure function clones objects and arrays along validated paths only when a descendant value changes, otherwise returns the same reference for structural sharing.
• Rewrite coerceValue primitive-array coercion — .map() replaces the in-place for loop so frozen arrays are safe.
• Add safety and non-mutation tests — covers frozen objects, reference integrity, structural sharing of untouched subtrees, and array coercion without mutation.
• Bump size-limit from 2 kB to 2.1 kB to accommodate the non-mutating coercion logic.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes — the new commit adds "lib": ["es2020", "es2022.object"] to tsconfig.json, resolving the Object.hasOwn TS2550 error. es2022.object is the minimal lib needed — it provides Object.hasOwn without pulling in unrelated ES2022 features.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

Reviewed changes — since the last approved review, this PR expanded to include Dict<string> type standardization across all packages and a substantial Nuxt runtimeEnv refactor.

• Standardized environment variable types to Dict<string> — replaced Record<string, string | undefined> and Record<string, unknown> with Dict<string> in core create-env.ts, parse-standard.ts, infer-type.ts, and all Next.js/Nuxt plugin files
• Removed runtimeEnv option from Nuxt createEnv — replaced with sourceEnv auto-detection from process.env and Nuxt's globalConfig; removed skipDestructureCheck validation; removed runtimeEnv from all three type-safety overloads (client.ts, server.ts, shared.ts)
• Removed String() and as string casts in Next.js createEnvInternal — runtimeEnv, extendedEnvValues, and combinedEnv are now typed as Dict<string>, making explicit string conversion redundant
• Removed runtimeEnv from Nuxt legacy detection — isLegacy now only checks for "client" or "shared" in the options, not runtimeEnv
• Widened stripEmptyStrings signature — from Record<string, string | undefined> to Record<string, unknown>
• Bumped size limit — from 2 kB to 2.1 kB in packages/arkenv/package.json

⚠️ Nuxt runtimeEnv removal is a breaking change with stale tests

The runtimeEnv option was removed from all three Nuxt type-safety overloads (client.ts, server.ts, shared.ts) and from the createEnvInternal implementation. Callers that were explicitly passing runtimeEnv to Nuxt's createEnv will get type errors and the provided runtimeEnv values are silently ignored (replaced by sourceEnv auto-detection).

The Nuxt test suite still references runtimeEnv in every test case (packages/nuxt/src/index.test.ts lines 10, 25, 43, 61, 82, 111, 159) — these tests are now stale and will fail because runtimeEnv` is no longer read from the options object.

The changeset (.changeset/fix-coercion-in-place-mutation.md) only covers the coercion fix — there is no changeset for this breaking change.

Technical details

# Nuxt `runtimeEnv` removal — breaking change and stale tests

## Affected sites
- `packages/nuxt/src/client.ts:24-26` — `runtimeEnv` removed from 1st overload signature
- `packages/nuxt/src/client.ts:37-38` — `runtimeEnv` removed from 2nd overload signature
- `packages/nuxt/src/client.ts:47` — `isLegacy` check no longer considers `runtimeEnv`
- `packages/nuxt/src/server.ts:23,35` — `runtimeEnv` removed from both overloads
- `packages/nuxt/src/shared.ts:22` — `runtimeEnv` removed from overload
- `packages/nuxt/src/create-env.ts:34-37` — `sourceEnv` auto-detection replaces `runtimeEnv`
- `packages/nuxt/src/create-env.ts:107-110` — extend loop reads from `sourceEnv` instead of `runtimeEnv`
- `packages/nuxt/src/create-env.ts:171-174` — final combinedEnv reads from `sourceEnv`
- `packages/nuxt/src/index.test.ts:10,25,43,61,82,111,159` — tests still pass `runtimeEnv`

## Required outcome
- Add a changeset documenting the `runtimeEnv` removal as a breaking change for `@arkenv/nuxt`
- Update the Nuxt test suite to use `sourceEnv`-compatible test data (e.g., mutate `process.env` before `createEnv` calls)
- Remove the stale `runtimeEnv` references from test cases

## Suggested approach
The Nuxt module already populates `nuxt.options.runtimeConfig`, so `sourceEnv` auto-detection is the correct direction. Tests should either:
1. Set `process.env` keys before calling `createEnv` to simulate `sourceEnv` detection, or
2. Restore a `runtimeEnv` override parameter for testing (lower priority than `sourceEnv`)

## Open questions for the human
- Is the removal of `runtimeEnv` from Nuxt intended to be a breaking change, or should it be restored as an override option?
- Should the Nuxt entry points expose a testing-only API for injecting runtime env values?

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

ℹ️ One minor nit — otherwise the changes cleanly address the prior review feedback.

Reviewed changes — since the last review, runtimeEnv was fully removed from the Nuxt adapter and tests were updated to use process.env / window.__NUXT__.

• Removed runtimeEnv from server.ts and shared.ts overloads — matching the earlier client.ts removal, all Nuxt entry points now omit runtimeEnv from their type signatures.
• Introduced server/client-aware sourceEnv — on the server, only process.env is consulted; on the client, window.__NUXT__.config.public takes priority with a process.env fallback.
• Removed skipDestructureCheck validation block — the runtime check that verified all client/shared keys were present in runtimeEnv is gone, since sourceEnv auto-detection replaces it.
• Updated Nuxt test suite — all tests now set process.env keys or mock window.__NUXT__ instead of passing runtimeEnv; removed the now-irrelevant "missing key in runtimeEnv" and "fallback to process.env" tests; added try/finally window restoration in client-side tests.

---

Note: 1 inline comment(s) dropped because they did not anchor to lines inside the PR diff:

• packages/nuxt/src/server.ts:42 (RIGHT) — line 42 (RIGHT) is not inside a diff hunk

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}