feat(nuxt): core API & flat layout support

[yamcodes]

Summary

This is the foundation ticket for the Nuxt integration parity epic. Before we can generate code, validate at build time, or harden the strict-layout boundary, the @arkenv/nuxt module and runtime must understand the flat layout the same way @arkenv/nextjs does.

Current behavior

• ModuleOptions.layout only accepts "simple" | "strict". There is no "flat" option and no deprecation alias for "simple".
• The module imports extractKeys from @arkenv/build, which only understands the legacy nested server/client/shared blocks.
• A flat env.ts such as

  import arkenv from "./generated/env.gen";
  export const env = arkenv({
    DATABASE_URL: "string",
    NUXT_PUBLIC_API_URL: "string",
    NODE_ENV: "string",
    CUSTOM_SHARED: "string",
  }, {
    exposeToClient: ["CUSTOM_SHARED"],
  });

  is parsed incorrectly because the parser looks for nested blocks.
• The @arkenv/nuxt runtime entry point (src/index.ts) only exposes the nested createEnv({ server, client, shared }) signature. It does not support createEnv(schema, options).
• createEnvInternal in Nuxt does not categorize flat keys by NUXT_PUBLIC_ prefix or by exposeToClient, so a flat schema would misclassify public/shared variables on the client.

Desired behavior

1. Add "flat" to ModuleOptions.layout and make it the default when a single env.ts file is detected.
2. Treat "simple" as a deprecated alias for "flat" and emit a one-time warning in development.
3. Implement flat key extraction in the module, honoring:
   • NUXT_PUBLIC_* keys as client keys.
   • NODE_ENV as implicitly shared.
   • exposeToClient (and deprecated expose/shared arrays) as shared keys.
   • Everything else as server keys.
4. Update the @arkenv/nuxt runtime createEnv signature to accept createEnv(schema, options) in addition to the legacy nested signature.
5. Update createEnvInternal to split a flat schema into server/client/shared buckets using the same rules as the parser.

Acceptance criteria

• ModuleOptions.layout supports "flat" and auto-detects it as the default for a single env.ts file.
• "simple" is accepted but logs a one-time deprecation warning in development.
• The module correctly extracts clientKeys, sharedKeys, and serverKeys from a flat env.ts that uses NUXT_PUBLIC_*, NODE_ENV, and exposeToClient.
• @arkenv/nuxt exports a flat createEnv(schema, options) overload with correct type inference.
• createEnvInternal categorizes flat schema keys into server/client/shared buckets using NUXT_PUBLIC_, NODE_ENV, and exposeToClient.
• Existing Nuxt runtime tests still pass and new tests are added for flat key extraction and flat runtime categorization.

Out of scope

• Build-time validation and env.gen.ts codegen (handled in the next ticket).
• The Vite plugin boundary patch (handled in the final ticket).
• Updating the with-nuxt example to use the flat layout (can be done here if convenient, but not required).

References

• Tracking epic: Tracking: Nuxt Integration Parity #1241
• ADR-0010 — Flat layout codegen and type inference strategy
• @arkenv/nextjs/src/config.ts — reference implementation for flat key extraction
• @arkenv/nextjs/src/create-env.ts — reference implementation for flat schema categorization

[pullfrog]

This run croaked 😵

The workflow encountered an error before any progress could be reported. Please check the link below for details.

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

[yamcodes]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Add flat layout support to @arkenv/nuxt, including module-level detection, key extraction, and runtime API overloads.

Current behavior:
The Nuxt module only understands the legacy nested layout (server/client/shared blocks). Its ModuleOptions.layout type is "simple" | "strict", its parser imports the nested extractKeys helper from @arkenv/build, and the runtime createEnv exported from @arkenv/nuxt only accepts the nested options object. A flat env.ts using arkenv(schema, { exposeToClient }) is therefore mis-parsed and mis-categorized.

Desired behavior:

• ModuleOptions.layout should accept "flat" and default to it for a single env.ts file.
• "simple" should remain valid but log a one-time deprecation warning in development.
• The module should extract client/shared/server keys from a flat schema using the same rules as @arkenv/nextjs: NUXT_PUBLIC_* → client, NODE_ENV → shared, exposeToClient/expose/shared arrays → shared, everything else → server.
• The @arkenv/nuxt runtime should expose a createEnv(schema, options) overload in addition to the legacy nested signature.
• createEnvInternal should split a flat schema into server/client/shared buckets using those same rules before validation and proxy creation.

Key interfaces:

• ModuleOptions.layout — extend to "flat" | "strict" with "simple" deprecated.
• Schema key extraction helpers — introduce flat-aware extraction (reuse patterns from @arkenv/nextjs/src/config.ts) instead of relying solely on the nested @arkenv/build extractKeys.
• createEnv overloads in @arkenv/nuxt — add a flat signature mirroring @arkenv/nextjs/src/index.ts.
• createEnvInternal flat branch — categorize keys by prefix and exposeToClient before building the validation schema.

Acceptance criteria:

• ModuleOptions.layout supports "flat" and auto-detects it as the default for a single env.ts file.
• "simple" is accepted but logs a one-time deprecation warning in development.
• The module correctly extracts clientKeys, sharedKeys, and serverKeys from a flat env.ts that uses NUXT_PUBLIC_*, NODE_ENV, and exposeToClient.
• @arkenv/nuxt exports a flat createEnv(schema, options) overload with correct type inference.
• createEnvInternal categorizes flat schema keys into server/client/shared buckets using NUXT_PUBLIC_, NODE_ENV, and exposeToClient.
• Existing Nuxt runtime tests still pass and new tests are added for flat key extraction and flat runtime categorization.

Out of scope:

• Build-time validation and env.gen.ts codegen.
• Vite plugin boundary patch for userland env/server.ts imports.