@agentuity/cli 1.0.44 → 1.0.46

package/bin/cli.ts

@@ -22,7 +22,7 @@ import type { CommandContext, LogLevel } from '../src/types';
 import { generateCLISchema } from '../src/schema-generator';
 import { generateAIHelp } from '../src/ai-help';
 import { setOutputOptions } from '../src/output';
-import type { GlobalOptions } from '../src/types';
+import type { Config, GlobalOptions } from '../src/types';
 import { ensureBunOnPath } from '../src/bun-path';
 import { checkForUpdates } from '../src/version-check';
 import { closeDatabase } from '../src/cache';
@@ -154,151 +154,165 @@ if (!hasHelp) {
 }
 const earlyOpts = program.opts();
 
-// Detect or override terminal color scheme
-let colorScheme = await detectColorScheme();
-if (earlyOpts.colorScheme === 'light' || earlyOpts.colorScheme === 'dark') {
-	colorScheme = earlyOpts.colorScheme;
-	if (process.env.DEBUG_COLORS) {
-		console.log(`[DEBUG] Using --color-scheme=${colorScheme} flag`);
-	}
+// Set JSON error format early, BEFORE any code that might throw,
+// so that startup failures also use the JSON error formatter.
+// Note: --error-format defaults to 'text', so we must check !== 'json'
+// rather than !earlyOpts.errorFormat (which would always be false).
+if (earlyOpts.json && earlyOpts.errorFormat !== 'json') {
+	earlyOpts.errorFormat = 'json';
 }
-setColorScheme(colorScheme);
+setOutputOptions(earlyOpts as GlobalOptions);
 
-// Debug: show detected color scheme
-if (process.env.DEBUG_COLORS) {
-	console.log(`[DEBUG] Color scheme: ${colorScheme}`);
-}
+// Variables that may or may not be initialized by the time an error occurs.
+// Hoisted here so the centralized error handler can reference them.
+let config: Config | null | undefined;
+let logger: ReturnType<typeof createCompositeLogger> | undefined;
 
-// Create logger instance with global options
-// In quiet or JSON mode, suppress most logging
-const effectiveLogLevel =
-	earlyOpts.quiet || earlyOpts.json ? 'error' : (earlyOpts.logLevel as LogLevel) || 'info';
-const consoleLogger = new ConsoleLogger(
-	effectiveLogLevel,
-	earlyOpts.logTimestamp || false,
-	colorScheme
-);
-consoleLogger.setShowPrefix(earlyOpts.logPrefix !== false);
-
-// Use the parsed operands from Commander.js parseOptions() which correctly
-// separates command names from option values. parsedOperands contains only
-// positional arguments (command/subcommand names), not flag values.
-// For help mode, parsedOperands is empty so we fall back to extracting from preprocessedArgs.
-const commandArgs = hasHelp
-	? preprocessedArgs.filter((arg) => !arg.startsWith('-'))
-	: parsedOperands;
-
-// Check if we should skip internal logging based on command or help flags
-// We need to check the commands first to see if skipInternalLogging is set
-const earlyCommandName = commandArgs[0];
-const earlySubcommandName = commandArgs[1];
-const commands = await discoverCommands();
-const earlyCommandDef = commands.find((cmd) => cmd.name === earlyCommandName);
-const earlySubcommandDef = earlySubcommandName
-	? earlyCommandDef?.subcommands?.find((sub) => sub.name === earlySubcommandName)
-	: undefined;
-
-// Skip internal logging if:
-// 1. Help flag is present
-// 2. No command provided (shows help)
-// 3. Command has skipInternalLogging set
-// 4. Subcommand has skipInternalLogging set
-const shouldSkipInternalLogging =
-	hasHelp ||
-	commandArgs.length === 0 ||
-	earlyCommandDef?.skipInternalLogging ||
-	earlySubcommandDef?.skipInternalLogging;
-
-// Create internal logger for trace/debug logging (always at trace level)
-const internalLogger = createInternalLogger(version, getPackageName());
-
-// Disable or initialize the internal logger based on command flags
-if (shouldSkipInternalLogging) {
-	internalLogger.disable();
-} else {
-	const command = commandArgs.length > 0 ? commandArgs.join(' ') : 'help';
-	// Extract --dir from argv if present (for project context in logs)
-	const projectDirArg = getProjectDirFromArgs();
-	// Filter out command/subcommand names from args by position, not by value.
-	// The first N entries of preprocessedArgs that are not flags are the command tokens.
-	// Skip the leading command tokens to get only the actual arguments.
-	let commandTokensToSkip = commandArgs.length;
-	const filteredArgs: string[] = [];
-	for (const arg of preprocessedArgs) {
-		if (commandTokensToSkip > 0 && !arg.startsWith('-') && commandArgs.includes(arg)) {
-			commandTokensToSkip--;
-		} else {
-			filteredArgs.push(arg);
+/**
+ * Main startup and command execution.
+ *
+ * Wrapped in a function so that the entire boot sequence (config loading,
+ * command discovery, update checks, command registration, and execution)
+ * is enclosed in a single try/catch whose error handler respects --json.
+ */
+async function main() {
+	// Detect or override terminal color scheme
+	let colorScheme = await detectColorScheme();
+	if (earlyOpts.colorScheme === 'light' || earlyOpts.colorScheme === 'dark') {
+		colorScheme = earlyOpts.colorScheme;
+		if (process.env.DEBUG_COLORS) {
+			console.log(`[DEBUG] Using --color-scheme=${colorScheme} flag`);
 		}
 	}
-	internalLogger.init(command, filteredArgs, undefined, projectDirArg);
-
-	// Set session ID in environment so forked child processes can share the same log file
-	process.env.AGENTUITY_INTERNAL_SESSION_ID = internalLogger.getSessionId();
+	setColorScheme(colorScheme);
 
-	// Set detected agent in session logs
-	const detectedAgent = getExecutingAgent();
-	if (detectedAgent) {
-		internalLogger.setDetectedAgent(detectedAgent);
+	// Debug: show detected color scheme
+	if (process.env.DEBUG_COLORS) {
+		console.log(`[DEBUG] Color scheme: ${colorScheme}`);
 	}
-}
-
-// Create composite logger that writes to both console and internal log
-const logger = createCompositeLogger(consoleLogger, internalLogger);
 
-// Set version check skip flag from CLI option
-if (earlyOpts.skipVersionCheck) {
-	process.env.AGENTUITY_SKIP_VERSION_CHECK = '1';
-}
+	// Create logger instance with global options
+	// In quiet or JSON mode, suppress most logging
+	const effectiveLogLevel =
+		earlyOpts.quiet || earlyOpts.json ? 'error' : (earlyOpts.logLevel as LogLevel) || 'info';
+	const consoleLogger = new ConsoleLogger(
+		effectiveLogLevel,
+		earlyOpts.logTimestamp || false,
+		colorScheme
+	);
+	consoleLogger.setShowPrefix(earlyOpts.logPrefix !== false);
+
+	// Use the parsed operands from Commander.js parseOptions() which correctly
+	// separates command names from option values. parsedOperands contains only
+	// positional arguments (command/subcommand names), not flag values.
+	// For help mode, parsedOperands is empty so we fall back to extracting from preprocessedArgs.
+	const commandArgs = hasHelp
+		? preprocessedArgs.filter((arg) => !arg.startsWith('-'))
+		: parsedOperands;
+
+	// Check if we should skip internal logging based on command or help flags
+	// We need to check the commands first to see if skipInternalLogging is set
+	const earlyCommandName = commandArgs[0];
+	const earlySubcommandName = commandArgs[1];
+	const commands = await discoverCommands();
+	const earlyCommandDef = commands.find((cmd) => cmd.name === earlyCommandName);
+	const earlySubcommandDef = earlySubcommandName
+		? earlyCommandDef?.subcommands?.find((sub) => sub.name === earlySubcommandName)
+		: undefined;
+
+	// Skip internal logging if:
+	// 1. Help flag is present
+	// 2. No command provided (shows help)
+	// 3. Command has skipInternalLogging set
+	// 4. Subcommand has skipInternalLogging set
+	const shouldSkipInternalLogging =
+		hasHelp ||
+		commandArgs.length === 0 ||
+		earlyCommandDef?.skipInternalLogging ||
+		earlySubcommandDef?.skipInternalLogging;
+
+	// Create internal logger for trace/debug logging (always at trace level)
+	const internalLogger = createInternalLogger(version, getPackageName());
+
+	// Disable or initialize the internal logger based on command flags
+	if (shouldSkipInternalLogging) {
+		internalLogger.disable();
+	} else {
+		const command = commandArgs.length > 0 ? commandArgs.join(' ') : 'help';
+		// Extract --dir from argv if present (for project context in logs)
+		const projectDirArg = getProjectDirFromArgs();
+		// Filter out command/subcommand names from args by position, not by value.
+		// The first N entries of preprocessedArgs that are not flags are the command tokens.
+		// Skip the leading command tokens to get only the actual arguments.
+		let commandTokensToSkip = commandArgs.length;
+		const filteredArgs: string[] = [];
+		for (const arg of preprocessedArgs) {
+			if (commandTokensToSkip > 0 && !arg.startsWith('-') && commandArgs.includes(arg)) {
+				commandTokensToSkip--;
+			} else {
+				filteredArgs.push(arg);
+			}
+		}
+		internalLogger.init(command, filteredArgs, undefined, projectDirArg);
 
-const config = await loadConfig(earlyOpts.config, false, earlyOpts.profile);
+		// Set session ID in environment so forked child processes can share the same log file
+		process.env.AGENTUITY_INTERNAL_SESSION_ID = internalLogger.getSessionId();
 
-// Update internal logger with userId if available from auth (keychain or config)
-try {
-	const auth = await getAuth();
-	if (auth?.userId) {
-		internalLogger.setUserId(auth.userId);
+		// Set detected agent in session logs
+		const detectedAgent = getExecutingAgent();
+		if (detectedAgent) {
+			internalLogger.setDetectedAgent(detectedAgent);
+		}
 	}
-} catch {
-	// Ignore auth errors - user might not be logged in
-}
 
-const ctx = {
-	config,
-	logger,
-	options: earlyOpts,
-	getExecutingAgent,
-};
+	// Create composite logger that writes to both console and internal log
+	logger = createCompositeLogger(consoleLogger, internalLogger);
 
-// Set global output options for utilities to use
-// When --json is used, automatically set error format to json
-if (earlyOpts.json && !earlyOpts.errorFormat) {
-	earlyOpts.errorFormat = 'json';
-}
-setOutputOptions(earlyOpts as GlobalOptions);
+	// Set version check skip flag from CLI option
+	if (earlyOpts.skipVersionCheck) {
+		process.env.AGENTUITY_SKIP_VERSION_CHECK = '1';
+	}
 
-// Check for updates before running commands (may upgrade and re-exec)
-// Find the command being run to check if it opts out of upgrade check
-// Use parsedOperands from Commander's parseOptions which correctly separates
-// command names from option values (e.g., "--file myfile" won't treat "myfile" as a command)
-// Also find the subcommand if present (e.g., "auth whoami" -> command="auth", subcommand="whoami")
-const commandName = parsedOperands[0];
-const subcommandName = parsedOperands[1];
-const commandDef = commands.find((cmd) => cmd.name === commandName);
-const subcommandDef = subcommandName
-	? commandDef?.subcommands?.find((sub) => sub.name === subcommandName)
-	: undefined;
+	config = await loadConfig(earlyOpts.config, false, earlyOpts.profile);
 
-await checkForUpdates(config, logger, earlyOpts, commandDef, subcommandDef, preprocessedArgs);
+	// Update internal logger with userId if available from auth (keychain or config)
+	try {
+		const auth = await getAuth();
+		if (auth?.userId) {
+			internalLogger.setUserId(auth.userId);
+		}
+	} catch {
+		// Ignore auth errors - user might not be logged in
+	}
 
-// Generate and store CLI schema globally for the schema command
-const cliSchema = generateCLISchema(program, commands, version);
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-(global as any).__CLI_SCHEMA__ = cliSchema;
+	const ctx = {
+		config,
+		logger,
+		options: earlyOpts,
+		getExecutingAgent,
+	};
+
+	// Check for updates before running commands (may upgrade and re-exec)
+	// Find the command being run to check if it opts out of upgrade check
+	// Use parsedOperands from Commander's parseOptions which correctly separates
+	// command names from option values (e.g., "--file myfile" won't treat "myfile" as a command)
+	// Also find the subcommand if present (e.g., "auth whoami" -> command="auth", subcommand="whoami")
+	const commandName = parsedOperands[0];
+	const subcommandName = parsedOperands[1];
+	const commandDef = commands.find((cmd) => cmd.name === commandName);
+	const subcommandDef = subcommandName
+		? commandDef?.subcommands?.find((sub) => sub.name === subcommandName)
+		: undefined;
+
+	await checkForUpdates(config, logger, earlyOpts, commandDef, subcommandDef, preprocessedArgs);
+
+	// Generate and store CLI schema globally for the schema command
+	const cliSchema = generateCLISchema(program, commands, version);
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	(global as any).__CLI_SCHEMA__ = cliSchema;
 
-await registerCommands(program, commands, ctx as unknown as CommandContext);
+	await registerCommands(program, commands, ctx as unknown as CommandContext);
 
-try {
 	await program.parseAsync(process.argv);
 	// Ensure clean exit after successful command execution.
 	// In TTY environments, process.stdin may keep the event loop alive
@@ -308,6 +322,10 @@ try {
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	const exit = (globalThis as any).AGENTUITY_PROCESS_EXIT || process.exit;
 	exit(0);
+}
+
+try {
+	await main();
 } catch (error) {
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	const exit = (globalThis as any).AGENTUITY_PROCESS_EXIT || process.exit;
@@ -369,19 +387,40 @@ try {
 	}
 
 	if (earlyOpts.errorFormat === 'json') {
-		const message = errorWithMessage?.message ?? String(error);
-		const code = isStructuredError(error) ? ErrorCode.API_ERROR : ErrorCode.INTERNAL_ERROR;
+		let message = errorWithMessage?.message ?? String(error);
+		// Classify the error: treat as API_ERROR if it's a structured error
+		// OR if the error carries a numeric status/statusCode (e.g. ServiceException)
+		const hasStatus =
+			typeof error === 'object' &&
+			error !== null &&
+			(('status' in error && typeof (error as any).status === 'number') ||
+				('statusCode' in error && typeof (error as any).statusCode === 'number'));
+		const code =
+			isStructuredError(error) || hasStatus ? ErrorCode.API_ERROR : ErrorCode.INTERNAL_ERROR;
 		const details: Record<string, unknown> = {};
 		if (isStructuredError(error) && errorWithMessage._tag) {
 			details.tag = errorWithMessage._tag;
 		}
-		if (
-			typeof error === 'object' &&
-			error !== null &&
-			'status' in error &&
-			typeof (error as any).status === 'number'
-		) {
-			details.status = (error as any).status;
+		if (typeof error === 'object' && error !== null) {
+			// Support both error.status (APIErrorResponse) and error.statusCode (ServiceException)
+			if ('status' in error && typeof (error as any).status === 'number') {
+				details.status = (error as any).status;
+			} else if ('statusCode' in error && typeof (error as any).statusCode === 'number') {
+				details.status = (error as any).statusCode;
+			}
+			if ('sessionId' in error && (error as any).sessionId) {
+				details.sessionId = (error as any).sessionId;
+			}
+		}
+		// Try to parse embedded JSON in API error messages
+		// API errors often have messages like: '{"success":false,"message":"not found: ..."}'
+		try {
+			const parsed = JSON.parse(message);
+			if (parsed && typeof parsed === 'object' && typeof parsed.message === 'string') {
+				message = parsed.message;
+			}
+		} catch {
+			// Not JSON, use message as-is
 		}
 		console.error(
 			formatErrorJSON(
@@ -389,13 +428,20 @@ try {
 			)
 		);
 	} else if (isStructuredError(error)) {
-		logger.error(error);
+		// Use the composite logger if available; fall back to console.error
+		// if the error occurred before logger initialization completed
+		if (logger) {
+			logger.error(error);
+		} else {
+			console.error(String(error));
+		}
 	} else {
-		logger.error(
-			'CLI error: %s %s',
-			errorWithMessage?.message ? errorWithMessage.message : String(error),
-			error
-		);
+		const msg = errorWithMessage?.message ? errorWithMessage.message : String(error);
+		if (logger) {
+			logger.error('CLI error: %s %s', msg, error);
+		} else {
+			console.error(`CLI error: ${msg}`);
+		}
 	}
 	closeDatabase();
 	exit(1);

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EACX,iBAAiB,EAEjB,cAAc,EAEd,MAAM,EAGN,MAAM,EAGN,MAAM,SAAS,CAAC;AAWjB,OAAO,EAAE,KAAK,UAAU,EAAyB,MAAM,mBAAmB,CAAC;AAqd3E,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAoPjE;AAkFD,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,UAAU,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,CAAC;CAC3C;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAyJ3F;AAirCD,wBAAsB,gBAAgB,CACrC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,OAAO,EAAE,cAAc,GACrB,OAAO,CAAC,IAAI,CAAC,CA6Of"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EACX,iBAAiB,EAEjB,cAAc,EAEd,MAAM,EAGN,MAAM,EAGN,MAAM,SAAS,CAAC;AAWjB,OAAO,EAAE,KAAK,UAAU,EAAyB,MAAM,mBAAmB,CAAC;AA0d3E,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAqSjE;AAkFD,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,UAAU,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,CAAC;CAC3C;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAyJ3F;AAirCD,wBAAsB,gBAAgB,CACrC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,OAAO,EAAE,cAAc,GACrB,OAAO,CAAC,IAAI,CAAC,CA6Of"}

package/dist/cli.js

@@ -11,9 +11,9 @@ import * as tui from './tui';
 import { parseArgsSchema, parseOptionsSchema, buildValidationInputAsync } from './schema-parser';
 import { defaultProfileName, loadProjectConfig, saveProjectId, saveRegion } from './config';
 import { APIClient, getAPIBaseURL, getAppBaseURL } from './api';
-import { ErrorCode, ExitCode, createError, exitWithError } from './errors';
+import { ErrorCode, ExitCode, createError, exitWithError, formatErrorJSON } from './errors';
 import { getCommand } from './command-prefix';
-import { isValidateMode, outputValidation } from './output';
+import { getOutputOptions, isValidateMode, outputValidation, } from './output';
 import { StructuredError } from '@agentuity/core';
 import { setProgram } from './program-ref';
 import { generateIntroPrompt } from './cmd/ai/intro';
@@ -413,6 +413,12 @@ export async function createCLI(version) {
     // Handle unknown commands
     program.on('command:*', (operands) => {
         const unknownCommand = operands[0];
+        const opts = getOutputOptions();
+        if (opts?.json || opts?.errorFormat === 'json') {
+            console.error(formatErrorJSON(createError(ErrorCode.UNKNOWN_COMMAND, `unknown command '${unknownCommand}'`)));
+            process.exit(1);
+            return;
+        }
         console.error(`error: unknown command '${unknownCommand}'`);
         console.error();
         const availableCommands = program.commands.map((cmd) => cmd.name());
@@ -426,13 +432,50 @@ export async function createCLI(version) {
         console.error(`Run '${getCommand('--help')}' for usage information.`);
         process.exit(1);
     });
+    // Track whether a JSON error was already emitted by outputError
+    // so we can suppress Commander's help-after-error text in JSON mode
+    let jsonErrorEmitted = false;
     // Custom error handling for argument/command parsing errors
     program.configureOutput({
+        writeErr: (str) => {
+            // In JSON mode, suppress Commander's help-after-error text
+            // (we already emitted a structured JSON error in outputError)
+            const opts = getOutputOptions();
+            if (jsonErrorEmitted && (opts?.json || opts?.errorFormat === 'json')) {
+                return;
+            }
+            process.stderr.write(str);
+        },
         outputError: (str, write) => {
             // Suppress "unknown option '--help'" error since we handle help flags specially
             if (str.includes("unknown option '--help'")) {
                 return;
             }
+            // In JSON mode, output structured JSON errors for all Commander parsing errors
+            const opts = getOutputOptions();
+            if (opts?.json || opts?.errorFormat === 'json') {
+                // Strip "error: " prefix and trailing newline for clean message
+                let message = str.replace(/^error:\s*/, '').replace(/\n$/, '');
+                let code = ErrorCode.INVALID_OPTION;
+                if (str.includes('unknown command') || str.includes('too many arguments')) {
+                    code = ErrorCode.UNKNOWN_COMMAND;
+                }
+                else if (str.includes('missing required argument')) {
+                    code = ErrorCode.MISSING_ARGUMENT;
+                }
+                // Extract Commander's "Did you mean" suggestion into a separate field
+                let suggestions;
+                const suggestionMatch = message.match(/\n\(Did you mean (.+)\?\)/);
+                if (suggestionMatch?.[1] != null) {
+                    suggestions = [suggestionMatch[1]];
+                    message = message.replace(/\n\(Did you mean .+\?\)/, '');
+                }
+                // Write directly to stderr (not via write/writeErr) to avoid
+                // self-suppression — writeErr suppresses output when jsonErrorEmitted is true
+                jsonErrorEmitted = true;
+                process.stderr.write(formatErrorJSON(createError(code, message, undefined, suggestions)) + '\n');
+                return;
+            }
             // Intercept commander.js error messages
             if (str.includes('too many arguments') || str.includes('unknown command')) {
                 // Extract potential command name from error context