cli-agent-mode 0.1.1 → 0.2.0

package/README.md

@@ -16,7 +16,7 @@ Two lines turn your CLI into one that agents can drive reliably:
 - **Stable exit codes** — `0` ok, `1` runtime error, `2` usage error.
 - **Clean stdout** — stray `console.log` inside actions is redirected to stderr in JSON mode.
 
-Zero dependencies. ~4 kB gzipped. ESM and CommonJS, Node 20+, commander 12+.
+Zero dependencies. ~4 kB gzipped. ESM and CommonJS, Node 22+ (tested on 22, 24, 26), commander 12–15 (tested in CI).
 
 ```bash
 npm i cli-agent-mode
@@ -131,6 +131,7 @@ If you are already on oclif, you have `--json`. If you are on commander — the
 - `--json` is reserved: it is removed from argv before parsing (except after `--`).
 - In JSON mode `console.log/info/debug` are redirected to stderr, but direct `process.stdout.write` calls inside actions are not — return data instead.
 - Typed `@commander-js/extra-typings` is not supported yet.
+- commander 15 is ESM-only: TypeScript projects compiled as CommonJS need TypeScript 5.9+ to import it (a commander limitation, not specific to this package).
 
 ## License
 

package/dist/index.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let commander = require("commander");
 let node_util = require("node:util");
-//#region src/detect.ts
+// src/detect.ts
 /**
 * Synchronous, dependency-free detection of AI coding agents.
 * Env variables mirror @vercel/detect-agent (Nov 2026) plus the `AI_AGENT` convention.
@@ -21,8 +21,7 @@ function detectAgent(env = process.env) {
 	if (env.COPILOT_MODEL || env.COPILOT_ALLOW_ALL) return "github-copilot";
 	if (env.REPL_ID) return "replit";
 }
-//#endregion
-//#region src/describe.ts
+// src/describe.ts
 const clean = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== void 0 && v !== "" && v !== false && !(Array.isArray(v) && v.length === 0)));
 function describeArgument(a) {
 	return clean({
@@ -71,8 +70,7 @@ function findCommand(root, path) {
 	}
 	return cur;
 }
-//#endregion
-//#region src/errors.ts
+// src/errors.ts
 /**
 * An error with a stable machine-readable `code`.
 *
@@ -101,9 +99,9 @@ const EXIT = {
 	ERROR: 1,
 	USAGE: 2
 };
-//#endregion
-//#region src/agent-mode.ts
+// src/agent-mode.ts
 const states = /* @__PURE__ */ new WeakMap();
+const hooked = /* @__PURE__ */ new WeakSet();
 const rootOf = (cmd) => {
 	let c = cmd;
 	while (c.parent) c = c.parent;
@@ -198,11 +196,18 @@ async function run(program, runOptions = {}) {
 	const json = runOptions.json ?? (extracted.json || (forced ?? (state.options.autoDetect && detectAgent(env) !== void 0)));
 	const mode = json ? "json" : "human";
 	let outBuf = "";
-	let errorCommand = program;
+	state.current = program;
 	const restore = [];
 	walk(program, (cmd) => {
-		const prevOutput = cmd.configureOutput();
-		const prevHelp = cmd.configureHelp();
+		if (!hooked.has(cmd)) {
+			hooked.add(cmd);
+			cmd.hook("preSubcommand", (_parent, sub) => {
+				const s = states.get(rootOf(sub));
+				if (s) s.current = sub;
+			});
+		}
+		const prevOutput = { ...cmd.configureOutput() };
+		const prevHelp = { ...cmd.configureHelp() };
 		restore.push(() => {
 			cmd.configureOutput(prevOutput);
 			cmd.configureHelp(prevHelp);
@@ -213,7 +218,6 @@ async function run(program, runOptions = {}) {
 			writeOut: (s) => json ? outBuf += s : stdout.write(s),
 			writeErr: (s) => json ? void 0 : stderr.write(s),
 			outputError: (s, write) => {
-				errorCommand = cmd;
 				if (!json) write(s);
 			}
 		});
@@ -264,7 +268,7 @@ async function run(program, runOptions = {}) {
 			exitCode = EXIT.OK;
 			if (!json) printed = true;
 		} else {
-			const { payload, code } = toPayload(err, program, errorCommand, state.options.describeCommand);
+			const { payload, code } = toPayload(err, program, state.current ?? program, state.options.describeCommand);
 			envelope = {
 				ok: false,
 				error: payload
@@ -327,7 +331,6 @@ function toPayload(err, root, at, describeName) {
 	};
 }
 const strip = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== void 0));
-//#endregion
 exports.AgentError = AgentError;
 exports.EXIT = EXIT;
 exports.agentMode = agentMode;

package/dist/index.d.cts

@@ -1,7 +1,5 @@
 /// <reference path="./commander-augment.d.ts" />
 import { Command } from "commander";
-
-//#region src/errors.d.ts
 interface AgentErrorOptions {
   /** One concrete next step the agent (or human) can follow literally. */
   suggestion?: string;
@@ -18,7 +16,7 @@ interface AgentErrorOptions {
  *   suggestion: 'Run "mycli env list" to see available environments.',
  * });
  */
-declare class AgentError extends Error {
+export declare class AgentError extends Error {
   readonly code: string;
   readonly suggestion?: string;
   readonly details?: unknown;
@@ -39,13 +37,11 @@ type Envelope<T = unknown> = {
   error: ErrorPayload;
 };
 /** Exit codes used by cli-agent-mode. */
-declare const EXIT: {
+export declare const EXIT: {
   readonly OK: 0;
   readonly ERROR: 1;
   readonly USAGE: 2;
 };
-//#endregion
-//#region src/agent-mode.d.ts
 interface AgentModeOptions {
   /** Switch to JSON automatically when an AI agent is detected (AI_AGENT, CLAUDECODE, CURSOR_AGENT, ...). Default: true. */
   autoDetect?: boolean;
@@ -83,11 +79,9 @@ interface RunResult {
  * program.command('deploy <env>').action(async (env) => ({ url: `https://${env}.example.com` }));
  * await run(program);
  */
-declare function agentMode<T extends Command>(program: T, options?: AgentModeOptions): T;
+export declare function agentMode<T extends Command>(program: T, options?: AgentModeOptions): T;
 /** Parse arguments, run the matching action and print the result or error in the right format. */
-declare function run(program: Command, runOptions?: RunOptions): Promise<RunResult>;
-//#endregion
-//#region src/describe.d.ts
+export declare function run(program: Command, runOptions?: RunOptions): Promise<RunResult>;
 interface ArgumentSchema {
   name: string;
   description?: string;
@@ -119,17 +113,14 @@ interface CommandSchema {
   commands?: CommandSchema[];
 }
 /** Compact JSON schema of a command and all of its visible subcommands. */
-declare function describeCommand(cmd: Command): CommandSchema;
+export declare function describeCommand(cmd: Command): CommandSchema;
 /** Resolve `["deploy", "preview"]` to the nested subcommand (by name or alias). */
-declare function findCommand(root: Command, path: string[]): Command | undefined;
-//#endregion
-//#region src/detect.d.ts
+export declare function findCommand(root: Command, path: string[]): Command | undefined;
 /**
  * Synchronous, dependency-free detection of AI coding agents.
  * Env variables mirror @vercel/detect-agent (Nov 2026) plus the `AI_AGENT` convention.
  * CURSOR_TRACE_ID is deliberately ignored: it is also set in Cursor's terminal for humans.
  * Returns the agent name or `undefined`.
  */
-declare function detectAgent(env?: NodeJS.ProcessEnv): string | undefined;
-//#endregion
-export { AgentError, type AgentErrorOptions, type AgentModeOptions, type ArgumentSchema, type CommandSchema, EXIT, type Envelope, type ErrorPayload, type OptionSchema, type RunOptions, type RunResult, agentMode, describeCommand, detectAgent, findCommand, run };
+export declare function detectAgent(env?: NodeJS.ProcessEnv): string | undefined;
+export type { AgentErrorOptions, AgentModeOptions, ArgumentSchema, CommandSchema, Envelope, ErrorPayload, OptionSchema, RunOptions, RunResult };

package/dist/index.d.mts

@@ -1,7 +1,5 @@
 /// <reference path="./commander-augment.d.ts" />
 import { Command } from "commander";
-
-//#region src/errors.d.ts
 interface AgentErrorOptions {
   /** One concrete next step the agent (or human) can follow literally. */
   suggestion?: string;
@@ -18,7 +16,7 @@ interface AgentErrorOptions {
  *   suggestion: 'Run "mycli env list" to see available environments.',
  * });
  */
-declare class AgentError extends Error {
+export declare class AgentError extends Error {
   readonly code: string;
   readonly suggestion?: string;
   readonly details?: unknown;
@@ -39,13 +37,11 @@ type Envelope<T = unknown> = {
   error: ErrorPayload;
 };
 /** Exit codes used by cli-agent-mode. */
-declare const EXIT: {
+export declare const EXIT: {
   readonly OK: 0;
   readonly ERROR: 1;
   readonly USAGE: 2;
 };
-//#endregion
-//#region src/agent-mode.d.ts
 interface AgentModeOptions {
   /** Switch to JSON automatically when an AI agent is detected (AI_AGENT, CLAUDECODE, CURSOR_AGENT, ...). Default: true. */
   autoDetect?: boolean;
@@ -83,11 +79,9 @@ interface RunResult {
  * program.command('deploy <env>').action(async (env) => ({ url: `https://${env}.example.com` }));
  * await run(program);
  */
-declare function agentMode<T extends Command>(program: T, options?: AgentModeOptions): T;
+export declare function agentMode<T extends Command>(program: T, options?: AgentModeOptions): T;
 /** Parse arguments, run the matching action and print the result or error in the right format. */
-declare function run(program: Command, runOptions?: RunOptions): Promise<RunResult>;
-//#endregion
-//#region src/describe.d.ts
+export declare function run(program: Command, runOptions?: RunOptions): Promise<RunResult>;
 interface ArgumentSchema {
   name: string;
   description?: string;
@@ -119,17 +113,14 @@ interface CommandSchema {
   commands?: CommandSchema[];
 }
 /** Compact JSON schema of a command and all of its visible subcommands. */
-declare function describeCommand(cmd: Command): CommandSchema;
+export declare function describeCommand(cmd: Command): CommandSchema;
 /** Resolve `["deploy", "preview"]` to the nested subcommand (by name or alias). */
-declare function findCommand(root: Command, path: string[]): Command | undefined;
-//#endregion
-//#region src/detect.d.ts
+export declare function findCommand(root: Command, path: string[]): Command | undefined;
 /**
  * Synchronous, dependency-free detection of AI coding agents.
  * Env variables mirror @vercel/detect-agent (Nov 2026) plus the `AI_AGENT` convention.
  * CURSOR_TRACE_ID is deliberately ignored: it is also set in Cursor's terminal for humans.
  * Returns the agent name or `undefined`.
  */
-declare function detectAgent(env?: NodeJS.ProcessEnv): string | undefined;
-//#endregion
-export { AgentError, type AgentErrorOptions, type AgentModeOptions, type ArgumentSchema, type CommandSchema, EXIT, type Envelope, type ErrorPayload, type OptionSchema, type RunOptions, type RunResult, agentMode, describeCommand, detectAgent, findCommand, run };
+export declare function detectAgent(env?: NodeJS.ProcessEnv): string | undefined;
+export type { AgentErrorOptions, AgentModeOptions, ArgumentSchema, CommandSchema, Envelope, ErrorPayload, OptionSchema, RunOptions, RunResult };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { CommanderError } from "commander";
 import { format } from "node:util";
-//#region src/detect.ts
+// src/detect.ts
 /**
 * Synchronous, dependency-free detection of AI coding agents.
 * Env variables mirror @vercel/detect-agent (Nov 2026) plus the `AI_AGENT` convention.
@@ -20,8 +20,7 @@ function detectAgent(env = process.env) {
 	if (env.COPILOT_MODEL || env.COPILOT_ALLOW_ALL) return "github-copilot";
 	if (env.REPL_ID) return "replit";
 }
-//#endregion
-//#region src/describe.ts
+// src/describe.ts
 const clean = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== void 0 && v !== "" && v !== false && !(Array.isArray(v) && v.length === 0)));
 function describeArgument(a) {
 	return clean({
@@ -70,8 +69,7 @@ function findCommand(root, path) {
 	}
 	return cur;
 }
-//#endregion
-//#region src/errors.ts
+// src/errors.ts
 /**
 * An error with a stable machine-readable `code`.
 *
@@ -100,9 +98,9 @@ const EXIT = {
 	ERROR: 1,
 	USAGE: 2
 };
-//#endregion
-//#region src/agent-mode.ts
+// src/agent-mode.ts
 const states = /* @__PURE__ */ new WeakMap();
+const hooked = /* @__PURE__ */ new WeakSet();
 const rootOf = (cmd) => {
 	let c = cmd;
 	while (c.parent) c = c.parent;
@@ -197,11 +195,18 @@ async function run(program, runOptions = {}) {
 	const json = runOptions.json ?? (extracted.json || (forced ?? (state.options.autoDetect && detectAgent(env) !== void 0)));
 	const mode = json ? "json" : "human";
 	let outBuf = "";
-	let errorCommand = program;
+	state.current = program;
 	const restore = [];
 	walk(program, (cmd) => {
-		const prevOutput = cmd.configureOutput();
-		const prevHelp = cmd.configureHelp();
+		if (!hooked.has(cmd)) {
+			hooked.add(cmd);
+			cmd.hook("preSubcommand", (_parent, sub) => {
+				const s = states.get(rootOf(sub));
+				if (s) s.current = sub;
+			});
+		}
+		const prevOutput = { ...cmd.configureOutput() };
+		const prevHelp = { ...cmd.configureHelp() };
 		restore.push(() => {
 			cmd.configureOutput(prevOutput);
 			cmd.configureHelp(prevHelp);
@@ -212,7 +217,6 @@ async function run(program, runOptions = {}) {
 			writeOut: (s) => json ? outBuf += s : stdout.write(s),
 			writeErr: (s) => json ? void 0 : stderr.write(s),
 			outputError: (s, write) => {
-				errorCommand = cmd;
 				if (!json) write(s);
 			}
 		});
@@ -263,7 +267,7 @@ async function run(program, runOptions = {}) {
 			exitCode = EXIT.OK;
 			if (!json) printed = true;
 		} else {
-			const { payload, code } = toPayload(err, program, errorCommand, state.options.describeCommand);
+			const { payload, code } = toPayload(err, program, state.current ?? program, state.options.describeCommand);
 			envelope = {
 				ok: false,
 				error: payload
@@ -326,5 +330,4 @@ function toPayload(err, root, at, describeName) {
 	};
 }
 const strip = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== void 0));
-//#endregion
 export { AgentError, EXIT, agentMode, describeCommand, detectAgent, findCommand, run };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-agent-mode",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Make any commander.js CLI agent-friendly: --json output envelopes, machine-readable errors with suggestions, a `describe` command that emits the CLI schema, and stable exit codes.",
   "keywords": [
     "cli",
@@ -24,7 +24,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "build": "tsdown src/index.ts --dts --format esm,cjs && node scripts/postbuild.mjs",
@@ -36,12 +36,12 @@
     "commander": ">=12"
   },
   "devDependencies": {
-    "@types/node": "^20.19.43",
-    "commander": "^14.0.3",
-    "tsdown": "^0.21.10",
+    "@types/node": "^22.20.5",
+    "commander": "^15.1.0",
+    "tsdown": "^0.23.7",
     "tsx": "^4.23.15",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.12"
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
   },
   "repository": {
     "type": "git",
@@ -65,5 +65,9 @@
     }
   },
   "main": "./dist/index.cjs",
-  "types": "./dist/index.d.cts"
+  "types": "./dist/index.d.cts",
+  "allowScripts": {
+    "esbuild": false,
+    "fsevents": false
+  }
 }