@ariestools/cli-kit-node 1.0.0 → 1.0.1

package/README.md

@@ -2,7 +2,7 @@
 
 Node.js process adapter for reusable actor command-line applications.
 
-The package supplies `nodeProcessHost`, a production `ProcessHost` backed by the active Node.js process. It exposes arguments and environment values through live getters, routes output through the Node console, creates a scoped readline interface for interactive questions, translates `SIGINT` into the structural interrupt contract, and delegates exit requests to `process.exit`.
+The package supplies `nodeProcessHost`, a production `ProcessHost` backed by the active Node.js process. It exposes arguments and environment values through live getters, routes output through the Node console, creates a scoped readline interface for interactive questions, translates `SIGINT` and `SIGTERM` into the structural interrupt contract, and delegates exit requests to `process.exit`. When the default interrupt signals must be narrowed or extended, `createNodeProcessHost({ signals })` builds a host bound to an explicit signal list; disposal always removes every bound signal listener.
 
 ```ts
 import { runProcessApplication } from '@ariestools/cli-kit'
@@ -16,6 +16,38 @@ await runProcessApplication({
 })
 ```
 
+## Dotenv composition
+
+Prefer loading local `.env` values into the host environment instead of mutating `process.env`. File values act as defaults: defined process environment entries always win.
+
+```ts
+import { createNodeProcessHostWithDotEnv } from '@ariestools/cli-kit-node'
+import { environmentToYargsConfig, runYargsApplication } from '@ariestools/cli-kit-yargs'
+
+const host = createNodeProcessHostWithDotEnv()
+// or explicitly:
+// createNodeProcessHost({
+//   environmentDefaults: loadDotEnvFile({ path: '.env' }),
+// })
+
+await runYargsApplication({
+  host,
+  configure: parser => parser
+    .config(environmentToYargsConfig(host.environment, 'XL1'))
+    .scriptName('xl1')
+    .help(),
+})
+```
+
+Helpers:
+
+| Export | Role |
+|--------|------|
+| `parseDotEnv` | Pure dotenv-format string parser |
+| `loadDotEnvFile` | Read a file (missing → `{}`); never mutates `process.env` |
+| `mergeEnvironments` | Primary-first merge for env layers |
+| `createNodeProcessHostWithDotEnv` | Host with `.env` merged under live `process.env` |
+
 Application code should depend on the `ProcessHost` contract from `@ariestools/cli-kit`. Use this package only at the Node.js composition boundary.
 
 ## License

package/dist/node/index.d.ts

@@ -1,2 +1,5 @@
+export * from './loadDotEnvFile.ts';
+export * from './mergeEnvironments.ts';
 export * from './nodeProcessHost.ts';
+export * from './parseDotEnv.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/node/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,wBAAwB,CAAA;AACtC,cAAc,sBAAsB,CAAA;AACpC,cAAc,kBAAkB,CAAA"}

package/dist/node/index.mjs

@@ -1,12 +1,81 @@
-// src/nodeProcessHost.ts
+// src/loadDotEnvFile.ts
+import fs from "node:fs";
+import path from "node:path";
 import PROCESS from "node:process";
+
+// src/parseDotEnv.ts
+function parseDotEnv(content) {
+  const result = {};
+  const text = content.codePointAt(0) === 65279 ? content.slice(1) : content;
+  const linePattern = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/mg;
+  let match;
+  while ((match = linePattern.exec(text)) !== null) {
+    const key = match[1];
+    if (key === void 0) continue;
+    let value = (match[2] ?? "").trim();
+    const isDoubleQuoted = value.startsWith('"') && value.endsWith('"');
+    const isSingleQuoted = value.startsWith("'") && value.endsWith("'");
+    const isBacktickQuoted = value.startsWith("`") && value.endsWith("`");
+    if (isSingleQuoted || isDoubleQuoted || isBacktickQuoted) {
+      value = value.slice(1, -1);
+      if (isDoubleQuoted) {
+        value = value.replaceAll(String.raw`\n`, "\n").replaceAll(String.raw`\r`, "\r").replaceAll(String.raw`\\"`, '"').replaceAll(String.raw`\\`, "\\");
+      }
+    } else {
+      value = value.replace(/\s+#.*$/, "").trim();
+    }
+    result[key] = value;
+  }
+  return result;
+}
+
+// src/loadDotEnvFile.ts
+function isErrnoException(error) {
+  return typeof error === "object" && error !== null && "code" in error;
+}
+function loadDotEnvFile(options = {}) {
+  const cwd = options.cwd ?? PROCESS.cwd();
+  const relativePath = options.path ?? ".env";
+  const absolutePath = path.isAbsolute(relativePath) ? relativePath : path.resolve(cwd, relativePath);
+  try {
+    return parseDotEnv(fs.readFileSync(absolutePath, "utf8"));
+  } catch (error) {
+    if (isErrnoException(error) && error.code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+// src/mergeEnvironments.ts
+function resolveEnvironmentValue(key, layers) {
+  for (const layer of layers) {
+    if (!Object.hasOwn(layer, key)) continue;
+    const value = layer[key];
+    if (value !== void 0) return value;
+  }
+  return void 0;
+}
+function mergeEnvironments(primary, ...fallbacks) {
+  const layers = [primary, ...fallbacks];
+  const keys = /* @__PURE__ */ new Set();
+  for (const layer of layers) {
+    for (const key of Object.keys(layer)) keys.add(key);
+  }
+  const result = {};
+  for (const key of keys) {
+    result[key] = resolveEnvironmentValue(key, layers);
+  }
+  return result;
+}
+
+// src/nodeProcessHost.ts
+import PROCESS2 from "node:process";
 import { createInterface } from "node:readline/promises";
 var nodeProcessIO = {
   get columns() {
-    return PROCESS.stdout.columns;
+    return PROCESS2.stdout.columns;
   },
   get isInteractive() {
-    return PROCESS.stdin.isTTY && PROCESS.stdout.isTTY;
+    return PROCESS2.stdin.isTTY && PROCESS2.stdout.isTTY;
   },
   error(...values) {
     console.error(...values);
@@ -15,7 +84,7 @@ var nodeProcessIO = {
     console.log(...values);
   },
   async question(prompt) {
-    const readline = createInterface({ input: PROCESS.stdin, output: PROCESS.stdout });
+    const readline = createInterface({ input: PROCESS2.stdin, output: PROCESS2.stdout });
     try {
       return await readline.question(prompt);
     } finally {
@@ -26,33 +95,64 @@ var nodeProcessIO = {
     console.warn(...values);
   }
 };
-var nodeProcessHost = {
-  get argv() {
-    return PROCESS.argv;
-  },
-  get environment() {
-    return PROCESS.env;
-  },
-  exit(code) {
-    PROCESS.exit(code);
-  },
-  get io() {
-    return nodeProcessIO;
-  },
-  get isDevelopment() {
-    return PROCESS.env.NODE_ENV === "development";
-  },
-  onInterrupt(listener) {
-    const handleInterrupt = () => {
-      void listener();
-    };
-    PROCESS.on("SIGINT", handleInterrupt);
-    return () => {
-      PROCESS.off("SIGINT", handleInterrupt);
-    };
+var DEFAULT_INTERRUPT_SIGNALS = ["SIGINT", "SIGTERM"];
+function createNodeProcessHost(options) {
+  const signals = options?.signals ?? DEFAULT_INTERRUPT_SIGNALS;
+  const environmentOverride = options?.environment;
+  const environmentDefaults = options?.environmentDefaults;
+  function resolveEnvironment() {
+    const primary = environmentOverride ?? PROCESS2.env;
+    if (environmentDefaults === void 0) return primary;
+    return mergeEnvironments(primary, environmentDefaults);
   }
-};
+  return {
+    get argv() {
+      return PROCESS2.argv;
+    },
+    get environment() {
+      return resolveEnvironment();
+    },
+    exit(code) {
+      PROCESS2.exit(code);
+    },
+    get io() {
+      return nodeProcessIO;
+    },
+    get isDevelopment() {
+      return resolveEnvironment().NODE_ENV === "development";
+    },
+    onInterrupt(listener) {
+      const handleInterrupt = () => {
+        void listener();
+      };
+      for (const signal of signals) PROCESS2.on(signal, handleInterrupt);
+      return () => {
+        for (const signal of signals) PROCESS2.off(signal, handleInterrupt);
+      };
+    }
+  };
+}
+function createNodeProcessHostWithDotEnv(options = {}) {
+  const {
+    cwd,
+    environment,
+    path: path2,
+    signals
+  } = options;
+  return createNodeProcessHost({
+    environment,
+    environmentDefaults: loadDotEnvFile({ cwd, path: path2 }),
+    signals
+  });
+}
+var nodeProcessHost = createNodeProcessHost();
 export {
-  nodeProcessHost
+  DEFAULT_INTERRUPT_SIGNALS,
+  createNodeProcessHost,
+  createNodeProcessHostWithDotEnv,
+  loadDotEnvFile,
+  mergeEnvironments,
+  nodeProcessHost,
+  parseDotEnv
 };
 //# sourceMappingURL=index.mjs.map

package/dist/node/index.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../../src/nodeProcessHost.ts"],
-  "sourcesContent": ["import PROCESS from 'node:process'\nimport { createInterface } from 'node:readline/promises'\n\nimport type { ProcessHost, ProcessIO } from '@ariestools/cli-kit'\n\nconst nodeProcessIO: ProcessIO = {\n  get columns(): number | undefined {\n    return PROCESS.stdout.columns\n  },\n  get isInteractive(): boolean {\n    return PROCESS.stdin.isTTY && PROCESS.stdout.isTTY\n  },\n  error(...values: readonly unknown[]): void {\n    console.error(...values)\n  },\n  log(...values: readonly unknown[]): void {\n    console.log(...values)\n  },\n  async question(prompt: string): Promise<string> {\n    const readline = createInterface({ input: PROCESS.stdin, output: PROCESS.stdout })\n    try {\n      return await readline.question(prompt)\n    } finally {\n      readline.close()\n    }\n  },\n  warn(...values: readonly unknown[]): void {\n    console.warn(...values)\n  },\n}\n\n/** Node.js adapter for the reusable CLI process boundary. */\nexport const nodeProcessHost: ProcessHost = {\n  get argv(): readonly string[] {\n    return PROCESS.argv\n  },\n  get environment(): Readonly<Record<string, string | undefined>> {\n    return PROCESS.env\n  },\n  exit(code: number): void {\n    PROCESS.exit(code)\n  },\n  get io(): ProcessIO {\n    return nodeProcessIO\n  },\n  get isDevelopment(): boolean {\n    return PROCESS.env.NODE_ENV === 'development'\n  },\n  onInterrupt(listener: () => Promise<void> | void): () => void {\n    const handleInterrupt = (): void => {\n      void listener()\n    }\n    PROCESS.on('SIGINT', handleInterrupt)\n    return () => {\n      PROCESS.off('SIGINT', handleInterrupt)\n    }\n  },\n}\n"],
-  "mappings": ";AAAA,OAAO,aAAa;AACpB,SAAS,uBAAuB;AAIhC,IAAM,gBAA2B;AAAA,EAC/B,IAAI,UAA8B;AAChC,WAAO,QAAQ,OAAO;AAAA,EACxB;AAAA,EACA,IAAI,gBAAyB;AAC3B,WAAO,QAAQ,MAAM,SAAS,QAAQ,OAAO;AAAA,EAC/C;AAAA,EACA,SAAS,QAAkC;AACzC,YAAQ,MAAM,GAAG,MAAM;AAAA,EACzB;AAAA,EACA,OAAO,QAAkC;AACvC,YAAQ,IAAI,GAAG,MAAM;AAAA,EACvB;AAAA,EACA,MAAM,SAAS,QAAiC;AAC9C,UAAM,WAAW,gBAAgB,EAAE,OAAO,QAAQ,OAAO,QAAQ,QAAQ,OAAO,CAAC;AACjF,QAAI;AACF,aAAO,MAAM,SAAS,SAAS,MAAM;AAAA,IACvC,UAAE;AACA,eAAS,MAAM;AAAA,IACjB;AAAA,EACF;AAAA,EACA,QAAQ,QAAkC;AACxC,YAAQ,KAAK,GAAG,MAAM;AAAA,EACxB;AACF;AAGO,IAAM,kBAA+B;AAAA,EAC1C,IAAI,OAA0B;AAC5B,WAAO,QAAQ;AAAA,EACjB;AAAA,EACA,IAAI,cAA4D;AAC9D,WAAO,QAAQ;AAAA,EACjB;AAAA,EACA,KAAK,MAAoB;AACvB,YAAQ,KAAK,IAAI;AAAA,EACnB;AAAA,EACA,IAAI,KAAgB;AAClB,WAAO;AAAA,EACT;AAAA,EACA,IAAI,gBAAyB;AAC3B,WAAO,QAAQ,IAAI,aAAa;AAAA,EAClC;AAAA,EACA,YAAY,UAAkD;AAC5D,UAAM,kBAAkB,MAAY;AAClC,WAAK,SAAS;AAAA,IAChB;AACA,YAAQ,GAAG,UAAU,eAAe;AACpC,WAAO,MAAM;AACX,cAAQ,IAAI,UAAU,eAAe;AAAA,IACvC;AAAA,EACF;AACF;",
-  "names": []
+  "sources": ["../../src/loadDotEnvFile.ts", "../../src/parseDotEnv.ts", "../../src/mergeEnvironments.ts", "../../src/nodeProcessHost.ts"],
+  "sourcesContent": ["import fs from 'node:fs'\nimport path from 'node:path'\nimport PROCESS from 'node:process'\n\nimport { parseDotEnv } from './parseDotEnv.ts'\n\nexport interface LoadDotEnvFileOptions {\n  /**\n   * Directory used to resolve a relative {@link path}. Defaults to\n   * `process.cwd()`.\n   */\n  readonly cwd?: string\n  /**\n   * Absolute or cwd-relative path to the dotenv file. Defaults to `.env`.\n   */\n  readonly path?: string\n}\n\nfunction isErrnoException(error: unknown): error is NodeJS.ErrnoException {\n  return typeof error === 'object' && error !== null && 'code' in error\n}\n\n/**\n * Reads and parses a dotenv file without mutating `process.env`.\n *\n * Missing files resolve to an empty object. Other filesystem errors propagate.\n */\nexport function loadDotEnvFile(options: LoadDotEnvFileOptions = {}): Record<string, string> {\n  const cwd = options.cwd ?? PROCESS.cwd()\n  const relativePath = options.path ?? '.env'\n  const absolutePath = path.isAbsolute(relativePath)\n    ? relativePath\n    : path.resolve(cwd, relativePath)\n\n  try {\n    return parseDotEnv(fs.readFileSync(absolutePath, 'utf8'))\n  } catch (error) {\n    if (isErrnoException(error) && error.code === 'ENOENT') return {}\n    throw error\n  }\n}\n", "/**\n * Parses dotenv-format content into a plain key/value map.\n *\n * Supports the common dotenv grammar used by local CLI configuration:\n * - optional `export` prefix\n * - single-quoted, double-quoted, and unquoted values\n * - `#` comments (including trailing comments on unquoted values)\n * - multi-line double-quoted values with `\\\\n` escape sequences\n *\n * Does not expand variable references (`$VAR` / `${VAR}`). Does not mutate\n * `process.env`.\n */\nexport function parseDotEnv(content: string): Record<string, string> {\n  const result: Record<string, string> = {}\n  const text = content.codePointAt(0) === 0xFE_FF ? content.slice(1) : content\n  const linePattern = /(?:^|^)\\s*(?:export\\s+)?([\\w.-]+)(?:\\s*=\\s*?|:\\s+?)(\\s*'(?:\\\\'|[^'])*'|\\s*\"(?:\\\\\"|[^\"])*\"|\\s*`(?:\\\\`|[^`])*`|[^#\\r\\n]+)?\\s*(?:#.*)?(?:$|$)/mg\n\n  let match: RegExpExecArray | null\n  while ((match = linePattern.exec(text)) !== null) {\n    const key = match[1]\n    if (key === undefined) continue\n    let value = (match[2] ?? '').trim()\n\n    const isDoubleQuoted = value.startsWith('\"') && value.endsWith('\"')\n    const isSingleQuoted = value.startsWith(\"'\") && value.endsWith(\"'\")\n    const isBacktickQuoted = value.startsWith('`') && value.endsWith('`')\n\n    if (isSingleQuoted || isDoubleQuoted || isBacktickQuoted) {\n      value = value.slice(1, -1)\n      if (isDoubleQuoted) {\n        value = value\n          .replaceAll(String.raw`\\n`, '\\n')\n          .replaceAll(String.raw`\\r`, '\\r')\n          .replaceAll(String.raw`\\\\\"`, '\"')\n          .replaceAll(String.raw`\\\\`, '\\\\')\n      }\n    } else {\n      value = value.replace(/\\s+#.*$/, '').trim()\n    }\n\n    result[key] = value\n  }\n\n  return result\n}\n", "/** Environment map accepted by process hosts and dotenv composition helpers. */\nexport type ProcessEnvironment = Readonly<Record<string, string | undefined>>\n\nfunction resolveEnvironmentValue(\n  key: string,\n  layers: readonly ProcessEnvironment[],\n): string | undefined {\n  for (const layer of layers) {\n    if (!Object.hasOwn(layer, key)) continue\n    const value = layer[key]\n    if (value !== undefined) return value\n  }\n  return undefined\n}\n\n/**\n * Merges environment layers with primary-first precedence.\n *\n * For each key, the first layer that owns the key with a value other than\n * `undefined` wins. Later layers only fill missing or undefined entries.\n *\n * Standard dotenv non-override composition (process wins over file):\n *\n * ```ts\n * mergeEnvironments(process.env, loadDotEnvFile())\n * ```\n */\nexport function mergeEnvironments(\n  primary: ProcessEnvironment,\n  ...fallbacks: readonly ProcessEnvironment[]\n): Record<string, string | undefined> {\n  const layers = [primary, ...fallbacks]\n  const keys = new Set<string>()\n  for (const layer of layers) {\n    for (const key of Object.keys(layer)) keys.add(key)\n  }\n\n  const result: Record<string, string | undefined> = {}\n  for (const key of keys) {\n    result[key] = resolveEnvironmentValue(key, layers)\n  }\n  return result\n}\n", "import PROCESS from 'node:process'\nimport { createInterface } from 'node:readline/promises'\n\nimport type { ProcessHost, ProcessIO } from '@ariestools/cli-kit'\n\nimport { loadDotEnvFile, type LoadDotEnvFileOptions } from './loadDotEnvFile.ts'\nimport { mergeEnvironments, type ProcessEnvironment } from './mergeEnvironments.ts'\n\nconst nodeProcessIO: ProcessIO = {\n  get columns(): number | undefined {\n    return PROCESS.stdout.columns\n  },\n  get isInteractive(): boolean {\n    return PROCESS.stdin.isTTY && PROCESS.stdout.isTTY\n  },\n  error(...values: readonly unknown[]): void {\n    console.error(...values)\n  },\n  log(...values: readonly unknown[]): void {\n    console.log(...values)\n  },\n  async question(prompt: string): Promise<string> {\n    const readline = createInterface({ input: PROCESS.stdin, output: PROCESS.stdout })\n    try {\n      return await readline.question(prompt)\n    } finally {\n      readline.close()\n    }\n  },\n  warn(...values: readonly unknown[]): void {\n    console.warn(...values)\n  },\n}\n\n/**\n * Signal name accepted for interrupt binding.\n *\n * A self-contained subset of Node's `NodeJS.Signals` so the public\n * declaration surface stays resolvable in consumers without `@types/node`.\n * Every member is a valid `NodeJS.Signals` value. `SIGUSR1` is deliberately\n * excluded: Node.js reserves it for starting the debugger, and binding a\n * listener to it can interfere with debugger attach.\n */\nexport type NodeInterruptSignal = 'SIGBREAK' | 'SIGHUP' | 'SIGINT' | 'SIGQUIT' | 'SIGTERM' | 'SIGUSR2'\n\n/** Signals translated into the structural interrupt contract by default. */\nexport const DEFAULT_INTERRUPT_SIGNALS: readonly NodeInterruptSignal[] = ['SIGINT', 'SIGTERM']\n\nexport interface NodeProcessHostOptions {\n  /**\n   * Full environment override. When set, `process.env` is not read for\n   * {@link ProcessHost.environment} or {@link ProcessHost.isDevelopment}\n   * unless the caller passed `process.env` itself.\n   */\n  readonly environment?: ProcessEnvironment\n  /**\n   * Values merged under the active environment (`process.env` or\n   * {@link environment}). The active environment wins for defined keys, so\n   * this is the right place for dotenv file values under non-override\n   * semantics. The map is fixed at host construction; the host does not\n   * re-read files.\n   */\n  readonly environmentDefaults?: ProcessEnvironment\n  /**\n   * Signals bound to interrupt listeners registered through `onInterrupt`.\n   * Defaults to {@link DEFAULT_INTERRUPT_SIGNALS} (`SIGINT` and `SIGTERM`).\n   * An empty list is honored literally: `onInterrupt` binds nothing, the\n   * listener is never invoked, and the returned disposer is a no-op.\n   */\n  readonly signals?: readonly NodeInterruptSignal[]\n}\n\nexport interface NodeProcessHostWithDotEnvOptions extends\n  NodeProcessHostOptions, LoadDotEnvFileOptions {}\n\n/**\n * Creates a Node.js adapter for the reusable CLI process boundary.\n *\n * Use this factory when interrupt signals must be narrowed or extended, when\n * a custom environment must be supplied, or when dotenv defaults should be\n * merged under the live process environment. Otherwise prefer the shared\n * {@link nodeProcessHost} instance.\n */\nexport function createNodeProcessHost(options?: NodeProcessHostOptions): ProcessHost {\n  const signals = options?.signals ?? DEFAULT_INTERRUPT_SIGNALS\n  const environmentOverride = options?.environment\n  const environmentDefaults = options?.environmentDefaults\n\n  function resolveEnvironment(): ProcessEnvironment {\n    const primary = environmentOverride ?? PROCESS.env\n    if (environmentDefaults === undefined) return primary\n    return mergeEnvironments(primary, environmentDefaults)\n  }\n\n  return {\n    get argv(): readonly string[] {\n      return PROCESS.argv\n    },\n    get environment(): ProcessEnvironment {\n      return resolveEnvironment()\n    },\n    exit(code: number): void {\n      PROCESS.exit(code)\n    },\n    get io(): ProcessIO {\n      return nodeProcessIO\n    },\n    get isDevelopment(): boolean {\n      return resolveEnvironment().NODE_ENV === 'development'\n    },\n    onInterrupt(listener: () => Promise<void> | void): () => void {\n      const handleInterrupt = (): void => {\n        void listener()\n      }\n      for (const signal of signals) PROCESS.on(signal, handleInterrupt)\n      return () => {\n        for (const signal of signals) PROCESS.off(signal, handleInterrupt)\n      }\n    },\n  }\n}\n\n/**\n * Creates a Node process host that loads a dotenv file as\n * {@link NodeProcessHostOptions.environmentDefaults}.\n *\n * The file is read once at construction. Real process environment values (or\n * an explicit {@link NodeProcessHostOptions.environment} override) win over\n * file values for shared keys. `process.env` is never mutated.\n *\n * ```ts\n * const host = createNodeProcessHostWithDotEnv()\n * // equivalent to:\n * // createNodeProcessHost({ environmentDefaults: loadDotEnvFile() })\n * ```\n */\nexport function createNodeProcessHostWithDotEnv(\n  options: NodeProcessHostWithDotEnvOptions = {},\n): ProcessHost {\n  const {\n    cwd, environment, path, signals,\n  } = options\n  return createNodeProcessHost({\n    environment,\n    environmentDefaults: loadDotEnvFile({ cwd, path }),\n    signals,\n  })\n}\n\n/** Node.js adapter for the reusable CLI process boundary. */\nexport const nodeProcessHost: ProcessHost = createNodeProcessHost()\n"],
+  "mappings": "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",
+  "names": ["PROCESS", "PROCESS", "path"]
 }

package/dist/node/loadDotEnvFile.d.ts

@@ -0,0 +1,18 @@
+export interface LoadDotEnvFileOptions {
+    /**
+     * Directory used to resolve a relative {@link path}. Defaults to
+     * `process.cwd()`.
+     */
+    readonly cwd?: string;
+    /**
+     * Absolute or cwd-relative path to the dotenv file. Defaults to `.env`.
+     */
+    readonly path?: string;
+}
+/**
+ * Reads and parses a dotenv file without mutating `process.env`.
+ *
+ * Missing files resolve to an empty object. Other filesystem errors propagate.
+ */
+export declare function loadDotEnvFile(options?: LoadDotEnvFileOptions): Record<string, string>;
+//# sourceMappingURL=loadDotEnvFile.d.ts.map

package/dist/node/loadDotEnvFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadDotEnvFile.d.ts","sourceRoot":"","sources":["../../src/loadDotEnvFile.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAMD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAa1F"}

package/dist/node/mergeEnvironments.d.ts

@@ -0,0 +1,16 @@
+/** Environment map accepted by process hosts and dotenv composition helpers. */
+export type ProcessEnvironment = Readonly<Record<string, string | undefined>>;
+/**
+ * Merges environment layers with primary-first precedence.
+ *
+ * For each key, the first layer that owns the key with a value other than
+ * `undefined` wins. Later layers only fill missing or undefined entries.
+ *
+ * Standard dotenv non-override composition (process wins over file):
+ *
+ * ```ts
+ * mergeEnvironments(process.env, loadDotEnvFile())
+ * ```
+ */
+export declare function mergeEnvironments(primary: ProcessEnvironment, ...fallbacks: readonly ProcessEnvironment[]): Record<string, string | undefined>;
+//# sourceMappingURL=mergeEnvironments.d.ts.map

package/dist/node/mergeEnvironments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mergeEnvironments.d.ts","sourceRoot":"","sources":["../../src/mergeEnvironments.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;AAc7E;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,kBAAkB,EAC3B,GAAG,SAAS,EAAE,SAAS,kBAAkB,EAAE,GAC1C,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAYpC"}

package/dist/node/nodeProcessHost.d.ts

@@ -1,4 +1,67 @@
 import type { ProcessHost } from '@ariestools/cli-kit';
+import { type LoadDotEnvFileOptions } from './loadDotEnvFile.ts';
+import { type ProcessEnvironment } from './mergeEnvironments.ts';
+/**
+ * Signal name accepted for interrupt binding.
+ *
+ * A self-contained subset of Node's `NodeJS.Signals` so the public
+ * declaration surface stays resolvable in consumers without `@types/node`.
+ * Every member is a valid `NodeJS.Signals` value. `SIGUSR1` is deliberately
+ * excluded: Node.js reserves it for starting the debugger, and binding a
+ * listener to it can interfere with debugger attach.
+ */
+export type NodeInterruptSignal = 'SIGBREAK' | 'SIGHUP' | 'SIGINT' | 'SIGQUIT' | 'SIGTERM' | 'SIGUSR2';
+/** Signals translated into the structural interrupt contract by default. */
+export declare const DEFAULT_INTERRUPT_SIGNALS: readonly NodeInterruptSignal[];
+export interface NodeProcessHostOptions {
+    /**
+     * Full environment override. When set, `process.env` is not read for
+     * {@link ProcessHost.environment} or {@link ProcessHost.isDevelopment}
+     * unless the caller passed `process.env` itself.
+     */
+    readonly environment?: ProcessEnvironment;
+    /**
+     * Values merged under the active environment (`process.env` or
+     * {@link environment}). The active environment wins for defined keys, so
+     * this is the right place for dotenv file values under non-override
+     * semantics. The map is fixed at host construction; the host does not
+     * re-read files.
+     */
+    readonly environmentDefaults?: ProcessEnvironment;
+    /**
+     * Signals bound to interrupt listeners registered through `onInterrupt`.
+     * Defaults to {@link DEFAULT_INTERRUPT_SIGNALS} (`SIGINT` and `SIGTERM`).
+     * An empty list is honored literally: `onInterrupt` binds nothing, the
+     * listener is never invoked, and the returned disposer is a no-op.
+     */
+    readonly signals?: readonly NodeInterruptSignal[];
+}
+export interface NodeProcessHostWithDotEnvOptions extends NodeProcessHostOptions, LoadDotEnvFileOptions {
+}
+/**
+ * Creates a Node.js adapter for the reusable CLI process boundary.
+ *
+ * Use this factory when interrupt signals must be narrowed or extended, when
+ * a custom environment must be supplied, or when dotenv defaults should be
+ * merged under the live process environment. Otherwise prefer the shared
+ * {@link nodeProcessHost} instance.
+ */
+export declare function createNodeProcessHost(options?: NodeProcessHostOptions): ProcessHost;
+/**
+ * Creates a Node process host that loads a dotenv file as
+ * {@link NodeProcessHostOptions.environmentDefaults}.
+ *
+ * The file is read once at construction. Real process environment values (or
+ * an explicit {@link NodeProcessHostOptions.environment} override) win over
+ * file values for shared keys. `process.env` is never mutated.
+ *
+ * ```ts
+ * const host = createNodeProcessHostWithDotEnv()
+ * // equivalent to:
+ * // createNodeProcessHost({ environmentDefaults: loadDotEnvFile() })
+ * ```
+ */
+export declare function createNodeProcessHostWithDotEnv(options?: NodeProcessHostWithDotEnvOptions): ProcessHost;
 /** Node.js adapter for the reusable CLI process boundary. */
 export declare const nodeProcessHost: ProcessHost;
 //# sourceMappingURL=nodeProcessHost.d.ts.map

package/dist/node/nodeProcessHost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nodeProcessHost.d.ts","sourceRoot":"","sources":["../../src/nodeProcessHost.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,qBAAqB,CAAA;AA4BjE,6DAA6D;AAC7D,eAAO,MAAM,eAAe,EAAE,WAyB7B,CAAA"}
+{"version":3,"file":"nodeProcessHost.d.ts","sourceRoot":"","sources":["../../src/nodeProcessHost.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,qBAAqB,CAAA;AAEjE,OAAO,EAAkB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAChF,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AA4BnF;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;AAEtG,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,EAAE,SAAS,mBAAmB,EAA0B,CAAA;AAE9F,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAA;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,kBAAkB,CAAA;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAA;CAClD;AAED,MAAM,WAAW,gCAAiC,SAChD,sBAAsB,EAAE,qBAAqB;CAAG;AAElD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,WAAW,CAqCnF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,GAAE,gCAAqC,GAC7C,WAAW,CASb;AAED,6DAA6D;AAC7D,eAAO,MAAM,eAAe,EAAE,WAAqC,CAAA"}

package/dist/node/parseDotEnv.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parses dotenv-format content into a plain key/value map.
+ *
+ * Supports the common dotenv grammar used by local CLI configuration:
+ * - optional `export` prefix
+ * - single-quoted, double-quoted, and unquoted values
+ * - `#` comments (including trailing comments on unquoted values)
+ * - multi-line double-quoted values with `\\n` escape sequences
+ *
+ * Does not expand variable references (`$VAR` / `${VAR}`). Does not mutate
+ * `process.env`.
+ */
+export declare function parseDotEnv(content: string): Record<string, string>;
+//# sourceMappingURL=parseDotEnv.d.ts.map

package/dist/node/parseDotEnv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseDotEnv.d.ts","sourceRoot":"","sources":["../../src/parseDotEnv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgCnE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ariestools/cli-kit-node",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Node.js process adapter for reusable actor command-line applications",
   "keywords": [
     "ariestools",
@@ -44,17 +44,17 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@ariestools/cli-kit": "~1.0.0"
+    "@ariestools/cli-kit": "~1.0.1"
   },
   "devDependencies": {
     "@ariestools/toolchain": "~8.7.21",
     "@ariestools/tsconfig": "~8.7.21",
     "@types/node": "~26.1.1",
     "eslint": "~10.7.0",
+    "eslint-import-resolver-typescript": "~4.4.5",
     "typescript": "~6.0.3",
     "vite": "~8.1.5",
-    "vitest": "~4.1.10",
-    "eslint-import-resolver-typescript": "~4.4.5"
+    "vitest": "~4.1.10"
   },
   "engines": {
     "node": ">=24"