@agentuity/cli 0.0.6

package/src/steps.ts

@@ -0,0 +1,245 @@
+/**
+ * Step progress UI component for showing animated steps with callbacks
+ *
+ * Displays a checklist where each step animates in place with a spinner,
+ * then shows success, skipped, or error icon based on callback result.
+ */
+
+import type { ColorScheme } from './terminal';
+
+// Spinner frames
+const FRAMES = ['◐', '◓', '◑', '◒'];
+
+// Icons
+const ICONS = {
+	success: '✓',
+	skipped: '○',
+	error: '✗',
+	pending: '☐',
+} as const;
+
+// Color definitions (light/dark adaptive)
+const COLORS = {
+	cyan: { light: '\x1b[36m', dark: '\x1b[96m' },
+	blue: { light: '\x1b[34m', dark: '\x1b[94m' },
+	magenta: { light: '\x1b[35m', dark: '\x1b[95m' },
+	green: { light: '\x1b[32m', dark: '\x1b[92m' },
+	yellow: { light: '\x1b[33m', dark: '\x1b[93m' },
+	red: { light: '\x1b[31m', dark: '\x1b[91m' },
+	gray: { light: '\x1b[90m', dark: '\x1b[37m' },
+	bold: '\x1b[1m',
+	strikethrough: '\x1b[9m',
+	reset: '\x1b[0m',
+} as const;
+
+// Spinner color sequence
+const SPINNER_COLORS = ['cyan', 'blue', 'magenta', 'cyan'] as const;
+
+let currentColorScheme: ColorScheme = 'dark';
+
+export function setStepsColorScheme(scheme: ColorScheme): void {
+	currentColorScheme = scheme;
+}
+
+function getColor(colorKey: keyof typeof COLORS): string {
+	const color = COLORS[colorKey];
+	if (typeof color === 'string') {
+		return color;
+	}
+	return color[currentColorScheme];
+}
+
+/**
+ * Step outcome
+ */
+export type StepOutcome =
+	| { status: 'success' }
+	| { status: 'skipped'; reason?: string }
+	| { status: 'error'; message: string };
+
+/**
+ * Helper functions for creating step outcomes
+ */
+export const stepSuccess = (): StepOutcome => ({ status: 'success' });
+export const stepSkipped = (reason?: string): StepOutcome => ({ status: 'skipped', reason });
+export const stepError = (message: string): StepOutcome => ({ status: 'error', message });
+
+/**
+ * Progress callback function
+ */
+export type ProgressCallback = (progress: number) => void;
+
+/**
+ * Step definition (without progress tracking)
+ */
+export interface SimpleStep {
+	type?: 'simple';
+	label: string;
+	run: () => Promise<StepOutcome>;
+}
+
+/**
+ * Step definition (with progress tracking)
+ */
+export interface ProgressStep {
+	type: 'progress';
+	label: string;
+	run: (progress: ProgressCallback) => Promise<StepOutcome>;
+}
+
+/**
+ * Step definition (discriminated union)
+ */
+export type Step = SimpleStep | ProgressStep;
+
+/**
+ * Internal step state
+ */
+type StepState =
+	| {
+			type: 'simple';
+			label: string;
+			run: () => Promise<StepOutcome>;
+			outcome?: StepOutcome;
+			progress?: number;
+	  }
+	| {
+			type: 'progress';
+			label: string;
+			run: (progress: ProgressCallback) => Promise<StepOutcome>;
+			outcome?: StepOutcome;
+			progress?: number;
+	  };
+
+/**
+ * Run a series of steps with animated progress
+ *
+ * Each step runs its callback while showing a spinner animation.
+ * Steps can complete with success, skipped, or error status.
+ * Exits with code 1 if any step errors.
+ */
+export async function runSteps(steps: Step[]): Promise<void> {
+	const state: StepState[] = steps.map((s) => {
+		const stepType = s.type === 'progress' ? 'progress' : 'simple';
+		return stepType === 'progress'
+			? {
+					type: 'progress' as const,
+					label: s.label,
+					run: s.run as (progress: ProgressCallback) => Promise<StepOutcome>,
+				}
+			: { type: 'simple' as const, label: s.label, run: s.run as () => Promise<StepOutcome> };
+	});
+
+	// Hide cursor
+	process.stdout.write('\x1B[?25l');
+
+	try {
+		// Initial render
+		process.stdout.write(renderSteps(state, -1) + '\n');
+
+		for (let stepIndex = 0; stepIndex < state.length; stepIndex++) {
+			const step = state[stepIndex];
+			let frameIndex = 0;
+
+			// Start spinner animation
+			const interval = setInterval(() => {
+				const colorKey = SPINNER_COLORS[frameIndex % SPINNER_COLORS.length];
+				const color = getColor(colorKey);
+				const frame = `${color}${COLORS.bold}${FRAMES[frameIndex % FRAMES.length]}${COLORS.reset}`;
+
+				// Move cursor up to the top of checklist
+				process.stdout.write(`\x1B[${state.length}A`);
+				process.stdout.write(renderSteps(state, stepIndex, frame) + '\n');
+
+				frameIndex++;
+			}, 120);
+
+			// Run the step with progress tracking
+			const progressCallback: ProgressCallback = (progress: number) => {
+				step.progress = Math.min(100, Math.max(0, progress));
+
+				// Move cursor up
+				process.stdout.write(`\x1B[${state.length}A`);
+				process.stdout.write(renderSteps(state, stepIndex) + '\n');
+			};
+
+			try {
+				// Use discriminant to determine if step has progress callback
+				const outcome =
+					step.type === 'progress' ? await step.run(progressCallback) : await step.run();
+				step.outcome = outcome;
+			} catch (err) {
+				step.outcome = {
+					status: 'error',
+					message: err instanceof Error ? err.message : String(err),
+				};
+			}
+
+			clearInterval(interval);
+
+			// Clear progress and final render with outcome
+			step.progress = undefined;
+			process.stdout.write(`\x1B[${state.length}A`);
+			process.stdout.write(renderSteps(state, stepIndex) + '\n');
+
+			// If error, show error message and exit
+			if (step.outcome?.status === 'error') {
+				const errorColor = getColor('red');
+				console.error(`\n${errorColor}Error: ${step.outcome.message}${COLORS.reset}\n`);
+				process.stdout.write('\x1B[?25h'); // Show cursor
+				process.exit(1);
+			}
+		}
+
+		// Show cursor again
+		process.stdout.write('\x1B[?25h\n');
+	} catch (err) {
+		// Ensure cursor is shown even if something goes wrong
+		process.stdout.write('\x1B[?25h');
+		throw err;
+	}
+}
+
+/**
+ * Render a progress indicator
+ */
+function renderProgress(progress: number): string {
+	const cyanColor = getColor('cyan');
+
+	const percentage = `${Math.floor(progress)}%`;
+	return ` ${cyanColor}${percentage}${COLORS.reset}`;
+}
+
+/**
+ * Render all steps as a multiline string
+ */
+function renderSteps(steps: StepState[], activeIndex: number, spinner?: string): string {
+	const grayColor = getColor('gray');
+	const greenColor = getColor('green');
+	const yellowColor = getColor('yellow');
+	const redColor = getColor('red');
+
+	const lines: string[] = [];
+
+	steps.forEach((s, i) => {
+		if (s.outcome?.status === 'success') {
+			lines.push(
+				`${greenColor}${ICONS.success}${COLORS.reset} ${grayColor}${COLORS.strikethrough}${s.label}${COLORS.reset}`
+			);
+		} else if (s.outcome?.status === 'skipped') {
+			const reason = s.outcome.reason ? ` ${grayColor}(${s.outcome.reason})${COLORS.reset}` : '';
+			lines.push(
+				`${yellowColor}${ICONS.skipped}${COLORS.reset} ${grayColor}${COLORS.strikethrough}${s.label}${COLORS.reset}${reason}`
+			);
+		} else if (s.outcome?.status === 'error') {
+			lines.push(`${redColor}${ICONS.error}${COLORS.reset} ${s.label}`);
+		} else if (i === activeIndex && spinner) {
+			const progressIndicator = s.progress !== undefined ? renderProgress(s.progress) : '';
+			lines.push(`${spinner} ${s.label}${progressIndicator}`);
+		} else {
+			lines.push(`${grayColor}${ICONS.pending}${COLORS.reset} ${s.label}`);
+		}
+	});
+
+	return lines.join('\n');
+}

package/src/terminal.ts

@@ -0,0 +1,151 @@
+export type ColorScheme = 'light' | 'dark';
+
+export async function detectColorScheme(): Promise<ColorScheme> {
+	const debug = process.env.DEBUG_COLORS === 'true';
+
+	// Check for explicit override
+	if (process.env.COLOR_SCHEME === 'light') {
+		if (debug) console.log('[DEBUG] Using COLOR_SCHEME=light override');
+		return 'light';
+	}
+	if (process.env.COLOR_SCHEME === 'dark') {
+		if (debug) console.log('[DEBUG] Using COLOR_SCHEME=dark override');
+		return 'dark';
+	}
+
+	// Check if we have stdout TTY at minimum
+	if (!process.stdout.isTTY) {
+		if (debug) console.log('[DEBUG] stdout not a TTY, defaulting to dark');
+		return 'dark'; // Default to dark mode
+	}
+
+	// Try to query terminal background color using OSC 11 (most reliable)
+	if (debug) console.log('[DEBUG] Querying terminal background with OSC 11...');
+	try {
+		const bgColor = await queryTerminalBackground();
+		if (bgColor) {
+			const luminance = calculateLuminance(bgColor);
+			const scheme = luminance > 0.5 ? 'light' : 'dark';
+			if (debug)
+				console.log(
+					`[DEBUG] OSC 11 response: rgb(${bgColor.r},${bgColor.g},${bgColor.b}), luminance: ${luminance.toFixed(2)}, scheme: ${scheme}`
+				);
+			return scheme;
+		} else {
+			if (debug) console.log('[DEBUG] OSC 11 query timed out or no response');
+		}
+	} catch (error) {
+		if (debug) console.log('[DEBUG] OSC 11 query failed:', error);
+	}
+
+	// Fall back to COLORFGBG environment variable (less reliable)
+	if (process.env.COLORFGBG) {
+		// COLORFGBG format is "foreground;background"
+		// This is unreliable but better than nothing
+		const parts = process.env.COLORFGBG.split(';');
+		const fg = parseInt(parts[0] || '7', 10);
+		const bg = parseInt(parts[1] || '0', 10);
+
+		// Heuristic: if background is 0 (black) and foreground is light (>=7), it's likely dark mode
+		// if background is light (>=7) and foreground is dark (<7), it's likely light mode
+		const scheme = bg >= 7 || bg > fg ? 'light' : 'dark';
+		if (debug)
+			console.log(
+				`[DEBUG] COLORFGBG fallback: ${process.env.COLORFGBG} (fg:${fg}, bg:${bg}), scheme: ${scheme}`
+			);
+		return scheme;
+	}
+
+	if (debug) console.log('[DEBUG] Defaulting to dark mode');
+	return 'dark'; // Default to dark mode
+}
+
+interface RGBColor {
+	r: number;
+	g: number;
+	b: number;
+}
+
+async function queryTerminalBackground(): Promise<RGBColor | null> {
+	// Skip if stdin is not available or not a TTY
+	if (!process.stdin.isTTY) {
+		return null;
+	}
+
+	return new Promise((resolve) => {
+		const timeout = setTimeout(() => {
+			cleanup();
+			resolve(null);
+		}, 100); // 100ms timeout
+
+		let response = '';
+
+		const onData = (data: Buffer) => {
+			response += data.toString();
+
+			// Look for OSC 11 response patterns:
+			// Pattern 1: ESC ] 11 ; rgb:RRRR/GGGG/BBBB ESC \ (xterm with ESC \ terminator)
+			// Pattern 2: ESC ] 11 ; rgb:RRRR/GGGG/BBBB BEL (xterm with BEL terminator)
+			// The color values can be 8-bit (RR), 12-bit (RRR), or 16-bit (RRRR)
+			// biome-ignore lint/suspicious/noControlCharactersInRegex: Control characters needed for ANSI escape sequences
+			const match = response.match(
+				// eslint-disable-next-line no-control-regex
+				/\x1b\]11;rgb:([0-9a-f]+)\/([0-9a-f]+)\/([0-9a-f]+)(?:\x1b\\|\x07)/i
+			);
+			if (match) {
+				cleanup();
+				clearTimeout(timeout);
+
+				// Parse RGB values - they can be different bit depths
+				// Normalize to 8-bit (0-255) by taking the most significant bits
+				const parseColorValue = (hex: string): number => {
+					if (hex.length === 4) {
+						// 16-bit: RRRR -> take first 2 chars
+						return parseInt(hex.slice(0, 2), 16);
+					} else if (hex.length === 3) {
+						// 12-bit: RRR -> take first 2 chars
+						return parseInt(hex.slice(0, 2), 16);
+					} else {
+						// 8-bit: RR
+						return parseInt(hex, 16);
+					}
+				};
+
+				const r = parseColorValue(match[1]);
+				const g = parseColorValue(match[2]);
+				const b = parseColorValue(match[3]);
+
+				resolve({ r, g, b });
+			}
+		};
+
+		const cleanup = () => {
+			process.stdin.setRawMode(false);
+			process.stdin.removeListener('data', onData);
+			process.stdin.pause(); // Pause stdin to allow process to exit
+		};
+
+		// Set stdin to raw mode to read escape sequences
+		process.stdin.setRawMode(true);
+		process.stdin.resume(); // Resume to receive data
+		process.stdin.on('data', onData);
+
+		// Send OSC 11 query with BEL terminator (more widely supported)
+		// Using BEL (\x07) as terminator instead of ESC \ for better compatibility
+		process.stdout.write('\x1b]11;?\x07');
+	});
+}
+
+function calculateLuminance(color: RGBColor): number {
+	// Convert RGB to relative luminance using the formula from WCAG
+	// https://www.w3.org/TR/WCAG20/#relativeluminancedef
+	const rsRGB = color.r / 255;
+	const gsRGB = color.g / 255;
+	const bsRGB = color.b / 255;
+
+	const r = rsRGB <= 0.03928 ? rsRGB / 12.92 : Math.pow((rsRGB + 0.055) / 1.055, 2.4);
+	const g = gsRGB <= 0.03928 ? gsRGB / 12.92 : Math.pow((gsRGB + 0.055) / 1.055, 2.4);
+	const b = bsRGB <= 0.03928 ? bsRGB / 12.92 : Math.pow((bsRGB + 0.055) / 1.055, 2.4);
+
+	return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}

package/src/tui.md

@@ -0,0 +1,254 @@
+# Terminal UI Utilities
+
+The `tui` module provides semantic helpers for formatted, colorized console output.
+
+## Usage
+
+```typescript
+import * as tui from '@agentuity/cli/tui';
+
+// Or from within the package:
+import * as tui from './tui';
+```
+
+## Message Functions
+
+Print semantic messages with automatic icons and colors:
+
+### `tui.success(message: string)`
+
+Print a success message with a green checkmark (✓).
+
+```typescript
+tui.success('Welcome to Agentuity! You are now logged in');
+// Output: ✓ Welcome to Agentuity! You are now logged in (in green)
+```
+
+### `tui.error(message: string)`
+
+Print an error message with a red X (✗).
+
+```typescript
+tui.error('Connection failed');
+// Output: ✗ Connection failed (in red)
+```
+
+### `tui.warning(message: string)`
+
+Print a warning message with a yellow warning icon (⚠).
+
+```typescript
+tui.warning('CLI Upgrade Required');
+// Output: ⚠ CLI Upgrade Required (in yellow)
+```
+
+### `tui.info(message: string)`
+
+Print an info message with a cyan info icon (ℹ).
+
+```typescript
+tui.info('Processing request...');
+// Output: ℹ Processing request... (in cyan)
+```
+
+## List Functions
+
+### `tui.bullet(message: string)`
+
+Print a bulleted list item (•).
+
+```typescript
+tui.bullet('First item');
+tui.bullet('Second item');
+```
+
+### `tui.arrow(message: string)`
+
+Print an arrow item (→), useful for showing next steps.
+
+```typescript
+tui.arrow('Run: agentuity deploy');
+tui.arrow('Visit: https://app.agentuity.com');
+```
+
+## Text Formatting
+
+These functions return formatted strings (don't print directly):
+
+### `tui.bold(text: string): string`
+
+Format text in bold.
+
+```typescript
+console.log(`Name: ${tui.bold('Production')}`);
+```
+
+### `tui.muted(text: string): string`
+
+Format text in muted/gray color.
+
+```typescript
+console.log(`${tui.muted('(optional)')}`);
+```
+
+### `tui.link(url: string): string`
+
+Format text as a clickable link (blue and underlined). If the terminal supports OSC 8 hyperlinks, creates a clickable link.
+
+```typescript
+console.log(`Visit: ${tui.link('https://agentuity.com')}`);
+```
+
+Supported terminals for clickable links:
+
+- iTerm2
+- WezTerm
+- Ghostty
+- Apple Terminal
+- Hyper
+- Kitty
+- Windows Terminal
+
+## Utility Functions
+
+### `tui.newline()`
+
+Print a blank line (shorthand for `console.log('')`).
+
+```typescript
+tui.success('Done!');
+tui.newline();
+console.log('Next steps:');
+```
+
+### `tui.waitForAnyKey(message?: string): Promise<void>`
+
+Wait for the user to press Enter before continuing. Useful for pausing execution to let the user read output or confirm an action.
+
+```typescript
+await tui.waitForAnyKey(); // Uses default message: "Press Enter to continue..."
+await tui.waitForAnyKey('Press Enter to open the browser...');
+```
+
+**Behavior:**
+
+- Waits for any key press (Enter, Space, etc.)
+- Automatically exits with code 1 if CTRL+C is pressed
+- Uses raw mode to capture single keypress
+
+**Use cases:**
+
+- Pausing before opening a browser
+- Letting user read important information
+- Confirming before proceeding with an action
+
+### `tui.copyToClipboard(text: string): Promise<boolean>`
+
+Copy text to the system clipboard. Returns `true` if successful, `false` otherwise.
+
+```typescript
+const copied = await tui.copyToClipboard('ABC123');
+if (copied) {
+	tui.success('Code copied to clipboard!');
+} else {
+	console.log('Copy the following code: ABC123');
+}
+```
+
+**Platform support:**
+
+- macOS: Uses `pbcopy`
+- Windows: Uses `clip`
+- Linux: Tries `xclip`, falls back to `xsel`
+
+**Note:** Silently fails if clipboard utilities are not available (returns `false`).
+
+### `tui.padRight(str: string, length: number, pad?: string): string`
+
+Pad a string to a specific length on the right.
+
+```typescript
+const name = tui.padRight('prod', 10, ' ');
+console.log(`${name} ${tui.muted('(active)')}`);
+```
+
+### `tui.padLeft(str: string, length: number, pad?: string): string`
+
+Pad a string to a specific length on the left.
+
+```typescript
+const count = tui.padLeft('5', 3, '0');
+console.log(count); // "005"
+```
+
+## Color Scheme
+
+The TUI module automatically adapts colors for light and dark terminals. You can set the color scheme:
+
+```typescript
+import { setColorScheme } from './tui';
+
+setColorScheme('dark'); // or 'light'
+```
+
+**Note:** The CLI automatically detects and sets the color scheme based on terminal settings.
+
+## Banner
+
+### `tui.banner(title: string, body: string)`
+
+Display a formatted banner with a bordered box around the content. Perfect for important messages, welcome screens, or upgrade notices.
+
+```typescript
+tui.banner('Welcome', 'Thank you for using Agentuity! Your setup is complete.');
+```
+
+Output:
+
+```
+╭──────────────────────────────────────────────────╮
+│                                                  │
+│                    Welcome                       │
+│                                                  │
+│ Thank you for using Agentuity! Your setup is     │
+│ complete.                                        │
+│                                                  │
+╰──────────────────────────────────────────────────╯
+```
+
+**Features:**
+
+- Automatically wraps text to fit within 80 characters
+- Centers the title
+- Pads body text with borders
+- Supports embedded formatting (bold, muted, links)
+- Handles unicode characters correctly (emoji, CJK characters) using `Bun.stringWidth()`
+
+## Complete Example
+
+```typescript
+import * as tui from './tui';
+
+tui.info('Deploying application...');
+tui.newline();
+
+tui.bullet('Building assets');
+tui.bullet('Uploading to server');
+tui.bullet('Running migrations');
+
+tui.newline();
+tui.success('Deployment complete!');
+tui.newline();
+
+console.log('Next steps:');
+tui.arrow(`Visit ${tui.link('https://app.agentuity.com')}`);
+tui.arrow(`View logs: ${tui.bold('agentuity logs')}`);
+```
+
+## Design Philosophy
+
+- **Semantic over presentational**: Use `tui.success()` instead of manually coloring text green
+- **Consistent icons**: Each message type has a standard icon
+- **Adaptive colors**: Colors adjust for light/dark terminals
+- **No logger prefix**: TUI functions use raw console output, no `[INFO]` prefixes
+- **Composable**: Text formatting functions return strings for flexible composition