feat: arkenv example: update .env.example from the env schema

[yamcodes]

Fixes #1234

Summary

• Add arkenv example to load the project schema (same discovery and loader as check) and write merge-aware .env.example (preserve comments/values, drop stale keys, append new keys).
• Reuse that path from arkenv init after scaffolding an existing project.
• Public name is example with no sync alias, so sync/generate stay free for later commands. Help one-liner: Update .env.example from the schema.
• Document the command (including CI/pre-commit) and emit --json created/updated/unchanged envelopes.

Test plan

• pnpm run typecheck
• pnpm run test -- --run
• pnpm run fix
• Run arkenv example in a fixture with env.ts and no .env.example
• Re-run with no schema change (no diff)
• Add/remove a key and confirm merge behavior

[changeset-bot]

🦋 Changeset detected

Latest commit: f7d2413

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

This PR includes changesets to release 1 package

Name	Type
arkenv	Minor

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/yamcodes/arkenv/@arkenv/agent-plugin@1643

arkenv

npm i https://pkg.pr.new/yamcodes/arkenv@1643

@arkenv/build

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

@arkenv/bun-plugin

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

@arkenv/core

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

@arkenv/fumadocs-ui

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

@arkenv/nextjs

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

@arkenv/nuxt

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

@arkenv/standard

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

@arkenv/vite-plugin

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

commit: f7d2413

[pullfrog]

ℹ️ No critical issues — two minor suggestions inline.

Reviewed changes

• arkenv sync command: a new SyncUseCase that locates the schema (reusing the extracted resolveSchemaPath), imports it via the Jiti loader, and writes a merge-aware .env.example with created/updated/unchanged status and --json settlement envelopes.
• merge-env-example feature: a block parser that attaches comment/blank preludes to their key, preserves surviving keys/values/comments in file order, drops stale keys, and appends new keys in declaration order. Covered by a focused unit test suite.
• CLI wiring: syncInput in cli.ts, composition.ts injects SyncUseCase into InitUseCase, help/meta.json entries, bin.ts dispatch, and the flag-position handling for check/sync.
• check refactor: resolveSchemaPath moved into features/schema-loader/ and reused by check, removing a private duplicated method.
• Docs/changeset: new sync.mdx, reference index/meta.json cards, CONTEXT.md/ARCHITECTURE.md entries, and a minor changeset.

The merge algorithm is sound — blocks attach leading comments to their assignment, surviving keys stay in file order so the merge is idempotent, and deduplication keeps "already in sync" runs stable. The re-run test correctly pins that the second run writes nothing and reports unchanged.

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

[pullfrog]

✅ No new issues found.

Reviewed changes

• Trailing-newline idempotency fix: mergeEnvExample now derives trailingNewline from the existing file (content.endsWith("\n")) instead of forcing one for any non-empty output, so a matching .env.example without a final newline stays unchanged on the first sync. The new regression test pins this and genuinely fails on the old logic. The content === existing equality check keeps the merge idempotent.
• Dropped dead isYes: removed from SyncInput and syncInput — SyncUseCase.execute never consulted it, so a passed --yes was silently ignored.

Both findings from the prior review are addressed correctly. The delta introduces no new issues — the newline change is covered by a real regression test and holds for created/updated/unchanged paths.

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

[pullfrog]

Caution

This PR no longer builds. Commit ccae9c47 ("refactor: rename sync command files to example") renamed the source files but updated none of the references that point at them, leaving 5+ unresolved imports and the whole arkenv package uncompilable. CI is already red on this head (test-build, test, test-typesafety, e2e, pkg-pr-new, and the vite-compat matrix all fail).

Reviewed changes

• Renamed commands/sync.ts → commands/example.ts, features/sync/ → features/example/, and sync.mdx → example.mdx (pure rename — 0 insertions) without touching any of the identifiers, imports, CLI routing, help text, or docs that reference the old names.

🚨 Rename is half-applied — the package does not compile

The rename moved the files but left every reference pointing at the deleted paths, so module resolution breaks and commands no longer exports SyncUseCase:

• index.ts:5 — export * from "./sync" (no such file) → breaks composition.ts's import { SyncUseCase } from "./commands".
• cli.ts:10 — imports ./commands/sync; init.ts:14 — imports ./sync; example.ts:3 — imports @/features/sync/merge-env-example; example.test.ts:10 — imports @/cli/commands/sync. All point at deleted paths.
• Beyond imports, the CLI surface never changed: bin.ts:53 dispatches the key sync, cli.ts:155/315 routes sync/syncInput, example.ts still emits commandId: "sync" and a DOCS_URL pointing at /docs/reference/sync, and help/meta.json still say sync.
• Docs were left dangling: every reference card (check.mdx:168, index.mdx:33, init.mdx:142) points to /docs/reference/sync, which no longer exists after sync.mdx → example.mdx (would 404). example.mdx:2 still has frontmatter title: sync. The changeset .changeset/arkenv-sync.md, CONTEXT.md's Sync term, and ARCHITECTURE.md's sync/ feature note all still document sync.

Technical details

# Finish (or revert) the `sync` → `example` rename

## Affected sites
- packages/arkenv/src/cli/commands/index.ts:5 — `export * from "./sync"` is a dead import
- packages/arkenv/src/cli/commands/example.ts:3 — imports `@/features/sync/merge-env-example`, but the dir is now `features/example/`
- packages/arkenv/src/cli/commands/init.ts:14 — imports `SyncUseCase` from `./sync` (gone)
- packages/arkenv/src/cli/cli.ts:10,155,315 — import, command route, and `syncInput` getter persisted as `sync`
- packages/arkenv/src/cli/commands/example.test.ts:10 — test imports `@/cli/commands/sync`
- packages/arkenv/src/bin.ts:53 — dispatch key `sync`
- apps/www/content/docs/reference/example.mdx — `title: sync` frontmatter; body/`commandId: "sync"`
- apps/www/content/docs/reference/{check,index,init}.mdx and meta.json — Cards / `"sync"` entry / URLs
- .changeset/arkenv-sync.md; docs/CONTEXT.md ("Sync" term); docs/ARCHITECTURE.md (`sync/` tree entry)

## Required outcome
The branch must typecheck, build, and pass CI. The public command name must be consistent
across implementation and every surface, and match the design doc's chosen story
(`docs/design/cli-env-example-command-name.md` chose `arkenv example`) — or revert back to
`sync` if that's preferred. Either direction is valid; a mix is not.

## Suggested approach
Per the design-doc lean (`arkenv example`): complete the rename across all surfaces — fix the
five imports (and rename `SyncUseCase`/`SyncInput` or keep as internal names), route the CLI
key + positional validation from `sync` → `example`, update `commandId: "example"` and
`DOCS_URL` → `/docs/reference/example`, retitle `example.mdx`, delete the stale `sync` cards
and the `meta.json` entry, and rewrite the changeset. If the intent was instead to keep
`sync` public, the clean fix is to revert `ccae9c47` entirely.

## Open questions for the human
Is the public name `arkenv example` (per the design doc) or stay `sync`? Settle before merge.

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

[pullfrog]

✅ No new issues found.

Reviewed changes

• Rename sync → example completed across every surface: the half-applied ccae9c47 rename (which broke the build) is now finished — SyncUseCase/SyncInput became ExampleUseCase/ExampleInput, the CLI routes and dispatches example, positional validation accepts it, commandId is "example", DOCS_URL points at /docs/reference/example, and help output, meta.json, the changeset, ADR 0027, CONTEXT.md, and ARCHITECTURE.md all say example, with zero stale sync references left in source or docs.
• arkenv init plumbing updated: InitUseCase now holds an optional ExampleUseCase and reuses it to seed .env.example for existing projects; its warning copy instructs users to run arkenv example.
• Success-message reworded: .env.example already matches the schema replaces "is already in sync with the schema", with the corresponding JSON and text assertions updated to match.

Verified this run: pnpm exec turbo run typecheck --filter=arkenv passes (5 tasks), the full arkenv suite is green (461 tests / 27 files), and CI on this head is green across test, test-build, test-typesafety, e2e, pkg-pr-new, the vite-compat matrix, and autofix. The prior CRITICAL finding is fully addressed.

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