refactor(cli): remove programmatic AST schema mutation in favor of init presets and doc snippets

[yamcodes]

Fixes #1716

Summary

• Deleted packages/arkenv/src/features/config-mutation/ containing programmatic AST / comment-marker mutation logic.
• Relocated framework bootstrap transformers (transformViteConfig, transformNextjsConfig, transformNuxtConfig) to adapters/node-workspace/utils/bootstrappers.ts and added unit tests in bootstrappers.test.ts.
• Removed arkenv preset command and its subcommand routing from bin.ts, cli.ts, and composition.ts.
• Updated CLI help messages and help tests.
• Preserved Day-1 hosting preset selection for arkenv init.
• Updated documentation: removed reference/preset.mdx, updated hosting-presets.mdx with copy-paste snippets for ArkType, Zod, and Valibot, and added permanent redirects in next.config.ts.
• Added changeset for arkenv.

[pullfrog]

Run failed. View the logs →

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

[changeset-bot]

🦋 Changeset detected

Latest commit: af71c26

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

This PR includes changesets to release 1 package

Name	Type
arkenv	Major

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

[pkg-pr-new]

Open in StackBlitz

@arkenv/agent-plugin

npm i https://pkg.pr.new/@arkenv/agent-plugin@1736

arkenv

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

@arkenv/build

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

@arkenv/bun-plugin

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

@arkenv/core

npm i https://pkg.pr.new/@arkenv/core@1736

@arkenv/fumadocs-ui

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

@arkenv/nextjs

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

@arkenv/nuxt

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

@arkenv/standard

npm i https://pkg.pr.new/@arkenv/standard@1736

@arkenv/vite-plugin

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

commit: af71c26

[yamcodes]

@pullfrog review please

[pullfrog]

Important

The CLI removal itself is clean and fully green, but several shipped surfaces still reference the removed arkenv preset command — the AI-agent guide, a Next-steps card on the check reference, and the installed arkenv skill. An agent following the guide will literally run a command that no longer exists. Details in the sections below.

Reviewed changes

• Removed the arkenv preset command end-to-end: bin.ts/cli.ts/composition.ts/help.ts routing, presetInput, --file flag, and the features/config-mutation AST + @arkenv-preset-start/end marker engine (with its ~1,000-line test suite).
• Relocated the three framework transformers (transformViteConfig, transformNextjsConfig, transformNuxtConfig) into adapters/node-workspace/utils/bootstrappers.ts byte-for-byte, backed by a new, slimmer bootstrappers.test.ts.
• Docs: deleted reference/preset.mdx, rewrote core-concepts/hosting-presets.mdx as per-validator copy-paste tabs, updated nav/index/cards, and added permanent redirects for /docs/reference/preset and /docs/reference/add-host.
• Added a major changeset for arkenv (command removal).

I verified the CLI package is green: built @repo/utils, @arkenv/core, @arkenv/standard, and the arkenv CLI, then ran the full packages/arkenv vitest suite — 397 tests pass, including the relocated bootstrappers.test.ts, the updated cli.test.ts (39) and help.test.ts, and the check/smoke suites. No behavioral diff between the deleted and relocated transformer implementations.

⚠️ Stale references to the removed preset surface remain

The PR swept preset out of index.mdx, init.mdx, meta.json, and preset.mdx, but four surfaces were missed:

• apps/www/content/docs/reference/check.mdx:204 — the "Next steps" Cards still render a preset card titled "Apply, refresh, or remove hosting provider presets." that hrefs /docs/reference/preset (now a 404 → redirect).
• apps/www/content/docs/guides/ai.mdx:109 — "Add the Vercel hosting preset with npx arkenv preset apply vercel --agent..." — this is the guide AI agents are pointed to, and the command is gone.
• skills/arkenv/SKILL.md:37-38,41-64,111-133 — the skill installed into user projects via npx skills add yamcodes/arkenv (and detected by NodeProjectScannerAdapter.hasSkill()) still documents preset apply/preset remove, --file, managed-block markers, and the .env.example sync rules for a command this PR deletes.
• apps/www/lib/normalize-package-manager-command.test.ts:126-130 — the presetPrompt fixture mirrors the ai.mdx text and will silently go stale with whatever replacement copy is chosen.

Technical details

# Remove stale `arkenv preset` references

## Affected sites
- apps/www/content/docs/reference/check.mdx:204 — `preset` Card href + description in Next steps
- apps/www/content/docs/guides/ai.mdx:109 — `npx arkenv preset apply vercel --agent` in the Hosting preset prompt
- skills/arkenv/SKILL.md:37-64, 111-133 — Managed Preset Blocks section + `preset apply`/`preset remove` command docs, `--file` option
- apps/www/lib/normalize-package-manager-command.test.ts:126-130 — fixture mirroring the ai.mdx prompt

## Required outcome
- No shipped docs/skill copy instructs the removed `preset` command. ai.mdx should route readers to the copy-paste snippets in `core-concepts/hosting-presets.mdx` (or `init --preset` for new projects); check.mdx's card should point there too; the skill should drop the preset-command and marker-management sections; the normalize fixture should track the replacement prompt text.

## Open questions for the human
- Does the installed skill ship verbatim from `skills/arkenv/SKILL.md`, or is there a build/copy step between repo and `npx skills add`?

ℹ️ init --preset still scaffolds marker blocks that nothing manages

arkenv init --preset vercel still emits // @arkenv-preset-start vercel / // @arkenv-preset-end vercel via assemble-simple.ts:59-60 and frameworks/layouts/codegen.ts:255-257, but this PR deletes the only tooling that ever acted on those markers and strips the "Why comment markers exist" doc section. Users scaffolding with a preset now get unexplained machine-owned-sounding comments in their env.ts, and anyone copy-pasting from the new hosting-presets snippets gets a schema without them — two shapes of the same feature. The markers are inert comments, so this is mergeable as-is; it's a design call only the author can make.

ℹ️ Nitpicks

• MutationInput.envImportPath is now accepted by all three transformers and used by none of them (Vite ignored it before too); it's a publicly exported field on the relocated module that reads as dead API.

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

[pullfrog]

Run failed. View the logs →

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

[yamcodes]

Addressed Code Review Feedback

1. Restored Transformer Test Coverage ():

   • Added behavior-pinning test cases covering 2-space and tab indentation preservation, absence of trailing newlines, callback form refusal, invalid syntax parse errors, and missing/non-object exports for Vite, Next.js, and Nuxt.
   • Added Next.js CommonJS refusal (), missing default export refusal, and inline regex deduplication tests.
   • Added Nuxt auto-creation of array and invalid array checks.

2. Cleaned Up Stale References to arkenv preset:

   • Updated Next steps Card in apps/www/content/docs/reference/check.mdx to point to /docs/core-concepts/hosting-presets.
   • Updated AI agent prompt snippet in apps/www/content/docs/guides/ai.mdx to use copy-paste hosting provider snippets instead of preset apply.
   • Updated test fixture in apps/www/lib/normalize-package-manager-command.test.ts.
   • Removed preset apply, preset remove, --file, and managed block documentation from skills/arkenv/SKILL.md.

3. Removed Dead Machine Marker Comments in init --preset:

   • Replaced inert // @arkenv-preset-start/end comments with clean human-readable comments (// [Provider] environment variables) in assemble-simple.ts and codegen.ts.
   • Removed dead marker utility functions (formatPresetStartMarker, formatPresetEndMarker, etc.) from presets.ts.

4. Cleaned Up Dead API Surface:

   • Removed unused envImportPath parameter from MutationInput in bootstrappers.ts.

[pullfrog]

✅ No new issues found in the incremental delta. All prior feedback is addressed — the stale preset references were swept from ai.mdx, the check reference card, SKILL.md, and the normalize fixture; the inert marker comments were removed from init --preset scaffold output; transformer test coverage was restored; and the dead MutationInput.envImportPath field was dropped. The delta's one real code change (an AST-level defineConfig callback guard) was verified against magicast's proxy shape and is double-covered by the retained legacy guard.

Reviewed changes

• Removed @arkenv-preset-start/end markers from init --preset scaffold output in assemble-simple.ts and frameworks/layouts/codegen.ts, and deleted the marker helper functions from scaffold/presets.ts, so scaffolding and the copy-paste docs produce the same marker-free schema shape.
• Rerouted the AI-agent hosting-preset prompt (guides/ai.mdx) and the check reference "Next steps" card to the copy-paste snippets in /docs/core-concepts/hosting-presets, replacing the removed npx arkenv preset apply vercel --agent instruction.
• Rewrote skills/arkenv/SKILL.md's hosting-preset guidance as code-first, removing preset apply/preset remove, the --file option, managed-block markers, and the .env.example sync rules for the deleted command.
• Replaced the preset apply fixture in normalize-package-manager-command.test.ts with an init --preset vercel prompt fixture (a command that still exists).
• Restored dropped transformer coverage in bootstrappers.test.ts (+175 lines): Vite space/tab indentation and trailing-newline preservation, defineConfig callback refusal, invalid-config and missing-default-export refusals, Next.js CommonJS refusal and inline-withArkEnv dedupe, plus Nuxt module-array creation and refusal paths.
• Added an AST-level callback guard in transformViteConfig (checks $ast.arguments[0].type for ArrowFunctionExpression/FunctionExpression) with the existing $args.$type guard retained as a fallback.

One mergeable leftover worth a follow-up: apps/www/content/docs/guides/migrating-to-v1.mdx:23 still lists the v1 arkenv CLI as "(init, preset)" in the package-mapping table — stale now that this PR removes preset (and #1733 already dropped example); the cell should read something like "(init, check)".

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