Update contributing guidelines, enhance CLI commands with new env options, and improve error handling in doctor/check commands. Bump package versions to 0.1.2 and add dotenv dependency.

Author: hasansmadix

.npmrc

@@ -0,0 +1,10 @@
+# Public registry (explicit; same as npm default).
+registry=https://registry.npmjs.org/
+
+# Do not add //registry.npmjs.org/:_authToken=... here — never commit tokens.
+# For local publish without OTP, use your user-level npmrc, for example:
+#   Windows: %USERPROFILE%\.npmrc
+#   macOS/Linux: ~/.npmrc
+# with a single line (Automation granular token from npmjs.com):
+#   //registry.npmjs.org/:_authToken=npm_yourTokenHere
+# See CONTRIBUTING.md

CONTRIBUTING.md

@@ -24,6 +24,15 @@ pnpm test
 3. Add or update tests when behavior or public API changes.
 4. Ensure `pnpm build` and `pnpm test` pass locally.
 
+### Pre-release check (maintainers)
+
+Before pushing a release or opening the version PR:
+
+1. `pnpm install`
+2. `pnpm build` (or `pnpm run build` from repo root)
+3. `pnpm test`
+4. From `packages/cli`, run `pnpm pack` and confirm `package/package.json` in the tarball lists a real semver for `@envra/core` (not `workspace:*`).
+
 ## Publishing (maintainers)
 
 We use [Changesets](https://github.com/changesets/changesets) for versioning and npm releases of `@envra/*`.
@@ -82,6 +91,37 @@ pnpm exec changeset publish
 
 Prefer the GitHub Action so versions and git tags stay aligned with changelogs.
 
+### Troubleshooting local `changeset publish`
+
+**`warn Received 404` for `npm info "@envra/..."`**
+
+Often normal: Changesets checks whether the **new** version (e.g. `0.1.1`) is already on the registry; until it is published, that can return 404. Your previous release (e.g. `0.1.0`) can still be live — verify with:
+
+```bash
+npm view @envra/core version
+```
+
+**`packages failed to publish` with no npm error**
+
+Changesets does not always print npm’s stderr. Run one package to see the real code:
+
+```bash
+pnpm build
+pnpm --filter @envra/core publish --access public --no-git-checks
+```
+
+**`npm error code EOTP` (most common after 0.1.0 works)**
+
+Your npm account uses **2FA for publishing**. Non-interactive `changeset publish` cannot prompt for an OTP.
+
+- **Quick:** publish with a fresh code from your authenticator:  
+  `pnpm --filter @envra/core publish --access public --no-git-checks --otp=123456`  
+  (repeat for other packages in order: core → cli, next, eslint-plugin — or use an Automation token below and run `pnpm exec changeset publish` once.)
+- **Better for repeated CLI publishes:** create an [**Automation**](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-granular-access-tokens-on-the-website) granular access token (publish-capable, no OTP), then `npm login` or set in user `.npmrc`:  
+  `//registry.npmjs.org/:_authToken=npm_yourTokenHere`
+
+GitHub Actions releases use **Trusted Publishing (OIDC)** and do not need this OTP when OIDC is configured on each package.
+
 ### Troubleshooting OIDC
 
 - `ENEEDAUTH`: workflow file name on npm must match `.github/workflows/release.yml` exactly; repo slug must match; use **GitHub-hosted** runners.

README.md

@@ -93,9 +93,17 @@ pnpm envra doctor -c ./env.config.ts
 
 Loads TypeScript configs via **jiti** (no separate compile step for the config file). Your app should depend on `@envra/core`; add `@envra/cli` as a dev dependency.
 
+Export `defineEnv` as `default` / `env`, or export field builders as `schema`, `environmentFields`, `envraSchema`, or `envFields`.
+
+**`check` / `doctor`** merge env in this order: start from `process.env`, then each `--env-file` (repeatable), then optional `--env-dir` loads `<dir>/.env` and `<dir>/.env.<node-env>`. Use `--env-preset nest` to default `--env-dir` to `env` (common Nest layout). `--node-env` overrides the segment for `.env.<name>` (default: `NODE_ENV` or `development`). **`--profile`** is the **schema** profile (requiredIn / onlyIn), not the file name.
+
+**`doctor --undeclared`**: `ignore-system` (default, skips noisy OS/npm/editor keys), `all`, or `loaded-only` (only keys that came from loaded files).
+
+**`--json`** on `check` / `doctor` prints machine-readable output for CI.
+
 | Command   | Use case                          |
 | --------- | --------------------------------- |
-| `check`   | CI / preflight — validate `process.env` |
+| `check`   | CI / preflight — validate merged env |
 | `sync`    | Regenerate `.env.example`         |
 | `docs`    | Regenerate `ENVIRONMENT.md`      |
 | `doctor`  | Undeclared vars, typos, deprecations, profile rules |
@@ -131,7 +139,7 @@ Treat this as directional; versions and features change over time.
 
 - **Node**: [examples/node-basic](examples/node-basic)
 - **Next.js App Router**: [examples/next-app-router](examples/next-app-router)
-- **NestJS**: [examples/nestjs](examples/nestjs) — `defineEnv` with `options.source` from `ConfigModule.validate`
+- **NestJS**: [examples/nestjs](examples/nestjs) — `defineEnv` with `unknownRecordToEnvSource(config)` in `ConfigModule.validate`
 
 ---
 
@@ -177,8 +185,6 @@ envra/
 
 - Optional Zod bridge package
 - More framework entrypoints
-- Explicit dotenv file as a source (alongside `process.env`)
-- Richer `doctor` policies
 
 ---
 

examples/nestjs/env.config.ts

@@ -1,4 +1,4 @@
-import { defineEnv, str, oneOf } from '@envra/core'
+import { defineEnv, str, unknownRecordToEnvSource, oneOf } from '@envra/core'
 
 /** Field builders only — use in ConfigModule.validate after merging env files */
 export const envraSchema = {
@@ -8,15 +8,12 @@ export const envraSchema = {
 
 /**
  * Nest `ConfigModule.forRoot({ validate })` receives a plain object.
- * Pass it as `source` to defineEnv:
+ * Use `unknownRecordToEnvSource` so numbers/objects are not coerced to `[object Object]`.
  */
 export function validateNestConfig(config: Record<string, unknown>) {
-  const flat: Record<string, string | undefined> = {}
-  for (const [k, v] of Object.entries(config))
-    flat[k] = v === undefined || v === null ? undefined : String(v)
-
+  const source = unknownRecordToEnvSource(config)
   return defineEnv(envraSchema, {
-    source: flat,
-    profile: flat.NODE_ENV ?? 'development',
+    source,
+    profile: source.NODE_ENV ?? 'development',
   }).values
 }

packages/cli/README.md

@@ -1,6 +1,6 @@
 # @envra/cli
 
-Command-line tools for [envra](https://github.com/hasansmadix/envra): validate `process.env`, generate `.env.example` and `ENVIRONMENT.md`, and run hygiene checks (`doctor`).
+Command-line tools for [envra](https://github.com/hasansmadix/envra): validate env, generate `.env.example` and `ENVIRONMENT.md`, and run hygiene checks (`doctor`).
 
 ## Install
 
@@ -21,7 +21,25 @@ pnpm envra docs   -c ./env.config.ts -o ENVIRONMENT.md
 pnpm envra doctor -c ./env.config.ts
 ```
 
-Export `defineEnv(...)` as `default` or `env`, or export `envraSchema` / `schema` as field builders so the CLI can read the schema.
+Export `defineEnv(...)` as `default` or `env`, or export field builders as `envraSchema`, `schema`, `environmentFields`, or `envFields`.
+
+## `check` and `doctor` — env loading
+
+- **`--env-file <path>`** — repeatable; each file is parsed with [dotenv](https://github.com/motdotla/dotenv) and merged (later overrides earlier). Starts from `process.env`.
+- **`--env-dir <dir>`** — after `--env-file`, loads `<dir>/.env` then `<dir>/.env.<node-env>` if they exist.
+- **`--node-env <name>`** — segment for `.env.<name>` (default: `NODE_ENV` or `development`).
+- **`--env-preset nest`** — sets default `--env-dir` to `env` (matches many Nest `ConfigModule` layouts).
+
+`--profile` / `-p` is the **schema** profile for envra rules (`requiredIn` / `onlyIn`), not the env file name.
+
+## `doctor`
+
+- **`--undeclared <policy>`** — `ignore-system` (default), `all`, or `loaded-only` (only warn on extra keys that appeared in loaded files).
+- **`--json`** — print structured JSON for CI.
+
+## Windows
+
+If `envra` fails when run via `node` on Windows, call the entry file directly, e.g. `node node_modules/@envra/cli/dist/cli.js check -c ./env.config.ts`.
 
 ## Documentation
 

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envra/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "CLI for envra: check, sync, docs, doctor",
   "keywords": [
     "env",
@@ -39,6 +39,7 @@
   "dependencies": {
     "@envra/core": "workspace:*",
     "commander": "^12.1.0",
+    "dotenv": "^17.2.3",
     "jiti": "^2.4.2"
   },
   "devDependencies": {

packages/cli/src/cli.ts

@@ -1,45 +1,103 @@
-import { Command } from 'commander'
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Command, Option } from 'commander'
+import type { DoctorUndeclaredPolicy } from '@envra/core'
 import { loadConfigModule } from './loaders/load-config'
 import { extractSchemaFromModule } from './loaders/extract-schema'
+import { mergeProcessEnvWithDotenvFiles } from './loaders/load-dotenv-merge'
 import { runCheck } from './commands/check'
 import { runSync } from './commands/sync'
 import { runDocs } from './commands/docs'
 import { runDoctorCmd } from './commands/doctor'
 import { env as processEnv } from 'node:process'
+import { cwd } from 'node:process'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8')) as { version: string }
 
 function resolveProfile(profile: string | undefined): string {
-  return (
-    profile ??
-    processEnv.NODE_ENV?.trim() ??
-    'development'
-  )
+  return profile ?? processEnv.NODE_ENV?.trim() ?? 'development'
 }
 
 function loadSchema(config: string) {
   const mod = loadConfigModule(config)
   const schema = extractSchemaFromModule(mod)
   if (!schema) {
     console.error(
-      'Could not find env schema. Export defineEnv() result as default or named `env`, or export `envraSchema` / `schema` as field builders.',
+      'Could not find env schema. Export defineEnv() result as default or named `env`, or export field builders as `envraSchema` / `schema` / `environmentFields` / `envFields`.',
     )
     process.exit(2)
   }
   return schema
 }
 
+function collectEnvFile(value: string, previous: string[]) {
+  return [...previous, value]
+}
+
+function buildMergedEnv(opts: {
+  envFile: string[]
+  envDir?: string
+  nodeEnv?: string
+  envPresetNest?: boolean
+}) {
+  return mergeProcessEnvWithDotenvFiles({
+    cwd: cwd(),
+    envFiles: opts.envFile,
+    envDir: opts.envDir,
+    nodeEnv: opts.nodeEnv,
+    nestPreset: opts.envPresetNest,
+  })
+}
+
+function envFileOption() {
+  return new Option('--env-file <path>', 'Load a .env file (repeatable; later overrides earlier)').argParser(
+    collectEnvFile,
+  )
+}
+
+function sharedEnvOptions(cmd: Command) {
+  return cmd
+    .addOption(envFileOption().default([]))
+    .addOption(new Option('--env-dir <dir>', 'Load <dir>/.env then <dir>/.env.<node-env>'))
+    .addOption(
+      new Option('--node-env <name>', 'Segment for .env.<name> (default: NODE_ENV or development)'),
+    )
+    .addOption(new Option('--env-preset <name>', 'Layout: nest → default --env-dir env').choices(['nest']))
+}
+
 const program = new Command()
-program.name('envra').description('envra — typed environment tooling').version('0.1.0')
+program.name('envra').description('envra — typed environment tooling').version(pkg.version)
 
-program
-  .command('check')
-  .description('Validate current process.env against schema')
-  .requiredOption('-c, --config <path>', 'Path to env config module (e.g. ./env.config.ts)')
-  .option('-p, --profile <name>', 'Profile (defaults to NODE_ENV or development)')
-  .action((opts: { config: string; profile?: string }) => {
+sharedEnvOptions(
+  program
+    .command('check')
+    .description('Validate merged env against schema')
+    .requiredOption('-c, --config <path>', 'Path to env config module (e.g. ./env.config.ts)')
+    .option('-p, --profile <name>', 'Schema profile (defaults to NODE_ENV or development)')
+    .option('--json', 'Print JSON result to stdout', false),
+).action(
+  (opts: {
+    config: string
+    profile?: string
+    envFile: string[]
+    envDir?: string
+    nodeEnv?: string
+    envPreset?: 'nest'
+    json: boolean
+  }) => {
     const schema = loadSchema(opts.config)
-    const code = runCheck(schema, resolveProfile(opts.profile))
+    const { env } = buildMergedEnv({
+      envFile: opts.envFile ?? [],
+      envDir: opts.envDir,
+      nodeEnv: opts.nodeEnv,
+      envPresetNest: opts.envPreset === 'nest',
+    })
+    const code = runCheck(schema, resolveProfile(opts.profile), env, opts.json)
     process.exit(code)
-  })
+  },
+)
 
 program
   .command('sync')
@@ -61,15 +119,44 @@ program
     runDocs(schema, opts.out)
   })
 
-program
-  .command('doctor')
-  .description('Hygiene: validation, undeclared vars, deprecations, typos')
-  .requiredOption('-c, --config <path>', 'Path to env config module')
-  .option('-p, --profile <name>', 'Profile (defaults to NODE_ENV or development)')
-  .action((opts: { config: string; profile?: string }) => {
+sharedEnvOptions(
+  program
+    .command('doctor')
+    .description('Hygiene: validation, undeclared vars, deprecations, typos')
+    .requiredOption('-c, --config <path>', 'Path to env config module')
+    .option('-p, --profile <name>', 'Schema profile (defaults to NODE_ENV or development)')
+    .addOption(
+      new Option('--undeclared <policy>', 'How to treat env keys outside the schema')
+        .choices(['all', 'ignore-system', 'loaded-only'])
+        .default('ignore-system'),
+    )
+    .option('--json', 'Print JSON result to stdout', false),
+).action(
+  (opts: {
+    config: string
+    profile?: string
+    undeclared: DoctorUndeclaredPolicy
+    envFile: string[]
+    envDir?: string
+    nodeEnv?: string
+    envPreset?: 'nest'
+    json: boolean
+  }) => {
     const schema = loadSchema(opts.config)
-    const code = runDoctorCmd(schema, resolveProfile(opts.profile))
+    const { env, loadedKeys } = buildMergedEnv({
+      envFile: opts.envFile ?? [],
+      envDir: opts.envDir,
+      nodeEnv: opts.nodeEnv,
+      envPresetNest: opts.envPreset === 'nest',
+    })
+    const code = runDoctorCmd(schema, resolveProfile(opts.profile), {
+      env,
+      undeclared: opts.undeclared,
+      loadedEnvKeys: opts.undeclared === 'loaded-only' ? loadedKeys : undefined,
+      json: opts.json,
+    })
     process.exit(code)
-  })
+  },
+)
 
 program.parse()

packages/cli/src/commands/check.ts

@@ -1,7 +1,6 @@
 import type { EnvSchema } from '@envra/core'
 import type { ValidationIssue } from '@envra/core'
 import { recordToEnvSource, validateSchema } from '@envra/core'
-import { env as processEnv } from 'node:process'
 
 function issuesByKey(issues: ValidationIssue[]): Map<string, ValidationIssue[]> {
   const m = new Map<string, ValidationIssue[]>()
@@ -13,12 +12,33 @@ function issuesByKey(issues: ValidationIssue[]): Map<string, ValidationIssue[]>
   return m
 }
 
-export function runCheck(schema: EnvSchema, profile: string): number {
-  const source = recordToEnvSource(processEnv as Record<string, string | undefined>)
+export function runCheck(
+  schema: EnvSchema,
+  profile: string,
+  env: Record<string, string | undefined>,
+  json: boolean,
+): number {
+  const source = recordToEnvSource(env)
   const { issues } = validateSchema(schema, source, profile)
   const byKey = issuesByKey(issues)
 
-  for (const key of Object.keys(schema)) {
+  const schemaKeys = Object.keys(schema)
+  if (json) {
+    const keyResults = schemaKeys.map((key) => {
+      const list = byKey.get(key) ?? []
+      return { key, ok: list.length === 0, issues: list }
+    })
+    const out = {
+      command: 'check' as const,
+      profile,
+      issueCount: issues.length,
+      keyResults,
+    }
+    console.log(JSON.stringify(out, null, 2))
+    return issues.length ? 1 : 0
+  }
+
+  for (const key of schemaKeys) {
     const list = byKey.get(key) ?? []
     if (list.length) {
       console.error(`✖ ${key}`)