@agentuity/cli 2.0.0-beta.1 → 2.0.1

package/src/errors.ts

@@ -1,22 +1,51 @@
 import type { Logger } from './types';
 
 /**
- * Standard exit codes for the CLI
+ * Standard exit codes for the CLI.
+ *
+ * Values start at 10 to avoid collisions with Unix signal numbers (1-9)
+ * and shell conventions (e.g. 2 = misuse of builtins, 9 = SIGKILL/OOM).
+ * Range 10-125 is safe — below shell-reserved 126-128 and signal-death
+ * codes 128+N.
+ *
+ * 0 and 1 are kept as universal success/failure codes.
  */
 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,
-	BUILD_FAILED = 9,
-	SECURITY_ERROR = 10,
+	VALIDATION_ERROR = 10,
+	AUTH_ERROR = 11,
+	NOT_FOUND = 12,
+	PERMISSION_ERROR = 13,
+	NETWORK_ERROR = 14,
+	FILE_ERROR = 15,
+	USER_CANCELLED = 16,
+	BUILD_FAILED = 17,
+	SECURITY_ERROR = 18,
+	PAYMENT_REQUIRED = 19,
+	UPGRADE_REQUIRED = 20,
 }
 
+/**
+ * Human-readable descriptions for each exit code.
+ * This is the single source of truth consumed by the schema generator and AI help.
+ */
+export const exitCodeDescriptions: Record<number, string> = {
+	[ExitCode.SUCCESS]: 'Success',
+	[ExitCode.GENERAL_ERROR]: 'General error',
+	[ExitCode.VALIDATION_ERROR]: 'Validation error (invalid arguments or options)',
+	[ExitCode.AUTH_ERROR]: 'Authentication error (login required or credentials invalid)',
+	[ExitCode.NOT_FOUND]: 'Resource not found (project, file, deployment, etc.)',
+	[ExitCode.PERMISSION_ERROR]: 'Permission denied (insufficient access rights)',
+	[ExitCode.NETWORK_ERROR]: 'Network error (API unreachable or timeout)',
+	[ExitCode.FILE_ERROR]: 'File system error (file read/write failed)',
+	[ExitCode.USER_CANCELLED]: 'User cancelled (operation aborted by user)',
+	[ExitCode.BUILD_FAILED]: 'Build failed',
+	[ExitCode.SECURITY_ERROR]: 'Security error (malware detected)',
+	[ExitCode.PAYMENT_REQUIRED]: 'Payment required (plan upgrade needed)',
+	[ExitCode.UPGRADE_REQUIRED]: 'Upgrade required (CLI version too old)',
+};
+
 /**
  * Standard error codes for the CLI
  */
@@ -152,7 +181,11 @@ export function getExitCode(errorCode: ErrorCode): ExitCode {
 
 		// Payment required - user needs to upgrade their plan
 		case ErrorCode.PAYMENT_REQUIRED:
-			return ExitCode.GENERAL_ERROR;
+			return ExitCode.PAYMENT_REQUIRED;
+
+		// Upgrade required - CLI version too old
+		case ErrorCode.UPGRADE_REQUIRED:
+			return ExitCode.UPGRADE_REQUIRED;
 
 		// Resource conflicts and other errors
 		case ErrorCode.RESOURCE_ALREADY_EXISTS:
@@ -162,7 +195,6 @@ export function getExitCode(errorCode: ErrorCode): ExitCode {
 		case ErrorCode.RUNTIME_ERROR:
 		case ErrorCode.INTERNAL_ERROR:
 		case ErrorCode.NOT_IMPLEMENTED:
-		case ErrorCode.UPGRADE_REQUIRED:
 		default:
 			return ExitCode.GENERAL_ERROR;
 	}

package/src/schema-generator.ts

@@ -1,5 +1,6 @@
 import type { Command } from 'commander';
 import type { CommandDefinition, SubcommandDefinition, CommandSchemas } from './types';
+import { exitCodeDescriptions } from './errors';
 import { parseArgsSchema, parseOptionsSchema } from './schema-parser';
 import * as z from 'zod';
 
@@ -313,18 +314,7 @@ export function generateCLISchema(
 		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)',
-			9: 'Build failed',
-		},
+		exitCodes: { ...exitCodeDescriptions },
 		globalOptions: [
 			{
 				name: 'config',

package/src/steps.ts

@@ -10,6 +10,7 @@ import type { LogLevel } from './types';
 import { ValidationInputError, ValidationOutputError, type IssuesType } from '@agentuity/server';
 import { clearLastLines, isTTYLike } from './tui';
 import { appendLog, isLogCollectionEnabled } from './log-collector';
+import { getOutputOptions, isJSONMode } from './output';
 
 /**
  * Error thrown when step execution is interrupted by a signal (e.g., Ctrl+C).
@@ -700,6 +701,43 @@ async function runStepsPlain(steps: Step[]): Promise<void> {
  * Run a series of steps with animated progress
  */
 export async function runSteps(steps: Step[], logLevel?: LogLevel): Promise<void> {
+	const outputOptions = getOutputOptions();
+
+	// In JSON mode, skip all UI rendering
+	if (outputOptions && isJSONMode(outputOptions)) {
+		const abortController = new AbortController();
+		for (const step of steps) {
+			if (abortController.signal.aborted) break;
+			if (step) {
+				const ctx: StepContext = {
+					signal: abortController.signal,
+					progress: () => {},
+				};
+				let outcome: StepOutcome;
+				try {
+					outcome = await step.run(ctx);
+				} catch (err) {
+					if (err instanceof Error && err.name === 'AbortError') {
+						throw new StepInterruptError();
+					}
+					outcome = {
+						status: 'error',
+						message: err instanceof Error ? err.message : String(err),
+						cause: err instanceof Error ? err : undefined,
+					};
+				}
+				if (outcome.status === 'error') {
+					if (outcome.cause instanceof Error && outcome.cause.name === 'AbortError') {
+						throw new StepInterruptError();
+					}
+					const errorMsg = outcome.message || 'An unknown error occurred';
+					throw new Error(errorMsg);
+				}
+			}
+		}
+		return;
+	}
+
 	const useTUI = isTTYLike() && (!logLevel || ['info', 'warn', 'error'].includes(logLevel));
 
 	if (useTUI) {

package/src/tui.ts

@@ -25,6 +25,12 @@ function ensureCursorRestoration(): void {
 	exitHandlerInstalled = true;
 
 	const restoreCursor = () => {
+		// Only write ANSI escape sequences when stderr is a real terminal.
+		// Writing to non-TTY streams (pipes, command substitution, etc.)
+		// pollutes captured output with invisible control characters.
+		if (!process.stderr.isTTY) {
+			return;
+		}
 		// Skip cursor restoration in CI - terminals don't support these sequences
 		if (process.env.CI) {
 			return;
@@ -293,8 +299,13 @@ export function getSeverityColor(severity: string): (text: string) => string {
 export function success(message: string): void {
 	const color = getColor('success');
 	const reset = getColor('reset');
-	// Clear line first to ensure no leftover content from previous output
-	process.stderr.write(`\r\x1b[2K${color}${ICONS.success} ${message}${reset}\n`);
+	if (process.stderr.isTTY) {
+		// Clear line first to ensure no leftover content from previous output
+		process.stderr.write(`\r\x1b[2K${color}${ICONS.success} ${message}${reset}\n`);
+	} else {
+		// No ANSI control sequences for non-TTY streams (pipes, command substitution)
+		process.stderr.write(`${ICONS.success} ${message}\n`);
+	}
 }
 
 /**
@@ -1242,18 +1253,23 @@ export async function spinner<T>(
 	const { getOutputOptions, shouldDisableProgress } = await import('./output');
 	const outputOptions = getOutputOptions();
 	const noProgress = outputOptions ? shouldDisableProgress(outputOptions) : false;
+	const isJsonMode = outputOptions?.json === true;
 
-	// If no interactive TTY-like environment or progress disabled, just execute
-	// the callback without animation
-	if (!isTTYLike() || noProgress) {
+	// If stderr is not a real terminal or progress disabled, just execute
+	// the callback without animation. We check stderr specifically because
+	// the spinner writes ANSI sequences to stderr — isTTYLike() may return
+	// true when stdout is a TTY but stderr is piped (e.g. 2>&1 in $()).
+	if (!process.stderr.isTTY || noProgress) {
 		try {
 			const result =
 				options.type === 'progress'
 					? await options.callback(() => {})
 					: options.type === 'logger'
 						? await options.callback((logMessage: string) => {
-								// In non-TTY mode, just write logs directly to stdout
-								process.stdout.write(logMessage + '\n');
+								// In JSON mode, don't write logs to stdout
+								if (!isJsonMode) {
+									process.stdout.write(logMessage + '\n');
+								}
 							})
 						: options.type === 'countdown'
 							? await options.callback()
@@ -1263,7 +1279,6 @@ export async function spinner<T>(
 
 			// If clearOnSuccess is true, don't show success message
 			// Also skip success message in JSON mode
-			const isJsonMode = outputOptions?.json === true;
 			if (!options.clearOnSuccess && !isJsonMode) {
 				const successColor = getColor('success');
 				console.error(`${successColor}${ICONS.success} ${message}${reset}`);
@@ -1273,7 +1288,7 @@ export async function spinner<T>(
 		} catch (err) {
 			const clearOnError =
 				(options.type === 'progress' || options.type === 'simple') && options.clearOnError;
-			if (!clearOnError) {
+			if (!clearOnError && !isJsonMode) {
 				const errorColor = getColor('error');
 				console.error(`${errorColor}${ICONS.error} ${message}${reset}`);
 			}

package/src/utils/stream-capture.ts

@@ -0,0 +1,39 @@
+import { createWriteStream } from 'node:fs';
+
+/**
+ * Stream a ReadableStream of raw bytes to a file on disk.
+ *
+ * This mirrors the pattern used by the deploy fork wrapper to capture child
+ * process stdout/stderr without accumulating the output in memory.  Returns
+ * the total number of bytes written.
+ */
+export async function captureStreamToFile(
+	stream: ReadableStream<Uint8Array>,
+	filePath: string
+): Promise<number> {
+	const writer = createWriteStream(filePath);
+	const reader = stream.getReader();
+	let totalBytes = 0;
+
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+
+			const ok = writer.write(value);
+			totalBytes += value.byteLength;
+
+			// Respect backpressure: wait for drain when the internal buffer is full
+			if (!ok) {
+				await new Promise<void>((resolve) => writer.once('drain', resolve));
+			}
+		}
+	} finally {
+		await new Promise<void>((resolve, reject) => {
+			writer.once('error', reject);
+			writer.end(resolve);
+		});
+	}
+
+	return totalBytes;
+}

package/src/utils/stream-url.ts

@@ -0,0 +1,226 @@
+import { writeAndDrain } from '@agentuity/server';
+import type { Logger } from '@agentuity/core';
+import * as tui from '../tui';
+
+export interface StreamUrlOptions {
+	signal?: AbortSignal;
+	follow?: boolean;
+	timestamps?: boolean;
+	grep?: string;
+	tail?: number;
+	json?: boolean;
+	label?: string;
+	raw?: boolean;
+	v2?: boolean;
+}
+
+export interface StreamUrlResult {
+	bytesRead: number;
+	chunks: number;
+}
+
+export class StreamFetchError extends Error {
+	constructor(
+		public status: number,
+		public statusText: string,
+		message: string
+	) {
+		super(message);
+		this.name = 'StreamFetchError';
+	}
+}
+
+function escapeRegExp(str: string): string {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export async function streamUrlToWritable(
+	url: string,
+	writable: NodeJS.WritableStream,
+	logger: Logger,
+	options: StreamUrlOptions = {}
+): Promise<StreamUrlResult> {
+	const {
+		signal,
+		follow,
+		timestamps,
+		grep,
+		tail,
+		json,
+		label = 'stream',
+		raw = false,
+		v2 = false,
+	} = options;
+	const streamStart = Date.now();
+	let bytesRead = 0;
+	let chunks = 0;
+
+	try {
+		const fetchUrl = new URL(url);
+
+		if (follow || v2) {
+			fetchUrl.searchParams.set('v', '2');
+		}
+		if (follow) {
+			fetchUrl.searchParams.set('follow', 'true');
+		}
+
+		const redactedUrl =
+			fetchUrl.origin + fetchUrl.pathname + (fetchUrl.search ? '?REDACTED' : '');
+		logger.debug('[%s] fetching: %s', label, redactedUrl);
+		const response = await fetch(fetchUrl.href, { signal });
+		logger.debug(
+			'[%s] response status=%d in %dms',
+			label,
+			response.status,
+			Date.now() - streamStart
+		);
+
+		if (!response.ok || !response.body) {
+			logger.debug('[%s] not ok or no body', label);
+			if (!json) {
+				tui.error(`Failed to fetch stream: ${response.status} ${response.statusText}`);
+			}
+			throw new StreamFetchError(
+				response.status,
+				response.statusText,
+				`Failed to fetch stream: ${response.status} ${response.statusText}`
+			);
+		}
+
+		const reader = response.body.getReader();
+
+		if (raw) {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) {
+					logger.debug(
+						'[%s] EOF after %dms (%d chunks, %d bytes)',
+						label,
+						Date.now() - streamStart,
+						chunks,
+						bytesRead
+					);
+					break;
+				}
+
+				if (value) {
+					chunks++;
+					bytesRead += value.length;
+					if (chunks <= 3 || chunks % 100 === 0) {
+						logger.debug(
+							'[%s] chunk #%d: %d bytes (total: %d bytes, +%dms)',
+							label,
+							chunks,
+							value.length,
+							bytesRead,
+							Date.now() - streamStart
+						);
+					}
+					await writeAndDrain(writable, value);
+				}
+			}
+		} else {
+			const decoder = new TextDecoder();
+			let leftover = '';
+			const grepPattern = grep ? new RegExp(escapeRegExp(grep), 'i') : null;
+			const needsFiltering = tail !== undefined || grepPattern !== null;
+			const tailBuffer: string[] = [];
+			const maxTail = tail ?? Infinity;
+			const liveOutput = follow && needsFiltering;
+
+			const outputLine = async (line: string) => {
+				if (json) {
+					const obj = {
+						timestamp: new Date().toISOString(),
+						stream: label,
+						message: line,
+					};
+					await writeAndDrain(writable, Buffer.from(JSON.stringify(obj) + '\n'));
+				} else {
+					const formatted = timestamps ? formatLineWithTimestamp(line) : line;
+					await writeAndDrain(writable, Buffer.from(formatted + '\n'));
+				}
+			};
+
+			const processFilteredLine = async (line: string) => {
+				if (grepPattern && !grepPattern.test(line)) {
+					return;
+				}
+				if (tail !== undefined) {
+					tailBuffer.push(line);
+					if (tailBuffer.length > maxTail) {
+						tailBuffer.shift();
+					}
+					if (liveOutput) {
+						await outputLine(line);
+					}
+				} else {
+					await outputLine(line);
+				}
+			};
+
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) {
+					if (leftover) {
+						if (needsFiltering) {
+							await processFilteredLine(leftover);
+						} else {
+							await outputLine(leftover);
+						}
+					}
+					logger.debug(
+						'[%s] EOF after %dms (%d chunks, %d bytes)',
+						label,
+						Date.now() - streamStart,
+						chunks,
+						bytesRead
+					);
+					break;
+				}
+
+				if (value) {
+					chunks++;
+					bytesRead += value.length;
+					const text = leftover + decoder.decode(value, { stream: true });
+					const lines = text.split('\n');
+					leftover = lines.pop() ?? '';
+
+					for (const line of lines) {
+						if (needsFiltering) {
+							await processFilteredLine(line);
+						} else {
+							await outputLine(line);
+						}
+					}
+				}
+			}
+
+			if (!liveOutput && needsFiltering && tailBuffer.length > 0) {
+				for (const line of tailBuffer) {
+					await outputLine(line);
+				}
+			}
+		}
+
+		return { bytesRead, chunks };
+	} catch (err) {
+		if (err instanceof Error && err.name === 'AbortError') {
+			logger.debug('[%s] aborted after %dms', label, Date.now() - streamStart);
+			return { bytesRead, chunks };
+		}
+		logger.debug('[%s] error after %dms: %s', label, Date.now() - streamStart, err);
+		throw err;
+	}
+}
+
+function formatLineWithTimestamp(line: string): string {
+	const timestamp = new Date().toLocaleTimeString('en-US', {
+		hour12: false,
+		hour: '2-digit',
+		minute: '2-digit',
+		second: '2-digit',
+	});
+	return `${tui.muted(timestamp)} ${line}`;
+}

package/src/utils/zip.ts

@@ -1,7 +1,8 @@
-import { readFileSync, lstatSync } from 'node:fs';
-import { relative } from 'node:path';
+import { createWriteStream, lstatSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { dirname, relative } from 'node:path';
 import { Glob } from 'bun';
-import AdmZip from 'adm-zip';
+import archiver from 'archiver';
 import { toForwardSlash } from './normalize-path';
 
 interface Options {
@@ -10,7 +11,20 @@ interface Options {
 }
 
 export async function zipDir(dir: string, outdir: string, options?: Options) {
-	const zip = new AdmZip();
+	await mkdir(dirname(outdir), { recursive: true });
+	const output = createWriteStream(outdir);
+	const zip = archiver('zip', {
+		zlib: { level: 9 },
+	});
+
+	const writeDone = new Promise<void>((resolve, reject) => {
+		output.on('close', resolve);
+		output.on('error', reject);
+		zip.on('error', reject);
+	});
+
+	zip.pipe(output);
+
 	const files = await Array.fromAsync(
 		new Glob('**/*').scan({ cwd: dir, absolute: true, dot: true, followSymlinks: false })
 	);
@@ -31,11 +45,8 @@ export async function zipDir(dir: string, outdir: string, options?: Options) {
 				// across machines and would cause EISDIR errors on extraction.
 				const stat = lstatSync(file);
 				if (!stat.isSymbolicLink() && !stat.isDirectory()) {
-					// Use addFile with explicit Unix permissions (0o644) instead of addLocalFile.
-					// On Windows, addLocalFile relies on OS file stats which may produce zip entries
-					// with incorrect Unix permission bits, causing EACCES errors when extracted on Linux.
-					const data = readFileSync(file);
-					zip.addFile(rel, data, '', 0o644);
+					// Set explicit Unix permissions (0o644) for portability across OSes.
+					zip.file(file, { name: rel, mode: 0o644 });
 				}
 			} catch (err) {
 				throw new Error(`Failed to add file to zip: ${rel} (${file})`, { cause: err });
@@ -48,7 +59,8 @@ export async function zipDir(dir: string, outdir: string, options?: Options) {
 			await Bun.sleep(10); // give some time for the progress bar to render
 		}
 	}
-	await zip.writeZip(outdir);
+	await zip.finalize();
+	await writeDone;
 	if (options?.progress) {
 		options.progress(100);
 		await Bun.sleep(100); // give some time for the progress bar to render