@agentuity/cli 1.0.0 → 1.0.2

package/src/tui/prompt.ts

@@ -55,6 +55,16 @@ interface PromptState {
 export class PromptFlow {
 	private states: PromptState[] = [];
 
+	private isInteractive(): boolean {
+		return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+	}
+
+	private nonInteractiveError(message: string): Error {
+		return new Error(
+			`${message} Use the appropriate --flag or environment variable to provide input.`
+		);
+	}
+
 	/**
 	 * Display intro banner
 	 */
@@ -84,7 +94,24 @@ export class PromptFlow {
 	 * Text input prompt
 	 */
 	async text(options: TextOptions): Promise<string> {
-		const { message, initial = '', validate } = options;
+		const { message, validate } = options;
+		const initial = options.initial ?? '';
+		const hasDefault = options.initial !== undefined;
+
+		if (!this.isInteractive()) {
+			if (hasDefault) {
+				const validationResult = validate ? await validate(initial) : true;
+				if (validationResult === true) {
+					return initial;
+				}
+				// Validation failed - include the error message if it's a string
+				const errorDetail = typeof validationResult === 'string' ? `: ${validationResult}` : '';
+				throw this.nonInteractiveError(
+					`Cannot prompt for "${message}" in non-interactive mode. Validation failed for default value "${initial}"${errorDetail}.`
+				);
+			}
+			throw this.nonInteractiveError(`Cannot prompt for "${message}" in non-interactive mode.`);
+		}
 
 		return new Promise((resolve, reject) => {
 			const rl = readline.createInterface({
@@ -208,6 +235,10 @@ export class PromptFlow {
 	async confirm(options: ConfirmOptions): Promise<boolean> {
 		const { message, initial = false } = options;
 
+		if (!this.isInteractive()) {
+			return initial;
+		}
+
 		return new Promise((resolve, reject) => {
 			const hint = initial ? 'Y/n' : 'y/N';
 
@@ -292,6 +323,18 @@ export class PromptFlow {
 	async select<T = string>(options: SelectOptions<T>): Promise<T> {
 		const { message, options: choices, initial } = options;
 
+		if (!this.isInteractive()) {
+			let selectedIndex = choices.findIndex((c) => c.value === initial);
+			if (selectedIndex === -1) selectedIndex = 0;
+			const selected = choices[selectedIndex];
+			if (!selected) {
+				throw this.nonInteractiveError(
+					`Cannot prompt for "${message}" in non-interactive mode.`
+				);
+			}
+			return selected.value;
+		}
+
 		return new Promise((resolve, reject) => {
 			let selectedIndex = choices.findIndex((c) => c.value === initial);
 			if (selectedIndex === -1) selectedIndex = 0;
@@ -397,6 +440,11 @@ export class PromptFlow {
 	async multiselect<T = string>(options: MultiSelectOptions<T>): Promise<T[]> {
 		const { message, options: choices, initial = [] } = options;
 
+		if (!this.isInteractive()) {
+			const choiceValues = new Set(choices.map((choice) => choice.value));
+			return initial.filter((value) => choiceValues.has(value));
+		}
+
 		return new Promise((resolve, reject) => {
 			let cursorIndex = 0;
 			const selected = new Set<number>(
@@ -466,8 +514,12 @@ export class PromptFlow {
 
 					// Sort indices to get consistent order for both values and labels
 					const sortedIndices = Array.from(selected).sort((a, b) => a - b);
-					const values = sortedIndices.map((i) => choices[i]?.value).filter((v) => v !== undefined);
-					const labels = sortedIndices.map((i) => choices[i]?.label).filter((l) => l !== undefined);
+					const values = sortedIndices
+						.map((i) => choices[i]?.value)
+						.filter((v) => v !== undefined);
+					const labels = sortedIndices
+						.map((i) => choices[i]?.label)
+						.filter((l) => l !== undefined);
 
 					// Clear all lines (message + all choices)
 					const totalLines = choices.length + 1;

package/src/tui/symbols.ts

@@ -2,6 +2,7 @@
  * Box drawing and UI symbols for TUI components
  * Supports Unicode with ASCII fallbacks for non-unicode terminals
  */
+import { getExecutingAgent } from '../agent-detection';
 
 // Detect unicode support
 const isUnicodeSupported = (): boolean => {
@@ -10,6 +11,11 @@ const isUnicodeSupported = (): boolean => {
 		return true;
 	}
 
+	// Use ASCII for AI coding agents (cleaner output for parsing)
+	if (getExecutingAgent()) {
+		return false;
+	}
+
 	if (process.platform !== 'win32') {
 		return process.env.TERM !== 'linux'; // Linux console (kernel) doesn't support Unicode
 	}

package/src/tui.ts

@@ -15,6 +15,7 @@ import type { Profile } from './types';
 import { type APIClient as APIClientType } from './api';
 import { getExitCode } from './errors';
 import { maskSecret } from './env-util';
+import { getExecutingAgent } from './agent-detection';
 
 // Install global exit handler to always restore terminal cursor
 // This ensures cursor is restored even when process.exit() is called directly
@@ -28,6 +29,10 @@ function ensureCursorRestoration(): void {
 		if (process.env.CI) {
 			return;
 		}
+		// Skip cursor restoration when running from an AI coding agent
+		if (getExecutingAgent()) {
+			return;
+		}
 		// Restore cursor visibility
 		process.stderr.write('\x1B[?25h');
 	};
@@ -56,26 +61,63 @@ export type {
 	MultiSelectOptions,
 } from './tui/prompt';
 
-// Icons
-export const ICONS = {
-	success: '✓',
-	error: '✗',
-	warning: '⚠',
-	info: 'ℹ',
-	arrow: '→',
-	bullet: '•',
-} as const;
+// Icons - use plain text alternatives when running from an AI coding agent
+function getIcons() {
+	if (getExecutingAgent()) {
+		return {
+			success: '[OK]',
+			error: '[ERROR]',
+			warning: '[WARN]',
+			info: '[INFO]',
+			arrow: '->',
+			bullet: '-',
+		} as const;
+	}
+	return {
+		success: '✓',
+		error: '✗',
+		warning: '⚠',
+		info: 'ℹ',
+		arrow: '→',
+		bullet: '•',
+	} as const;
+}
+
+// Export ICONS as a getter for backward compatibility
+// Proxy with full traps for enumeration and serialization support
+export const ICONS = new Proxy({} as ReturnType<typeof getIcons>, {
+	get(_target, prop: keyof ReturnType<typeof getIcons>) {
+		return getIcons()[prop];
+	},
+	has(_target, prop) {
+		return prop in getIcons();
+	},
+	ownKeys() {
+		return Object.keys(getIcons());
+	},
+	getOwnPropertyDescriptor(_target, prop) {
+		const icons = getIcons();
+		if (prop in icons) {
+			return { configurable: true, enumerable: true, value: icons[prop as keyof typeof icons] };
+		}
+	},
+});
 
 /**
  * Check if we should treat the terminal as TTY-like for interactive output
  * (real TTY on stdout or stderr, or FORCE_COLOR set by fork wrapper).
  * Returns false in CI environments since CI terminals often don't support
  * cursor control sequences reliably.
+ * Returns false when running from an AI coding agent (no interactive prompts/spinners).
  */
 export function isTTYLike(): boolean {
 	if (process.env.CI) {
 		return false;
 	}
+	// Disable interactive features when running from an AI coding agent
+	if (getExecutingAgent()) {
+		return false;
+	}
 	return !!process.stdout.isTTY || !!process.stderr.isTTY || process.env.FORCE_COLOR === '1';
 }
 
@@ -100,6 +142,10 @@ export function shouldUseColors(): boolean {
 	if (process.env.FORCE_COLOR === '1') {
 		return true;
 	}
+	// Disable colors when running from an AI coding agent (cleaner output for parsing)
+	if (getExecutingAgent()) {
+		return false;
+	}
 	return (
 		!process.env.NO_COLOR &&
 		!process.env.CI &&

package/src/types.ts

@@ -54,6 +54,7 @@ export const ConfigSchema = zod.object({
 			last_legacy_warning: zod.number().optional().describe('Last legacy CLI warning timestamp'),
 			signup_banner_shown: zod.boolean().optional().describe('If the signup banner was shown'),
 			orgId: zod.string().optional().describe('Default organization ID'),
+			projectId: zod.string().optional().describe('Default project ID'),
 			region: zod.string().optional().describe('Default cloud region'),
 			project_dir: zod.string().optional().describe('Last used project directory'),
 		})
@@ -284,6 +285,7 @@ export interface AuthData {
 
 export interface GlobalOptions {
 	config?: string;
+	profile?: string;
 	logLevel: LogLevel;
 	logTimestamp?: boolean;
 	logPrefix?: boolean;
@@ -322,6 +324,38 @@ export interface CommandSchemas {
 	aliases?: Record<string, string[]>;
 }
 
+/**
+ * Declarative resource selection rule for schema-driven testing
+ */
+export interface ResourceSelectionRule {
+	/** Resource type */
+	resource: 'org' | 'project' | 'region';
+
+	/** Is this resource required for the command? */
+	required: boolean;
+
+	/** CLI flag name (e.g., 'org-id', 'region') */
+	flag: string;
+
+	/** Environment variable name */
+	envVar: string;
+
+	/** Config preference key (if applicable) */
+	configPref?: string;
+
+	/** Can be implied from context (e.g., project from agentuity.json) */
+	canBeImplied?: boolean;
+
+	/** Source file or context for implied values (e.g., 'agentuity.json') */
+	impliedFrom?: string;
+
+	/** Can be inferred from cache (for prefixed IDs) */
+	canUseCache?: boolean;
+
+	/** Operation type affects behavior */
+	operationType?: 'read' | 'execute' | 'mutate';
+}
+
 export type ProjectConfig = zod.infer<typeof ProjectSchema>;
 
 export type Requires = {
@@ -428,13 +462,13 @@ export type CommandContextFromSpecs<
 	 *
 	 * @example
 	 * ```typescript
-	 * const agent = await ctx.isExecutingFromAgent();
+	 * const agent = ctx.getExecutingAgent();
 	 * if (agent) {
 	 *   logger.debug(`Running from agent: ${agent}`);
 	 * }
 	 * ```
 	 */
-	isExecutingFromAgent: () => Promise<string | undefined>;
+	getExecutingAgent: () => string | undefined;
 } & AddArgs<A> &
 	AddOpts<Op> &
 	AddAuth<AuthMode<R, O>> &
@@ -480,6 +514,7 @@ export function createSubcommand<
 	tags?: string[];
 	skipSkill?: boolean;
 	webUrl?: WebUrl<R, O, A, Op>;
+	resourceRules?: ResourceSelectionRule[];
 	schema?: A extends z.ZodType
 		? Op extends z.ZodType
 			? Res extends z.ZodType
@@ -527,6 +562,7 @@ export function createCommand<
 	tags?: string[];
 	skipSkill?: boolean;
 	webUrl?: WebUrl<R, O, A, Op>;
+	resourceRules?: ResourceSelectionRule[];
 	schema?: A extends z.ZodType
 		? Op extends z.ZodType
 			? Res extends z.ZodType
@@ -567,6 +603,7 @@ type CommandDefBase =
 			pagination?: PaginationInfo;
 			tags?: string[];
 			schema?: CommandSchemas;
+			resourceRules?: ResourceSelectionRule[];
 			webUrl?: string | ((ctx: CommandContext) => string | undefined | null);
 			handler(ctx: CommandContext): unknown | Promise<unknown>;
 			subcommands?: SubcommandDefinition[];
@@ -587,6 +624,7 @@ type CommandDefBase =
 			pagination?: PaginationInfo;
 			tags?: string[];
 			schema?: CommandSchemas;
+			resourceRules?: ResourceSelectionRule[];
 			webUrl?: string | ((ctx: CommandContext) => string | undefined | null);
 			handler?: undefined;
 			subcommands: SubcommandDefinition[];
@@ -607,7 +645,10 @@ type SubcommandDefBase =
 			pagination?: PaginationInfo;
 			tags?: string[];
 			schema?: CommandSchemas;
+			resourceRules?: ResourceSelectionRule[];
 			webUrl?: string | ((ctx: CommandContext) => string | undefined | null);
+			requires?: Requires;
+			optional?: Optional;
 			handler(ctx: CommandContext): unknown | Promise<unknown>;
 			subcommands?: SubcommandDefinition[];
 	  }
@@ -625,7 +666,10 @@ type SubcommandDefBase =
 			pagination?: PaginationInfo;
 			tags?: string[];
 			schema?: CommandSchemas;
+			resourceRules?: ResourceSelectionRule[];
 			webUrl?: string | ((ctx: CommandContext) => string | undefined | null);
+			requires?: Requires;
+			optional?: Optional;
 			handler?: undefined;
 			subcommands: SubcommandDefinition[];
 	  };

package/src/version-check.ts

@@ -5,6 +5,7 @@ import { getVersion, getCompareUrl, getReleaseUrl, toTag } from './version';
 import * as tui from './tui';
 import { saveConfig } from './config';
 import { $ } from 'bun';
+import { getExecutingAgent } from './agent-detection';
 
 const ONE_HOUR_MS = 60 * 60 * 1000;
 
@@ -33,6 +34,11 @@ function shouldSkipCheck(
 		return true;
 	}
 
+	// Skip if running from an AI coding agent (don't interrupt with upgrade prompts)
+	if (getExecutingAgent()) {
+		return true;
+	}
+
 	// Skip if no TTY (CI, redirected output, etc.)
 	if (!process.stdin.isTTY || !process.stdout.isTTY) {
 		return true;