@agentuity/cli 0.0.60 → 0.0.61

package/src/crypto/box.ts

@@ -62,6 +62,7 @@
 import { createCipheriv, createDecipheriv, createECDH, randomBytes, KeyObject } from 'node:crypto';
 import { Readable, Writable } from 'node:stream';
 import { createHash } from 'node:crypto';
+import { StructuredError } from '@agentuity/core';
 
 const FRAME = 65519;
 const DEK_SIZE = 32;
@@ -87,13 +88,64 @@ function concatKDFSHA256(z: Buffer, keyDataLen: number, ...otherInfo: Buffer[]):
 	return h.digest();
 }
 
+const InvalidECPublicKeyError = StructuredError('InvalidECPublicKeyError', 'Invalid EC public key');
+const InvalidECPrivateKeyError = StructuredError(
+	'InvalidECPrivateKeyError',
+	'Invalid EC private key'
+);
+const InvalidDEKTooShortError = StructuredError(
+	'InvalidDEKTooShortError',
+	'Invalid DEK too short (wrapped)'
+);
+const InvalidDEKFormatError = StructuredError(
+	'InvalidDEKFormatError',
+	'Invalid DEK format (wrapped)'
+);
+const DEKUnwrappedFailedError = StructuredError('DEKUnwrappedFailedError', 'DEK unwrap failed');
+
+const InvalidKeyECOnlyError = StructuredError(
+	'InvalidKeyECOnlyError',
+	'Invalid Key: only EC keys supported'
+);
+const InvalidKeyP256OnlyError = StructuredError(
+	'InvalidKeyP256OnlyError',
+	'Invalid Key: only P-256 keys supported'
+);
+
+const InvalidCipherTextLengthError = StructuredError(
+	'InvalidCipherTextLengthError',
+	'ciphertext length exceeds uint16 limit'
+);
+
+const InvalidWrappedDEKLengthError = StructuredError(
+	'InvalidWrappedDEKLengthError',
+	'invalid wrapped DEK length'
+);
+
+const UnexpectedEOFChunkLengthError = StructuredError(
+	'UnexpectedEOFChunkLengthError',
+	'unexpected EOF reading chunk length'
+);
+
+const UnexpectedChunkTooLargeError = StructuredError(
+	'UnexpectedChunkTooLargeError',
+	'chunk too large'
+);
+
+const UnexpectedChunkTooShortError = StructuredError(
+	'UnexpectedChunkTooShortError',
+	'chunk too short for auth tag'
+);
+
+const UnexpectedEOFError = StructuredError('UnexpectedEOFError', 'unexpected EOF');
+
 function wrapDEKWithECDH(dek: Buffer, recipientPub: KeyObject): Buffer {
 	const ephemeral = createECDH('prime256v1');
 	ephemeral.generateKeys();
 
 	const jwk = recipientPub.export({ format: 'jwk' });
 	if (!jwk.x || !jwk.y) {
-		throw new Error('Invalid EC public key');
+		throw new InvalidECPublicKeyError();
 	}
 
 	const xBuf = Buffer.from(jwk.x, 'base64url');
@@ -116,7 +168,7 @@ function wrapDEKWithECDH(dek: Buffer, recipientPub: KeyObject): Buffer {
 
 function unwrapDEKWithECDH(wrapped: Buffer, recipientPriv: KeyObject): Buffer {
 	if (wrapped.length < PUBKEY_LEN + 12 + DEK_SIZE + GCM_TAG) {
-		throw new Error('wrapped DEK too short');
+		throw new InvalidDEKTooShortError();
 	}
 
 	const ephemeralPubBytes = wrapped.subarray(0, PUBKEY_LEN);
@@ -124,7 +176,7 @@ function unwrapDEKWithECDH(wrapped: Buffer, recipientPriv: KeyObject): Buffer {
 
 	const jwk = recipientPriv.export({ format: 'jwk' });
 	if (!jwk.d) {
-		throw new Error('Invalid EC private key');
+		throw new InvalidECPrivateKeyError();
 	}
 
 	const ecdh = createECDH('prime256v1');
@@ -139,14 +191,14 @@ function unwrapDEKWithECDH(wrapped: Buffer, recipientPriv: KeyObject): Buffer {
 
 		const nonceSize = 12;
 		if (remaining.length < nonceSize) {
-			throw new Error('invalid wrapped DEK format');
+			throw new InvalidDEKFormatError();
 		}
 
 		const nonce = remaining.subarray(0, nonceSize);
 		const ciphertextAndTag = remaining.subarray(nonceSize);
 
 		if (ciphertextAndTag.length < GCM_TAG) {
-			throw new Error('invalid wrapped DEK format');
+			throw new InvalidDEKFormatError();
 		}
 
 		const ciphertext = ciphertextAndTag.subarray(0, ciphertextAndTag.length - GCM_TAG);
@@ -158,8 +210,8 @@ function unwrapDEKWithECDH(wrapped: Buffer, recipientPriv: KeyObject): Buffer {
 		let plaintext: Buffer;
 		try {
 			plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
-		} catch (_err) {
-			throw new Error('DEK unwrap failed');
+		} catch (err) {
+			throw new DEKUnwrappedFailedError({ cause: err });
 		}
 
 		kek.fill(0);
@@ -182,11 +234,11 @@ export async function encryptFIPSKEMDEMStream(
 	dst: Writable
 ): Promise<number> {
 	if (pub.asymmetricKeyType !== 'ec') {
-		throw new Error('only EC keys supported');
+		throw new InvalidKeyECOnlyError();
 	}
 	const keyDetails = pub.asymmetricKeyDetails;
 	if (!keyDetails || keyDetails.namedCurve !== 'prime256v1') {
-		throw new Error('only P-256 keys supported');
+		throw new InvalidKeyP256OnlyError();
 	}
 
 	const dek = randomBytes(DEK_SIZE);
@@ -234,7 +286,7 @@ export async function encryptFIPSKEMDEMStream(
 			const ct = Buffer.concat([ciphertext, tag]);
 
 			if (ct.length > 0xffff) {
-				throw new Error('ciphertext length exceeds uint16 limit');
+				throw new InvalidCipherTextLengthError();
 			}
 
 			const ctLenBuf = Buffer.alloc(2);
@@ -264,11 +316,11 @@ export async function decryptFIPSKEMDEMStream(
 	dst: Writable
 ): Promise<number> {
 	if (priv.asymmetricKeyType !== 'ec') {
-		throw new Error('only EC keys supported');
+		throw new InvalidKeyECOnlyError();
 	}
 	const keyDetails = priv.asymmetricKeyDetails;
 	if (!keyDetails || keyDetails.namedCurve !== 'prime256v1') {
-		throw new Error('only P-256 keys supported');
+		throw new InvalidKeyP256OnlyError();
 	}
 
 	const it = src[Symbol.asyncIterator]();
@@ -279,7 +331,7 @@ export async function decryptFIPSKEMDEMStream(
 		const wrappedLen = lenBuf.readUInt16BE(0);
 
 		if (wrappedLen === 0 || wrappedLen > 200) {
-			throw new Error('invalid wrapped DEK length');
+			throw new InvalidWrappedDEKLengthError();
 		}
 
 		const wrapped = Buffer.alloc(wrappedLen);
@@ -305,19 +357,19 @@ export async function decryptFIPSKEMDEMStream(
 					break;
 				}
 				if (chunkLenRead < 2) {
-					throw new Error('unexpected EOF reading chunk length');
+					throw new UnexpectedEOFChunkLengthError();
 				}
 
 				const chunkLen = chunkLenBuf.readUInt16BE(0);
 				if (chunkLen > FRAME + GCM_TAG) {
-					throw new Error('chunk too large');
+					throw new UnexpectedChunkTooLargeError();
 				}
 
 				const cipherBuf = Buffer.alloc(chunkLen);
 				await readExact(it, src, cipherBuf);
 
 				if (cipherBuf.length < GCM_TAG) {
-					throw new Error('chunk too short for auth tag');
+					throw new UnexpectedChunkTooShortError();
 				}
 
 				const ciphertext = cipherBuf.subarray(0, cipherBuf.length - GCM_TAG);
@@ -438,7 +490,7 @@ async function readExact(
 	while (offset < buf.length) {
 		const result = await iterator.next();
 		if (result.done) {
-			throw new Error('unexpected EOF');
+			throw new UnexpectedEOFError();
 		}
 
 		const chunk = result.value;

package/src/download.ts

@@ -1,5 +1,6 @@
 import { Transform, Readable } from 'node:stream';
 import * as tui from './tui';
+import { APIError } from '@agentuity/server';
 
 export interface DownloadOptions {
 	url: string;
@@ -25,7 +26,12 @@ export async function downloadWithProgress(
 
 	const response = await fetch(url, { headers: requestHeaders });
 	if (!response.ok) {
-		throw new Error(`Download failed: ${response.statusText}`);
+		throw new APIError({
+			url,
+			status: response.status,
+			sessionId: response.headers.get('x-session-id'),
+			error: `Download failed: ${response.statusText}`,
+		});
 	}
 
 	const contentLength = parseInt(response.headers.get('content-length') || '0', 10);

package/src/env-util.ts

@@ -204,6 +204,9 @@ export function splitEnvAndSecrets(vars: EnvVars): {
 
 /**
  * Mask a secret value for display
+ * - For URLs with credentials: parses and masks username/password partially
+ * - For long strings: shows more context (first 6 and last 6 chars)
+ * - For short strings: shows generic masking
  */
 export function maskSecret(value: string): string {
 	if (!value) {
@@ -214,8 +217,47 @@ export function maskSecret(value: string): string {
 		return '***';
 	}
 
-	// Show first 4 and last 4 characters
-	return `${value.slice(0, 4)}...${value.slice(-4)}`;
+	// Try to parse as URL with credentials
+	try {
+		const url = new URL(value);
+
+		// If URL has username or password, mask them partially
+		if (url.username || url.password) {
+			let maskedAuth = '';
+
+			if (url.username) {
+				// Show first 2 and last 2 chars of username
+				const len = url.username.length;
+				if (len <= 4) {
+					maskedAuth = '***';
+				} else {
+					maskedAuth = `${url.username.slice(0, 2)}***${url.username.slice(-2)}`;
+				}
+			}
+
+			if (url.password) {
+				// Show first 3 and last 3 chars of password
+				const len = url.password.length;
+				if (len <= 6) {
+					maskedAuth += ':***';
+				} else {
+					maskedAuth += `:${url.password.slice(0, 3)}***${url.password.slice(-3)}`;
+				}
+			} else if (url.username) {
+				// Username but no password
+				maskedAuth += ':***';
+			}
+
+			// Reconstruct URL with masked credentials
+			const maskedUrl = `${url.protocol}//${maskedAuth}@${url.host}${url.pathname}${url.search}${url.hash}`;
+			return maskedUrl;
+		}
+	} catch {
+		// Not a valid URL, fall through to regular masking
+	}
+
+	// For long strings, show first 6 and last 6 characters for better context
+	return `${value.slice(0, 6)}...${value.slice(-6)}`;
 }
 
 /**

package/src/errors.ts

@@ -13,6 +13,7 @@ export enum ExitCode {
 	NETWORK_ERROR = 6,
 	FILE_ERROR = 7,
 	USER_CANCELLED = 8,
+	BUILD_FAILED = 9,
 }
 
 /**
@@ -68,6 +69,9 @@ export enum ErrorCode {
 
 	// User cancellation
 	USER_CANCELLED = 'USER_CANCELLED',
+
+	// Build failed error
+	BUILD_FAILED = 'BUILD_FAILED',
 }
 
 /**
@@ -121,6 +125,10 @@ export function getExitCode(errorCode: ErrorCode): ExitCode {
 		case ErrorCode.USER_CANCELLED:
 			return ExitCode.USER_CANCELLED;
 
+		// Build errors
+		case ErrorCode.BUILD_FAILED:
+			return ExitCode.BUILD_FAILED;
+
 		// Resource conflicts and other errors
 		case ErrorCode.RESOURCE_ALREADY_EXISTS:
 		case ErrorCode.RESOURCE_CONFLICT:
@@ -203,7 +211,7 @@ export function exitWithError(
 	if (errorFormat === 'json') {
 		console.error(formatErrorJSON(error));
 	} else {
-		console.error(formatErrorHuman(error));
+		logger.error(formatErrorHuman(error));
 	}
 	const exitCode = error.exitCode ?? getExitCode(error.code);
 	process.exit(exitCode);

package/src/index.ts

@@ -1,6 +1,11 @@
 export { createCLI, registerCommands } from './cli';
 export { validateRuntime, isBun } from './runtime';
-export { generateCLISchema, type CLISchema, type SchemaCommand } from './schema-generator';
+export {
+	generateCLISchema,
+	type CLISchema,
+	type SchemaCommand,
+	type SchemaExample,
+} from './schema-generator';
 export {
 	ErrorCode,
 	createError,

package/src/schema-generator.ts

@@ -31,13 +31,18 @@ export interface SchemaPagination {
 	};
 }
 
+export interface SchemaExample {
+	command: string;
+	description: string;
+}
+
 export interface SchemaCommand {
 	name: string;
 	description: string;
 	aliases?: string[];
 	arguments?: SchemaArgument[];
 	options?: SchemaOption[];
-	examples?: string[];
+	examples?: SchemaExample[];
 	response?: unknown;
 	idempotent?: boolean;
 	prerequisites?: string[];
@@ -280,6 +285,7 @@ export function generateCLISchema(
 			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',
 		},
 		globalOptions: [
 			{

package/src/steps.ts

@@ -7,7 +7,7 @@
 
 import type { ColorScheme } from './terminal';
 import type { LogLevel } from './types';
-import { ValidationError } from '@agentuity/server';
+import { ValidationInputError, ValidationOutputError, type IssuesType } from '@agentuity/server';
 
 /**
  * Get the appropriate exit function (Bun.exit or process.exit)
@@ -201,6 +201,17 @@ export async function runSteps(steps: Step[], logLevel?: LogLevel): Promise<void
 	}
 }
 
+function printValidationIssues(issues?: IssuesType) {
+	const errorColor = getColor('red');
+	console.error(`${errorColor}Validation details:${COLORS.reset}`);
+	if (issues) {
+		for (const issue of issues) {
+			const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+			console.error(`  ${path}: ${issue.message}`);
+		}
+	}
+}
+
 /**
  * Run steps with animated TUI (original behavior)
  */
@@ -283,12 +294,11 @@ async function runStepsTUI(state: StepState[]): Promise<void> {
 			if (step.outcome?.status === 'error') {
 				const errorColor = getColor('red');
 				console.error(`\n${errorColor}Error: ${step.outcome.message}${COLORS.reset}`);
-				if (step.outcome.cause instanceof ValidationError) {
-					console.error(`${errorColor}Validation details:${COLORS.reset}`);
-					for (const issue of step.outcome.cause.issues) {
-						const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
-						console.error(`  ${path}: ${issue.message}`);
-					}
+				if (
+					step.outcome.cause instanceof ValidationInputError ||
+					step.outcome.cause instanceof ValidationOutputError
+				) {
+					printValidationIssues(step.outcome.cause.issues);
 				}
 				console.error('');
 				process.stdout.write('\x1B[?25h'); // Show cursor
@@ -342,12 +352,11 @@ async function runStepsPlain(state: StepState[]): Promise<void> {
 			console.log(`${redColor}${ICONS.error}${COLORS.reset} ${step.label}`);
 			const errorColor = getColor('red');
 			console.error(`\n${errorColor}Error: ${step.outcome.message}${COLORS.reset}`);
-			if (step.outcome.cause instanceof ValidationError) {
-				console.error(`${errorColor}Validation details:${COLORS.reset}`);
-				for (const issue of step.outcome.cause.issues) {
-					const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
-					console.error(`  ${path}: ${issue.message}`);
-				}
+			if (
+				step.outcome.cause instanceof ValidationInputError ||
+				step.outcome.cause instanceof ValidationOutputError
+			) {
+				printValidationIssues(step.outcome.cause.issues);
 			}
 			console.error('');
 			process.exit(1);

package/src/tui.ts

@@ -49,6 +49,7 @@ function getColors() {
 			muted: { light: '', dark: '' },
 			bold: { light: '', dark: '' },
 			link: { light: '', dark: '' },
+			primary: { light: '', dark: '' },
 			reset: '',
 		} as const;
 	}
@@ -82,6 +83,10 @@ function getColors() {
 			light: '\x1b[34;4m', // blue underline (need ANSI for underline)
 			dark: '\x1b[94;4m', // bright blue underline
 		},
+		primary: {
+			light: Bun.color('#000000', 'ansi') || '\x1b[30m', // black
+			dark: Bun.color('#FFFFFF', 'ansi') || '\x1b[97m', // white
+		},
 		reset: '\x1b[0m',
 	} as const;
 }
@@ -139,6 +144,12 @@ export function colorMuted(text: string): string {
 	return `${color}${text}${reset}`;
 }
 
+export function colorPrimary(text: string): string {
+	const color = getColor('primary');
+	const reset = getColor('reset');
+	return `${color}${text}${reset}`;
+}
+
 /**
  * Get the appropriate color function for a log severity level
  */
@@ -241,25 +252,15 @@ export function bold(text: string): string {
  * Used for table headings
  */
 export function heading(text: string): string {
-	const USE_COLORS = shouldUseColors();
-	if (!USE_COLORS) {
-		return text;
-	}
-
-	// For light mode: use inverse (black bg, white text)
-	// For dark mode: use white bold
-	const style = isDarkMode()
-		? '\x1b[1;37m' // bold white
-		: '\x1b[7m'; // inverse
+	const color = getColor('info');
 	const reset = getColor('reset');
-	return `${style}${text}${reset}`;
+	return `${color}${text}${reset}`;
 }
 
 /**
  * Format text as a link (blue and underlined)
  */
-export function link(url: string, title?: string): string {
-	const color = getColor('link');
+export function link(url: string, title?: string, color = getColor('link')): string {
 	const reset = getColor('reset');
 
 	// Check if terminal supports hyperlinks (OSC 8) and colors are enabled
@@ -1439,6 +1440,11 @@ export function table<T extends Record<string, unknown>>(
 		head?: string[];
 		colAligns?: Array<'left' | 'right' | 'center'>;
 		wordWrap?: boolean;
+		style?: {
+			head?: string[];
+			border?: string[];
+		};
+		colors?: boolean;
 	}) => {
 		push(row: unknown[]): void;
 		toString(): string;
@@ -1454,11 +1460,14 @@ export function table<T extends Record<string, unknown>>(
 	let columnNames: string[];
 	let colAligns: Array<'left' | 'right' | 'center'>;
 
+	let headings: string[];
+
 	if (isAdvancedMode) {
 		// Advanced mode: use provided column configurations
 		const columnConfigs = columns as TableColumn[];
 		columnNames = columnConfigs.map((col) => col.name);
 		colAligns = columnConfigs.map((col) => col.alignment || 'left');
+		headings = columnNames.map((name) => heading(name));
 	} else {
 		// Simple mode: determine column names from data or columns parameter
 		columnNames = columns
@@ -1467,15 +1476,18 @@ export function table<T extends Record<string, unknown>>(
 				? Object.keys(data[0])
 				: [];
 		colAligns = columnNames.map(() => 'left' as const);
+		headings = columnNames.map((name) => heading(name));
 	}
 
-	// Apply heading style to column names
-	const headings = columnNames.map((name) => heading(name));
-
 	const t = new Table({
 		head: headings,
 		colAligns,
 		wordWrap: true,
+		style: {
+			head: [], // Disable cli-table3's default red styling - we apply our own via heading()
+			border: [], // Disable default border styling too
+		},
+		colors: false, // Completely disable cli-table3's color system to preserve our ANSI codes
 	});
 
 	// Add rows to table

package/src/types.ts

@@ -127,6 +127,11 @@ export interface PaginationInfo {
 	};
 }
 
+export interface CommandExample {
+	command: string;
+	description: string;
+}
+
 export interface CommandSchemas {
 	args?: z.ZodType;
 	options?: z.ZodType;
@@ -263,7 +268,7 @@ export function createSubcommand<
 	toplevel?: boolean;
 	requires?: R;
 	optional?: O;
-	examples?: string[];
+	examples?: CommandExample[];
 	idempotent?: boolean;
 	prerequisites?: string[];
 	pagination?: PaginationInfo;
@@ -304,7 +309,7 @@ export function createCommand<
 	hidden?: boolean;
 	requires?: R;
 	optional?: O;
-	examples?: string[];
+	examples?: CommandExample[];
 	idempotent?: boolean;
 	prerequisites?: string[];
 	pagination?: PaginationInfo;
@@ -338,7 +343,7 @@ type CommandDefBase =
 			description: string;
 			aliases?: string[];
 			banner?: boolean;
-			examples?: string[];
+			examples?: CommandExample[];
 			idempotent?: boolean;
 			prerequisites?: string[];
 			pagination?: PaginationInfo;
@@ -352,7 +357,7 @@ type CommandDefBase =
 			description: string;
 			aliases?: string[];
 			banner?: boolean;
-			examples?: string[];
+			examples?: CommandExample[];
 			idempotent?: boolean;
 			prerequisites?: string[];
 			pagination?: PaginationInfo;
@@ -369,7 +374,7 @@ type SubcommandDefBase =
 			aliases?: string[];
 			toplevel?: boolean;
 			banner?: boolean;
-			examples?: string[];
+			examples?: CommandExample[];
 			idempotent?: boolean;
 			prerequisites?: string[];
 			pagination?: PaginationInfo;
@@ -384,7 +389,7 @@ type SubcommandDefBase =
 			aliases?: string[];
 			toplevel?: boolean;
 			banner?: boolean;
-			examples?: string[];
+			examples?: CommandExample[];
 			idempotent?: boolean;
 			prerequisites?: string[];
 			pagination?: PaginationInfo;

package/src/utils/date.ts

@@ -1,3 +1,7 @@
+import { StructuredError } from '@agentuity/core';
+
+const InvalidDateFormatError = StructuredError('InvalidDateFormatError')<{ input: string }>();
+
 /**
  * Parse duration string (e.g., "1h", "2d", "1y") or ISO date to ISO date string
  *
@@ -16,7 +20,7 @@ export function parseExpiresAt(input: string): string {
 		// Validate it's a valid date
 		const date = new Date(input);
 		if (isNaN(date.getTime())) {
-			throw new Error(`Invalid date format: ${input}`);
+			throw new InvalidDateFormatError({ input, message: `Invalid date format: ${input}` });
 		}
 		return date.toISOString();
 	}
@@ -26,9 +30,10 @@ export function parseExpiresAt(input: string): string {
 	const match = input.match(durationRegex);
 
 	if (!match) {
-		throw new Error(
-			`Invalid expires-at format: ${input}. Use ISO date (2025-12-31T23:59:59Z) or duration (1h, 2d, 1y)`
-		);
+		throw new InvalidDateFormatError({
+			input,
+			message: `Invalid expires-at format: ${input}. Use ISO date (2025-12-31T23:59:59Z) or duration (1h, 2d, 1y)`,
+		});
 	}
 
 	const [, amount, unit] = match;