RFC: Pre-v1 Surface Area & Maintenance Prioritization

[yamcodes]

Following the decision to simplify our architecture by replacing the strict layout engine with a clean, documented two-module recipe (ADR 0020), we are reviewing the remaining API surface to ensure ArkEnv v1 is rock-solid, maintainable, and free of niche maintenance debt.

Here is a breakdown of candidate areas for pruning or simplification before tagging v1.0.0.

---

1. ✂️ CLI Code Mutation (arkenv preset apply / remove)

• Proposal: Remove programmatic AST/regex mutation of user schema files.
• Why: Modifying user TypeScript files across multiple validator dialects (ArkType, Zod, Valibot), formatters (Prettier, Biome), and comment styles is inherently brittle.
• Alternative: Support hosting presets (Vercel, Railway, Cloudflare, etc.) during initial arkenv init scaffolding, and provide clean copy-paste snippets in docs for existing projects.

---

2. ✂️ Custom Dotenv Formatting Linter in arkenv check

• Proposal: Prune the custom .env AST parser and style/formatting linter (ADR 0017).
• Why: Dedicated ecosystem tools (like dotenv-linter) already excel at checking whitespace, sorting, and duplicate keys in .env files.
• Alternative: Keep arkenv check laser-focused on its primary mandate: validating runtime environment variables against the declared schema.

---

3. 📦 Package Namespace Hygiene (@arkenv/fumadocs-ui & @arkenv/agent-plugin)

• @arkenv/fumadocs-ui:
  • ArkEnv is an environment variable validation library. Publishing and maintaining a documentation theme package on npm adds release noise.
  • Proposal: Move it to an internal workspace package (or inline into apps/www).
• @arkenv/agent-plugin (MCP Server / Coding Agent Tools):
  • Proposal: Decouple from core package release cycles to allow rapid iteration without affecting core v1 stability and semantic versioning.

---

4. 💬 The Bun Plugin (@arkenv/bun-plugin) — Keep or Recipe?

• Context: Bun already loads .env natively at boot into process.env and Bun.env. For standard backend servers and scripts, @arkenv/core and @arkenv/standard work with zero configuration and zero plugins.
• The Trade-off: The plugin is only required for fullstack Bun client-bundling (Bun.build with asset transformation).
• Question: Is maintaining dedicated Bun plugin lifecycle tests and mock harnesses worth it for v1, or should client bundling in Bun be documented as a recipe?

---

5. 🔋 Custom Scope Keywords in Core (string.host, number.port, etc.)

• Context: @arkenv/core provides domain-specific ArkType keywords out of the box.
• The Trade-off: While maintaining a custom ArkType scope requires staying in sync with upstream keyword mechanics, it provides instant "batteries-included" developer experience for common env-var types.
• Proposal: Keep domain-specific keywords intact for high-DX validation.

---

We'd love your thoughts:

• Which of these cuts make the most sense for a rock-solid v1?
• Are there other edge-case features in the CLI or integrations you think should be pruned?

[yamcodes]

📋 Outcomes & Tracking Issues

Following review and factoring in our independent versioning strategy with Changesets (ADR 0012), here is the finalized pre-v1 execution plan:

1. ✂️ Programmatic AST Mutation (arkenv preset apply/remove):

   • Decision: Remove AST/regex code mutation from the CLI to eliminate formatting/syntax edge-case debt. Keep hosting presets strictly in initial arkenv init scaffolding and copyable doc snippets.
   • Tracking Issue: refactor(cli): remove programmatic AST schema mutation in favor of init presets and doc snippets #1716

2. ✂️ Custom Dotenv Formatting Linter in arkenv check:

   • Decision: Prune the internal .env AST parser and formatting checks (superseding ADR 0017). Lock arkenv check strictly to runtime value validation against schemas.
   • Archived Spec: Converted issue arkenv lint #481 to Discussion RFC: (Dev-time .env file linter) #1710.
   • Tracking Issue: refactor(cli): narrow arkenv check and drop custom dotenv AST formatting parser #1717

3. 🛡️ Floating Packages (@arkenv/agent-plugin, @arkenv/fumadocs-ui, @arkenv/bun-plugin):

   • Decision: Retained in the monorepo. Because ArkEnv uses independent versioning via Changesets, strategic assets like the MCP @arkenv/agent-plugin and @arkenv/bun-plugin can float in their own release cycles without creating risk or version coupling for the core v1 milestone.

4. 🔋 Custom Scope Keywords (string.host, number.port):

   • Decision: Retained in @arkenv/core for high-DX, batteries-included env validation.