@ariestools/cli-kit-node

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 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.

Interrupt listeners start synchronously. A listener that throws or rejects is reported through the host's error output and requests exit 1. An exit already requested through that same host is preserved, and ProcessExitError retains its selected status. Hosts do not coordinate exit requests made through other hosts. Failures in diagnostic output or the exit boundary are contained so the interrupt handler does not produce another detached rejection.

Each binding snapshots and deduplicates its configured signals, so one physical signal is delivered once to that binding. If registration fails partway through, the host attempts to remove every owned listener it attempted, including the failing event. Successful rollback preserves the original error; distinct rollback failures aggregate. Disposal uses the captured signal set even if the caller later changes its array, attempts every removal, and surfaces removal failure. Other listeners are not removed. Failed removal is reported as failure, not proof that the handler was removed.

Passing this full Node host to runServiceUntilInterrupt or runCliSystemUntilInterrupt enables their bounded process policy: clean cleanup returns; a second interrupt requests exit 130 and the shutdown deadline requests exit 1. Supplying only onInterrupt retains the documented minimal-host path. Native signal behavior is qualified on Unix fixtures; Windows signal behavior remains a separate qualification target.

import { runProcessApplication } from '@ariestools/cli-kit'
import { nodeProcessHost } from '@ariestools/cli-kit-node'

await runProcessApplication({
  application: async (host) => {
    host.io.log('Application started')
  },
  host: nodeProcessHost,
})

Dotenv composition

Prefer loading local .env values into the host environment instead of mutating process.env. Precedence is active environment (the explicit override or live process.env), then dotenv values, then caller-provided environmentDefaults. Undefined values fall through to the next layer; empty strings remain defined values. The file and caller defaults are combined once when the host is created; the active environment remains live.

import { createNodeProcessHostWithDotEnv } from '@ariestools/cli-kit-node'
import { environmentToYargsConfig, runYargsApplication } from '@ariestools/cli-kit-yargs'

const host = createNodeProcessHostWithDotEnv({
  environmentDefaults: { XL1_PORT: '8080' },
})
// or explicitly:
// createNodeProcessHost({
//   environmentDefaults: mergeEnvironments(loadDotEnvFile({ path: '.env' }), { XL1_PORT: '8080' }),
// })

await runYargsApplication({
  host,
  configure: parser => parser
    .option('port', { type: 'number' })
    .config(environmentToYargsConfig(host.environment, 'XL1', { allowedKeys: ['port'] }))
    .scriptName('xl1')
    .strictOptions()
    .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 |

parseDotEnv follows dotenv's classic parser grammar, frozen against 17.2.3. The same classic grammar is used by the inspected 16.6.1 and 18.0.5/18.0.6 defaults. Optional export, comments, single/double/backtick quoting, multiline values, and permissive malformed input are retained. Only values starting with a double quote expand literal \n and \r; other escapes stay literal, and single quotes/backticks do not expand escapes. Variable references remain literal. Real CRLF and bare CR are normalized to LF before parsing.

Compatibility change: the kit's former additional backslash/quote decoding is removed. Windows paths, regular expressions, JSON, and credential strings that relied on that extra decoding can change. Repeated backslashes do not shield the classic parser's \n/\r expansion. Multiline CR bytes now become LF. An upstream parser excerpt, its BSD-2-Clause license, and a 110-case differential corpus are test-only fixtures; there is no new runtime dependency. Newline normalization adds a content scan and possible string allocation while two escape-decoding passes are removed. No throughput or strict worst-case bound is claimed.

Application code should depend on the ProcessHost contract from @ariestools/cli-kit. Use this package only at the Node.js composition boundary.

License

LGPL-3.0-only