(v1) Unify error normalization and formatting

[yamcodes]

Fixes #709

Refactor the error system to use a normalized EnvIssue format, support sensitive credential masking/redaction with programmatic overrides, add a non-throwing safeCreateEnv API for RSC/Next.js integrations, and provide a stable base for CLI/IDE integrations.

[pullfrog]

Run failed. View the logs →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using Kimi K2 ｜ 𝕏}

[changeset-bot]

🦋 Changeset detected

Latest commit: df221c2

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

This PR includes changesets to release 5 packages

Name	Type
arkenv	Major
@arkenv/bun-plugin	Patch
@arkenv/nextjs	Patch
@arkenv/nuxt	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 21 2026, 11:51 PM (Asia/Almaty)

[pullfrog]

Run failed. View the logs →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using Kimi K2 ｜ 𝕏}

[pkg-pr-new]

Open in StackBlitz

arkenv

npm i https://pkg.pr.new/arkenv@1157

@arkenv/build

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

@arkenv/bun-plugin

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

@arkenv/cli

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

@arkenv/fumadocs-ui

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

@arkenv/nextjs

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

@arkenv/nuxt

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

@arkenv/vite-plugin

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

commit: c9532d0

[arkenv-bot]

📦 Bundle Size Report

Package	Size	Limit	Diff	Status
arkenv	2.17 kB	2.25 kB	+25.4%	✅
arkenv/standard	2.01 kB	2.05 kB	+99.0%	✅
arkenv/core	497 B	500 B	+12.7%	✅

✅ All size limits passed!

[pullfrog]

Reviewed changes — First review of this PR. Introduces EnvIssue type normalization across both ArkType and Standard Schema engines, safeCreateEnv non-throwing API, and sensitive-value redaction in error messages.

• Introduce EnvIssue type with code, expected, received, meta fields replacing the flat ValidationIssue type in core.ts; deprecate old type as alias.
• Add safeCreateEnv to both arkenv and arkenv/standard returning a SafeCreateEnvResult<T> discriminated union instead of throwing.
• Implement secret redaction via SENSITIVE_KEYWORDS regex patterns, shouldRedact(), safeStringify(), and debugSecrets config/ARKENV_DEBUG_SECRETS env var.
• Normalize Standard Schema errors in parse-standard.ts to resolve received values (JSON-parse + traversal), map engine-level codes to EnvIssueCode, and append styled (was …) values.
• Map ArkType error codes to EnvIssueCode in arkErrorsToIssues with proper expected/received extraction and redaction support.
• Update ArkEnvError to store issues publicly and accept debugSecrets options.
• Add formatIssues/formatError utilities with deprecated formatInternalErrors alias.
• Add changeset marking a minor version bump with breaking-change notice for error message format.
• Add/update tests in errors.test.ts and standard-mode.test.ts for redaction, safeCreateEnv, and error normalization.

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

[pullfrog]

Reviewed changes — incremental delta since the prior Pullfrog review. The 94f275f commit addresses both review threads: tightened sensitive-keyword regex patterns, added a public exclusion in shouldRedact, and removed the unused _options/options parameters across formatting functions and the ArkEnvError constructor.

• Tightened SENSITIVE_KEYWORDS regex patterns — broad patterns like /key/i, /pass/i, /auth/i are now anchored to (_|^)...(_|$) boundaries to avoid false positives on non-sensitive variable names (COMPASS, AUTHOR, etc.).
• Added public exclusion in shouldRedact — paths containing public (e.g. PUBLIC_KEY) are no longer redacted, even when they match a sensitive keyword pattern.
• Removed unused _options parameter from formatIssues, formatError, and the deprecated formatInternalErrors — the parameter was never wired through since redaction happens at issue-creation time.
• Removed unused options parameter from the ArkEnvError constructor, along with a duplicate formatIssues call in the constructor body.
• Cleaned up parse-standard.ts error construction — the config passthrough to ArkEnvError (which was ignored) has been removed.

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

[pullfrog]

Reviewed changes — incremental delta since the prior Pullfrog review. The 083837c commit extracts redaction utilities into a shared module and optimizes the Standard Schema error mapping to resolve size-limit failures.

• Extracted safeStringify / shouldRedact / SENSITIVE_PATTERN to src/utils/redact.ts — moved out of core.ts and arktype/index.ts into a shared utility module; consolidated 11 separate regex patterns into a single combined pattern.
• Optimized parse-standard.ts error mapping — extracted getProp helper for path traversal, deduplicated type-checks via msg variable, consolidated meta extraction with ?? nullish coalescing, and streamlined message-suffix construction.
• Bumped size-limit thresholds in package.json to 2.3 kB (arkenv) and 2.1 kB (arkenv/standard).

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

[pullfrog]

ℹ️ No critical issues — minor suggestions inline.

Reviewed changes — incremental delta since the prior Pullfrog review at 083837c. Renames create-env.ts → arkenv.ts and createEnv() → arkenv(), reorganizes imports from @/ aliases to relative paths, adds coerce/arrayFormat/emptyAsUndefined/debugSecrets config options to ParseStandardConfig, adds safeCreateEnv to the arkenv/standard entry point, exposes getSchemaKeys from the main index, and bumps size-limit thresholds.

• Renamed create-env.ts to arkenv.ts — file moved, function createEnv renamed to arkenv, safeCreateEnv moved alongside. Updated all internal callers, re-exports, and type references.
• Reorganized arktype/index.ts imports — replaced @/arkenv, @/coercion, @/core, @/utils/style-text alias imports with relative .ts paths. Removed .ts extensions from two imports in core.ts.
• Added coercion and redaction config to ParseStandardConfig — new coerce, arrayFormat, emptyAsUndefined, and debugSecrets options flow through the Standard Schema path alongside the existing ArkType path.
• Wired emptyAsUndefined coercion pipeline in parse-standard.ts — stripEmptyStrings applied to env before validation; extracted processedEnv variable used consistently in received-value traversal.
• Added safeCreateEnv to arkenv/standard entry — mirrors the non-throwing API from the main arkenv export.
• Exposed getSchemaKeys from the main index — new public utility for extracting keys from schema definitions in either ArkType or Standard Schema format.

ℹ️ Dead formatIssuePath function

formatIssuePath at packages/arkenv/src/parse-standard.ts:150 is defined but never called. The inline getProp helper + path construction replaced the call site at line 252, but the function wasn't removed. Since both implementations produce the same result, one is dead code.

Technical details

# Dead `formatIssuePath` function

## Affected sites
- `packages/arkenv/src/parse-standard.ts:150` — `formatIssuePath` function definition, no callers via grep

## Required outcome
- Remove the unused `formatIssuePath` function or replace the inline `getProp` + `${key}.${issue.path.map(getProp).join(".")}` pattern with a call to it.

ℹ️ Nitpicks

• packages/arkenv/src/arkenv.ts:39 — JSDoc still references createEnv (stale from the rename to arkenv).

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

[pullfrog]

✅ No new issues found.

Reviewed changes — delta since the prior Pullfrog review at 979c137. Replaces the standalone safeArkEnv function with a { safe: true } option on arkenv(), and changes SafeArkEnvResult from exposing the full error object to returning issues directly.

• Replaced safeArkEnv with { safe: true } option — added overload signatures distinguishing the safe (SafeArkEnvResult<T>) and throwing (T) return types in both arkenv.ts (6 overloads) and standard.ts (2 overloads). All call sites, tests, and documentation updated to arkenv(def, { safe: true }).
• Changed SafeArkEnvResult failure branch from { success: false; error: ArkEnvError } to { success: false; issues: readonly EnvIssue[] }. executeSafe now extracts error.issues directly.

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

[pullfrog]

✅ No new issues found.

Reviewed changes — 10 new commits since the prior Pullfrog review at f922185. Strips engine-specific metadata from EnvIssueMeta, removes the deprecated formatError() wrapper, expands error code maps with type-safe exhaustiveness, and hardens framework integrations against the safe: true option.

• Removed engine metadata from EnvIssueMeta — fields engine and engineCode stripped from the type, all call sites, and all test assertions. Justified by the new ADR 0010 on bundle isolation.
• Removed formatError() — the deprecated wrapper over formatIssues() is gone; all callers and tests updated. Changeset note updated accordingly.
• Expanded ARKTYPE_CODE_MAP — new codes minLength, unit, proto, domain, exactLength, before, after, predicate mapped; type-safe via satisfies Record<ArkError["code"], EnvIssueCode> with in operator guard in mapArkTypeCode.
• STANDARD_CODE_MAP now uses satisfies Record<string, EnvIssueCode> and in operator lookup, matching the ArkType pattern.
• Made buildEnvIssue's meta parameter optional — defaults to {}, consistent with the now-optional meta field on EnvIssue.
• Hardened framework integrations — all plugin configs (vite, bun, nextjs, nuxt) now type-restrict safe via Omit<ArkEnvConfig, "safe"> and explicitly pass safe: false at runtime.
• Added ADR 0010 — bundle isolation over DRYness, documenting why the two parsing engines remain split despite visual similarity.
• Added safe option docs — options.mdx documents the safe option with an integration caveat; quickstart.mdx updated with pattern.
• Updated changeset and skills — changeset text tightened (safeArkEnv API → { safe: true } API), formatError reference removed; changeset/SKILL.md added v1+ bump rules table.
• Vite test mocks — added as any on mockReturnValue calls to satisfy the richer return-type union.

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