@getargvio/yargs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 getargvio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @getargvio/yargs
+
+Auto-instruments a [yargs](https://github.com/yargs/yargs) command tree
+with [`@getargvio/argvio`](https://www.npmjs.com/package/@getargvio/argvio)
+CLI usage telemetry.
+
+## Install
+
+```sh
+npm install @getargvio/yargs
+```
+
+`yargs` is a peer dependency — bring your own (`>=17.0.0`).
+
+## Usage
+
+```ts
+import yargs from 'yargs'
+import { hideBin } from 'yargs/helpers'
+import { instrument } from '@getargvio/yargs'
+
+const y = yargs(hideBin(process.argv)).scriptName('mycli')
+// ... add commands as usual ...
+
+const { client } = instrument(y, process.env.MYCLI_ARGVIO_KEY ?? '', 'mycli', '1.4.0')
+
+const argv = await y.parseAsync()
+await client.shutdown(3000)
+```
+
+See [docs/yargs-integration.md](docs/yargs-integration.md) for exactly
+what's captured automatically, the `exitProcess(false)` requirement,
+and why `.fail()` behaves differently here than you might expect.
+
+## License
+
+MIT — see [LICENSE](../../LICENSE).

package/dist/index.cjs

@@ -0,0 +1,96 @@
+'use strict';
+
+var argvio = require('@getargvio/argvio');
+
+// src/index.ts
+var INVOCATION_MARKER = /* @__PURE__ */ Symbol("argvio.recordedInvocation");
+function extractFlagNames(rawArgs) {
+  const names = /* @__PURE__ */ new Set();
+  for (const token of rawArgs) {
+    if (!token.startsWith("-") || token === "-" || token === "--") continue;
+    const name = token.replace(/^--?/, "").split("=")[0];
+    if (name) names.add(name);
+  }
+  return [...names];
+}
+function commandPathFrom(argv) {
+  const script = typeof argv["$0"] === "string" ? argv["$0"] : "";
+  const segments = argv._.map((segment) => String(segment));
+  return [script, ...segments].filter(Boolean).join(" ");
+}
+function guessCommandPathFromRawArgs(rawArgs) {
+  const segments = [];
+  for (const token of rawArgs) {
+    if (token.startsWith("-")) break;
+    segments.push(token);
+  }
+  return segments.join(" ");
+}
+function instrumentYargs(yargsInstance, client, options = {}) {
+  const classify = options.classify ?? (() => argvio.ErrorCategory.Unknown);
+  const captureHelp = options.captureHelp ?? true;
+  const captureInvocation = options.captureInvocation ?? true;
+  const helpFlags = options.helpFlags ?? ["--help", "-h"];
+  yargsInstance.exitProcess(false);
+  let lastCommandPath = "";
+  let rawArgs = [];
+  if (captureInvocation) {
+    yargsInstance.middleware((argv) => {
+      const marker = argv;
+      if (marker[INVOCATION_MARKER]) return;
+      marker[INVOCATION_MARKER] = true;
+      lastCommandPath = commandPathFrom(argv);
+      client.recordCommandInvocation(lastCommandPath, extractFlagNames(rawArgs));
+    }, true);
+  }
+  yargsInstance.fail((msg, err, yi) => {
+    if (options.onFail) {
+      options.onFail(msg, err, yi);
+      return;
+    }
+    process.stderr.write(`${msg}
+`);
+    throw err ?? new Error(msg);
+  });
+  const wrapParse = (original) => {
+    return function wrapped(...args) {
+      const maybeArgs = args[0];
+      rawArgs = Array.isArray(maybeArgs) ? maybeArgs.map(String) : process.argv.slice(2);
+      if (captureHelp && helpFlags.some((flag) => rawArgs.includes(flag))) {
+        client.recordHelpFlagUsage(guessCommandPathFromRawArgs(rawArgs));
+      }
+      const start = Date.now();
+      let resultPromise;
+      try {
+        resultPromise = original.apply(this, args);
+      } catch (err) {
+        resultPromise = Promise.reject(err);
+      }
+      return resultPromise.then((result) => {
+        client.recordExitCode(lastCommandPath, 0);
+        client.recordLatency(lastCommandPath, Date.now() - start);
+        return result;
+      }).catch((err) => {
+        client.recordExitCode(lastCommandPath, 1);
+        client.recordLatency(lastCommandPath, Date.now() - start);
+        client.recordError(
+          lastCommandPath,
+          classify(err instanceof Error ? err : new Error(String(err)))
+        );
+        throw err;
+      });
+    };
+  };
+  yargsInstance.parseAsync = wrapParse(yargsInstance.parseAsync.bind(yargsInstance));
+  return yargsInstance;
+}
+function instrument(yargsInstance, apiKey, cliName, cliVersion, clientOptions = {}, hookOptions = {}) {
+  const client = argvio.createClient(apiKey, cliName, cliVersion, clientOptions);
+  instrumentYargs(yargsInstance, client, hookOptions);
+  return { client, yargs: yargsInstance };
+}
+
+exports.instrument = instrument;
+exports.instrumentYargs = instrumentYargs;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["ErrorCategory","createClient"],"mappings":";;;;;AAMA,IAAM,iBAAA,0BAA2B,2BAA2B,CAAA;AA4B5D,SAAS,iBAAiB,OAAA,EAAsC;AAC9D,EAAA,MAAM,KAAA,uBAAY,GAAA,EAAY;AAC9B,EAAA,KAAA,MAAW,SAAS,OAAA,EAAS;AAC3B,IAAA,IAAI,CAAC,MAAM,UAAA,CAAW,GAAG,KAAK,KAAA,KAAU,GAAA,IAAO,UAAU,IAAA,EAAM;AAC/D,IAAA,MAAM,IAAA,GAAO,MAAM,OAAA,CAAQ,MAAA,EAAQ,EAAE,CAAA,CAAE,KAAA,CAAM,GAAG,CAAA,CAAE,CAAC,CAAA;AACnD,IAAA,IAAI,IAAA,EAAM,KAAA,CAAM,GAAA,CAAI,IAAI,CAAA;AAAA,EAC1B;AACA,EAAA,OAAO,CAAC,GAAG,KAAK,CAAA;AAClB;AAEA,SAAS,gBAAgB,IAAA,EAAyB;AAChD,EAAA,MAAM,MAAA,GAAS,OAAO,IAAA,CAAK,IAAI,MAAM,QAAA,GAAW,IAAA,CAAK,IAAI,CAAA,GAAI,EAAA;AAC7D,EAAA,MAAM,QAAA,GAAW,KAAK,CAAA,CAAE,GAAA,CAAI,CAAC,OAAA,KAAY,MAAA,CAAO,OAAO,CAAC,CAAA;AACxD,EAAA,OAAO,CAAC,QAAQ,GAAG,QAAQ,EAAE,MAAA,CAAO,OAAO,CAAA,CAAE,IAAA,CAAK,GAAG,CAAA;AACvD;AAQA,SAAS,4BAA4B,OAAA,EAAoC;AACvE,EAAA,MAAM,WAAqB,EAAC;AAC5B,EAAA,KAAA,MAAW,SAAS,OAAA,EAAS;AAC3B,IAAA,IAAI,KAAA,CAAM,UAAA,CAAW,GAAG,CAAA,EAAG;AAC3B,IAAA,QAAA,CAAS,KAAK,KAAK,CAAA;AAAA,EACrB;AACA,EAAA,OAAO,QAAA,CAAS,KAAK,GAAG,CAAA;AAC1B;AAyBO,SAAS,eAAA,CACd,aAAA,EACA,MAAA,EACA,OAAA,GAA4B,EAAC,EACvB;AACN,EAAA,MAAM,QAAA,GAAW,OAAA,CAAQ,QAAA,KAAa,MAAMA,oBAAA,CAAc,OAAA,CAAA;AAC1D,EAAA,MAAM,WAAA,GAAc,QAAQ,WAAA,IAAe,IAAA;AAC3C,EAAA,MAAM,iBAAA,GAAoB,QAAQ,iBAAA,IAAqB,IAAA;AACvD,EAAA,MAAM,SAAA,GAAY,OAAA,CAAQ,SAAA,IAAa,CAAC,UAAU,IAAI,CAAA;AAEtD,EAAA,aAAA,CAAc,YAAY,KAAK,CAAA;AAE/B,EAAA,IAAI,eAAA,GAAkB,EAAA;AACtB,EAAA,IAAI,UAA6B,EAAC;AAElC,EAAA,IAAI,iBAAA,EAAmB;AACrB,IAAA,aAAA,CAAc,UAAA,CAAW,CAAC,IAAA,KAAS;AACjC,MAAA,MAAM,MAAA,GAAS,IAAA;AACf,MAAA,IAAI,MAAA,CAAO,iBAAiB,CAAA,EAAG;AAC/B,MAAA,MAAA,CAAO,iBAAiB,CAAA,GAAI,IAAA;AAE5B,MAAA,eAAA,GAAkB,gBAAgB,IAAI,CAAA;AACtC,MAAA,MAAA,CAAO,uBAAA,CAAwB,eAAA,EAAiB,gBAAA,CAAiB,OAAO,CAAC,CAAA;AAAA,IAC3E,GAAG,IAAI,CAAA;AAAA,EACT;AAcA,EAAA,aAAA,CAAc,IAAA,CAAK,CAAC,GAAA,EAAK,GAAA,EAAK,EAAA,KAAO;AACnC,IAAA,IAAI,QAAQ,MAAA,EAAQ;AAClB,MAAA,OAAA,CAAQ,MAAA,CAAO,GAAA,EAAK,GAAA,EAAK,EAAE,CAAA;AAC3B,MAAA;AAAA,IACF;AACA,IAAA,OAAA,CAAQ,MAAA,CAAO,KAAA,CAAM,CAAA,EAAG,GAAG;AAAA,CAAI,CAAA;AAC/B,IAAA,MAAM,GAAA,IAAO,IAAI,KAAA,CAAM,GAAG,CAAA;AAAA,EAC5B,CAAC,CAAA;AAED,EAAA,MAAM,SAAA,GAAY,CAAC,QAAA,KAA+B;AAChD,IAAA,OAAO,SAAS,WAAuB,IAAA,EAA2B;AAChE,MAAA,MAAM,SAAA,GAAY,KAAK,CAAC,CAAA;AACxB,MAAA,OAAA,GAAU,KAAA,CAAM,OAAA,CAAQ,SAAS,CAAA,GAAI,SAAA,CAAU,GAAA,CAAI,MAAM,CAAA,GAAI,OAAA,CAAQ,IAAA,CAAK,KAAA,CAAM,CAAC,CAAA;AAEjF,MAAA,IAAI,WAAA,IAAe,UAAU,IAAA,CAAK,CAAC,SAAS,OAAA,CAAQ,QAAA,CAAS,IAAI,CAAC,CAAA,EAAG;AACnE,QAAA,MAAA,CAAO,mBAAA,CAAoB,2BAAA,CAA4B,OAAO,CAAC,CAAA;AAAA,MACjE;AAEA,MAAA,MAAM,KAAA,GAAQ,KAAK,GAAA,EAAI;AACvB,MAAA,IAAI,aAAA;AACJ,MAAA,IAAI;AAMF,QAAA,aAAA,GAAiB,QAAA,CAAmD,KAAA,CAAM,IAAA,EAAM,IAAI,CAAA;AAAA,MACtF,SAAS,GAAA,EAAK;AACZ,QAAA,aAAA,GAAgB,OAAA,CAAQ,OAAO,GAAG,CAAA;AAAA,MACpC;AACA,MAAA,OAAO,aAAA,CACJ,IAAA,CAAK,CAAC,MAAA,KAAoB;AACzB,QAAA,MAAA,CAAO,cAAA,CAAe,iBAAiB,CAAC,CAAA;AACxC,QAAA,MAAA,CAAO,aAAA,CAAc,eAAA,EAAiB,IAAA,CAAK,GAAA,KAAQ,KAAK,CAAA;AACxD,QAAA,OAAO,MAAA;AAAA,MACT,CAAC,CAAA,CACA,KAAA,CAAM,CAAC,GAAA,KAAiB;AACvB,QAAA,MAAA,CAAO,cAAA,CAAe,iBAAiB,CAAC,CAAA;AACxC,QAAA,MAAA,CAAO,aAAA,CAAc,eAAA,EAAiB,IAAA,CAAK,GAAA,KAAQ,KAAK,CAAA;AACxD,QAAA,MAAA,CAAO,WAAA;AAAA,UACL,eAAA;AAAA,UACA,QAAA,CAAS,eAAe,KAAA,GAAQ,GAAA,GAAM,IAAI,KAAA,CAAM,MAAA,CAAO,GAAG,CAAC,CAAC;AAAA,SAC9D;AACA,QAAA,MAAM,GAAA;AAAA,MACR,CAAC,CAAA;AAAA,IACL,CAAA;AAAA,EACF,CAAA;AAEA,EAAA,aAAA,CAAc,aAAa,SAAA,CAAU,aAAA,CAAc,UAAA,CAAW,IAAA,CAAK,aAAa,CAAC,CAAA;AAEjF,EAAA,OAAO,aAAA;AACT;AAWO,SAAS,UAAA,CACd,aAAA,EACA,MAAA,EACA,OAAA,EACA,UAAA,EACA,gBAA+B,EAAC,EAChC,WAAA,GAAgC,EAAC,EACA;AACjC,EAAA,MAAM,MAAA,GAASC,mBAAA,CAAa,MAAA,EAAQ,OAAA,EAAS,YAAY,aAAa,CAAA;AACtE,EAAA,eAAA,CAAgB,aAAA,EAAe,QAAQ,WAAW,CAAA;AAClD,EAAA,OAAO,EAAE,MAAA,EAAQ,KAAA,EAAO,aAAA,EAAc;AACxC","file":"index.cjs","sourcesContent":["import type { Argv, Arguments } from 'yargs'\n\nimport type { Client, ClientOptions } from '@getargvio/argvio'\nimport { createClient, ErrorCategory } from '@getargvio/argvio'\nimport type { ErrorCategory as ErrorCategoryType } from '@getargvio/argvio'\n\nconst INVOCATION_MARKER = Symbol('argvio.recordedInvocation')\n\n/** Configures {@link instrumentYargs}. */\nexport interface YargsHookOptions {\n  /** Maps a caught error to an {@link ErrorCategoryType}. Without it, every error is recorded as `ErrorCategory.Unknown`. */\n  classify?: (err: Error) => ErrorCategoryType\n  /** Skip the best-effort help-flag capture (see docs/yargs-integration.md for why it's best-effort). */\n  captureHelp?: boolean\n  /** Skip the `middleware`-based command-invocation capture. */\n  captureInvocation?: boolean\n  /**\n   * Called from inside the installed `.fail()` handler instead of this\n   * package's default print-and-rethrow behavior. Use this if you\n   * already have your own `.fail()` logic you want preserved —\n   * `instrumentYargs` cannot chain with a pre-existing `.fail()` handler\n   * the way it can with `middleware` (see docs/yargs-integration.md).\n   * Error/exit-code recording itself always happens uniformly in the\n   * wrapped `parseAsync`, regardless of whether `onFail` is set. Note\n   * `.fail()` only fires for validation errors and *rejected* async\n   * handlers — for the async-rejection case specifically, yargs invokes\n   * `.fail()` purely as a side effect and swallows anything it throws,\n   * so `onFail` cannot change whether the original rejection propagates.\n   */\n  onFail?: (msg: string, err: Error | undefined, yargsInstance: Argv) => void\n  /** Flag tokens treated as a help request for the best-effort help capture. Defaults to `['--help', '-h']`. */\n  helpFlags?: readonly string[]\n}\n\nfunction extractFlagNames(rawArgs: readonly string[]): string[] {\n  const names = new Set<string>()\n  for (const token of rawArgs) {\n    if (!token.startsWith('-') || token === '-' || token === '--') continue\n    const name = token.replace(/^--?/, '').split('=')[0]\n    if (name) names.add(name)\n  }\n  return [...names]\n}\n\nfunction commandPathFrom(argv: Arguments): string {\n  const script = typeof argv['$0'] === 'string' ? argv['$0'] : ''\n  const segments = argv._.map((segment) => String(segment))\n  return [script, ...segments].filter(Boolean).join(' ')\n}\n\n/**\n * Best-effort command path guess before parsing has happened (used for\n * help capture, which fires before yargs has resolved a command path\n * of its own). No CLI name prefix — the builder-side `Argv` has no\n * public getter for `scriptName`, only a setter.\n */\nfunction guessCommandPathFromRawArgs(rawArgs: readonly string[]): string {\n  const segments: string[] = []\n  for (const token of rawArgs) {\n    if (token.startsWith('-')) break\n    segments.push(token)\n  }\n  return segments.join(' ')\n}\n\ntype ParseFn = Argv['parseAsync']\n\n/**\n * Wires automatic telemetry capture into a yargs instance:\n *\n * - Command path + flag names (see `Client.recordCommandInvocation`) are\n *   captured via global `middleware(fn, true)` — applied before\n *   validation, so it still runs even if validation later fails.\n * - Exit code, latency, and errors are captured by wrapping\n *   `parseAsync`/`parse` — the one place guaranteed to run exactly once\n *   per invocation, regardless of success or failure.\n * - Help usage is captured on a **best-effort** basis: yargs handles\n *   `--help`/`-h` internally before middleware, `.fail()`, or any\n *   command handler ever runs, so this package scans the raw args\n *   for help flags *before* calling the real parse.\n *\n * Calls `yargsInstance.exitProcess(false)`: with the default\n * `exitProcess(true)`, yargs calls `process.exit()` itself on failure or\n * `--help`, before this package's wrapped `parseAsync`/`.fail()` ever\n * get a chance to record anything. After instrumenting, your own code\n * must await `parseAsync()` and decide the real process exit itself —\n * see docs/yargs-integration.md.\n */\nexport function instrumentYargs(\n  yargsInstance: Argv,\n  client: Client,\n  options: YargsHookOptions = {},\n): Argv {\n  const classify = options.classify ?? (() => ErrorCategory.Unknown)\n  const captureHelp = options.captureHelp ?? true\n  const captureInvocation = options.captureInvocation ?? true\n  const helpFlags = options.helpFlags ?? ['--help', '-h']\n\n  yargsInstance.exitProcess(false)\n\n  let lastCommandPath = ''\n  let rawArgs: readonly string[] = []\n\n  if (captureInvocation) {\n    yargsInstance.middleware((argv) => {\n      const marker = argv as unknown as Record<symbol, boolean>\n      if (marker[INVOCATION_MARKER]) return\n      marker[INVOCATION_MARKER] = true\n\n      lastCommandPath = commandPathFrom(argv)\n      client.recordCommandInvocation(lastCommandPath, extractFlagNames(rawArgs))\n    }, true)\n  }\n\n  // yargs only ever routes a failure through `.fail()` for validation\n  // errors and *rejected* async handlers — a handler that throws\n  // synchronously bypasses `.fail()` entirely and propagates straight\n  // out of `parse()`/`parseAsync()`. So `.fail()` here does not itself\n  // record anything (that would double-count the async-rejection case\n  // and miss the synchronous-throw case); its only jobs are (a) letting\n  // a vendor plug in `onFail`, and (b) — critically — converting a\n  // validation failure into an actual thrown error. Without this, with\n  // `exitProcess(false)`, yargs' default fail behavior swallows the\n  // failure and `parseAsync()` would resolve as if nothing went wrong.\n  // Error/exit-code/latency recording happens uniformly for every\n  // failure mode in the `parseAsync` wrapper's `catch` below instead.\n  yargsInstance.fail((msg, err, yi) => {\n    if (options.onFail) {\n      options.onFail(msg, err, yi)\n      return\n    }\n    process.stderr.write(`${msg}\\n`)\n    throw err ?? new Error(msg)\n  })\n\n  const wrapParse = (original: ParseFn): ParseFn => {\n    return function wrapped(this: Argv, ...args: Parameters<ParseFn>) {\n      const maybeArgs = args[0]\n      rawArgs = Array.isArray(maybeArgs) ? maybeArgs.map(String) : process.argv.slice(2)\n\n      if (captureHelp && helpFlags.some((flag) => rawArgs.includes(flag))) {\n        client.recordHelpFlagUsage(guessCommandPathFromRawArgs(rawArgs))\n      }\n\n      const start = Date.now()\n      let resultPromise: Promise<unknown>\n      try {\n        // A command handler that throws synchronously (as opposed to\n        // returning a rejected Promise) makes yargs' own `parse()`\n        // throw synchronously too, bypassing `.fail()` entirely — this\n        // try/catch normalizes that into a rejected promise so both\n        // failure modes go through the same recording path below.\n        resultPromise = (original as (...a: unknown[]) => Promise<unknown>).apply(this, args)\n      } catch (err) {\n        resultPromise = Promise.reject(err)\n      }\n      return resultPromise\n        .then((result: unknown) => {\n          client.recordExitCode(lastCommandPath, 0)\n          client.recordLatency(lastCommandPath, Date.now() - start)\n          return result\n        })\n        .catch((err: unknown) => {\n          client.recordExitCode(lastCommandPath, 1)\n          client.recordLatency(lastCommandPath, Date.now() - start)\n          client.recordError(\n            lastCommandPath,\n            classify(err instanceof Error ? err : new Error(String(err))),\n          )\n          throw err\n        })\n    } as ParseFn\n  }\n\n  yargsInstance.parseAsync = wrapParse(yargsInstance.parseAsync.bind(yargsInstance))\n\n  return yargsInstance\n}\n\n/**\n * Builds a `Client` (using `cliName`/`cliVersion` you provide — yargs\n * has no built-in fields to read them from) and calls\n * {@link instrumentYargs} to wire up capture.\n *\n *     const { client } = instrument(yargsInstance, apiKey, 'mycli', '1.4.0')\n *     const argv = await yargsInstance.parseAsync()\n *     await client.shutdown()\n */\nexport function instrument(\n  yargsInstance: Argv,\n  apiKey: string,\n  cliName: string,\n  cliVersion: string,\n  clientOptions: ClientOptions = {},\n  hookOptions: YargsHookOptions = {},\n): { client: Client; yargs: Argv } {\n  const client = createClient(apiKey, cliName, cliVersion, clientOptions)\n  instrumentYargs(yargsInstance, client, hookOptions)\n  return { client, yargs: yargsInstance }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,65 @@
+import { Argv } from 'yargs';
+import { ErrorCategory, ClientOptions, Client } from '@getargvio/argvio';
+
+/** Configures {@link instrumentYargs}. */
+interface YargsHookOptions {
+    /** Maps a caught error to an {@link ErrorCategoryType}. Without it, every error is recorded as `ErrorCategory.Unknown`. */
+    classify?: (err: Error) => ErrorCategory;
+    /** Skip the best-effort help-flag capture (see docs/yargs-integration.md for why it's best-effort). */
+    captureHelp?: boolean;
+    /** Skip the `middleware`-based command-invocation capture. */
+    captureInvocation?: boolean;
+    /**
+     * Called from inside the installed `.fail()` handler instead of this
+     * package's default print-and-rethrow behavior. Use this if you
+     * already have your own `.fail()` logic you want preserved —
+     * `instrumentYargs` cannot chain with a pre-existing `.fail()` handler
+     * the way it can with `middleware` (see docs/yargs-integration.md).
+     * Error/exit-code recording itself always happens uniformly in the
+     * wrapped `parseAsync`, regardless of whether `onFail` is set. Note
+     * `.fail()` only fires for validation errors and *rejected* async
+     * handlers — for the async-rejection case specifically, yargs invokes
+     * `.fail()` purely as a side effect and swallows anything it throws,
+     * so `onFail` cannot change whether the original rejection propagates.
+     */
+    onFail?: (msg: string, err: Error | undefined, yargsInstance: Argv) => void;
+    /** Flag tokens treated as a help request for the best-effort help capture. Defaults to `['--help', '-h']`. */
+    helpFlags?: readonly string[];
+}
+/**
+ * Wires automatic telemetry capture into a yargs instance:
+ *
+ * - Command path + flag names (see `Client.recordCommandInvocation`) are
+ *   captured via global `middleware(fn, true)` — applied before
+ *   validation, so it still runs even if validation later fails.
+ * - Exit code, latency, and errors are captured by wrapping
+ *   `parseAsync`/`parse` — the one place guaranteed to run exactly once
+ *   per invocation, regardless of success or failure.
+ * - Help usage is captured on a **best-effort** basis: yargs handles
+ *   `--help`/`-h` internally before middleware, `.fail()`, or any
+ *   command handler ever runs, so this package scans the raw args
+ *   for help flags *before* calling the real parse.
+ *
+ * Calls `yargsInstance.exitProcess(false)`: with the default
+ * `exitProcess(true)`, yargs calls `process.exit()` itself on failure or
+ * `--help`, before this package's wrapped `parseAsync`/`.fail()` ever
+ * get a chance to record anything. After instrumenting, your own code
+ * must await `parseAsync()` and decide the real process exit itself —
+ * see docs/yargs-integration.md.
+ */
+declare function instrumentYargs(yargsInstance: Argv, client: Client, options?: YargsHookOptions): Argv;
+/**
+ * Builds a `Client` (using `cliName`/`cliVersion` you provide — yargs
+ * has no built-in fields to read them from) and calls
+ * {@link instrumentYargs} to wire up capture.
+ *
+ *     const { client } = instrument(yargsInstance, apiKey, 'mycli', '1.4.0')
+ *     const argv = await yargsInstance.parseAsync()
+ *     await client.shutdown()
+ */
+declare function instrument(yargsInstance: Argv, apiKey: string, cliName: string, cliVersion: string, clientOptions?: ClientOptions, hookOptions?: YargsHookOptions): {
+    client: Client;
+    yargs: Argv;
+};
+
+export { type YargsHookOptions, instrument, instrumentYargs };

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import { Argv } from 'yargs';
+import { ErrorCategory, ClientOptions, Client } from '@getargvio/argvio';
+
+/** Configures {@link instrumentYargs}. */
+interface YargsHookOptions {
+    /** Maps a caught error to an {@link ErrorCategoryType}. Without it, every error is recorded as `ErrorCategory.Unknown`. */
+    classify?: (err: Error) => ErrorCategory;
+    /** Skip the best-effort help-flag capture (see docs/yargs-integration.md for why it's best-effort). */
+    captureHelp?: boolean;
+    /** Skip the `middleware`-based command-invocation capture. */
+    captureInvocation?: boolean;
+    /**
+     * Called from inside the installed `.fail()` handler instead of this
+     * package's default print-and-rethrow behavior. Use this if you
+     * already have your own `.fail()` logic you want preserved —
+     * `instrumentYargs` cannot chain with a pre-existing `.fail()` handler
+     * the way it can with `middleware` (see docs/yargs-integration.md).
+     * Error/exit-code recording itself always happens uniformly in the
+     * wrapped `parseAsync`, regardless of whether `onFail` is set. Note
+     * `.fail()` only fires for validation errors and *rejected* async
+     * handlers — for the async-rejection case specifically, yargs invokes
+     * `.fail()` purely as a side effect and swallows anything it throws,
+     * so `onFail` cannot change whether the original rejection propagates.
+     */
+    onFail?: (msg: string, err: Error | undefined, yargsInstance: Argv) => void;
+    /** Flag tokens treated as a help request for the best-effort help capture. Defaults to `['--help', '-h']`. */
+    helpFlags?: readonly string[];
+}
+/**
+ * Wires automatic telemetry capture into a yargs instance:
+ *
+ * - Command path + flag names (see `Client.recordCommandInvocation`) are
+ *   captured via global `middleware(fn, true)` — applied before
+ *   validation, so it still runs even if validation later fails.
+ * - Exit code, latency, and errors are captured by wrapping
+ *   `parseAsync`/`parse` — the one place guaranteed to run exactly once
+ *   per invocation, regardless of success or failure.
+ * - Help usage is captured on a **best-effort** basis: yargs handles
+ *   `--help`/`-h` internally before middleware, `.fail()`, or any
+ *   command handler ever runs, so this package scans the raw args
+ *   for help flags *before* calling the real parse.
+ *
+ * Calls `yargsInstance.exitProcess(false)`: with the default
+ * `exitProcess(true)`, yargs calls `process.exit()` itself on failure or
+ * `--help`, before this package's wrapped `parseAsync`/`.fail()` ever
+ * get a chance to record anything. After instrumenting, your own code
+ * must await `parseAsync()` and decide the real process exit itself —
+ * see docs/yargs-integration.md.
+ */
+declare function instrumentYargs(yargsInstance: Argv, client: Client, options?: YargsHookOptions): Argv;
+/**
+ * Builds a `Client` (using `cliName`/`cliVersion` you provide — yargs
+ * has no built-in fields to read them from) and calls
+ * {@link instrumentYargs} to wire up capture.
+ *
+ *     const { client } = instrument(yargsInstance, apiKey, 'mycli', '1.4.0')
+ *     const argv = await yargsInstance.parseAsync()
+ *     await client.shutdown()
+ */
+declare function instrument(yargsInstance: Argv, apiKey: string, cliName: string, cliVersion: string, clientOptions?: ClientOptions, hookOptions?: YargsHookOptions): {
+    client: Client;
+    yargs: Argv;
+};
+
+export { type YargsHookOptions, instrument, instrumentYargs };

package/dist/index.js

@@ -0,0 +1,93 @@
+import { ErrorCategory, createClient } from '@getargvio/argvio';
+
+// src/index.ts
+var INVOCATION_MARKER = /* @__PURE__ */ Symbol("argvio.recordedInvocation");
+function extractFlagNames(rawArgs) {
+  const names = /* @__PURE__ */ new Set();
+  for (const token of rawArgs) {
+    if (!token.startsWith("-") || token === "-" || token === "--") continue;
+    const name = token.replace(/^--?/, "").split("=")[0];
+    if (name) names.add(name);
+  }
+  return [...names];
+}
+function commandPathFrom(argv) {
+  const script = typeof argv["$0"] === "string" ? argv["$0"] : "";
+  const segments = argv._.map((segment) => String(segment));
+  return [script, ...segments].filter(Boolean).join(" ");
+}
+function guessCommandPathFromRawArgs(rawArgs) {
+  const segments = [];
+  for (const token of rawArgs) {
+    if (token.startsWith("-")) break;
+    segments.push(token);
+  }
+  return segments.join(" ");
+}
+function instrumentYargs(yargsInstance, client, options = {}) {
+  const classify = options.classify ?? (() => ErrorCategory.Unknown);
+  const captureHelp = options.captureHelp ?? true;
+  const captureInvocation = options.captureInvocation ?? true;
+  const helpFlags = options.helpFlags ?? ["--help", "-h"];
+  yargsInstance.exitProcess(false);
+  let lastCommandPath = "";
+  let rawArgs = [];
+  if (captureInvocation) {
+    yargsInstance.middleware((argv) => {
+      const marker = argv;
+      if (marker[INVOCATION_MARKER]) return;
+      marker[INVOCATION_MARKER] = true;
+      lastCommandPath = commandPathFrom(argv);
+      client.recordCommandInvocation(lastCommandPath, extractFlagNames(rawArgs));
+    }, true);
+  }
+  yargsInstance.fail((msg, err, yi) => {
+    if (options.onFail) {
+      options.onFail(msg, err, yi);
+      return;
+    }
+    process.stderr.write(`${msg}
+`);
+    throw err ?? new Error(msg);
+  });
+  const wrapParse = (original) => {
+    return function wrapped(...args) {
+      const maybeArgs = args[0];
+      rawArgs = Array.isArray(maybeArgs) ? maybeArgs.map(String) : process.argv.slice(2);
+      if (captureHelp && helpFlags.some((flag) => rawArgs.includes(flag))) {
+        client.recordHelpFlagUsage(guessCommandPathFromRawArgs(rawArgs));
+      }
+      const start = Date.now();
+      let resultPromise;
+      try {
+        resultPromise = original.apply(this, args);
+      } catch (err) {
+        resultPromise = Promise.reject(err);
+      }
+      return resultPromise.then((result) => {
+        client.recordExitCode(lastCommandPath, 0);
+        client.recordLatency(lastCommandPath, Date.now() - start);
+        return result;
+      }).catch((err) => {
+        client.recordExitCode(lastCommandPath, 1);
+        client.recordLatency(lastCommandPath, Date.now() - start);
+        client.recordError(
+          lastCommandPath,
+          classify(err instanceof Error ? err : new Error(String(err)))
+        );
+        throw err;
+      });
+    };
+  };
+  yargsInstance.parseAsync = wrapParse(yargsInstance.parseAsync.bind(yargsInstance));
+  return yargsInstance;
+}
+function instrument(yargsInstance, apiKey, cliName, cliVersion, clientOptions = {}, hookOptions = {}) {
+  const client = createClient(apiKey, cliName, cliVersion, clientOptions);
+  instrumentYargs(yargsInstance, client, hookOptions);
+  return { client, yargs: yargsInstance };
+}
+
+export { instrument, instrumentYargs };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { Argv, Arguments } from 'yargs'\n\nimport type { Client, ClientOptions } from '@getargvio/argvio'\nimport { createClient, ErrorCategory } from '@getargvio/argvio'\nimport type { ErrorCategory as ErrorCategoryType } from '@getargvio/argvio'\n\nconst INVOCATION_MARKER = Symbol('argvio.recordedInvocation')\n\n/** Configures {@link instrumentYargs}. */\nexport interface YargsHookOptions {\n  /** Maps a caught error to an {@link ErrorCategoryType}. Without it, every error is recorded as `ErrorCategory.Unknown`. */\n  classify?: (err: Error) => ErrorCategoryType\n  /** Skip the best-effort help-flag capture (see docs/yargs-integration.md for why it's best-effort). */\n  captureHelp?: boolean\n  /** Skip the `middleware`-based command-invocation capture. */\n  captureInvocation?: boolean\n  /**\n   * Called from inside the installed `.fail()` handler instead of this\n   * package's default print-and-rethrow behavior. Use this if you\n   * already have your own `.fail()` logic you want preserved —\n   * `instrumentYargs` cannot chain with a pre-existing `.fail()` handler\n   * the way it can with `middleware` (see docs/yargs-integration.md).\n   * Error/exit-code recording itself always happens uniformly in the\n   * wrapped `parseAsync`, regardless of whether `onFail` is set. Note\n   * `.fail()` only fires for validation errors and *rejected* async\n   * handlers — for the async-rejection case specifically, yargs invokes\n   * `.fail()` purely as a side effect and swallows anything it throws,\n   * so `onFail` cannot change whether the original rejection propagates.\n   */\n  onFail?: (msg: string, err: Error | undefined, yargsInstance: Argv) => void\n  /** Flag tokens treated as a help request for the best-effort help capture. Defaults to `['--help', '-h']`. */\n  helpFlags?: readonly string[]\n}\n\nfunction extractFlagNames(rawArgs: readonly string[]): string[] {\n  const names = new Set<string>()\n  for (const token of rawArgs) {\n    if (!token.startsWith('-') || token === '-' || token === '--') continue\n    const name = token.replace(/^--?/, '').split('=')[0]\n    if (name) names.add(name)\n  }\n  return [...names]\n}\n\nfunction commandPathFrom(argv: Arguments): string {\n  const script = typeof argv['$0'] === 'string' ? argv['$0'] : ''\n  const segments = argv._.map((segment) => String(segment))\n  return [script, ...segments].filter(Boolean).join(' ')\n}\n\n/**\n * Best-effort command path guess before parsing has happened (used for\n * help capture, which fires before yargs has resolved a command path\n * of its own). No CLI name prefix — the builder-side `Argv` has no\n * public getter for `scriptName`, only a setter.\n */\nfunction guessCommandPathFromRawArgs(rawArgs: readonly string[]): string {\n  const segments: string[] = []\n  for (const token of rawArgs) {\n    if (token.startsWith('-')) break\n    segments.push(token)\n  }\n  return segments.join(' ')\n}\n\ntype ParseFn = Argv['parseAsync']\n\n/**\n * Wires automatic telemetry capture into a yargs instance:\n *\n * - Command path + flag names (see `Client.recordCommandInvocation`) are\n *   captured via global `middleware(fn, true)` — applied before\n *   validation, so it still runs even if validation later fails.\n * - Exit code, latency, and errors are captured by wrapping\n *   `parseAsync`/`parse` — the one place guaranteed to run exactly once\n *   per invocation, regardless of success or failure.\n * - Help usage is captured on a **best-effort** basis: yargs handles\n *   `--help`/`-h` internally before middleware, `.fail()`, or any\n *   command handler ever runs, so this package scans the raw args\n *   for help flags *before* calling the real parse.\n *\n * Calls `yargsInstance.exitProcess(false)`: with the default\n * `exitProcess(true)`, yargs calls `process.exit()` itself on failure or\n * `--help`, before this package's wrapped `parseAsync`/`.fail()` ever\n * get a chance to record anything. After instrumenting, your own code\n * must await `parseAsync()` and decide the real process exit itself —\n * see docs/yargs-integration.md.\n */\nexport function instrumentYargs(\n  yargsInstance: Argv,\n  client: Client,\n  options: YargsHookOptions = {},\n): Argv {\n  const classify = options.classify ?? (() => ErrorCategory.Unknown)\n  const captureHelp = options.captureHelp ?? true\n  const captureInvocation = options.captureInvocation ?? true\n  const helpFlags = options.helpFlags ?? ['--help', '-h']\n\n  yargsInstance.exitProcess(false)\n\n  let lastCommandPath = ''\n  let rawArgs: readonly string[] = []\n\n  if (captureInvocation) {\n    yargsInstance.middleware((argv) => {\n      const marker = argv as unknown as Record<symbol, boolean>\n      if (marker[INVOCATION_MARKER]) return\n      marker[INVOCATION_MARKER] = true\n\n      lastCommandPath = commandPathFrom(argv)\n      client.recordCommandInvocation(lastCommandPath, extractFlagNames(rawArgs))\n    }, true)\n  }\n\n  // yargs only ever routes a failure through `.fail()` for validation\n  // errors and *rejected* async handlers — a handler that throws\n  // synchronously bypasses `.fail()` entirely and propagates straight\n  // out of `parse()`/`parseAsync()`. So `.fail()` here does not itself\n  // record anything (that would double-count the async-rejection case\n  // and miss the synchronous-throw case); its only jobs are (a) letting\n  // a vendor plug in `onFail`, and (b) — critically — converting a\n  // validation failure into an actual thrown error. Without this, with\n  // `exitProcess(false)`, yargs' default fail behavior swallows the\n  // failure and `parseAsync()` would resolve as if nothing went wrong.\n  // Error/exit-code/latency recording happens uniformly for every\n  // failure mode in the `parseAsync` wrapper's `catch` below instead.\n  yargsInstance.fail((msg, err, yi) => {\n    if (options.onFail) {\n      options.onFail(msg, err, yi)\n      return\n    }\n    process.stderr.write(`${msg}\\n`)\n    throw err ?? new Error(msg)\n  })\n\n  const wrapParse = (original: ParseFn): ParseFn => {\n    return function wrapped(this: Argv, ...args: Parameters<ParseFn>) {\n      const maybeArgs = args[0]\n      rawArgs = Array.isArray(maybeArgs) ? maybeArgs.map(String) : process.argv.slice(2)\n\n      if (captureHelp && helpFlags.some((flag) => rawArgs.includes(flag))) {\n        client.recordHelpFlagUsage(guessCommandPathFromRawArgs(rawArgs))\n      }\n\n      const start = Date.now()\n      let resultPromise: Promise<unknown>\n      try {\n        // A command handler that throws synchronously (as opposed to\n        // returning a rejected Promise) makes yargs' own `parse()`\n        // throw synchronously too, bypassing `.fail()` entirely — this\n        // try/catch normalizes that into a rejected promise so both\n        // failure modes go through the same recording path below.\n        resultPromise = (original as (...a: unknown[]) => Promise<unknown>).apply(this, args)\n      } catch (err) {\n        resultPromise = Promise.reject(err)\n      }\n      return resultPromise\n        .then((result: unknown) => {\n          client.recordExitCode(lastCommandPath, 0)\n          client.recordLatency(lastCommandPath, Date.now() - start)\n          return result\n        })\n        .catch((err: unknown) => {\n          client.recordExitCode(lastCommandPath, 1)\n          client.recordLatency(lastCommandPath, Date.now() - start)\n          client.recordError(\n            lastCommandPath,\n            classify(err instanceof Error ? err : new Error(String(err))),\n          )\n          throw err\n        })\n    } as ParseFn\n  }\n\n  yargsInstance.parseAsync = wrapParse(yargsInstance.parseAsync.bind(yargsInstance))\n\n  return yargsInstance\n}\n\n/**\n * Builds a `Client` (using `cliName`/`cliVersion` you provide — yargs\n * has no built-in fields to read them from) and calls\n * {@link instrumentYargs} to wire up capture.\n *\n *     const { client } = instrument(yargsInstance, apiKey, 'mycli', '1.4.0')\n *     const argv = await yargsInstance.parseAsync()\n *     await client.shutdown()\n */\nexport function instrument(\n  yargsInstance: Argv,\n  apiKey: string,\n  cliName: string,\n  cliVersion: string,\n  clientOptions: ClientOptions = {},\n  hookOptions: YargsHookOptions = {},\n): { client: Client; yargs: Argv } {\n  const client = createClient(apiKey, cliName, cliVersion, clientOptions)\n  instrumentYargs(yargsInstance, client, hookOptions)\n  return { client, yargs: yargsInstance }\n}\n"]}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@getargvio/yargs",
+  "description": "Auto-instruments a yargs command tree with @getargvio/argvio CLI usage telemetry",
+  "version": "0.1.0",
+  "author": "getargvio",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getargvio/argvio-node.git",
+    "directory": "packages/yargs"
+  },
+  "homepage": "https://github.com/getargvio/argvio-node/tree/main/packages/yargs",
+  "bugs": {
+    "url": "https://github.com/getargvio/argvio-node/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "yargs",
+    "cli",
+    "telemetry",
+    "opentelemetry",
+    "analytics"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "yargs": ">=17.0.0"
+  },
+  "dependencies": {
+    "@getargvio/argvio": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "@types/yargs": "^17",
+    "typescript": "^5",
+    "vitest": "^4.1.11",
+    "yargs": "^18"
+  }
+}