(v1) CLI managed preset blocks (`preset apply` / `remove`, markers, `--preset`)

[yamcodes]

Problem

Hosting preset keys are mixed into generated/mutated schemas with no clear ownership boundary. Re-applying or updating a preset is ambiguous, and Day-2 mutation (add host) does not share the same safety model as bootstrap (init). Naming is still host-specific (--host-preset, add host) even though the product direction is a generic preset surface (see #1447 — decided here).

Decision summary (resolves #1447)

Generalize the CLI surface to presets now; keep the v1 catalog hosts-only (vercel, netlify). Non-host packs (Supabase, Sentry, etc.) are follow-ups once this plumbing ships.

Surface	Canonical	Notes
Bootstrap flag	init --preset <id>	Replace/alias --host-preset / -H
Apply / refresh	arkenv preset apply <provider>	Idempotent; nuke-and-pave owned blocks
Remove	arkenv preset remove <provider>	Deletes owned blocks + related .env.example keys when safe
Legacy	arkenv add host	Deprecated alias → preset apply

init bootstraps an ArkEnv project (and may seed managed preset blocks + persist schema entry). Day-2 preset lifecycle does not ride init.

Desired behavior

Managed blocks

Preset-owned schema text is delimited by comments:

// @arkenv-preset-start vercel
// ...
// @arkenv-preset-end vercel

• Flat layout: one block per preset id (vercel).
• Strict layout: role-suffixed blocks as needed, e.g. vercel:server, vercel:client. User runs preset apply vercel / remove vercel; the CLI manages all blocks for that base id.
• Refresh: nuke-and-pave everything between matching markers.
• Composability: multiple presets may stack (one owned region set each) as long as keys do not collide.

Ownership & collisions (fail closed)

• Outside markers = user-owned. Sacred.
• If preset apply needs a key that already exists outside this preset’s blocks → fail with a clear resolution message (no silent skip, no AST “definition match”, no steal).
• Cross-preset key collision → fail the same way.
• Legacy unmarked keys (from older init / add host): also fail closed. User deletes unmarked keys, then re-runs apply. No heuristic adoption.

.env / .env.example

• Append missing keys to .env.example only if that file already exists.
• Never write .env (secrets). Future --write-env is out of scope.
• On remove: strip keys that preset owned from .env.example when ownership is clear; if cross-preset sharing of an example key is unclear, leave a stale empty key rather than risk breaking another preset.

Discovery

• init persists an arkenv schema entry/root (including layout strategy) on the nearest package.json — not merely a single file path (must support flat and strict).
• preset apply / remove read that pointer for zero-config Day 2.
• Override with -f / --file (or equivalent schema path flag).
• No path heuristics as the primary strategy for v1.

Git safety

• Require a clean git working tree by default for preset apply / preset remove (and any writes they perform).
• Bypass with --force.
• Not a git repo → proceed. Unknown status → warn and proceed.

Malformed markers

• If start/end markers are missing, unbalanced, or otherwise malformed → fail closed (especially on remove). Do not delete past an unmatched start marker.

Scope boundaries

• preset apply / preset remove do not touch .gitignore or provider-specific dotfiles (.vercel, .netlify, …). Baseline .env ignores remain init-only.
• v1 catalog: vercel, netlify only (plus any already-approved host ids if already in tree). No new SaaS/observability packs in this issue.
• Does not require inventing a semantic validator AST differ across Zod / Valibot / ArkType.
• preset remove does not remove the package.json arkenv workspace pointer.

Acceptance criteria

• arkenv preset apply <provider> inserts or refreshes managed comment blocks for the provider (nuke-and-pave inside markers).
• arkenv preset remove <provider> removes all blocks for that base id (including :server / :client suffixes) and updates .env.example per the rules above.
• init --preset <id> seeds managed blocks and writes the package.json arkenv schema entry/root; --host-preset / -H remain as aliases or are clearly deprecated toward --preset.
• arkenv add host remains as a deprecated alias of preset apply (or documented migration) without a second divergent code path long-term.
• Multiple presets can coexist; key collisions (user-owned or cross-preset) fail closed with actionable errors.
• Legacy unmarked colliding keys fail closed (no auto-adopt).
• .env.example: append missing keys only if file exists; never touch .env.
• Discovery uses package.json arkenv entry; -f overrides; no heuristics-first discovery.
• Dirty git tree aborts apply/remove unless --force; non-repo OK; unknown warns.
• Malformed/unbalanced markers → fail closed on remove (and apply when relevant).
• Strict layout uses role-suffixed markers; flat uses unsuffixed id.
• Docs updated for hosting presets / CLI: new commands, markers, collisions, git gate, scope vs init.
• ArkEnv agent skill updated: document preset apply / preset remove, fail-closed collisions, and legacy unmarked→marked migration guidance. Skill reasons and prepares; CLI remains the authority for owned-region mutation (do not teach agents to bypass fail-closed apply).
• Tests cover apply, refresh, remove, collisions, legacy unmarked failure, git gate, strict vs flat markers, .env.example append-only.
• (v1) Generalize CLI --host-preset to --preset #1447 closed as decided by this issue.

Agent skill boundary

Judgment-heavy work (especially migrating legacy unmarked preset keys to managed blocks, and collision triage) may be guided by the ArkEnv agent skill. The skill interprets CLI refusals and proposes safe next steps; it must not become a soft auto-adopt path that rewrites user-owned unmarked keys. Deterministic apply/remove/git gates stay in the CLI.

Out of scope

• Non-host preset catalogs (Supabase, Sentry, Stripe, …)
• Writing .env / --write-env
• .gitignore mutation from apply/remove
• Heuristic adoption of unmarked legacy keys
• Comment-preserving AST merge inside managed blocks
• Forcing users from strict → flat layout

Related

• Closes the naming decision in (v1) Generalize CLI --host-preset to --preset #1447
• Builds on hosting presets epic Presets for popular hosting providers #610 / ADR 0014
• Phase 4 additional hosts (Add hosting presets for Cloudflare, Railway, Render, and Fly.io (Phase 4) #1269) remain independent catalog expansion

[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: Ship machine-owned preset comment blocks with a generic preset apply / preset remove CLI, init --preset, package.json schema entry discovery, and fail-closed ownership — hosts-only catalog for v1.

Current behavior:

• Hosting preset keys from init / add host are interleaved into schemas with no begin/end ownership markers.
• Day-2 mutation is named add host and does not share a full apply/refresh/remove lifecycle.
• Bootstrap naming is host-specific (--host-preset / -H).
• Dirty-tree gating exists for bootstrap-style flows but is not part of a coherent preset mutation contract tied to managed blocks.

Desired behavior:

• Preset-owned regions use stable comment markers: @arkenv-preset-start <id> / @arkenv-preset-end <id>.
• Flat layout: one block per preset id. Strict layout: role suffixes (<id>:server, <id>:client) as needed; user-facing commands take the base id and manage all matching blocks.
• arkenv preset apply <provider> inserts or refreshes (nuke-and-pave inside markers). Multiple presets may stack.
• Collisions with user-owned keys (outside markers), cross-preset keys, or legacy unmarked keys: fail closed with actionable errors — no silent skip, no AST equality absorb, no heuristic adoption.
• .env.example: append missing keys only if the file already exists; never write .env.
• Discovery: init writes an arkenv schema entry/root (layout-aware) on nearest package.json; apply/remove read it; -f overrides. No heuristics-first discovery.
• arkenv preset remove <provider> deletes all blocks for that base id; strips .env.example keys when ownership is clear; prefer leaving a stale example key over breaking another preset; refuse on malformed/unbalanced markers; do not remove the package.json arkenv pointer.
• Clean git tree required by default for apply/remove; --force bypass; not-a-repo OK; unknown status warn+proceed.
• Canonical naming: init --preset; deprecate/alias --host-preset and add host toward the preset commands.
• v1 provider catalog: existing hosts only (vercel, netlify). Apply/remove must not touch .gitignore or provider dotfiles.

Key interfaces:

• CLI commands: preset apply, preset remove; bootstrap flag --preset (with host-preset aliases as needed)
• Marker contract: @arkenv-preset-start / @arkenv-preset-end with optional role suffix after :
• package.json arkenv field: schema entry/root + enough layout metadata for flat vs strict injection
• Preset catalog remains hosting-provider ids for this issue; IR should not assume “host” is the only future kind
• .env.example append/strip helpers that never open .env by default
• Git working-tree gate shared by apply/remove (force bypass)

Acceptance criteria:

• preset apply inserts/refreshes managed blocks (nuke-and-pave); preset remove tears them down safely
• Strict role-suffixed markers and flat unsuffixed markers both work; base-id commands cover all roles
• Fail closed on user-owned, cross-preset, and legacy unmarked collisions
• .env.example append-missing-only-if-exists; never touch .env; remove prefers stale key over unsafe strip
• package.json arkenv schema entry written by init; read by apply/remove; -f override
• Dirty git aborts unless --force; non-repo OK
• Malformed markers fail closed on remove
• init --preset + deprecated aliases for old host naming; docs + tests updated
• Catalog limited to existing hosts; no .gitignore mutation from apply/remove
• (v1) Generalize CLI --host-preset to --preset #1447 closed as decided here

Out of scope:

• Non-host preset packs (Supabase, Sentry, Stripe, …)
• --write-env / writing .env
• .gitignore or provider dotfile management from apply/remove
• Heuristic adoption of unmarked legacy keys
• Comment-preserving merges inside managed blocks
• Forcing strict → flat migration

[yamcodes]

This was generated by AI during triage.

Agent Brief amendment

Add to acceptance criteria / skill surface:

• Update the ArkEnv agent skill with preset apply / preset remove, fail-closed collision behavior, and legacy unmarked→marked migration guidance.
• Skill owns judgment (inspect custom validators, propose migration steps, triage collisions, interpret refusal JSON).
• CLI remains the authority for mutating owned regions — agents must re-invoke preset apply / remove after preparation, not bypass fail-closed rules by hand-editing unmarked keys into “adopted” blocks.

[yamcodes]

@abhimanyutiwaribot This is a task similar to what you worked on for v0, but with an updated strategy for v1.

Is this something you might be interested in working on?

Requires understanding the new v1 alpha (not too different from v0 but has key changes like renaming @arkenv/cli to arkenv, and some structural changes).