@ariestools/cli-kit-yargs 1.0.0 → 1.0.1

package/README.md

@@ -4,9 +4,16 @@ Yargs adapter for reusable actor command-line applications.
 
 The package keeps Yargs out of `@ariestools/cli-kit` while routing parser help, version, validation errors, asynchronous failures, and exits through the core `ProcessHost` boundary. This makes a configured CLI safe to exercise with a recording host instead of allowing Yargs to write to the ambient console or terminate the test process.
 
+`runYargsApplication` accepts an optional `mapFailureToExitCode` mapper applied to parser and handler failures alike: the mapper receives the failure origin (`'parse'` for validation failures, `'handler'` for handler or middleware rejections), returning a number selects the exit code, `undefined` retains the default exit code one, and help and error output are unchanged. A mapper that throws, or returns a code outside the integer range 0–255, falls back to exit code one. Intentional `ProcessExitError` exits pass through untouched.
+
 Use `environmentToYargsConfig` when an application owns config-file loading and wants to replace Yargs' process-global `.env()` lookup with an explicitly supplied environment. The resulting flat dotted object preserves Yargs' environment key normalization and can be passed to `.config()` before parsing:
 
 ```ts
+import { createNodeProcessHostWithDotEnv } from '@ariestools/cli-kit-node'
+import { environmentToYargsConfig, runYargsApplication } from '@ariestools/cli-kit-yargs'
+
+const host = createNodeProcessHostWithDotEnv()
+
 await runYargsApplication({
   host,
   configure: parser => parser
@@ -18,7 +25,7 @@ await runYargsApplication({
 })
 ```
 
-This conversion preserves command-line-over-environment precedence, but it is not a general substitute for `.env()` in applications that also use Yargs-native config-file options: Yargs ranks config objects below config files, and treats a top-level `extends` key in a config object specially. Such applications should resolve those precedence and reserved-key rules before passing the object to `.config()`.
+Load dotenv files through `@ariestools/cli-kit-node` (`loadDotEnvFile` / `createNodeProcessHostWithDotEnv`) so values reach `host.environment` without mutating `process.env`. This conversion preserves command-line-over-environment precedence, but it is not a general substitute for Yargs-native config-file options: Yargs ranks config objects below config files, and treats a top-level `extends` key in a config object specially. Such applications should resolve those precedence and reserved-key rules before passing the object to `.config()`.
 
 ## License
 

package/dist/node/index.mjs

@@ -37,7 +37,8 @@ function environmentToYargsConfig(environment, prefix) {
 // src/runYargsApplication.ts
 import {
   exitProcess,
-  ProcessExitError
+  ProcessExitError,
+  resolveFailureExitCode
 } from "@ariestools/cli-kit";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
@@ -55,6 +56,7 @@ function reportFailureHandlerError(host, result) {
 async function runYargsApplication({
   configure,
   host,
+  mapFailureToExitCode,
   onFailure
 }) {
   const applicationArguments = hideBin([...host.argv]);
@@ -72,7 +74,7 @@ async function runYargsApplication({
     host.io.error();
     host.io.error(error);
     reportFailureHandlerError(host, failureHandlerResult);
-    exitProcess(host, 1);
+    exitProcess(host, resolveFailureExitCode(mapFailureToExitCode, error, "handler"));
   }
   if (captured.error !== void 0) {
     const failureHandlerResult = await invokeFailureHandler(onFailure, captured.error);
@@ -82,7 +84,7 @@ async function runYargsApplication({
       host.io.error(captured.error);
     }
     reportFailureHandlerError(host, failureHandlerResult);
-    exitProcess(host, 1);
+    exitProcess(host, resolveFailureExitCode(mapFailureToExitCode, captured.error, "parse"));
   }
   if (captured.output.length > 0) {
     host.io.log(captured.output);

package/dist/node/index.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/environmentToYargsConfig.ts", "../../src/runYargsApplication.ts"],
-  "sourcesContent": ["export type CliEnvironment = Readonly<Record<string, string | undefined>>\n\n/**\n * Matches the segment normalization used by yargs-parser for environment keys.\n * Keeping this local avoids coupling the adapter to an unexported parser helper.\n */\nfunction camelCaseEnvironmentSegment(value: string): string {\n  const isCamelCase = value !== value.toLowerCase() && value !== value.toUpperCase()\n  const normalized = isCamelCase ? value : value.toLowerCase()\n  if (!normalized.includes('-') && !normalized.includes('_')) return normalized\n\n  let result = ''\n  let isNextCharacterUpper = false\n  const leadingHyphens = /^-+/.exec(normalized)\n  const start = leadingHyphens?.[0].length ?? 0\n  for (let index = start; index < normalized.length; index++) {\n    let character = normalized.charAt(index)\n    if (isNextCharacterUpper) {\n      isNextCharacterUpper = false\n      character = character.toUpperCase()\n    }\n    if (index !== 0 && (character === '-' || character === '_')) {\n      isNextCharacterUpper = true\n    } else if (character !== '-' && character !== '_') {\n      result += character\n    }\n  }\n  return result\n}\n\n/**\n * Converts a prefixed environment into the flat dotted config shape accepted\n * by Yargs. Values remain strings so Yargs applies its normal option typing and\n * coercion after command-line arguments have taken precedence.\n */\nexport function environmentToYargsConfig(\n  environment: CliEnvironment,\n  prefix: string,\n): Record<string, string | undefined> {\n  const config: Record<string, string | undefined> = {}\n  for (const [environmentName, environmentValue] of Object.entries(environment)) {\n    if (!environmentName.startsWith(prefix)) continue\n    const keys = environmentName.split('__').map((key, index) => {\n      return camelCaseEnvironmentSegment(index === 0 ? key.slice(prefix.length) : key)\n    })\n    const configKey = keys.join('.')\n    if (!Object.hasOwn(config, configKey)) config[configKey] = environmentValue\n  }\n  return config\n}\n", "import {\n  exitProcess, ProcessExitError, type ProcessHost,\n} from '@ariestools/cli-kit'\nimport type { Argv } from 'yargs'\nimport yargs from 'yargs'\nimport { hideBin } from 'yargs/helpers'\n\nexport interface RunYargsApplicationOptions {\n  readonly configure: (parser: Argv) => Argv\n  readonly host: ProcessHost\n  readonly onFailure?: (error: unknown) => Promise<void> | void\n}\n\ninterface CapturedParseOutput {\n  error: Error | undefined\n  output: string\n}\n\ninterface FailureHandlerResult {\n  readonly error?: unknown\n  readonly hasError: boolean\n}\n\nasync function invokeFailureHandler(\n  handler: RunYargsApplicationOptions['onFailure'],\n  error: unknown,\n): Promise<FailureHandlerResult> {\n  try {\n    await handler?.(error)\n    return { hasError: false }\n  } catch (failureHandlerError) {\n    return { error: failureHandlerError, hasError: true }\n  }\n}\n\nfunction reportFailureHandlerError(host: ProcessHost, result: FailureHandlerResult): void {\n  if (result.hasError) host.io.error('Error handling application failure:', result.error)\n}\n\n/**\n * Runs a configured Yargs app through the supplied process boundary.\n * Yargs' parse callback prevents its default console and process.exit calls;\n * the adapter then routes the equivalent output and exit through ProcessHost.\n */\nexport async function runYargsApplication({\n  configure,\n  host,\n  onFailure,\n}: RunYargsApplicationOptions): Promise<void> {\n  const applicationArguments = hideBin([...host.argv])\n  const parser = configure(yargs(applicationArguments))\n  const captured: CapturedParseOutput = { error: undefined, output: '' }\n\n  try {\n    await parser.parseAsync(applicationArguments, {}, (error, _argv, output) => {\n      // Yargs 18 reports `null` on success at runtime despite @types/yargs\n      // declaring this callback value as `Error | undefined`.\n      captured.error = error ?? undefined\n      captured.output = output\n    })\n  } catch (error) {\n    if (error instanceof ProcessExitError) throw error\n    const failureHandlerResult = await invokeFailureHandler(onFailure, error)\n    host.io.error(await parser.getHelp())\n    host.io.error()\n    host.io.error(error)\n    reportFailureHandlerError(host, failureHandlerResult)\n    exitProcess(host, 1)\n  }\n\n  if (captured.error !== undefined) {\n    const failureHandlerResult = await invokeFailureHandler(onFailure, captured.error)\n    if (captured.output.length > 0) {\n      host.io.error(captured.output)\n    } else {\n      host.io.error(captured.error)\n    }\n    reportFailureHandlerError(host, failureHandlerResult)\n    exitProcess(host, 1)\n  }\n\n  if (captured.output.length > 0) {\n    host.io.log(captured.output)\n    exitProcess(host, 0)\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["export type CliEnvironment = Readonly<Record<string, string | undefined>>\n\n/**\n * Matches the segment normalization used by yargs-parser for environment keys.\n * Keeping this local avoids coupling the adapter to an unexported parser helper.\n */\nfunction camelCaseEnvironmentSegment(value: string): string {\n  const isCamelCase = value !== value.toLowerCase() && value !== value.toUpperCase()\n  const normalized = isCamelCase ? value : value.toLowerCase()\n  if (!normalized.includes('-') && !normalized.includes('_')) return normalized\n\n  let result = ''\n  let isNextCharacterUpper = false\n  const leadingHyphens = /^-+/.exec(normalized)\n  const start = leadingHyphens?.[0].length ?? 0\n  for (let index = start; index < normalized.length; index++) {\n    let character = normalized.charAt(index)\n    if (isNextCharacterUpper) {\n      isNextCharacterUpper = false\n      character = character.toUpperCase()\n    }\n    if (index !== 0 && (character === '-' || character === '_')) {\n      isNextCharacterUpper = true\n    } else if (character !== '-' && character !== '_') {\n      result += character\n    }\n  }\n  return result\n}\n\n/**\n * Converts a prefixed environment into the flat dotted config shape accepted\n * by Yargs. Values remain strings so Yargs applies its normal option typing and\n * coercion after command-line arguments have taken precedence.\n */\nexport function environmentToYargsConfig(\n  environment: CliEnvironment,\n  prefix: string,\n): Record<string, string | undefined> {\n  const config: Record<string, string | undefined> = {}\n  for (const [environmentName, environmentValue] of Object.entries(environment)) {\n    if (!environmentName.startsWith(prefix)) continue\n    const keys = environmentName.split('__').map((key, index) => {\n      return camelCaseEnvironmentSegment(index === 0 ? key.slice(prefix.length) : key)\n    })\n    const configKey = keys.join('.')\n    if (!Object.hasOwn(config, configKey)) config[configKey] = environmentValue\n  }\n  return config\n}\n", "import {\n  exitProcess, type FailureExitCodeMapper, ProcessExitError, type ProcessHost, resolveFailureExitCode,\n} from '@ariestools/cli-kit'\nimport type { Argv } from 'yargs'\nimport yargs from 'yargs'\nimport { hideBin } from 'yargs/helpers'\n\nexport interface RunYargsApplicationOptions {\n  readonly configure: (parser: Argv) => Argv\n  readonly host: ProcessHost\n  /**\n   * Optional failure policy applied to parser and handler failures alike.\n   * The mapper receives the failure origin (`'parse'` for validation\n   * failures, `'handler'` for handler or middleware rejections) so exit\n   * codes such as `usage` versus `software` need no error sniffing.\n   * Returning a number selects the exit code; `undefined`, a thrown mapper,\n   * or a result outside the integer range 0\u2013255 retains the default exit\n   * code one. Intentional `ProcessExitError` exits are never offered to\n   * the mapper.\n   */\n  readonly mapFailureToExitCode?: FailureExitCodeMapper\n  readonly onFailure?: (error: unknown) => Promise<void> | void\n}\n\ninterface CapturedParseOutput {\n  error: Error | undefined\n  output: string\n}\n\ninterface FailureHandlerResult {\n  readonly error?: unknown\n  readonly hasError: boolean\n}\n\nasync function invokeFailureHandler(\n  handler: RunYargsApplicationOptions['onFailure'],\n  error: unknown,\n): Promise<FailureHandlerResult> {\n  try {\n    await handler?.(error)\n    return { hasError: false }\n  } catch (failureHandlerError) {\n    return { error: failureHandlerError, hasError: true }\n  }\n}\n\nfunction reportFailureHandlerError(host: ProcessHost, result: FailureHandlerResult): void {\n  if (result.hasError) host.io.error('Error handling application failure:', result.error)\n}\n\n/**\n * Runs a configured Yargs app through the supplied process boundary.\n * Yargs' parse callback prevents its default console and process.exit calls;\n * the adapter then routes the equivalent output and exit through ProcessHost.\n */\nexport async function runYargsApplication({\n  configure,\n  host,\n  mapFailureToExitCode,\n  onFailure,\n}: RunYargsApplicationOptions): Promise<void> {\n  const applicationArguments = hideBin([...host.argv])\n  const parser = configure(yargs(applicationArguments))\n  const captured: CapturedParseOutput = { error: undefined, output: '' }\n\n  try {\n    await parser.parseAsync(applicationArguments, {}, (error, _argv, output) => {\n      // Yargs 18 reports `null` on success at runtime despite @types/yargs\n      // declaring this callback value as `Error | undefined`.\n      captured.error = error ?? undefined\n      captured.output = output\n    })\n  } catch (error) {\n    if (error instanceof ProcessExitError) throw error\n    const failureHandlerResult = await invokeFailureHandler(onFailure, error)\n    host.io.error(await parser.getHelp())\n    host.io.error()\n    host.io.error(error)\n    reportFailureHandlerError(host, failureHandlerResult)\n    exitProcess(host, resolveFailureExitCode(mapFailureToExitCode, error, 'handler'))\n  }\n\n  if (captured.error !== undefined) {\n    const failureHandlerResult = await invokeFailureHandler(onFailure, captured.error)\n    if (captured.output.length > 0) {\n      host.io.error(captured.output)\n    } else {\n      host.io.error(captured.error)\n    }\n    reportFailureHandlerError(host, failureHandlerResult)\n    exitProcess(host, resolveFailureExitCode(mapFailureToExitCode, captured.error, 'parse'))\n  }\n\n  if (captured.output.length > 0) {\n    host.io.log(captured.output)\n    exitProcess(host, 0)\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/node/runYargsApplication.d.ts

@@ -1,8 +1,19 @@
-import { type ProcessHost } from '@ariestools/cli-kit';
+import { type FailureExitCodeMapper, type ProcessHost } from '@ariestools/cli-kit';
 import type { Argv } from 'yargs';
 export interface RunYargsApplicationOptions {
     readonly configure: (parser: Argv) => Argv;
     readonly host: ProcessHost;
+    /**
+     * Optional failure policy applied to parser and handler failures alike.
+     * The mapper receives the failure origin (`'parse'` for validation
+     * failures, `'handler'` for handler or middleware rejections) so exit
+     * codes such as `usage` versus `software` need no error sniffing.
+     * Returning a number selects the exit code; `undefined`, a thrown mapper,
+     * or a result outside the integer range 0–255 retains the default exit
+     * code one. Intentional `ProcessExitError` exits are never offered to
+     * the mapper.
+     */
+    readonly mapFailureToExitCode?: FailureExitCodeMapper;
     readonly onFailure?: (error: unknown) => Promise<void> | void;
 }
 /**
@@ -10,5 +21,5 @@ export interface RunYargsApplicationOptions {
  * Yargs' parse callback prevents its default console and process.exit calls;
  * the adapter then routes the equivalent output and exit through ProcessHost.
  */
-export declare function runYargsApplication({ configure, host, onFailure, }: RunYargsApplicationOptions): Promise<void>;
+export declare function runYargsApplication({ configure, host, mapFailureToExitCode, onFailure, }: RunYargsApplicationOptions): Promise<void>;
 //# sourceMappingURL=runYargsApplication.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"runYargsApplication.d.ts","sourceRoot":"","sources":["../../src/runYargsApplication.ts"],"names":[],"mappings":"AAAA,OAAO,EAC0B,KAAK,WAAW,EAChD,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAIjC,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,IAAI,KAAK,IAAI,CAAA;IAC1C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC9D;AA4BD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,EACxC,SAAS,EACT,IAAI,EACJ,SAAS,GACV,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAqC5C"}
+{"version":3,"file":"runYargsApplication.d.ts","sourceRoot":"","sources":["../../src/runYargsApplication.ts"],"names":[],"mappings":"AAAA,OAAO,EACQ,KAAK,qBAAqB,EAAoB,KAAK,WAAW,EAC5E,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAIjC,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,IAAI,KAAK,IAAI,CAAA;IAC1C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B;;;;;;;;;OASG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,qBAAqB,CAAA;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC9D;AA4BD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,EACxC,SAAS,EACT,IAAI,EACJ,oBAAoB,EACpB,SAAS,GACV,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAqC5C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ariestools/cli-kit-yargs",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Yargs adapter for reusable actor command-line applications",
   "keywords": [
     "ariestools",
@@ -46,16 +46,16 @@
   "dependencies": {
     "@types/yargs": "~17.0.35",
     "yargs": "~18.0.0",
-    "@ariestools/cli-kit": "~1.0.0"
+    "@ariestools/cli-kit": "~1.0.1"
   },
   "devDependencies": {
     "@ariestools/toolchain": "~8.7.21",
     "@ariestools/tsconfig": "~8.7.21",
     "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"