@nifrajs/cli 2.14.1 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/cli",
-  "version": "2.14.1",
+  "version": "3.1.0",
   "description": "The nifra CLI - zero-config dev/build/start for a nifra app (`nifra dev`, `nifra build`, `nifra start`).",
   "keywords": [
     "bun",
@@ -66,14 +66,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/client": "2.14.1",
-    "@nifrajs/core": "2.14.1",
-    "@nifrajs/mcp": "2.14.1",
-    "@nifrajs/runner": "2.14.1",
-    "@nifrajs/schema": "2.14.1",
-    "@nifrajs/testing": "2.14.1",
-    "@nifrajs/web": "2.14.1",
-    "create-nifra": "2.14.1"
+    "@nifrajs/client": "3.1.0",
+    "@nifrajs/core": "3.1.0",
+    "@nifrajs/mcp": "3.1.0",
+    "@nifrajs/runner": "3.1.0",
+    "@nifrajs/schema": "3.1.0",
+    "@nifrajs/testing": "3.1.0",
+    "@nifrajs/web": "3.1.0",
+    "create-nifra": "3.1.0"
   },
   "repository": {
     "type": "git",

package/src/check.ts

@@ -2585,7 +2585,7 @@ export async function collectCheckResult(
       diagnostics.push({
         rule: "duplicate-install",
         severity: "error",
-        message: `${finding.package} identity preflight found ${finding.cause} (${copies}) - ${finding.explanation}`,
+        message: `${finding.package} identity preflight found ${finding.cause} (${copies}) - ${finding.explanation}${finding.topology === undefined ? "" : `. Topology: ${finding.topology}`}${finding.scope === undefined ? "" : `. Scope: ${finding.scope}`}`,
         fix: finding.remediation,
         suggestion: {
           kind: "manual",
@@ -2593,29 +2593,50 @@ export async function collectCheckResult(
           steps: [
             "Align workspace dependency and peer ranges on one compatible version.",
             "Remove stale nested installs and run the package manager from the workspace root.",
-            "Run `nifra doctor` again; do not suppress same-version duplicate paths.",
+            'If the copies come from a linked sibling repository and collapsing them is not an option, declare the package: "nifra": { "singleCopy": ["<package>"] } in package.json, plus the bunfig.toml preload.',
+            "Run `nifra doctor` again; do not suppress an undeclared same-version duplicate path.",
           ],
         },
       })
     }
+    // Declared single-copy: the resolver collapses these before anything loads, so the build is sound
+    // and the gate stays green. It is still worth a line - the guarantee lives in a declaration now,
+    // and a reader who deletes it gets a null hook dispatcher with no obvious cause.
+    for (const finding of dr.deduplicatedInstalls ?? []) {
+      const copies = finding.copies.map((copy) => copy.path).join("; ")
+      diagnostics.push({
+        rule: "duplicate-install",
+        severity: "warning",
+        message: `${finding.package} is installed at ${finding.copies.length} paths (${copies}) and is declared single-copy - nifra resolves every duplicate to this app's copy`,
+        fix: finding.remediation,
+      })
+    }
     // Advisory (never fails the gate): while actively editing a linked package its dist is always
     // momentarily behind. The finding earns its keep when a dev server is about to start against it -
     // Bun reads live `src` while Vite's SSR runner reads the artifact, so a stale one 500s inside
     // framework/shared-package code and reads exactly like an upstream regression.
     for (const f of dr.staleDists) {
+      // The rebuild is only actionable with the LOCATION: a workspace link routinely points into a
+      // sibling repo, so "rebuild @nifrajs/core" left the developer to go find the checkout and guess
+      // the script. Name the directory and the package's own script, or say plainly that it declares
+      // none - never suggest a command that would fail.
+      const rebuild =
+        f.buildScript === undefined
+          ? `${f.packageDir} declares no build script - build it the way that package expects`
+          : `cd ${f.packageDir} && bun run ${f.buildScript}   (or \`nifra fix --code NF-C010\`)`
       diagnostics.push({
         rule: "stale-workspace-dist",
         severity: "warning",
         message: f.missing
-          ? `${f.package} was never built - ${f.distFile} is missing, but its export map serves it to Vite SSR/node consumers while Bun reads src - rebuild ${f.package}`
-          : `${f.package} has a stale build artifact - ${f.distFile} is ${f.behindSeconds}s older than ${f.sourceFile}, and Vite SSR/node consumers read the artifact while Bun reads src - rebuild ${f.package}`,
-        fix: `rebuild ${f.package}`,
-        evidence: [f.package, f.distFile, f.sourceFile],
+          ? `${f.package} was never built - ${f.distFile} is missing, but its export map serves it to Vite SSR/node consumers while Bun reads src - ${rebuild}`
+          : `${f.package} has a stale build artifact - ${f.distFile} is ${f.behindSeconds}s older than ${f.sourceFile}, and Vite SSR/node consumers read the artifact while Bun reads src - ${rebuild}`,
+        fix: rebuild,
+        evidence: [f.package, f.distFile, f.sourceFile, f.packageDir],
         suggestion: {
           kind: "manual",
           title: `Rebuild ${f.package}`,
           steps: [
-            `Run the package's build (usually \`bun run build\` in its directory) so ${f.distFile} matches its source again.`,
+            rebuild,
             "Only workspace-linked installs drift; npm tarballs are immutable and never flagged.",
           ],
         },

package/src/cli.ts

@@ -21,6 +21,7 @@ import {
 import { discoverRoutes } from "@nifrajs/web/fs"
 import type { BunPlugin } from "bun"
 import { bindCommandArgv, findCommandSpec, renderCommandCatalogHelp } from "./command-catalog.ts"
+import { applyEnvFiles, takeEnvFileFlags } from "./env-file.ts"
 import { type LoadedApp, loadApp, type NifraFramework } from "./load.ts"
 import { chooseBuildPipeline, describePipeline } from "./pipeline-guard.ts"
 
@@ -188,10 +189,16 @@ routes/ from the current directory. Run from your project root.
 Port: \`dev\` and \`start\` share the default ${DEFAULT_DEV_PORT}. Override with \`--port <n>\` (alias \`-p\`) or the
 \`PORT\` env var (\`--port\` wins over \`PORT\`, which wins over the default).
 
+Env: \`--env-file <path>\` works on EVERY command and may be repeated (later files win). Commands that
+reflect your app import it, so an app that validates its environment at module scope needs that
+environment present - without it the app aborts before nifra runs a single check. A variable already
+set in the process environment is never overwritten by a file.
+  e.g. \`nifra check --env-file .env.local\`
+
 ${renderCommandCatalogHelp()}`
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "2.14.1"
+const CLI_VERSION = "3.1.0"
 
 // A render adapter + nifra server are opaque to the CLI (it just forwards them); cast at the seam.
 const asAdapter = (v: unknown): RenderAdapter => v as RenderAdapter
@@ -661,8 +668,34 @@ export function assureBundleRequested(argv: readonly string[]): boolean {
   )
 }
 
+/**
+ * A command that reflects the project imports it, and an app that validates its environment at module
+ * scope calls `process.exit` from inside that import. Nothing is throwable at that point, so the whole
+ * output is the app's own abort message with no hint that a nifra command triggered it. Name the cause
+ * on the way out and point at the flag that supplies the environment.
+ */
+function installReflectionExitHint(): (command: string | undefined) => void {
+  let inFlight: string | undefined
+  process.on("exit", (code) => {
+    if (inFlight === undefined || code === 0) return
+    process.stderr.write(
+      `\n[nifra] \`nifra ${inFlight}\` reflects this project by importing it, and the import exited ` +
+        `with code ${code} before the command produced a result - the message above came from your app, not nifra.\n` +
+        `        If it is the app's environment validation, supply the environment and re-run:\n` +
+        `        nifra ${inFlight} --env-file .env.local\n`,
+    )
+  })
+  return (command) => {
+    inFlight = command
+  }
+}
+
 async function main(): Promise<void> {
-  const argv = Bun.argv.slice(2)
+  const { argv: rawArgv, files: envFiles } = takeEnvFileFlags(Bun.argv.slice(2))
+  // Applied before any command runs: a reflecting command imports the app on its first await, and the
+  // app reads its environment at module scope, so the variables must already be in place by then.
+  if (envFiles.length > 0) await applyEnvFiles(process.cwd(), envFiles)
+  const argv = rawArgv
   const command = argv[0]
   if (command === undefined || command === "--help" || command === "-h" || command === "help") {
     console.log(HELP)
@@ -709,9 +742,12 @@ async function main(): Promise<void> {
   }
   const catalogSpec = command === undefined ? undefined : findCommandSpec(command)
   if (catalogSpec?.transports.includes("cli")) {
+    const markReflecting = installReflectionExitHint()
     try {
       const input = bindCommandArgv(catalogSpec, argv.slice(1))
+      markReflecting(command)
       const output = await catalogSpec.run(input, { cwd: process.cwd(), cliVersion: CLI_VERSION })
+      markReflecting(undefined)
       const asRecord = output as unknown as Record<string, unknown>
       const wantsJson = asRecord.json === true || argv.includes("--json")
       if (wantsJson) {
@@ -723,6 +759,9 @@ async function main(): Promise<void> {
       if (catalogSpec.success !== undefined && !catalogSpec.success(output, input))
         process.exitCode = 1
     } catch (err) {
+      // A thrown error is nifra's own reporting path, not a silent abort: clear the sentinel so the
+      // hint stays reserved for the case where the process died inside the app import.
+      markReflecting(undefined)
       console.error(formatCliError(err))
       process.exitCode = 1
     }

package/src/command-catalog.ts

@@ -376,6 +376,9 @@ interface ContextCommandOutput {
 interface FixCommandOutput {
   readonly ok: boolean
   readonly changed: readonly string[]
+  /** Recipes that refused, with the reason. A recipe that cannot act says so here instead of
+   * aborting the run or - worse - reporting nothing at all. */
+  readonly failed: readonly { readonly code: string; readonly reason: string }[]
   readonly diagnostics: readonly unknown[]
 }
 interface SnapshotCommandOutput {
@@ -1071,6 +1074,7 @@ const fixSpec: CommandSpec<FixInput, FixCommandOutput> = {
     properties: {
       ok: { type: "boolean" },
       changed: { type: "array" },
+      failed: { type: "array" },
       diagnostics: { type: "array" },
     },
     required: ["ok", "diagnostics"],
@@ -1091,18 +1095,34 @@ const fixSpec: CommandSpec<FixInput, FixCommandOutput> = {
       ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
     })
     const changed: string[] = []
+    const failed: { code: string; reason: string }[] = []
     for (const diagnostic of result.structuredDiagnostics ?? [])
       if (value.code === undefined || diagnostic.code === value.code)
-        changed.push(...(await applyDiagnosticRecipe(ctx.cwd, diagnostic)))
+        // One recipe that cannot act must not cancel the others, and must not pass silently either:
+        // record why and keep going, so a run over many diagnostics still reports every outcome.
+        try {
+          changed.push(...(await applyDiagnosticRecipe(ctx.cwd, diagnostic)))
+        } catch (error) {
+          failed.push({
+            code: diagnostic.code,
+            reason: error instanceof Error ? error.message : String(error),
+          })
+        }
     const final = await collectCheckResult(ctx.cwd, {
       lintsOnly: true,
       ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
     })
-    return { ok: final.ok, changed, diagnostics: final.structuredDiagnostics ?? final.diagnostics }
+    return {
+      ok: final.ok,
+      changed,
+      failed,
+      diagnostics: final.structuredDiagnostics ?? final.diagnostics,
+    }
   },
   render: (out) => [
     out.ok ? "✓ fixes applied" : "✖ unresolved diagnostics remain",
     ...out.changed.map((file) => `  changed ${file}`),
+    ...out.failed.map((f) => `  could not fix ${f.code}: ${f.reason}`),
     ...out.diagnostics.map((d) => `  ${String((d as { code?: unknown }).code ?? "diagnostic")}`),
   ],
   success: (out) => out.ok,

package/src/doctor.ts

@@ -25,12 +25,14 @@ import {
   displayPath,
   type IdentityParityCopy,
   type IdentityParityFinding,
+  identityParityBasis,
   resolvedInstalledCopy,
 } from "@nifrajs/web/internal/parity"
 import { codePositionMask, type SourceFinding, stripComments, walkSource } from "./check.ts"
 import { detectToolingDrift, type ToolingDrift } from "./mcp-root.ts"
 import { collectPipelineReport, type PipelineReport } from "./pipeline-report.ts"
 import { type ResolvedTarget, resolveTarget } from "./port.ts"
+import { buildScriptName } from "./workspace-link.ts"
 
 // Runtime-provided modules that are never an npm dependency: Node core (bare + `node:` form) and Bun's
 // own `bun` module. `node:`/`bun:`-prefixed specifiers are filtered in packageOf by prefix.
@@ -141,6 +143,25 @@ export interface DoctorResult {
   readonly findings: readonly DoctorFinding[]
   /** Packages that resolve to more than one physical install across this workspace. */
   readonly duplicateInstalls: readonly DuplicateInstallFinding[]
+  /**
+   * Duplicate installs the app declared single-copy (`"nifra": { "singleCopy": [...] }`), which nifra
+   * collapses to one copy at resolve time. Reported so the topology stays visible, never folded into
+   * `ok`: the copies exist on disk but cannot both load. Absent on an older result shape.
+   */
+  readonly deduplicatedInstalls?: readonly DuplicateInstallFinding[]
+  /**
+   * Which tree the identity scan actually looked at, in the same words the build/dev preflight uses.
+   * Both run the same seam now; printing the basis is what lets a reader confirm that instead of
+   * having to trust it. Absent on an older result shape.
+   */
+  readonly identityBasis?: string
+  /**
+   * The identity scan stopped at the workspace-enumeration cap, so "no duplicates" means "none in the
+   * part that was scanned". Never folded into `ok` - a huge workspace is not a defect - but it is
+   * always printed, because an unqualified clean bill from a partial scan is the failure mode this
+   * whole report exists to avoid.
+   */
+  readonly identityScanTruncated?: boolean
   /** Workspace-linked deps whose `default`-condition artifact lags their `bun`-condition source.
    * Advisory (never folded into `ok`): while actively editing a linked package its dist is always
    * momentarily behind - the finding matters when a dev server starts against it. */
@@ -360,18 +381,52 @@ export async function collectDuplicateInstalls(
   cwd: string,
   rootPackage: Record<string, unknown>,
 ): Promise<DuplicateInstallFinding[]> {
-  const result = await collectIdentityParity(cwd, rootPackage, { useWorkspaceRoot: true })
-  return result.findings.map(
-    (finding): DuplicateInstallFinding => ({
-      ...finding,
-      copies: finding.copies.map((copy): DuplicateInstallCopy => ({ ...copy })),
-    }),
-  )
+  return (await collectAllDuplicateInstalls(cwd, rootPackage)).duplicates
+}
+
+const asDuplicateInstall = (finding: IdentityParityFinding): DuplicateInstallFinding => ({
+  ...finding,
+  copies: finding.copies.map((copy): DuplicateInstallCopy => ({ ...copy })),
+})
+
+/**
+ * Both halves of the identity scan: what still breaks, and what a declaration already collapses -
+ * plus the basis they were decided on.
+ *
+ * The basis travels with the findings because doctor and the build/dev preflight answer the same
+ * question, and a reader who gets two answers needs to see which tree each one looked at. They now
+ * scan identically (one shared seam, one workspace resolution), so the line is corroboration rather
+ * than an excuse - and it is the only way a TRUNCATED scan can be told apart from a clean one.
+ */
+export async function collectAllDuplicateInstalls(
+  cwd: string,
+  rootPackage: Record<string, unknown>,
+): Promise<{
+  readonly duplicates: DuplicateInstallFinding[]
+  readonly deduplicated: DuplicateInstallFinding[]
+  readonly basis: string
+  readonly truncated: boolean
+}> {
+  const result = await collectIdentityParity(cwd, rootPackage)
+  return {
+    duplicates: result.findings.map(asDuplicateInstall),
+    deduplicated: result.deduplicated.map(asDuplicateInstall),
+    basis: identityParityBasis(result),
+    truncated: result.truncated,
+  }
 }
 
 /** A workspace-linked dependency whose build artifact is older than its source. */
 export interface StaleDistFinding {
   readonly package: string
+  /** Where the linked package actually lives, relative to the doctor root when possible. A workspace
+   * link routinely points into a SIBLING repo, so "rebuild it" is not actionable without the path -
+   * this is the directory the rebuild runs in. */
+  readonly packageDir: string
+  /** The package's own build script name (`scripts.build` etc.), or `undefined` when it declares none -
+   * then the rebuild cannot be automated and the report says so instead of suggesting a command that
+   * would fail. */
+  readonly buildScript: string | undefined
   /** The `default`-condition artifact (what Vite's SSR runner, vitest, and node consumers load),
    * relative to the doctor root when possible. `missing: true` means it was never built at all. */
   readonly distFile: string
@@ -482,6 +537,8 @@ export async function collectStaleWorkspaceDists(
           newest = candidate
       }
       if (newest === undefined) continue
+      const packageDir = displayPath(cwd, copy.path)
+      const buildScript = buildScriptName(meta)
       // Report the package once, anchored on its stalest (or missing) artifact.
       let worst: StaleDistFinding | undefined
       for (const pair of pairs) {
@@ -491,6 +548,8 @@ export async function collectStaleWorkspaceDists(
           distStat === undefined
             ? {
                 package: name,
+                packageDir,
+                buildScript,
                 distFile: displayPath(cwd, distPath),
                 missing: true,
                 sourceFile: displayPath(cwd, newest.file),
@@ -499,6 +558,8 @@ export async function collectStaleWorkspaceDists(
             : distStat.mtimeMs < newest.mtimeMs
               ? {
                   package: name,
+                  packageDir,
+                  buildScript,
                   distFile: displayPath(cwd, distPath),
                   missing: false,
                   sourceFile: displayPath(cwd, newest.file),
@@ -704,7 +765,8 @@ export async function collectDoctorResult(
     { includeTests: true },
   )
   findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line)
-  const duplicateInstalls = await collectDuplicateInstalls(cwd, pkg)
+  const identity = await collectAllDuplicateInstalls(cwd, pkg)
+  const duplicateInstalls = identity.duplicates
   const staleDists = await collectStaleWorkspaceDists(cwd, pkg)
   const pipeline = await collectPipelineReport(cwd)
   const pipelineErrors = pipeline.findings.filter((f) => f.severity === "error")
@@ -724,6 +786,9 @@ export async function collectDoctorResult(
     ran: true,
     findings,
     duplicateInstalls,
+    deduplicatedInstalls: identity.deduplicated,
+    identityBasis: identity.basis,
+    ...(identity.truncated ? { identityScanTruncated: true } : {}),
     staleDists,
     readiness,
     ...(toolingDrift !== undefined ? { toolingDrift } : {}),
@@ -906,6 +971,14 @@ export async function runDoctor(
     console.log(
       "✓ every imported package is declared and identity-sensitive installs are deduplicated",
     )
+    if (result.identityBasis !== undefined) console.log(`  identity scan: ${result.identityBasis}`)
+    // A partial scan that prints a bare ✓ is a lie by omission - the packages past the cap were never
+    // looked at, and the reader has no way to know that from the tick alone.
+    if (result.identityScanTruncated === true) {
+      console.log(
+        "  ! the identity scan was truncated, so this is not a clean bill for the whole workspace",
+      )
+    }
     return true
   }
   // Group by package so the fix ("add X to dependencies") is stated once with its import sites.
@@ -926,6 +999,7 @@ export async function runDoctor(
     console.log(
       `${byPkg.size > 0 ? "\n" : ""}✗ identity-sensitive packages resolve to multiple physical copies:\n`,
     )
+    if (result.identityBasis !== undefined) console.log(`  scan: ${result.identityBasis}\n`)
     for (const finding of result.duplicateInstalls) {
       console.log(`  ${finding.package} [${finding.cause}]`)
       console.log(`      versions: ${finding.versions.join(", ")}`)
@@ -933,9 +1007,26 @@ export async function runDoctor(
         console.log(`      ${copy.version} at ${copy.path} ← ${copy.importers.join(", ")}`)
       }
       console.log(`      ${finding.explanation}`)
+      // The shape of the split decides which fix can work, so it is printed above the fix itself.
+      if (finding.topology !== undefined) console.log(`      topology: ${finding.topology}`)
+      // Why a copy this directory never imports still counts. Without it, a workspace-wide answer
+      // read from inside one app looks like the tool checking the wrong project.
+      if (finding.scope !== undefined) console.log(`      scope: ${finding.scope}`)
       console.log(`      fix: ${finding.remediation}`)
     }
   }
+  // Not a failure and not silence: the copies are real, and whoever reads this report needs to know
+  // the graph is held together by a declaration rather than by the install.
+  if (result.deduplicatedInstalls !== undefined && result.deduplicatedInstalls.length > 0) {
+    console.log("\n• identity-sensitive packages deduplicated by declaration:\n")
+    for (const finding of result.deduplicatedInstalls) {
+      console.log(`  ${finding.package} @ ${finding.versions.join(", ")}`)
+      for (const copy of finding.copies) {
+        console.log(`      ${copy.path} ← ${copy.importers.join(", ")}`)
+      }
+      console.log(`      ${finding.remediation}`)
+    }
+  }
   if (result.readiness?.strict === true && result.readiness.ok === false) {
     console.log("\n✗ production readiness is incomplete under --strict")
   }

package/src/env-file.ts

@@ -0,0 +1,121 @@
+/**
+ * `--env-file <path>` for every `nifra` command.
+ *
+ * Most nifra commands (`check`, `assure`, `levels`, `routes`, `capabilities`, `manifest`, `contracts`,
+ * `openapi`, `types`) reflect a project by IMPORTING it, and a production-grade app validates its
+ * environment at module scope. Without the app's environment those commands do not report a gate
+ * failure - the app's own validator kills the process before nifra reaches its first check, and the
+ * only output is the app's `FATAL: invalid environment` with nothing tying it to the command that was
+ * run. This flag supplies that environment the same way `bun --env-file` / `node --env-file` do, so a
+ * project whose env lives in an uncommitted `.env.local` stays checkable.
+ *
+ * Two deliberate rules:
+ *   - A variable already present in `process.env` WINS. The shell (and CI's secret store) is the more
+ *     explicit source; a checked-in defaults file must never shadow it.
+ *   - A missing file is an error, never a silent no-op. `--env-file .env.prod` that quietly did nothing
+ *     would make the command look like it verified an environment it never loaded.
+ */
+import { readFile } from "node:fs/promises"
+import { resolve } from "node:path"
+
+const ENV_FILE_FLAG = "--env-file"
+
+/**
+ * A `KEY=VALUE` line. `export ` is tolerated so a file that is also `source`-able works. The key is
+ * POSIX-shaped on purpose: it keeps a stray `- foo` bullet or a YAML `key: value` line from being read
+ * as an assignment when the wrong file is passed.
+ */
+const ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/
+
+/** Strip one layer of matching quotes; a double-quoted value also expands `\n`, `\r`, `\t` and `\"`. */
+function unquote(raw: string): string {
+  const value = raw.trim()
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    return value
+      .slice(1, -1)
+      .replace(/\\([nrt"\\])/g, (_, char: string) =>
+        char === "n" ? "\n" : char === "r" ? "\r" : char === "t" ? "\t" : char,
+      )
+  }
+  if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1)
+  // Unquoted: an inline ` #` starts a comment, matching every dotenv reader. A `#` with no leading
+  // space is part of the value (URLs and generated secrets contain one).
+  const comment = value.search(/\s#/)
+  return (comment === -1 ? value : value.slice(0, comment)).trim()
+}
+
+/** Parse dotenv text into a plain record. Later assignments to the same key win, as in a shell. */
+export function parseEnvFile(text: string): Record<string, string> {
+  const values: Record<string, string> = {}
+  for (const line of text.split(/\r?\n/)) {
+    if (line.trim() === "" || line.trimStart().startsWith("#")) continue
+    const match = ASSIGNMENT.exec(line)
+    if (match === null) continue
+    values[match[1] as string] = unquote(match[2] as string)
+  }
+  return values
+}
+
+/**
+ * Pull every `--env-file <path>` / `--env-file=<path>` out of `argv`, leaving the rest for the command
+ * parser (which rejects options it does not know). Repeatable; later files override earlier ones, the
+ * same precedence `node --env-file` uses.
+ */
+export function takeEnvFileFlags(argv: readonly string[]): {
+  readonly argv: readonly string[]
+  readonly files: readonly string[]
+} {
+  const rest: string[] = []
+  const files: string[] = []
+  for (let index = 0; index < argv.length; index++) {
+    const token = argv[index] as string
+    if (token === ENV_FILE_FLAG) {
+      const value = argv[index + 1]
+      if (value === undefined || value.startsWith("-")) {
+        throw new Error(`[nifra] ${ENV_FILE_FLAG} needs a path, e.g. ${ENV_FILE_FLAG} .env.local`)
+      }
+      files.push(value)
+      index++
+      continue
+    }
+    if (token.startsWith(`${ENV_FILE_FLAG}=`)) {
+      const value = token.slice(ENV_FILE_FLAG.length + 1)
+      if (value === "") {
+        throw new Error(`[nifra] ${ENV_FILE_FLAG} needs a path, e.g. ${ENV_FILE_FLAG}=.env.local`)
+      }
+      files.push(value)
+      continue
+    }
+    rest.push(token)
+  }
+  return { argv: rest, files }
+}
+
+/**
+ * Read each file in order and merge it into `process.env`, never overwriting a variable the process
+ * already has. Returns the resolved paths that were applied so a command can say what it loaded.
+ */
+export async function applyEnvFiles(
+  cwd: string,
+  files: readonly string[],
+): Promise<readonly string[]> {
+  const applied: string[] = []
+  const merged: Record<string, string> = {}
+  for (const file of files) {
+    const path = resolve(cwd, file)
+    let text: string
+    try {
+      text = await readFile(path, "utf8")
+    } catch {
+      throw new Error(`[nifra] --env-file not found or unreadable: ${path}`)
+    }
+    // Files merge left to right, so a later `--env-file` overrides an earlier one; the merged result
+    // is applied afterwards so that precedence never depends on which file happened to define a key.
+    Object.assign(merged, parseEnvFile(text))
+    applied.push(path)
+  }
+  for (const [key, value] of Object.entries(merged)) {
+    if (process.env[key] === undefined) process.env[key] = value
+  }
+  return applied
+}