fix(cli): generate .env and .env.example files during init

[yamcodes]

Closes #1280. Automatically generates .env and .env.example files at the project root during scaffold init if they don't already exist, preventing Node/tsx crash on boot.

[changeset-bot]

🦋 Changeset detected

Latest commit: 98e634f

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

This PR includes changesets to release 1 package

Name	Type
@arkenv/cli	Patch

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

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

@arkenv/build

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

@arkenv/bun-plugin

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

@arkenv/cli

npm i https://pkg.pr.new/@arkenv/cli@1281

@arkenv/fumadocs-ui

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

@arkenv/nextjs

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

@arkenv/nuxt

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

@arkenv/vite-plugin

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

commit: 81c7c0e

[arkenv-bot]

📦 Bundle Size Report

No results found

✅ All size limits passed!

[pullfrog]

Important

Copying the full contents of .env into .env.example in existing projects risks leaking secret values into a file that is commonly committed.

Reviewed changes — This PR makes arkenv init generate .env and .env.example so scaffolded projects boot without a missing-env crash.

• Mirror existing env files — InitUseCase.collectExistingProject() now reads any existing .env / .env.example and passes their contents into ProjectOptions.
• Add default env values — planner.ts adds per-example defaults for new projects and framework/keyed defaults for existing projects, then plans creation of missing env files.
• Add planner tests — planner.test.ts covers new-project defaults, key-derived existing-project defaults, and copying a single existing file to its missing counterpart.

⚠️ New-project env files can overwrite templates from the cloned example

In mode === "new", .env and .env.example are unconditionally added to plan.files. The executor clones the example first and then writes every planned file, so any .env / .env.example that ships inside the example repository will be overwritten. The current registry examples do not ship env files, so this is not a live bug, but it conflicts with the PR's stated intent of "generate if they don't already exist."

Technical details

# New-project env files can overwrite templates from the cloned example

## Affected sites
- `packages/cli/src/features/scaffold/planner.ts:199-224` — new-mode env files are always pushed to `plan.files`, independent of what the cloned example contains.

## Required outcome
- New-project scaffolding should not overwrite `.env` or `.env.example` files that already exist after the example is cloned.

## Suggested approach
- Either collect `existingFiles` from the cloned target directory before calling `createPlan`, or have the executor skip `plan.files` whose paths already exist when the action is `"create"`.

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

[yamcodes]

This was generated by AI.

Pullfrog Review Update:
All items in the Pullfrog review have been addressed:

1. New-project template overwriting: Fixed by updating the executor to check await this.workspace.exists(file.path) and skip writing if file.action === 'create' and the file already exists. Added test verification in executor.test.ts.

[pullfrog]

Important

The latest commit fixes the prior secret-leak concern but introduces regressions in planner.test.ts. The new-project template-overwrite concern from the previous review is unchanged.

Reviewed changes — The latest commit strips values when mirroring .env to .env.example and adds .gitignore checks for existing projects.

• Added stripValuesFromEnvContent in planner.ts to remove values from existing .env content before copying to .env.example, resolving the prior secret-leak concern.
• Added gitignore handling in planner.ts for existing projects—creating .gitignore when missing or appending .env / .env.local rules when absent.
• init.ts now reads the existing .gitignore and passes gitignoreContent into ProjectOptions.
• Added tests for value stripping, gitignore creation, gitignore append, and no-op when .env is already ignored.
• The new-project env-template overwrite concern flagged in the prior review remains unaddressed (no code changes in that path).

⚠️ Existing planner tests fail because of the new gitignore logic

defaultState includes .env and .env.example but not .gitignore. In existing-project mode this now causes a .gitignore file to be appended to the plan, so three existing assertions on plan.files.length fail. Add /test/.gitignore to defaultState.existingFiles (or update the affected length assertions) so the unrelated gitignore behavior is not asserted implicitly by every existing test.

Technical details

# Existing planner tests fail because of the new gitignore logic

## Affected sites
- `packages/cli/src/features/scaffold/planner.test.ts:21` — `defaultState.existingFiles` lacks `.gitignore`, causing unexpected plan entries in existing-project tests.
- `packages/cli/src/features/scaffold/planner.test.ts:27` — `creates a basic plan` expects 1 file but receives 2.
- `packages/cli/src/features/scaffold/planner.test.ts:308` — strict-layout test expects 3 files but receives 4.
- `packages/cli/src/features/scaffold/planner.test.ts:347` — rerun-overwrite test expects 3 files but receives 4.

## Required outcome
- Update the test fixture so existing tests do not fail due to unrelated gitignore behavior.

## Suggested approach
- Add `"/test/.gitignore"` to `defaultState.existingFiles`. Because no `gitignoreContent` is provided, the planner will see an existing `.gitignore` and take no action, keeping existing tests focused on env-schema behavior.
- Keep the new gitignore tests overriding `existingFiles` / `gitignoreContent` explicitly to exercise the feature.

ℹ️ Nitpicks

• The appended .gitignore rules only cover .env and .env.local. Other conventional env files (e.g. .env.development, .env.production) are not ignored and could be committed by mistake."

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

[pullfrog]

Important

The latest delta adds the executor-level overwrite guard and passes its tests. No new issues were introduced. The planner.test.ts regressions flagged in the prior review are still present.

Reviewed changes — The delta between 20bf1139 and 6998468d adds the executor-level skip for existing files and applies autofix formatting.

• Executor now skips action: "create" files that already exist, resolving the latent new-project template-overwrite concern.
• Added executor.test.ts coverage verifying that a planned create action is not written when the path is already present.
• Applied Biome formatting fixes across planner.ts and planner.test.ts.

ℹ️ Note on prior feedback

No new issues were introduced by these commits. The existing-test regression noted in the previous review (planner.test.ts length assertions failing because defaultState omits .gitignore) is unchanged and still needs a fix before this PR should land."

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

Important

The latest delta adds a correct changeset, but the previously flagged planner.test.ts regression is still unaddressed. Three existing planner tests fail because defaultState triggers .gitignore generation; the open review thread at planner.test.ts:21 still contains the fix.

Reviewed changes — The only change since the prior review is a new .changeset/generate-env-files.md describing the init env-file generation as a patch release.

• Added changeset for @arkenv/cli — accurately summarizes the .env / .env.example scaffolding, value stripping, .gitignore updates, and create-action skip behavior.

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes — The planner.test.ts fixture now mocks gitignore existence so existing tests stay focused on env-schema behavior.

• Fixed planner.test.ts regression — added /test/.gitignore to defaultState.existingFiles, so existing-project tests no longer implicitly assert .gitignore creation and the three previously failing length assertions pass.
• Merged latest dev into the feature branch.

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