(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: c0a5415

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

This PR includes changesets to release 4 packages

Name	Type
arkenv	Minor
@arkenv/bun-plugin	Patch
@arkenv/nextjs	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 5 2026, 10:45 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/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/vite-plugin

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

commit: c0a5415

[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) ｜ 𝕏}