@agentuity/cli 0.0.47 → 0.0.49

package/src/cmd/secret/list.ts

@@ -3,12 +3,18 @@ import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { projectGet } from '@agentuity/server';
 import { maskSecret } from '../../env-util';
+import { getCommand } from '../../command-prefix';
+
+const SecretListResponseSchema = z.record(z.string(), z.string().describe('Secret value'));
 
 export const listSubcommand = createSubcommand({
 	name: 'list',
 	aliases: ['ls'],
 	description: 'List all secrets',
+	tags: ['read-only', 'fast', 'requires-auth', 'requires-project'],
+	examples: [getCommand('secret list'), getCommand('secret list --no-mask')],
 	requires: { auth: true, project: true, apiClient: true },
+	idempotent: true,
 	schema: {
 		options: z.object({
 			mask: z
@@ -16,6 +22,7 @@ export const listSubcommand = createSubcommand({
 				.default(!!process.stdout.isTTY)
 				.describe('mask the values in output (default: true in TTY for secrets)'),
 		}),
+		response: SecretListResponseSchema,
 	},
 
 	async handler(ctx) {
@@ -30,7 +37,7 @@ export const listSubcommand = createSubcommand({
 
 		if (Object.keys(secrets).length === 0) {
 			tui.info('No secrets found');
-			return;
+			return {};
 		}
 
 		// Display the secrets
@@ -52,5 +59,7 @@ export const listSubcommand = createSubcommand({
 				console.log(`${key}=${displayValue}`);
 			}
 		}
+
+		return secrets;
 	},
 });

package/src/cmd/secret/pull.ts

@@ -10,15 +10,28 @@ import {
 	writeEnvFile,
 	mergeEnvVars,
 } from '../../env-util';
+import { getCommand } from '../../command-prefix';
+
+const SecretPullResponseSchema = z.object({
+	success: z.boolean().describe('Whether pull succeeded'),
+	pulled: z.number().describe('Number of items pulled'),
+	path: z.string().describe('Local file path where secrets were saved'),
+	force: z.boolean().describe('Whether force mode was used'),
+});
 
 export const pullSubcommand = createSubcommand({
 	name: 'pull',
 	description: 'Pull secrets from cloud to local .env.production file',
+	tags: ['slow', 'requires-auth', 'requires-project'],
+	idempotent: true,
+	examples: [getCommand('secret pull'), getCommand('secret pull --force')],
 	requires: { auth: true, project: true, apiClient: true },
+	prerequisites: ['cloud deploy'],
 	schema: {
 		options: z.object({
 			force: z.boolean().default(false).describe('overwrite local values with cloud values'),
 		}),
+		response: SecretPullResponseSchema,
 	},
 
 	async handler(ctx) {
@@ -74,5 +87,12 @@ export const pullSubcommand = createSubcommand({
 
 		const count = Object.keys(cloudSecrets).length;
 		tui.success(`Pulled ${count} secret${count !== 1 ? 's' : ''} to ${targetEnvPath}`);
+
+		return {
+			success: true,
+			pulled: count,
+			path: targetEnvPath,
+			force: opts?.force ?? false,
+		};
 	},
 });

package/src/cmd/secret/push.ts

@@ -1,12 +1,34 @@
+import { z } from 'zod';
 import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { projectEnvUpdate } from '@agentuity/server';
 import { findEnvFile, readEnvFile, filterAgentuitySdkKeys } from '../../env-util';
+import { getCommand } from '../../command-prefix';
+
+const SecretPushResponseSchema = z.object({
+	success: z.boolean().describe('Whether push succeeded'),
+	pushed: z.number().describe('Number of items pushed'),
+	source: z.string().describe('Source file path'),
+});
 
 export const pushSubcommand = createSubcommand({
 	name: 'push',
 	description: 'Push secrets from local .env.production file to cloud',
+	tags: [
+		'mutating',
+		'updates-resource',
+		'slow',
+		'api-intensive',
+		'requires-auth',
+		'requires-project',
+	],
+	idempotent: true,
+	examples: [getCommand('secret push')],
 	requires: { auth: true, project: true, apiClient: true },
+	prerequisites: ['secret set'],
+	schema: {
+		response: SecretPushResponseSchema,
+	},
 
 	async handler(ctx) {
 		const { apiClient, project, projectDir } = ctx;
@@ -20,7 +42,11 @@ export const pushSubcommand = createSubcommand({
 
 		if (Object.keys(filteredSecrets).length === 0) {
 			tui.warning('No secrets to push');
-			return;
+			return {
+				success: false,
+				pushed: 0,
+				source: envFilePath,
+			};
 		}
 
 		// Push to cloud (using secrets field)
@@ -33,5 +59,11 @@ export const pushSubcommand = createSubcommand({
 
 		const count = Object.keys(filteredSecrets).length;
 		tui.success(`Pushed ${count} secret${count !== 1 ? 's' : ''} to cloud`);
+
+		return {
+			success: true,
+			pushed: count,
+			source: envFilePath,
+		};
 	},
 });

package/src/cmd/secret/set.ts

@@ -3,16 +3,30 @@ import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { projectEnvUpdate } from '@agentuity/server';
 import { findEnvFile, readEnvFile, writeEnvFile, filterAgentuitySdkKeys } from '../../env-util';
+import { getCommand } from '../../command-prefix';
+
+const SecretSetResponseSchema = z.object({
+	success: z.boolean().describe('Whether the operation succeeded'),
+	key: z.string().describe('Secret key name'),
+	path: z.string().describe('Local file path where secret was saved'),
+});
 
 export const setSubcommand = createSubcommand({
 	name: 'set',
 	description: 'Set a secret',
+	tags: ['mutating', 'updates-resource', 'slow', 'requires-auth', 'requires-project'],
+	idempotent: true,
+	examples: [
+		getCommand('secret set DATABASE_URL "postgres://user:pass@host:5432/db"'),
+		getCommand('secret set STRIPE_SECRET_KEY "sk_live_..."'),
+	],
 	requires: { auth: true, project: true, apiClient: true },
 	schema: {
 		args: z.object({
 			key: z.string().min(1, 'key must not be empty').describe('the secret key'),
 			value: z.string().min(1, 'value must not be empty').describe('the secret value'),
 		}),
+		response: SecretSetResponseSchema,
 	},
 
 	async handler(ctx) {
@@ -41,5 +55,11 @@ export const setSubcommand = createSubcommand({
 		await writeEnvFile(envFilePath, filteredEnv);
 
 		tui.success(`Secret '${args.key}' set successfully (cloud + ${envFilePath})`);
+
+		return {
+			success: true,
+			key: args.key,
+			path: envFilePath,
+		};
 	},
 });

package/src/cmd/version/index.ts

@@ -1,17 +1,30 @@
 import { createCommand } from '../../types';
 import { getVersion } from '../../version';
 import { createLogger } from '@agentuity/server';
+import { getCommand } from '../../command-prefix';
+import { z } from 'zod';
+import { ErrorCode } from '../../errors';
+
+const VersionResponseSchema = z.string().describe('CLI version number');
 
 export const command = createCommand({
 	name: 'version',
 	description: 'Display version information',
+	tags: ['read-only', 'fast'],
+	examples: [getCommand('version'), getCommand('--version')],
+	schema: {
+		response: VersionResponseSchema,
+	},
+	idempotent: true,
 
 	async handler() {
 		try {
-			console.log(getVersion());
+			const version = getVersion();
+			console.log(version);
+			return version;
 		} catch (error) {
 			const logger = createLogger();
-			logger.fatal('Failed to retrieve version: %s', error);
+			logger.fatal('Failed to retrieve version: %s', error, ErrorCode.INTERNAL_ERROR);
 		}
 	},
 });

package/src/config.ts

@@ -41,7 +41,7 @@ export async function ensureConfigDir(): Promise<void> {
 
 export async function saveProfile(path: string): Promise<void> {
 	await ensureConfigDir();
-	await writeFile(getProfilePath(), path, { mode: 0o644 });
+	await writeFile(getProfilePath(), path, { mode: 0o600 });
 }
 
 export async function getProfile(): Promise<string> {
@@ -108,7 +108,12 @@ function expandTilde(path: string): string {
 	return path;
 }
 
+let cachedConfig: Config | null | undefined;
+
 export async function loadConfig(customPath?: string): Promise<Config | null> {
+	if (cachedConfig !== undefined) {
+		return cachedConfig;
+	}
 	const configPath = customPath ? expandTilde(customPath) : await getProfile();
 
 	try {
@@ -171,11 +176,13 @@ export async function loadConfig(customPath?: string): Promise<Config | null> {
 			result.data.overrides = overrides;
 		}
 
+		cachedConfig = result.data;
 		return result.data;
 	} catch (error) {
 		if (error instanceof Error) {
 			console.error(`Error loading config from ${configPath}:`, error.message);
 		}
+		cachedConfig = null;
 		return null;
 	}
 }
@@ -230,6 +237,7 @@ export async function saveConfig(config: Config, customPath?: string): Promise<v
 	await writeFile(configPath, content + '\n', { mode: 0o600 });
 	// Ensure existing files get correct permissions on upgrade
 	await chmod(configPath, 0o600);
+	cachedConfig = config;
 }
 
 async function getOrInitConfig(): Promise<Config> {
@@ -582,10 +590,15 @@ export async function loadBuildMetadata(dir: string): Promise<BuildMetadata> {
 	return result.data;
 }
 
-export async function loadDevelopmentProjectSDKKey(
-	projectDir: string
-): Promise<string | undefined> {
-	const files: string[] = ['.env.development', '.env.local', '.env'];
+export async function loadProjectSDKKey(projectDir: string): Promise<string | undefined> {
+	const files: string[] =
+		process.env.NODE_ENV === 'production'
+			? ['.env', '.env.production']
+			: ['.env.development', '.env.local', '.env'];
+	const c = await getOrInitConfig();
+	if (c) {
+		files.unshift(`.env.${c.name}`);
+	}
 	for (const filename of files) {
 		const fn = join(projectDir, filename);
 		if (existsSync(fn)) {

package/src/errors.ts

@@ -0,0 +1,222 @@
+import type { Logger } from './types';
+
+/**
+ * Standard exit codes for the CLI
+ */
+export enum ExitCode {
+	SUCCESS = 0,
+	GENERAL_ERROR = 1,
+	VALIDATION_ERROR = 2,
+	AUTH_ERROR = 3,
+	NOT_FOUND = 4,
+	PERMISSION_ERROR = 5,
+	NETWORK_ERROR = 6,
+	FILE_ERROR = 7,
+	USER_CANCELLED = 8,
+}
+
+/**
+ * Standard error codes for the CLI
+ */
+export enum ErrorCode {
+	// Validation errors
+	VALIDATION_FAILED = 'VALIDATION_FAILED',
+	MISSING_ARGUMENT = 'MISSING_ARGUMENT',
+	INVALID_ARGUMENT = 'INVALID_ARGUMENT',
+	INVALID_OPTION = 'INVALID_OPTION',
+	UNKNOWN_COMMAND = 'UNKNOWN_COMMAND',
+
+	// Authentication errors
+	AUTH_REQUIRED = 'AUTH_REQUIRED',
+	AUTH_FAILED = 'AUTH_FAILED',
+	AUTH_EXPIRED = 'AUTH_EXPIRED',
+	PERMISSION_DENIED = 'PERMISSION_DENIED',
+
+	// Project/Configuration errors
+	PROJECT_NOT_FOUND = 'PROJECT_NOT_FOUND',
+	PROJECT_INVALID = 'PROJECT_INVALID',
+	CONFIG_NOT_FOUND = 'CONFIG_NOT_FOUND',
+	CONFIG_INVALID = 'CONFIG_INVALID',
+
+	// Resource errors
+	RESOURCE_NOT_FOUND = 'RESOURCE_NOT_FOUND',
+	RESOURCE_ALREADY_EXISTS = 'RESOURCE_ALREADY_EXISTS',
+	RESOURCE_CONFLICT = 'RESOURCE_CONFLICT',
+
+	// Organization/Region errors
+	ORG_REQUIRED = 'ORG_REQUIRED',
+	ORG_NOT_FOUND = 'ORG_NOT_FOUND',
+	REGION_REQUIRED = 'REGION_REQUIRED',
+	REGION_NOT_FOUND = 'REGION_NOT_FOUND',
+	NO_REGIONS_AVAILABLE = 'NO_REGIONS_AVAILABLE',
+
+	// Network/API errors
+	NETWORK_ERROR = 'NETWORK_ERROR',
+	API_ERROR = 'API_ERROR',
+	TIMEOUT = 'TIMEOUT',
+
+	// File system errors
+	FILE_NOT_FOUND = 'FILE_NOT_FOUND',
+	FILE_READ_ERROR = 'FILE_READ_ERROR',
+	FILE_WRITE_ERROR = 'FILE_WRITE_ERROR',
+	DIRECTORY_NOT_FOUND = 'DIRECTORY_NOT_FOUND',
+
+	// Runtime errors
+	RUNTIME_ERROR = 'RUNTIME_ERROR',
+	INTERNAL_ERROR = 'INTERNAL_ERROR',
+	NOT_IMPLEMENTED = 'NOT_IMPLEMENTED',
+
+	// User cancellation
+	USER_CANCELLED = 'USER_CANCELLED',
+}
+
+/**
+ * Map error codes to exit codes
+ */
+export function getExitCode(errorCode: ErrorCode): ExitCode {
+	switch (errorCode) {
+		// Validation errors
+		case ErrorCode.VALIDATION_FAILED:
+		case ErrorCode.MISSING_ARGUMENT:
+		case ErrorCode.INVALID_ARGUMENT:
+		case ErrorCode.INVALID_OPTION:
+		case ErrorCode.UNKNOWN_COMMAND:
+		case ErrorCode.PROJECT_INVALID:
+		case ErrorCode.CONFIG_INVALID:
+			return ExitCode.VALIDATION_ERROR;
+
+		// Authentication errors
+		case ErrorCode.AUTH_REQUIRED:
+		case ErrorCode.AUTH_FAILED:
+		case ErrorCode.AUTH_EXPIRED:
+			return ExitCode.AUTH_ERROR;
+
+		// Permission errors
+		case ErrorCode.PERMISSION_DENIED:
+			return ExitCode.PERMISSION_ERROR;
+
+		// Not found errors
+		case ErrorCode.PROJECT_NOT_FOUND:
+		case ErrorCode.CONFIG_NOT_FOUND:
+		case ErrorCode.RESOURCE_NOT_FOUND:
+		case ErrorCode.ORG_NOT_FOUND:
+		case ErrorCode.REGION_NOT_FOUND:
+		case ErrorCode.FILE_NOT_FOUND:
+		case ErrorCode.DIRECTORY_NOT_FOUND:
+		case ErrorCode.NO_REGIONS_AVAILABLE:
+			return ExitCode.NOT_FOUND;
+
+		// Network/API errors
+		case ErrorCode.NETWORK_ERROR:
+		case ErrorCode.API_ERROR:
+		case ErrorCode.TIMEOUT:
+			return ExitCode.NETWORK_ERROR;
+
+		// File system errors
+		case ErrorCode.FILE_READ_ERROR:
+		case ErrorCode.FILE_WRITE_ERROR:
+			return ExitCode.FILE_ERROR;
+
+		// User cancellation
+		case ErrorCode.USER_CANCELLED:
+			return ExitCode.USER_CANCELLED;
+
+		// Resource conflicts and other errors
+		case ErrorCode.RESOURCE_ALREADY_EXISTS:
+		case ErrorCode.RESOURCE_CONFLICT:
+		case ErrorCode.ORG_REQUIRED:
+		case ErrorCode.REGION_REQUIRED:
+		case ErrorCode.RUNTIME_ERROR:
+		case ErrorCode.INTERNAL_ERROR:
+		case ErrorCode.NOT_IMPLEMENTED:
+		default:
+			return ExitCode.GENERAL_ERROR;
+	}
+}
+
+/**
+ * Structured error information
+ */
+export interface StructuredError {
+	code: ErrorCode;
+	message: string;
+	details?: Record<string, unknown>;
+	suggestions?: string[];
+	exitCode?: ExitCode;
+}
+
+/**
+ * Format error in JSON structure
+ */
+export function formatErrorJSON(error: StructuredError): string {
+	const exitCode = error.exitCode ?? getExitCode(error.code);
+	const output: Record<string, unknown> = {
+		error: {
+			code: error.code,
+			message: error.message,
+			exitCode,
+		},
+	};
+
+	if (error.details) {
+		(output.error as Record<string, unknown>).details = error.details;
+	}
+
+	if (error.suggestions && error.suggestions.length > 0) {
+		(output.error as Record<string, unknown>).suggestions = error.suggestions;
+	}
+
+	return JSON.stringify(output, null, 2);
+}
+
+/**
+ * Format error for human-readable output
+ */
+export function formatErrorHuman(error: StructuredError): string {
+	let output = `error: ${error.message}`;
+
+	if (error.details && Object.keys(error.details).length > 0) {
+		output += '\n\nDetails:';
+		for (const [key, value] of Object.entries(error.details)) {
+			output += `\n  ${key}: ${JSON.stringify(value)}`;
+		}
+	}
+
+	if (error.suggestions && error.suggestions.length > 0) {
+		output += '\n\nSuggestions:';
+		for (const suggestion of error.suggestions) {
+			output += `\n  - ${suggestion}`;
+		}
+	}
+
+	return output;
+}
+
+/**
+ * Exit the process with a structured error
+ */
+export function exitWithError(
+	error: StructuredError,
+	logger: Logger,
+	errorFormat: 'json' | 'text' = 'text'
+): never {
+	if (errorFormat === 'json') {
+		console.error(formatErrorJSON(error));
+	} else {
+		console.error(formatErrorHuman(error));
+	}
+	const exitCode = error.exitCode ?? getExitCode(error.code);
+	process.exit(exitCode);
+}
+
+/**
+ * Create a structured error from a simple message and code
+ */
+export function createError(
+	code: ErrorCode,
+	message: string,
+	details?: Record<string, unknown>,
+	suggestions?: string[]
+): StructuredError {
+	return { code, message, details, suggestions };
+}

package/src/explain.ts

@@ -0,0 +1,126 @@
+import type { GlobalOptions } from './types';
+import * as tui from './tui';
+
+/**
+ * Utilities for explain mode and dry-run mode
+ */
+
+/**
+ * Check if explain mode is enabled
+ */
+export function isExplainMode(options: GlobalOptions): boolean {
+	return options.explain === true;
+}
+
+/**
+ * Check if dry-run mode is enabled
+ */
+export function isDryRunMode(options: GlobalOptions): boolean {
+	return options.dryRun === true;
+}
+
+/**
+ * Check if the command should execute (not explain, not dry-run unless specifically handling dry-run)
+ */
+export function shouldExecute(options: GlobalOptions): boolean {
+	return !options.explain && !options.dryRun;
+}
+
+/**
+ * Explanation step for a command action
+ */
+export interface ExplainStep {
+	action: string;
+	details?: Record<string, unknown>;
+}
+
+/**
+ * Explanation plan for a command
+ */
+export interface ExplainPlan {
+	command: string;
+	description: string;
+	prerequisites?: string[];
+	steps: ExplainStep[];
+	warnings?: string[];
+	estimatedDuration?: string;
+}
+
+/**
+ * Output an explanation plan
+ */
+export function outputExplain(plan: ExplainPlan, options: GlobalOptions): void {
+	if (options.json) {
+		console.log(JSON.stringify({ explain: plan }, null, 2));
+		return;
+	}
+
+	// Human-readable output
+	console.log(tui.bold('Command Explanation:'));
+	console.log(`  ${plan.command}`);
+	tui.newline();
+
+	if (plan.description) {
+		console.log(tui.bold('Description:'));
+		console.log(`  ${plan.description}`);
+		tui.newline();
+	}
+
+	if (plan.prerequisites && plan.prerequisites.length > 0) {
+		console.log(tui.bold('Prerequisites:'));
+		for (const prereq of plan.prerequisites) {
+			console.log(`  ${tui.bullet} ${prereq}`);
+		}
+		tui.newline();
+	}
+
+	console.log(tui.bold('This command will:'));
+	for (const step of plan.steps) {
+		console.log(`  • ${step.action}`);
+		if (step.details && Object.keys(step.details).length > 0) {
+			for (const [key, value] of Object.entries(step.details)) {
+				console.log(`    ${tui.muted(`${key}: ${JSON.stringify(value)}`)}`);
+			}
+		}
+	}
+	tui.newline();
+
+	if (plan.warnings && plan.warnings.length > 0) {
+		console.log(tui.bold('Warnings:'));
+		for (const warn of plan.warnings) {
+			console.log(`  ⚠ ${warn}`);
+		}
+		tui.newline();
+	}
+
+	if (plan.estimatedDuration) {
+		console.log(tui.muted(`Estimated duration: ${plan.estimatedDuration}`));
+		tui.newline();
+	}
+}
+
+/**
+ * Create a simple explain plan
+ */
+export function createExplainPlan(
+	command: string,
+	description: string,
+	steps: string[]
+): ExplainPlan {
+	return {
+		command,
+		description,
+		steps: steps.map((action) => ({ action })),
+	};
+}
+
+/**
+ * Output dry-run result
+ */
+export function outputDryRun(message: string, options: GlobalOptions): void {
+	if (options.json) {
+		console.log(JSON.stringify({ dryRun: true, message }, null, 2));
+	} else {
+		console.log(tui.muted('[DRY RUN] ') + message);
+	}
+}

package/src/index.ts

@@ -1,5 +1,47 @@
 export { createCLI, registerCommands } from './cli';
 export { validateRuntime, isBun } from './runtime';
+export { generateCLISchema, type CLISchema, type SchemaCommand } from './schema-generator';
+export {
+	ErrorCode,
+	createError,
+	exitWithError,
+	formatErrorJSON,
+	formatErrorHuman,
+	type StructuredError,
+} from './errors';
+export { wrapLogger, CLILogger } from './cli-logger';
+export {
+	isJSONMode,
+	isQuietMode,
+	shouldDisableProgress,
+	shouldDisableColors,
+	outputJSON,
+	outputSuccess,
+	outputInfo,
+	outputWarning,
+	canPrompt,
+	createSuccessResponse,
+	createErrorResponse,
+	createMetadata,
+	setOutputOptions,
+	getOutputOptions,
+	createBatchResult,
+	outputBatchResult,
+	type JSONResponse,
+	type ResponseMetadata,
+	type BatchItemResult,
+	type BatchOperationResult,
+} from './output';
+export {
+	isExplainMode,
+	isDryRunMode,
+	shouldExecute,
+	outputExplain,
+	createExplainPlan,
+	outputDryRun,
+	type ExplainPlan,
+	type ExplainStep,
+} from './explain';
 export { getVersion, getRevision, getPackageName, getPackage } from './version';
 export { requireAuth, optionalAuth } from './auth';
 export {
@@ -27,6 +69,15 @@ export { discoverCommands } from './cmd';
 export { detectColorScheme } from './terminal';
 export { getCommandPrefix, getCommand } from './command-prefix';
 export * as tui from './tui';
+export {
+	createRepl,
+	type ReplConfig,
+	type ReplCommand,
+	type ReplContext,
+	type ParsedCommand,
+	type CommandHandler,
+	type TableColumn,
+} from './repl';
 export { runSteps, setStepsColorScheme, stepSuccess, stepSkipped, stepError } from './steps';
 export { playSound } from './sound';
 export {