@getargvio/commander 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,39 @@
+# @getargvio/commander
+
+Auto-instruments a [commander](https://github.com/tj/commander.js)
+command tree with
+[`@getargvio/argvio`](https://www.npmjs.com/package/@getargvio/argvio)
+CLI usage telemetry.
+
+## Install
+
+```sh
+npm install @getargvio/commander
+```
+
+`commander` is a peer dependency — bring your own (`>=12.0.0`).
+
+## Usage
+
+```ts
+import { Command } from 'commander'
+import { instrument } from '@getargvio/commander'
+
+const program = new Command()
+program.name('mycli').version('1.4.0')
+// ... add commands as usual ...
+
+const { client } = instrument(program, process.env.MYCLI_ARGVIO_KEY ?? '', '1.4.0')
+
+await program.parseAsync()
+await client.shutdown(3000)
+```
+
+See [docs/commander-integration.md](docs/commander-integration.md) for
+exactly what's captured automatically, the `exitOverride()` requirement,
+and why `--help`/`--version` are treated as control flow rather than
+errors.
+
+## License
+
+MIT — see [LICENSE](../../LICENSE).

package/dist/index.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+var commander = require('commander');
+var argvio = require('@getargvio/argvio');
+
+// src/index.ts
+function changedOptionNames(cmd) {
+  const names = [];
+  for (const option of cmd.options) {
+    const key = option.attributeName();
+    if (cmd.getOptionValueSource(key) === "cli") {
+      names.push(option.long?.replace(/^--/, "") ?? option.short?.replace(/^-/, "") ?? key);
+    }
+  }
+  return names;
+}
+function commandPath(cmd) {
+  const names = [];
+  for (let current = cmd; current; current = current.parent) {
+    names.unshift(current.name());
+  }
+  return names.join(" ");
+}
+function isControlFlowExit(err) {
+  return err instanceof commander.CommanderError && err.exitCode === 0;
+}
+function instrumentCommander(program, client, options = {}) {
+  const classify = options.classify ?? (() => argvio.ErrorCategory.Unknown);
+  const captureHelp = options.captureHelp ?? true;
+  const captureInvocation = options.captureInvocation ?? true;
+  program.exitOverride();
+  let lastCommandPath = program.name();
+  if (captureInvocation) {
+    program.hook("preAction", (_thisCommand, actionCommand) => {
+      lastCommandPath = commandPath(actionCommand);
+      client.recordCommandInvocation(lastCommandPath, changedOptionNames(actionCommand));
+    });
+  }
+  if (captureHelp) {
+    const originalOutputHelp = program.outputHelp.bind(program);
+    program.outputHelp = ((...args) => {
+      client.recordHelpFlagUsage(lastCommandPath);
+      return originalOutputHelp(...args);
+    });
+  }
+  const originalParseAsync = program.parseAsync.bind(program);
+  program.parseAsync = (async (...args) => {
+    const start = Date.now();
+    try {
+      const result = await originalParseAsync(...args);
+      client.recordExitCode(lastCommandPath, 0);
+      client.recordLatency(lastCommandPath, Date.now() - start);
+      return result;
+    } catch (err) {
+      client.recordLatency(lastCommandPath, Date.now() - start);
+      if (isControlFlowExit(err)) {
+        client.recordExitCode(lastCommandPath, 0);
+      } else {
+        client.recordExitCode(lastCommandPath, 1);
+        const error = err instanceof Error ? err : new Error(String(err));
+        client.recordError(lastCommandPath, classify(error));
+      }
+      throw err;
+    }
+  });
+  return program;
+}
+function instrument(program, apiKey, cliVersion, clientOptions = {}, hookOptions = {}) {
+  const client = argvio.createClient(apiKey, program.name(), cliVersion, clientOptions);
+  instrumentCommander(program, client, hookOptions);
+  return { client, program };
+}
+
+exports.instrument = instrument;
+exports.instrumentCommander = instrumentCommander;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["CommanderError","ErrorCategory","createClient"],"mappings":"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","file":"index.cjs","sourcesContent":["import { CommanderError } from 'commander'\nimport type { Command } from 'commander'\n\nimport type { Client, ClientOptions } from '@getargvio/argvio'\nimport { createClient, ErrorCategory } from '@getargvio/argvio'\nimport type { ErrorCategory as ErrorCategoryType } from '@getargvio/argvio'\n\n/** Configures {@link instrumentCommander}. */\nexport interface CommanderHookOptions {\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 `outputHelp` wrapping. */\n  captureHelp?: boolean\n  /** Skip the `preAction` hook-based command-invocation capture. */\n  captureInvocation?: boolean\n}\n\n/** Names of options the user explicitly passed on the command line — never their values. */\nfunction changedOptionNames(cmd: Command): string[] {\n  const names: string[] = []\n  for (const option of cmd.options) {\n    const key = option.attributeName()\n    if (cmd.getOptionValueSource(key) === 'cli') {\n      names.push(option.long?.replace(/^--/, '') ?? option.short?.replace(/^-/, '') ?? key)\n    }\n  }\n  return names\n}\n\n/** The full command path (e.g. `\"mycli sub leaf\"`), walking up to the root command. */\nfunction commandPath(cmd: Command): string {\n  const names: string[] = []\n  for (let current: Command | null = cmd; current; current = current.parent) {\n    names.unshift(current.name())\n  }\n  return names.join(' ')\n}\n\n/**\n * Reports whether `err` represents commander's own control flow (help\n * or version display via `--help`/`-h`/`--version`) rather than an\n * actual failure. `exitOverride()` makes both of those throw a\n * `CommanderError` with `exitCode: 0` instead of calling\n * `process.exit()` directly — this package must not record those as\n * errors or non-zero exit codes.\n */\nfunction isControlFlowExit(err: unknown): err is CommanderError {\n  return err instanceof CommanderError && err.exitCode === 0\n}\n\n/**\n * Wires automatic telemetry capture into a commander command tree:\n *\n * - Command path + option names (see `Client.recordCommandInvocation`)\n *   are captured via `program.hook('preAction', ...)` — fires reliably\n *   for every resolved action command (verified against commander's own\n *   source: unlike `postAction`, `preAction` runs unconditionally before\n *   the action handler).\n * - Exit code and latency are captured by wrapping `program.parseAsync`\n *   — `postAction` does **not** run when an action handler throws or its\n *   returned promise rejects, so this package does not rely on it at\n *   all, measuring whole-invocation latency instead.\n * - Errors are captured in that same `parseAsync` wrapper's `catch`,\n *   distinguishing a real failure from commander's own `--help`/\n *   `--version` control-flow exits (see {@link isControlFlowExit}).\n * - Help usage is captured by wrapping the public, chainable\n *   `outputHelp` method.\n *\n * Calls `program.exitOverride()`: without it, commander calls\n * `process.exit()` itself on `--help`, `--version`, or a command\n * failure, before this package's wrapped `parseAsync` ever gets a\n * chance to record anything. After instrumenting, your own code owns\n * the real process exit — see docs/commander-integration.md.\n */\nexport function instrumentCommander(\n  program: Command,\n  client: Client,\n  options: CommanderHookOptions = {},\n): Command {\n  const classify = options.classify ?? (() => ErrorCategory.Unknown)\n  const captureHelp = options.captureHelp ?? true\n  const captureInvocation = options.captureInvocation ?? true\n\n  program.exitOverride()\n\n  let lastCommandPath = program.name()\n\n  if (captureInvocation) {\n    program.hook('preAction', (_thisCommand, actionCommand) => {\n      lastCommandPath = commandPath(actionCommand)\n      client.recordCommandInvocation(lastCommandPath, changedOptionNames(actionCommand))\n    })\n  }\n\n  if (captureHelp) {\n    const originalOutputHelp = program.outputHelp.bind(program)\n    program.outputHelp = ((...args: Parameters<Command['outputHelp']>) => {\n      client.recordHelpFlagUsage(lastCommandPath)\n      return originalOutputHelp(...args)\n    }) as Command['outputHelp']\n  }\n\n  const originalParseAsync = program.parseAsync.bind(program)\n  program.parseAsync = (async (...args: Parameters<Command['parseAsync']>) => {\n    const start = Date.now()\n    try {\n      const result = await originalParseAsync(...args)\n      client.recordExitCode(lastCommandPath, 0)\n      client.recordLatency(lastCommandPath, Date.now() - start)\n      return result\n    } catch (err) {\n      client.recordLatency(lastCommandPath, Date.now() - start)\n      if (isControlFlowExit(err)) {\n        client.recordExitCode(lastCommandPath, 0)\n      } else {\n        client.recordExitCode(lastCommandPath, 1)\n        const error = err instanceof Error ? err : new Error(String(err))\n        client.recordError(lastCommandPath, classify(error))\n      }\n      throw err\n    }\n  }) as Command['parseAsync']\n\n  return program\n}\n\n/**\n * Builds a `Client` (using `program.name()`/`program.version()`) and\n * calls {@link instrumentCommander} to wire up capture.\n *\n *     const { client } = instrument(program, apiKey, '1.4.0')\n *     await program.parseAsync()\n *     await client.shutdown()\n */\nexport function instrument(\n  program: Command,\n  apiKey: string,\n  cliVersion: string,\n  clientOptions: ClientOptions = {},\n  hookOptions: CommanderHookOptions = {},\n): { client: Client; program: Command } {\n  const client = createClient(apiKey, program.name(), cliVersion, clientOptions)\n  instrumentCommander(program, client, hookOptions)\n  return { client, program }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,51 @@
+import { Command } from 'commander';
+import { ErrorCategory, ClientOptions, Client } from '@getargvio/argvio';
+
+/** Configures {@link instrumentCommander}. */
+interface CommanderHookOptions {
+    /** Maps a caught error to an {@link ErrorCategoryType}. Without it, every error is recorded as `ErrorCategory.Unknown`. */
+    classify?: (err: Error) => ErrorCategory;
+    /** Skip the `outputHelp` wrapping. */
+    captureHelp?: boolean;
+    /** Skip the `preAction` hook-based command-invocation capture. */
+    captureInvocation?: boolean;
+}
+/**
+ * Wires automatic telemetry capture into a commander command tree:
+ *
+ * - Command path + option names (see `Client.recordCommandInvocation`)
+ *   are captured via `program.hook('preAction', ...)` — fires reliably
+ *   for every resolved action command (verified against commander's own
+ *   source: unlike `postAction`, `preAction` runs unconditionally before
+ *   the action handler).
+ * - Exit code and latency are captured by wrapping `program.parseAsync`
+ *   — `postAction` does **not** run when an action handler throws or its
+ *   returned promise rejects, so this package does not rely on it at
+ *   all, measuring whole-invocation latency instead.
+ * - Errors are captured in that same `parseAsync` wrapper's `catch`,
+ *   distinguishing a real failure from commander's own `--help`/
+ *   `--version` control-flow exits (see {@link isControlFlowExit}).
+ * - Help usage is captured by wrapping the public, chainable
+ *   `outputHelp` method.
+ *
+ * Calls `program.exitOverride()`: without it, commander calls
+ * `process.exit()` itself on `--help`, `--version`, or a command
+ * failure, before this package's wrapped `parseAsync` ever gets a
+ * chance to record anything. After instrumenting, your own code owns
+ * the real process exit — see docs/commander-integration.md.
+ */
+declare function instrumentCommander(program: Command, client: Client, options?: CommanderHookOptions): Command;
+/**
+ * Builds a `Client` (using `program.name()`/`program.version()`) and
+ * calls {@link instrumentCommander} to wire up capture.
+ *
+ *     const { client } = instrument(program, apiKey, '1.4.0')
+ *     await program.parseAsync()
+ *     await client.shutdown()
+ */
+declare function instrument(program: Command, apiKey: string, cliVersion: string, clientOptions?: ClientOptions, hookOptions?: CommanderHookOptions): {
+    client: Client;
+    program: Command;
+};
+
+export { type CommanderHookOptions, instrument, instrumentCommander };

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import { Command } from 'commander';
+import { ErrorCategory, ClientOptions, Client } from '@getargvio/argvio';
+
+/** Configures {@link instrumentCommander}. */
+interface CommanderHookOptions {
+    /** Maps a caught error to an {@link ErrorCategoryType}. Without it, every error is recorded as `ErrorCategory.Unknown`. */
+    classify?: (err: Error) => ErrorCategory;
+    /** Skip the `outputHelp` wrapping. */
+    captureHelp?: boolean;
+    /** Skip the `preAction` hook-based command-invocation capture. */
+    captureInvocation?: boolean;
+}
+/**
+ * Wires automatic telemetry capture into a commander command tree:
+ *
+ * - Command path + option names (see `Client.recordCommandInvocation`)
+ *   are captured via `program.hook('preAction', ...)` — fires reliably
+ *   for every resolved action command (verified against commander's own
+ *   source: unlike `postAction`, `preAction` runs unconditionally before
+ *   the action handler).
+ * - Exit code and latency are captured by wrapping `program.parseAsync`
+ *   — `postAction` does **not** run when an action handler throws or its
+ *   returned promise rejects, so this package does not rely on it at
+ *   all, measuring whole-invocation latency instead.
+ * - Errors are captured in that same `parseAsync` wrapper's `catch`,
+ *   distinguishing a real failure from commander's own `--help`/
+ *   `--version` control-flow exits (see {@link isControlFlowExit}).
+ * - Help usage is captured by wrapping the public, chainable
+ *   `outputHelp` method.
+ *
+ * Calls `program.exitOverride()`: without it, commander calls
+ * `process.exit()` itself on `--help`, `--version`, or a command
+ * failure, before this package's wrapped `parseAsync` ever gets a
+ * chance to record anything. After instrumenting, your own code owns
+ * the real process exit — see docs/commander-integration.md.
+ */
+declare function instrumentCommander(program: Command, client: Client, options?: CommanderHookOptions): Command;
+/**
+ * Builds a `Client` (using `program.name()`/`program.version()`) and
+ * calls {@link instrumentCommander} to wire up capture.
+ *
+ *     const { client } = instrument(program, apiKey, '1.4.0')
+ *     await program.parseAsync()
+ *     await client.shutdown()
+ */
+declare function instrument(program: Command, apiKey: string, cliVersion: string, clientOptions?: ClientOptions, hookOptions?: CommanderHookOptions): {
+    client: Client;
+    program: Command;
+};
+
+export { type CommanderHookOptions, instrument, instrumentCommander };

package/dist/index.js

@@ -0,0 +1,74 @@
+import { CommanderError } from 'commander';
+import { ErrorCategory, createClient } from '@getargvio/argvio';
+
+// src/index.ts
+function changedOptionNames(cmd) {
+  const names = [];
+  for (const option of cmd.options) {
+    const key = option.attributeName();
+    if (cmd.getOptionValueSource(key) === "cli") {
+      names.push(option.long?.replace(/^--/, "") ?? option.short?.replace(/^-/, "") ?? key);
+    }
+  }
+  return names;
+}
+function commandPath(cmd) {
+  const names = [];
+  for (let current = cmd; current; current = current.parent) {
+    names.unshift(current.name());
+  }
+  return names.join(" ");
+}
+function isControlFlowExit(err) {
+  return err instanceof CommanderError && err.exitCode === 0;
+}
+function instrumentCommander(program, client, options = {}) {
+  const classify = options.classify ?? (() => ErrorCategory.Unknown);
+  const captureHelp = options.captureHelp ?? true;
+  const captureInvocation = options.captureInvocation ?? true;
+  program.exitOverride();
+  let lastCommandPath = program.name();
+  if (captureInvocation) {
+    program.hook("preAction", (_thisCommand, actionCommand) => {
+      lastCommandPath = commandPath(actionCommand);
+      client.recordCommandInvocation(lastCommandPath, changedOptionNames(actionCommand));
+    });
+  }
+  if (captureHelp) {
+    const originalOutputHelp = program.outputHelp.bind(program);
+    program.outputHelp = ((...args) => {
+      client.recordHelpFlagUsage(lastCommandPath);
+      return originalOutputHelp(...args);
+    });
+  }
+  const originalParseAsync = program.parseAsync.bind(program);
+  program.parseAsync = (async (...args) => {
+    const start = Date.now();
+    try {
+      const result = await originalParseAsync(...args);
+      client.recordExitCode(lastCommandPath, 0);
+      client.recordLatency(lastCommandPath, Date.now() - start);
+      return result;
+    } catch (err) {
+      client.recordLatency(lastCommandPath, Date.now() - start);
+      if (isControlFlowExit(err)) {
+        client.recordExitCode(lastCommandPath, 0);
+      } else {
+        client.recordExitCode(lastCommandPath, 1);
+        const error = err instanceof Error ? err : new Error(String(err));
+        client.recordError(lastCommandPath, classify(error));
+      }
+      throw err;
+    }
+  });
+  return program;
+}
+function instrument(program, apiKey, cliVersion, clientOptions = {}, hookOptions = {}) {
+  const client = createClient(apiKey, program.name(), cliVersion, clientOptions);
+  instrumentCommander(program, client, hookOptions);
+  return { client, program };
+}
+
+export { instrument, instrumentCommander };
+//# 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 { CommanderError } from 'commander'\nimport type { Command } from 'commander'\n\nimport type { Client, ClientOptions } from '@getargvio/argvio'\nimport { createClient, ErrorCategory } from '@getargvio/argvio'\nimport type { ErrorCategory as ErrorCategoryType } from '@getargvio/argvio'\n\n/** Configures {@link instrumentCommander}. */\nexport interface CommanderHookOptions {\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 `outputHelp` wrapping. */\n  captureHelp?: boolean\n  /** Skip the `preAction` hook-based command-invocation capture. */\n  captureInvocation?: boolean\n}\n\n/** Names of options the user explicitly passed on the command line — never their values. */\nfunction changedOptionNames(cmd: Command): string[] {\n  const names: string[] = []\n  for (const option of cmd.options) {\n    const key = option.attributeName()\n    if (cmd.getOptionValueSource(key) === 'cli') {\n      names.push(option.long?.replace(/^--/, '') ?? option.short?.replace(/^-/, '') ?? key)\n    }\n  }\n  return names\n}\n\n/** The full command path (e.g. `\"mycli sub leaf\"`), walking up to the root command. */\nfunction commandPath(cmd: Command): string {\n  const names: string[] = []\n  for (let current: Command | null = cmd; current; current = current.parent) {\n    names.unshift(current.name())\n  }\n  return names.join(' ')\n}\n\n/**\n * Reports whether `err` represents commander's own control flow (help\n * or version display via `--help`/`-h`/`--version`) rather than an\n * actual failure. `exitOverride()` makes both of those throw a\n * `CommanderError` with `exitCode: 0` instead of calling\n * `process.exit()` directly — this package must not record those as\n * errors or non-zero exit codes.\n */\nfunction isControlFlowExit(err: unknown): err is CommanderError {\n  return err instanceof CommanderError && err.exitCode === 0\n}\n\n/**\n * Wires automatic telemetry capture into a commander command tree:\n *\n * - Command path + option names (see `Client.recordCommandInvocation`)\n *   are captured via `program.hook('preAction', ...)` — fires reliably\n *   for every resolved action command (verified against commander's own\n *   source: unlike `postAction`, `preAction` runs unconditionally before\n *   the action handler).\n * - Exit code and latency are captured by wrapping `program.parseAsync`\n *   — `postAction` does **not** run when an action handler throws or its\n *   returned promise rejects, so this package does not rely on it at\n *   all, measuring whole-invocation latency instead.\n * - Errors are captured in that same `parseAsync` wrapper's `catch`,\n *   distinguishing a real failure from commander's own `--help`/\n *   `--version` control-flow exits (see {@link isControlFlowExit}).\n * - Help usage is captured by wrapping the public, chainable\n *   `outputHelp` method.\n *\n * Calls `program.exitOverride()`: without it, commander calls\n * `process.exit()` itself on `--help`, `--version`, or a command\n * failure, before this package's wrapped `parseAsync` ever gets a\n * chance to record anything. After instrumenting, your own code owns\n * the real process exit — see docs/commander-integration.md.\n */\nexport function instrumentCommander(\n  program: Command,\n  client: Client,\n  options: CommanderHookOptions = {},\n): Command {\n  const classify = options.classify ?? (() => ErrorCategory.Unknown)\n  const captureHelp = options.captureHelp ?? true\n  const captureInvocation = options.captureInvocation ?? true\n\n  program.exitOverride()\n\n  let lastCommandPath = program.name()\n\n  if (captureInvocation) {\n    program.hook('preAction', (_thisCommand, actionCommand) => {\n      lastCommandPath = commandPath(actionCommand)\n      client.recordCommandInvocation(lastCommandPath, changedOptionNames(actionCommand))\n    })\n  }\n\n  if (captureHelp) {\n    const originalOutputHelp = program.outputHelp.bind(program)\n    program.outputHelp = ((...args: Parameters<Command['outputHelp']>) => {\n      client.recordHelpFlagUsage(lastCommandPath)\n      return originalOutputHelp(...args)\n    }) as Command['outputHelp']\n  }\n\n  const originalParseAsync = program.parseAsync.bind(program)\n  program.parseAsync = (async (...args: Parameters<Command['parseAsync']>) => {\n    const start = Date.now()\n    try {\n      const result = await originalParseAsync(...args)\n      client.recordExitCode(lastCommandPath, 0)\n      client.recordLatency(lastCommandPath, Date.now() - start)\n      return result\n    } catch (err) {\n      client.recordLatency(lastCommandPath, Date.now() - start)\n      if (isControlFlowExit(err)) {\n        client.recordExitCode(lastCommandPath, 0)\n      } else {\n        client.recordExitCode(lastCommandPath, 1)\n        const error = err instanceof Error ? err : new Error(String(err))\n        client.recordError(lastCommandPath, classify(error))\n      }\n      throw err\n    }\n  }) as Command['parseAsync']\n\n  return program\n}\n\n/**\n * Builds a `Client` (using `program.name()`/`program.version()`) and\n * calls {@link instrumentCommander} to wire up capture.\n *\n *     const { client } = instrument(program, apiKey, '1.4.0')\n *     await program.parseAsync()\n *     await client.shutdown()\n */\nexport function instrument(\n  program: Command,\n  apiKey: string,\n  cliVersion: string,\n  clientOptions: ClientOptions = {},\n  hookOptions: CommanderHookOptions = {},\n): { client: Client; program: Command } {\n  const client = createClient(apiKey, program.name(), cliVersion, clientOptions)\n  instrumentCommander(program, client, hookOptions)\n  return { client, program }\n}\n"]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@getargvio/commander",
+  "description": "Auto-instruments a commander 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/commander"
+  },
+  "homepage": "https://github.com/getargvio/argvio-node/tree/main/packages/commander",
+  "bugs": {
+    "url": "https://github.com/getargvio/argvio-node/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "commander",
+    "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": {
+    "commander": ">=12.0.0"
+  },
+  "dependencies": {
+    "@getargvio/argvio": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "commander": "^15",
+    "typescript": "^5",
+    "vitest": "^4.1.11"
+  }
+}