@agentuity/cli 1.0.56 → 1.0.58

package/src/cmd/cloud/deploy-fork.ts

@@ -13,7 +13,7 @@
 import { spawn, type Subprocess } from 'bun';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { appendFileSync, createWriteStream, existsSync, readFileSync, unlinkSync } from 'node:fs';
 import type { APIClient } from '../../api';
 import { getUserAgent } from '../../api';
 import { isUnicode } from '../../tui/symbols';
@@ -37,12 +37,14 @@ export interface ForkDeployResult {
 }
 
 /**
- * Stream data to a Pulse stream URL
+ * Stream data to a Pulse stream URL.
+ * Accepts a string, Blob/BunFile, or ReadableStream as the body to avoid
+ * loading large outputs into memory.
  */
 async function streamToPulse(
 	streamURL: string,
 	sdkKey: string,
-	data: string,
+	data: string | Blob | ReadableStream<Uint8Array>,
 	logger: Logger
 ): Promise<void> {
 	try {
@@ -74,7 +76,8 @@ export async function runForkedDeploy(options: ForkDeployOptions): Promise<ForkD
 	const buildLogsStreamURL = deployment.buildLogsStreamURL;
 	const reportFile = join(tmpdir(), `agentuity-deploy-${deploymentId}.json`);
 	const cleanLogsFile = join(tmpdir(), `agentuity-deploy-${deploymentId}-logs.txt`);
-	let outputBuffer = '';
+	const rawLogsFile = join(tmpdir(), `agentuity-deploy-${deploymentId}-raw.txt`);
+	const rawLogsWriter = createWriteStream(rawLogsFile);
 	let proc: Subprocess | null = null;
 	let cancelled = false;
 
@@ -195,7 +198,6 @@ export async function runForkedDeploy(options: ForkDeployOptions): Promise<ForkD
 
 		const handleOutput = async (stream: ReadableStream<Uint8Array>, isStderr: boolean) => {
 			const reader = stream.getReader();
-			const decoder = new TextDecoder();
 			const target = isStderr ? process.stderr : process.stdout;
 
 			try {
@@ -203,8 +205,9 @@ export async function runForkedDeploy(options: ForkDeployOptions): Promise<ForkD
 					const { done, value } = await reader.read();
 					if (done) break;
 
-					const text = decoder.decode(value, { stream: true });
-					outputBuffer += text;
+					// Stream raw bytes to disk instead of accumulating in memory.
+					// This prevents OOM / ERR_STRING_TOO_LONG crashes on large builds.
+					rawLogsWriter.write(value);
 					target.write(value);
 				}
 			} catch (err) {
@@ -223,6 +226,11 @@ export async function runForkedDeploy(options: ForkDeployOptions): Promise<ForkD
 
 		await Promise.all([stdoutPromise, stderrPromise]);
 
+		// Close the raw logs writer so the file is fully flushed before reading
+		await new Promise<void>((resolve) => {
+			rawLogsWriter.end(resolve);
+		});
+
 		const exitCode = await proc.exited;
 		logger.debug('Child process exited with code: %d', exitCode);
 
@@ -249,12 +257,11 @@ export async function runForkedDeploy(options: ForkDeployOptions): Promise<ForkD
 					logger.debug('Failed to read clean logs file: %s', err);
 				}
 			}
-			// Fall back to raw output if no clean logs
-			if (!logsContent && outputBuffer) {
-				logsContent = outputBuffer;
-			}
 			if (logsContent) {
 				await streamToPulse(buildLogsStreamURL, sdkKey, logsContent, logger);
+			} else if (existsSync(rawLogsFile)) {
+				// Stream raw logs file directly to Pulse without loading into memory
+				await streamToPulse(buildLogsStreamURL, sdkKey, Bun.file(rawLogsFile), logger);
 			}
 		}
 
@@ -307,11 +314,27 @@ export async function runForkedDeploy(options: ForkDeployOptions): Promise<ForkD
 					// ignore
 				}
 			}
-			if (!logsContent) {
-				logsContent = outputBuffer;
+			if (logsContent) {
+				logsContent += `\n\n--- FORK ERROR ---\n${errorMessage}\n`;
+				await streamToPulse(buildLogsStreamURL, sdkKey, logsContent, logger);
+			} else {
+				// Append error to raw logs file and stream it without loading into memory
+				try {
+					appendFileSync(rawLogsFile, `\n\n--- FORK ERROR ---\n${errorMessage}\n`);
+				} catch {
+					// ignore — file may not exist if child never produced output
+				}
+				if (existsSync(rawLogsFile)) {
+					await streamToPulse(buildLogsStreamURL, sdkKey, Bun.file(rawLogsFile), logger);
+				} else {
+					await streamToPulse(
+						buildLogsStreamURL,
+						sdkKey,
+						`--- FORK ERROR ---\n${errorMessage}\n`,
+						logger
+					);
+				}
 			}
-			logsContent += `\n\n--- FORK ERROR ---\n${errorMessage}\n`;
-			await streamToPulse(buildLogsStreamURL, sdkKey, logsContent, logger);
 		}
 
 		try {
@@ -360,7 +383,7 @@ export async function runForkedDeploy(options: ForkDeployOptions): Promise<ForkD
 		process.off('SIGTERM', sigtermHandler);
 
 		// Clean up temp files
-		for (const file of [reportFile, cleanLogsFile]) {
+		for (const file of [reportFile, cleanLogsFile, rawLogsFile]) {
 			if (existsSync(file)) {
 				try {
 					unlinkSync(file);

package/src/cmd/cloud/sandbox/snapshot/build.ts

@@ -17,7 +17,7 @@ import { z } from 'zod';
 import { getCommand } from '../../../../command-prefix';
 import { getCatalystAPIClient } from '../../../../config';
 import { encryptFIPSKEMDEMStream } from '../../../../crypto/box';
-import { ErrorCode } from '../../../../errors';
+import { ErrorCode, getExitCode } from '../../../../errors';
 import * as tui from '../../../../tui';
 import { createCommand } from '../../../../types';
 import { validateAptDependencies } from '../../../../utils/apt-validator';
@@ -941,7 +941,7 @@ export const buildSubcommand = createCommand({
 									2
 								)
 							);
-							process.exit(ErrorCode.MALWARE_DETECTED);
+							process.exit(getExitCode(ErrorCode.MALWARE_DETECTED));
 						}
 
 						console.log('');

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/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;

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;
+}