@agentuity/cli 0.0.48 → 0.0.50

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,122 @@ 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;
+	}
+}
+
+/**
+ * Table column definition
+ */
+export interface TableColumn {
+	/** Column name */
+	name: string;
+	/** Column alignment */
+	alignment?: 'left' | 'right' | 'center';
+}
+
+/**
+ * Display data in a formatted table using console-table-printer
+ *
+ * Supports two modes:
+ * 1. Simple mode: Pass data array and optional column names
+ * 2. Advanced mode: Pass column configurations with custom names and alignment
+ *
+ * @param data - Array of data objects to display
+ * @param columns - Column names or column configurations
+ * @param options - Additional options
+ * @returns If render=true, returns the table as a string, otherwise prints to stdout
+ */
+export function table<T extends Record<string, unknown>>(
+	data: T[],
+	columns?: (keyof T)[] | TableColumn[],
+	options?: { render?: boolean }
+): string | void {
+	// Dynamic import to avoid type errors (console-table-printer has poor typings)
+	// eslint-disable-next-line @typescript-eslint/no-require-imports
+	const { Table } = require('console-table-printer') as {
+		Table: new (options?: { columns?: Array<{ name: string; alignment: string }> }) => {
+			addRow(row: Record<string, unknown>): void;
+			printTable(): void;
+			render(): string;
+		};
+	};
+
+	if (!data || data.length === 0) {
+		return options?.render ? '' : undefined;
+	}
+
+	// Determine if we're using advanced column config or simple column names
+	const isAdvancedMode = columns && columns.length > 0 && typeof columns[0] === 'object';
+
+	let tableConfig: { columns: Array<{ name: string; alignment: string }> };
+
+	if (isAdvancedMode) {
+		// Advanced mode: use provided column configurations
+		tableConfig = {
+			columns: (columns as TableColumn[]).map((col) => ({
+				name: col.name,
+				alignment: col.alignment || 'left',
+			})),
+		};
+	} else {
+		// Simple mode: determine column names from data or columns parameter
+		const columnNames = columns
+			? (columns as (keyof T)[]).map((c) => String(c))
+			: data.length > 0
+				? Object.keys(data[0])
+				: [];
+
+		tableConfig = {
+			columns: columnNames.map((name) => ({
+				name,
+				alignment: 'left',
+			})),
+		};
+	}
+
+	const t = new Table(tableConfig);
+
+	// Add rows to table
+	for (const row of data) {
+		if (columns && !isAdvancedMode) {
+			// Simple mode with column filtering
+			const filtered: Record<string, unknown> = {};
+			for (const col of columns as (keyof T)[]) {
+				filtered[String(col)] = row[col];
+			}
+			t.addRow(filtered);
+		} else {
+			// Advanced mode or no column filtering
+			t.addRow(row);
+		}
+	}
+
+	if (options?.render) {
+		return t.render();
+	} else {
+		t.printTable();
+	}
+}