@agentuity/cli 0.0.48 → 0.0.49

package/src/schema-generator.ts

@@ -0,0 +1,389 @@
+import type { Command } from 'commander';
+import type { CommandDefinition, SubcommandDefinition, CommandSchemas } from './types';
+import { parseArgsSchema, parseOptionsSchema } from './schema-parser';
+import * as z from 'zod';
+
+export interface SchemaArgument {
+	name: string;
+	type: string;
+	required: boolean;
+	variadic: boolean;
+	description?: string;
+}
+
+export interface SchemaOption {
+	name: string;
+	type: 'string' | 'number' | 'boolean';
+	required: boolean;
+	default?: unknown;
+	description?: string;
+	enum?: string[];
+}
+
+export interface SchemaPagination {
+	supported: boolean;
+	defaultLimit?: number;
+	maxLimit?: number;
+	parameters?: {
+		limit?: string;
+		offset?: string;
+		cursor?: string;
+	};
+}
+
+export interface SchemaCommand {
+	name: string;
+	description: string;
+	aliases?: string[];
+	arguments?: SchemaArgument[];
+	options?: SchemaOption[];
+	examples?: string[];
+	response?: unknown;
+	idempotent?: boolean;
+	prerequisites?: string[];
+	pagination?: SchemaPagination;
+	tags?: string[];
+	subcommands?: SchemaCommand[];
+	requires?: {
+		auth?: boolean;
+		project?: boolean;
+		org?: boolean;
+		region?: boolean;
+		regions?: boolean;
+	};
+	optional?: {
+		auth?: boolean | string;
+		project?: boolean;
+		org?: boolean;
+		region?: boolean;
+	};
+}
+
+export interface CLISchema {
+	name: string;
+	version: string;
+	description: string;
+	exitCodes: Record<number, string>;
+	globalOptions: SchemaOption[];
+	commands: SchemaCommand[];
+}
+
+/**
+ * Extract schema information from a CommandDefinition
+ */
+function extractCommandSchema(def: CommandDefinition): SchemaCommand {
+	const schema: SchemaCommand = {
+		name: def.name,
+		description: def.description,
+	};
+
+	if (def.aliases) {
+		schema.aliases = def.aliases;
+	}
+
+	// Extract examples if available
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((def as any).examples) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		schema.examples = (def as any).examples;
+	}
+
+	// Extract idempotent marker
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((def as any).idempotent !== undefined) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		schema.idempotent = (def as any).idempotent;
+	}
+
+	// Extract prerequisites
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((def as any).prerequisites) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		schema.prerequisites = (def as any).prerequisites;
+	}
+
+	// Extract pagination
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((def as any).pagination) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		schema.pagination = (def as any).pagination;
+	}
+
+	// Extract tags
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((def as any).tags) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		schema.tags = (def as any).tags;
+	}
+
+	// Extract requires/optional
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const d = def as any;
+	if (d.requires) {
+		schema.requires = {
+			auth: d.requires.auth === true,
+			project: d.requires.project === true,
+			org: d.requires.org === true,
+			region: d.requires.region === true,
+			regions: d.requires.regions === true,
+		};
+	}
+	if (d.optional) {
+		schema.optional = {
+			auth: d.optional.auth === true || typeof d.optional.auth === 'string',
+			project: d.optional.project === true,
+			org: d.optional.org === true,
+			region: d.optional.region === true,
+		};
+	}
+
+	// Extract subcommands recursively
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((def as any).subcommands) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		schema.subcommands = ((def as any).subcommands as SubcommandDefinition[]).map((sub) =>
+			extractSubcommandSchema(sub)
+		);
+	}
+
+	return schema;
+}
+
+/**
+ * Extract schema information from a SubcommandDefinition
+ */
+function extractSubcommandSchema(def: SubcommandDefinition): SchemaCommand {
+	const schema: SchemaCommand = {
+		name: def.name,
+		description: def.description,
+	};
+
+	if (def.aliases) {
+		schema.aliases = def.aliases;
+	}
+
+	// Extract examples if available
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((def as any).examples) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		schema.examples = (def as any).examples;
+	}
+
+	// Extract idempotent marker
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((def as any).idempotent !== undefined) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		schema.idempotent = (def as any).idempotent;
+	}
+
+	// Extract prerequisites
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((def as any).prerequisites) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		schema.prerequisites = (def as any).prerequisites;
+	}
+
+	// Extract pagination
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((def as any).pagination) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		schema.pagination = (def as any).pagination;
+	}
+
+	// Extract tags
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((def as any).tags) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		schema.tags = (def as any).tags;
+	}
+
+	// Extract requires/optional
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const d = def as any;
+	if (d.requires) {
+		schema.requires = {
+			auth: d.requires.auth === true,
+			project: d.requires.project === true,
+			org: d.requires.org === true,
+			region: d.requires.region === true,
+			regions: d.requires.regions === true,
+		};
+	}
+	if (d.optional) {
+		schema.optional = {
+			auth: d.optional.auth === true || typeof d.optional.auth === 'string',
+			project: d.optional.project === true,
+			org: d.optional.org === true,
+			region: d.optional.region === true,
+		};
+	}
+
+	// Extract args and options from schema if available
+	if (d.schema) {
+		const schemas = d.schema as CommandSchemas;
+
+		if (schemas.args) {
+			const parsedArgs = parseArgsSchema(schemas.args);
+			schema.arguments = parsedArgs.metadata.map((arg) => ({
+				name: arg.name,
+				type: arg.variadic ? 'array' : 'string',
+				required: !arg.optional,
+				variadic: arg.variadic,
+			}));
+		}
+
+		if (schemas.options) {
+			const parsedOptions = parseOptionsSchema(schemas.options);
+			schema.options = parsedOptions.map((opt) => ({
+				name: opt.name,
+				type: opt.type,
+				required: !opt.hasDefault,
+				default: opt.defaultValue,
+				description: opt.description,
+			}));
+		}
+
+		if (schemas.response) {
+			schema.response = z.toJSONSchema(schemas.response);
+		}
+	}
+
+	// Extract nested subcommands recursively
+	if (d.subcommands) {
+		schema.subcommands = (d.subcommands as SubcommandDefinition[]).map((sub) =>
+			extractSubcommandSchema(sub)
+		);
+	}
+
+	return schema;
+}
+
+/**
+ * Generate JSON schema for the entire CLI
+ */
+export function generateCLISchema(
+	program: Command,
+	commands: CommandDefinition[],
+	version: string
+): CLISchema {
+	const schema: CLISchema = {
+		name: 'agentuity',
+		version,
+		description: 'Agentuity CLI',
+		exitCodes: {
+			0: 'Success',
+			1: 'General error',
+			2: 'Validation error (invalid arguments or options)',
+			3: 'Authentication error (login required or credentials invalid)',
+			4: 'Resource not found (project, file, deployment, etc.)',
+			5: 'Permission denied (insufficient access rights)',
+			6: 'Network error (API unreachable or timeout)',
+			7: 'File system error (file read/write failed)',
+			8: 'User cancelled (operation aborted by user)',
+		},
+		globalOptions: [
+			{
+				name: 'config',
+				type: 'string',
+				required: false,
+				description: 'Config file path',
+			},
+			{
+				name: 'log-level',
+				type: 'string',
+				required: false,
+				default: 'info',
+				description: 'Log level',
+				enum: ['debug', 'trace', 'info', 'warn', 'error'],
+			},
+			{
+				name: 'log-timestamp',
+				type: 'boolean',
+				required: false,
+				default: false,
+				description: 'Show timestamps in log output',
+			},
+			{
+				name: 'log-prefix',
+				type: 'boolean',
+				required: false,
+				default: true,
+				description: 'Show log level prefixes',
+			},
+			{
+				name: 'org-id',
+				type: 'string',
+				required: false,
+				description: 'Use a specific organization when performing operations',
+			},
+			{
+				name: 'color-scheme',
+				type: 'string',
+				required: false,
+				description: 'Color scheme: light or dark',
+				enum: ['light', 'dark'],
+			},
+			{
+				name: 'color',
+				type: 'string',
+				required: false,
+				default: 'auto',
+				description: 'Color output: auto, always, never',
+				enum: ['auto', 'always', 'never'],
+			},
+			{
+				name: 'error-format',
+				type: 'string',
+				required: false,
+				default: 'text',
+				description: 'Error output format: json or text',
+				enum: ['json', 'text'],
+			},
+			{
+				name: 'json',
+				type: 'boolean',
+				required: false,
+				default: false,
+				description: 'Output in JSON format (machine-readable)',
+			},
+			{
+				name: 'quiet',
+				type: 'boolean',
+				required: false,
+				default: false,
+				description: 'Suppress non-essential output',
+			},
+			{
+				name: 'no-progress',
+				type: 'boolean',
+				required: false,
+				default: false,
+				description: 'Disable progress indicators',
+			},
+			{
+				name: 'explain',
+				type: 'boolean',
+				required: false,
+				default: false,
+				description: 'Show what the command would do without executing',
+			},
+			{
+				name: 'dry-run',
+				type: 'boolean',
+				required: false,
+				default: false,
+				description: 'Execute command without making changes',
+			},
+			{
+				name: 'validate',
+				type: 'boolean',
+				required: false,
+				default: false,
+				description: 'Validate arguments and options without executing',
+			},
+		],
+		commands: commands.map(extractCommandSchema),
+	};
+
+	return schema;
+}

package/src/tui.ts

@@ -5,12 +5,14 @@
  * Uses Bun's built-in color support and ANSI escape codes.
  */
 import { stringWidth } from 'bun';
+import { colorize } from 'json-colorizer';
 import enquirer from 'enquirer';
 import { type OrganizationList, projectList } from '@agentuity/server';
+import * as readline from 'readline';
 import type { ColorScheme } from './terminal';
 import type { Profile } from './types';
 import { type APIClient as APIClientType } from './api';
-import * as readline from 'readline';
+import { getExitCode } from './errors';
 
 // Icons
 const ICONS = {
@@ -100,13 +102,46 @@ function getColor(colorKey: keyof ReturnType<typeof getColors>): string {
 	return color[currentColorScheme];
 }
 
+/**
+ * Color helpers that return colored strings (for inline use, no icons)
+ */
+export function colorSuccess(text: string): string {
+	const color = getColor('success');
+	const reset = getColor('reset');
+	return `${color}${text}${reset}`;
+}
+
+export function colorError(text: string): string {
+	const color = getColor('error');
+	const reset = getColor('reset');
+	return `${color}${text}${reset}`;
+}
+
+export function colorWarning(text: string): string {
+	const color = getColor('warning');
+	const reset = getColor('reset');
+	return `${color}${text}${reset}`;
+}
+
+export function colorInfo(text: string): string {
+	const color = getColor('info');
+	const reset = getColor('reset');
+	return `${color}${text}${reset}`;
+}
+
+export function colorMuted(text: string): string {
+	const color = getColor('muted');
+	const reset = getColor('reset');
+	return `${color}${text}${reset}`;
+}
+
 /**
  * Print a success message with a green checkmark
  */
 export function success(message: string): void {
 	const color = getColor('success');
 	const reset = getColor('reset');
-	console.log(`${color}${ICONS.success} ${message}${reset}`);
+	process.stderr.write(`${color}${ICONS.success} ${message}${reset}\n`);
 }
 
 /**
@@ -115,17 +150,23 @@ export function success(message: string): void {
 export function error(message: string): void {
 	const color = getColor('error');
 	const reset = getColor('reset');
-	console.error(`${color}${ICONS.error} ${message}${reset}`);
+	process.stderr.write(`${color}${ICONS.error} ${message}${reset}\n`);
 }
 
 /**
  * Print an error message with a red X and then exit
  */
-export function fatal(message: string): never {
+export function fatal(message: string, errorCode?: import('./errors').ErrorCode): never {
 	const color = getColor('error');
 	const reset = getColor('reset');
-	console.error(`${color}${ICONS.error} ${message}${reset}`);
-	process.exit(1);
+	process.stderr.write(`${color}${ICONS.error} ${message}${reset}\n`);
+
+	if (errorCode) {
+		const exitCode = getExitCode(errorCode);
+		process.exit(exitCode);
+	} else {
+		process.exit(1);
+	}
 }
 
 /**
@@ -134,7 +175,7 @@ export function fatal(message: string): never {
 export function warning(message: string, asError = false): void {
 	const color = asError ? getColor('error') : getColor('warning');
 	const reset = getColor('reset');
-	console.log(`${color}${ICONS.warning} ${message}${reset}`);
+	process.stderr.write(`${color}${ICONS.warning} ${message}${reset}\n`);
 }
 
 /**
@@ -143,7 +184,7 @@ export function warning(message: string, asError = false): void {
 export function info(message: string): void {
 	const color = getColor('info');
 	const reset = getColor('reset');
-	console.log(`${color}${ICONS.info} ${message}${reset}`);
+	process.stderr.write(`${color}${ICONS.info} ${message}${reset}\n`);
 }
 
 /**
@@ -213,21 +254,21 @@ function supportsHyperlinks(): boolean {
  * Print a bulleted list item
  */
 export function bullet(message: string): void {
-	console.log(`${ICONS.bullet} ${message}`);
+	process.stderr.write(`${ICONS.bullet} ${message}\n`);
 }
 
 /**
  * Print an arrow item (for showing next steps)
  */
 export function arrow(message: string): void {
-	console.log(`${ICONS.arrow} ${message}`);
+	process.stderr.write(`${ICONS.arrow} ${message}\n`);
 }
 
 /**
  * Print a blank line
  */
 export function newline(): void {
-	console.log('');
+	process.stderr.write('\n');
 }
 
 /**
@@ -774,8 +815,13 @@ export async function spinner<T>(
 	const message = options.message;
 	const reset = getColor('reset');
 
-	// If no TTY, just execute the callback without animation
-	if (!process.stderr.isTTY) {
+	// Check if progress should be disabled (from global options)
+	const { getOutputOptions, shouldDisableProgress } = await import('./output');
+	const outputOptions = getOutputOptions();
+	const noProgress = outputOptions ? shouldDisableProgress(outputOptions) : false;
+
+	// If no TTY or progress disabled, just execute the callback without animation
+	if (!process.stderr.isTTY || noProgress) {
 		try {
 			const result =
 				options.type === 'progress'
@@ -1293,3 +1339,28 @@ export async function showProfileList(
 
 	return response.name;
 }
+
+export function json(value: unknown) {
+	const stringValue = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+
+	if (shouldUseColors() && process.stdout.isTTY) {
+		try {
+			console.log(colorize(stringValue));
+			return;
+		} catch {
+			/* */
+		}
+	}
+	console.log(stringValue);
+}
+
+export function plural(count: number, singular: string, plural: string): string {
+	switch (count) {
+		case 0:
+			return plural;
+		case 1:
+			return singular;
+		default:
+			return plural;
+	}
+}

package/src/types.ts

@@ -104,11 +104,31 @@ export interface GlobalOptions {
 	logTimestamp?: boolean;
 	logPrefix?: boolean;
 	orgId?: string;
+	errorFormat?: 'json' | 'text';
+	json?: boolean;
+	quiet?: boolean;
+	noProgress?: boolean;
+	color?: 'auto' | 'always' | 'never';
+	explain?: boolean;
+	dryRun?: boolean;
+	validate?: boolean;
+}
+
+export interface PaginationInfo {
+	supported: boolean;
+	defaultLimit?: number;
+	maxLimit?: number;
+	parameters?: {
+		limit?: string;
+		offset?: string;
+		cursor?: string;
+	};
 }
 
 export interface CommandSchemas {
 	args?: z.ZodType;
 	options?: z.ZodType;
+	response?: z.ZodType;
 }
 
 export type ProjectConfig = zod.infer<typeof ProjectSchema>;
@@ -240,14 +260,19 @@ export function createSubcommand<
 	toplevel?: boolean;
 	requires?: R;
 	optional?: O;
+	examples?: string[];
+	idempotent?: boolean;
+	prerequisites?: string[];
+	pagination?: PaginationInfo;
+	tags?: string[];
 	schema?: A extends z.ZodType
 		? Op extends z.ZodType
-			? { args: A; options: Op }
-			: { args: A }
+			? { args: A; options: Op; response?: z.ZodType }
+			: { args: A; response?: z.ZodType }
 		: Op extends z.ZodType
-			? { options: Op }
-			: never;
-	handler(ctx: CommandContext<R, O, A, Op>): void | Promise<void>;
+			? { options: Op; response?: z.ZodType }
+			: { response?: z.ZodType };
+	handler(ctx: CommandContext<R, O, A, Op>): unknown | Promise<unknown>;
 }): SubcommandDefinition {
 	return definition as unknown as SubcommandDefinition;
 }
@@ -265,14 +290,19 @@ export function createCommand<
 	hidden?: boolean;
 	requires?: R;
 	optional?: O;
+	examples?: string[];
+	idempotent?: boolean;
+	prerequisites?: string[];
+	pagination?: PaginationInfo;
+	tags?: string[];
 	schema?: A extends z.ZodType
 		? Op extends z.ZodType
-			? { args: A; options: Op }
-			: { args: A }
+			? { args: A; options: Op; response?: z.ZodType }
+			: { args: A; response?: z.ZodType }
 		: Op extends z.ZodType
-			? { options: Op }
-			: never;
-	handler?(ctx: CommandContext<R, O, A, Op>): void | Promise<void>;
+			? { options: Op; response?: z.ZodType }
+			: { response?: z.ZodType };
+	handler?(ctx: CommandContext<R, O, A, Op>): unknown | Promise<unknown>;
 	subcommands?: SubcommandDefinition[];
 }): CommandDefinition {
 	return definition as unknown as CommandDefinition;
@@ -284,8 +314,13 @@ type CommandDefBase =
 			description: string;
 			aliases?: string[];
 			banner?: boolean;
+			examples?: string[];
+			idempotent?: boolean;
+			prerequisites?: string[];
+			pagination?: PaginationInfo;
+			tags?: string[];
 			schema?: CommandSchemas;
-			handler(ctx: CommandContext): void | Promise<void>;
+			handler(ctx: CommandContext): unknown | Promise<unknown>;
 			subcommands?: SubcommandDefinition[];
 	  }
 	| {
@@ -293,6 +328,11 @@ type CommandDefBase =
 			description: string;
 			aliases?: string[];
 			banner?: boolean;
+			examples?: string[];
+			idempotent?: boolean;
+			prerequisites?: string[];
+			pagination?: PaginationInfo;
+			tags?: string[];
 			schema?: CommandSchemas;
 			handler?: undefined;
 			subcommands: SubcommandDefinition[];
@@ -305,8 +345,13 @@ type SubcommandDefBase =
 			aliases?: string[];
 			toplevel?: boolean;
 			banner?: boolean;
+			examples?: string[];
+			idempotent?: boolean;
+			prerequisites?: string[];
+			pagination?: PaginationInfo;
+			tags?: string[];
 			schema?: CommandSchemas;
-			handler(ctx: CommandContext): void | Promise<void>;
+			handler(ctx: CommandContext): unknown | Promise<unknown>;
 			subcommands?: SubcommandDefinition[];
 	  }
 	| {
@@ -315,6 +360,11 @@ type SubcommandDefBase =
 			aliases?: string[];
 			toplevel?: boolean;
 			banner?: boolean;
+			examples?: string[];
+			idempotent?: boolean;
+			prerequisites?: string[];
+			pagination?: PaginationInfo;
+			tags?: string[];
 			schema?: CommandSchemas;
 			handler?: undefined;
 			subcommands: SubcommandDefinition[];