@agentuity/cli 0.0.109 → 0.0.111

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/cli",
-	"version": "0.0.109",
+	"version": "0.0.111",
 	"license": "Apache-2.0",
 	"author": "Agentuity employees and contributors",
 	"type": "module",
@@ -40,8 +40,9 @@
 		"prepublishOnly": "bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@agentuity/core": "0.0.109",
-		"@agentuity/server": "0.0.109",
+		"@agentuity/auth": "0.0.111",
+		"@agentuity/core": "0.0.111",
+		"@agentuity/server": "0.0.111",
 		"@datasert/cronjs-parser": "^1.4.0",
 		"@terascope/fetch-github-release": "^2.2.1",
 		"@vitejs/plugin-react": "^5.1.2",
@@ -58,10 +59,10 @@
 		"tar-fs": "^3.1.1",
 		"typescript": "^5.9.0",
 		"vite": "^7.2.7",
-		"zod": "^4.1.12"
+		"zod": "^4.3.5"
 	},
 	"devDependencies": {
-		"@agentuity/test-utils": "0.0.109",
+		"@agentuity/test-utils": "0.0.111",
 		"@types/adm-zip": "^0.5.7",
 		"@types/bun": "latest",
 		"@types/tar-fs": "^2.0.4",

package/src/build-report.ts

@@ -0,0 +1,457 @@
+/**
+ * Build Report
+ *
+ * Structured error/warning collection and reporting for build and deploy commands.
+ * Outputs a JSON file with a strict schema for CI tooling integration.
+ */
+
+import { writeFileSync } from 'node:fs';
+import type { GrammarItem } from './tsc-output-parser';
+
+/**
+ * Error codes for non-TypeScript errors.
+ * TypeScript errors use their native TS#### codes.
+ */
+export const BuildErrorCodes = {
+	// AST/Metadata errors (AST0xx)
+	AST001: 'MetadataNameMissing',
+	AST002: 'DuplicateName',
+	AST003: 'InvalidExport',
+	AST004: 'InvalidCronExpression',
+	AST005: 'InvalidAgentConfig',
+
+	// Build errors (BUILD0xx)
+	BUILD001: 'AppFileNotFound',
+	BUILD002: 'SourceDirNotFound',
+	BUILD003: 'DependencyUpgradeFailed',
+	BUILD004: 'BundleFailed',
+	BUILD005: 'EntryPointNotFound',
+	BUILD006: 'ViteBuildFailed',
+	BUILD007: 'RuntimePackageNotFound',
+	BUILD008: 'TypecheckToolFailed',
+
+	// Validation errors (VAL0xx)
+	VAL001: 'AgentIdentifierCollision',
+	VAL002: 'InvalidRoutePath',
+	VAL003: 'InvalidRouteMethod',
+	VAL004: 'SchemaValidationFailed',
+
+	// Deploy errors (DEPLOY0xx)
+	DEPLOY001: 'DeploymentCreationFailed',
+	DEPLOY002: 'UploadFailed',
+	DEPLOY003: 'DeploymentTimeout',
+	DEPLOY004: 'DeploymentFailed',
+	DEPLOY005: 'EncryptionFailed',
+	DEPLOY006: 'CDNUploadFailed',
+} as const;
+
+export type BuildErrorCode = keyof typeof BuildErrorCodes;
+
+/**
+ * Error scopes for categorizing errors
+ */
+export type ErrorScope = 'typescript' | 'ast' | 'build' | 'bundler' | 'validation' | 'deploy';
+
+/**
+ * File-specific error with location information
+ */
+export interface FileError {
+	type: 'file';
+	scope: ErrorScope;
+	path: string;
+	line: number;
+	column: number;
+	message: string;
+	code?: string;
+}
+
+/**
+ * General error without file location
+ */
+export interface GeneralError {
+	type: 'general';
+	scope: ErrorScope;
+	message: string;
+	code?: string;
+}
+
+/**
+ * Union type for all build errors
+ */
+export type BuildError = FileError | GeneralError;
+
+/**
+ * Union type for all build warnings (same structure as errors)
+ */
+export type BuildWarning = FileError | GeneralError;
+
+/**
+ * Diagnostic timing information for a build phase
+ */
+export interface BuildDiagnostic {
+	name: string;
+	startedAt: string;
+	completedAt: string;
+	durationMs: number;
+}
+
+/**
+ * Complete build report structure
+ */
+export interface BuildReport {
+	success: boolean;
+	errors: BuildError[];
+	warnings: BuildWarning[];
+	diagnostics: BuildDiagnostic[];
+}
+
+/**
+ * Diagnostic phases for timing
+ */
+export const DiagnosticPhases = [
+	'typecheck',
+	'client-build',
+	'workbench-build',
+	'server-build',
+	'metadata-generation',
+	'zip-package',
+	'encrypt',
+	'code-upload',
+	'cdn-upload',
+	'deployment-wait',
+] as const;
+
+export type DiagnosticPhase = (typeof DiagnosticPhases)[number];
+
+/**
+ * Active diagnostic tracker
+ */
+interface ActiveDiagnostic {
+	name: string;
+	startedAt: Date;
+}
+
+/**
+ * Build Report Collector
+ *
+ * Collects errors, warnings, and diagnostic timing information throughout
+ * the build/deploy pipeline. Can be configured to automatically write
+ * the report on process exit.
+ */
+export class BuildReportCollector {
+	private errors: BuildError[] = [];
+	private warnings: BuildWarning[] = [];
+	private diagnostics: BuildDiagnostic[] = [];
+	private activeDiagnostics: Map<string, ActiveDiagnostic> = new Map();
+	private outputPath: string | null = null;
+	private autoWriteEnabled = false;
+	private written = false;
+
+	private beforeExitHandler: (() => void) | null = null;
+	private sigintHandler: (() => void) | null = null;
+	private sigtermHandler: (() => void) | null = null;
+
+	/**
+	 * Set the output path for the report file
+	 */
+	setOutputPath(path: string): void {
+		this.outputPath = path;
+	}
+
+	/**
+	 * Enable automatic writing of the report on process exit.
+	 * This ensures the report is written even if the process exits unexpectedly.
+	 */
+	enableAutoWrite(): void {
+		if (this.autoWriteEnabled || !this.outputPath) return;
+
+		this.autoWriteEnabled = true;
+
+		// Use beforeExit for graceful exits
+		this.beforeExitHandler = () => {
+			this.writeSync();
+		};
+		process.once('beforeExit', this.beforeExitHandler);
+
+		// Handle SIGINT/SIGTERM with process.once to avoid stacking handlers
+		this.sigintHandler = () => {
+			this.writeSync();
+			process.exit(130);
+		};
+		this.sigtermHandler = () => {
+			this.writeSync();
+			process.exit(143);
+		};
+		process.once('SIGINT', this.sigintHandler);
+		process.once('SIGTERM', this.sigtermHandler);
+	}
+
+	/**
+	 * Disable automatic writing and remove signal handlers.
+	 * Call this when done with the collector to prevent handler conflicts.
+	 */
+	disableAutoWrite(): void {
+		if (!this.autoWriteEnabled) return;
+
+		this.autoWriteEnabled = false;
+
+		if (this.beforeExitHandler) {
+			process.removeListener('beforeExit', this.beforeExitHandler);
+			this.beforeExitHandler = null;
+		}
+		if (this.sigintHandler) {
+			process.removeListener('SIGINT', this.sigintHandler);
+			this.sigintHandler = null;
+		}
+		if (this.sigtermHandler) {
+			process.removeListener('SIGTERM', this.sigtermHandler);
+			this.sigtermHandler = null;
+		}
+	}
+
+	/**
+	 * Add TypeScript errors from parsed tsc output
+	 */
+	addTypeScriptErrors(items: GrammarItem[]): void {
+		for (const item of items) {
+			if (item.type !== 'Item' || !item.value) continue;
+
+			const val = item.value;
+			const isError = val.tsError?.value?.type === 'error';
+			const isWarning = val.tsError?.value?.type === 'warning';
+
+			if (!isError && !isWarning) continue;
+
+			const entry: FileError = {
+				type: 'file',
+				scope: 'typescript',
+				path: val.path?.value ?? 'unknown',
+				line: val.cursor?.value?.line ?? 0,
+				column: val.cursor?.value?.col ?? 0,
+				message: (val.message?.value ?? '').trim(),
+				code: val.tsError?.value?.errorString,
+			};
+
+			if (isError) {
+				this.errors.push(entry);
+			} else {
+				this.warnings.push(entry);
+			}
+		}
+	}
+
+	/**
+	 * Add a file-specific error
+	 */
+	addFileError(
+		scope: ErrorScope,
+		path: string,
+		line: number,
+		column: number,
+		message: string,
+		code?: string
+	): void {
+		this.errors.push({
+			type: 'file',
+			scope,
+			path,
+			line,
+			column,
+			message,
+			code,
+		});
+	}
+
+	/**
+	 * Add a general error without file location
+	 */
+	addGeneralError(scope: ErrorScope, message: string, code?: string): void {
+		this.errors.push({
+			type: 'general',
+			scope,
+			message,
+			code,
+		});
+	}
+
+	/**
+	 * Add a file-specific warning
+	 */
+	addFileWarning(
+		scope: ErrorScope,
+		path: string,
+		line: number,
+		column: number,
+		message: string,
+		code?: string
+	): void {
+		this.warnings.push({
+			type: 'file',
+			scope,
+			path,
+			line,
+			column,
+			message,
+			code,
+		});
+	}
+
+	/**
+	 * Add a general warning without file location
+	 */
+	addGeneralWarning(scope: ErrorScope, message: string, code?: string): void {
+		this.warnings.push({
+			type: 'general',
+			scope,
+			message,
+			code,
+		});
+	}
+
+	/**
+	 * Start timing a diagnostic phase
+	 * @returns A function to call when the phase completes
+	 */
+	startDiagnostic(name: string): () => void {
+		const startedAt = new Date();
+		this.activeDiagnostics.set(name, { name, startedAt });
+
+		return () => {
+			this.endDiagnostic(name);
+		};
+	}
+
+	/**
+	 * End a diagnostic phase
+	 */
+	private endDiagnostic(name: string): void {
+		const active = this.activeDiagnostics.get(name);
+		if (!active) return;
+
+		const completedAt = new Date();
+		const durationMs = completedAt.getTime() - active.startedAt.getTime();
+
+		this.diagnostics.push({
+			name,
+			startedAt: active.startedAt.toISOString(),
+			completedAt: completedAt.toISOString(),
+			durationMs,
+		});
+
+		this.activeDiagnostics.delete(name);
+	}
+
+	/**
+	 * Check if there are any errors
+	 */
+	hasErrors(): boolean {
+		return this.errors.length > 0;
+	}
+
+	/**
+	 * Check if there are any warnings
+	 */
+	hasWarnings(): boolean {
+		return this.warnings.length > 0;
+	}
+
+	/**
+	 * Get the error count
+	 */
+	getErrorCount(): number {
+		return this.errors.length;
+	}
+
+	/**
+	 * Get the warning count
+	 */
+	getWarningCount(): number {
+		return this.warnings.length;
+	}
+
+	/**
+	 * Generate the complete build report
+	 */
+	toReport(): BuildReport {
+		// Complete any active diagnostics - collect keys first to avoid
+		// iterating while modifying the map
+		const activeKeys = [...this.activeDiagnostics.keys()];
+		for (const name of activeKeys) {
+			this.endDiagnostic(name);
+		}
+
+		return {
+			success: this.errors.length === 0,
+			errors: [...this.errors],
+			warnings: [...this.warnings],
+			diagnostics: [...this.diagnostics],
+		};
+	}
+
+	/**
+	 * Write the report to the configured output path asynchronously
+	 */
+	async write(): Promise<void> {
+		if (!this.outputPath || this.written) return;
+
+		this.written = true;
+		const report = this.toReport();
+		const file = Bun.file(this.outputPath);
+		await file.write(JSON.stringify(report, null, '\t'));
+	}
+
+	/**
+	 * Write the report synchronously (for exit handlers)
+	 */
+	writeSync(): void {
+		if (!this.outputPath || this.written) return;
+
+		this.written = true;
+		const report = this.toReport();
+		writeFileSync(this.outputPath, JSON.stringify(report, null, '\t'));
+	}
+
+	/**
+	 * Force write the report (bypasses the written flag)
+	 * Use this when you want to update the report file mid-process
+	 */
+	async forceWrite(): Promise<void> {
+		if (!this.outputPath) return;
+
+		const report = this.toReport();
+		const file = Bun.file(this.outputPath);
+		await file.write(JSON.stringify(report, null, '\t'));
+		this.written = true;
+	}
+}
+
+/**
+ * Global collector instance for use across the build pipeline.
+ * Commands should create their own collector and pass it through,
+ * but this provides a fallback for error handling in deeply nested code.
+ */
+let globalCollector: BuildReportCollector | null = null;
+
+/**
+ * Set the global collector instance
+ */
+export function setGlobalCollector(collector: BuildReportCollector): void {
+	globalCollector = collector;
+}
+
+/**
+ * Get the global collector instance (may be null)
+ */
+export function getGlobalCollector(): BuildReportCollector | null {
+	return globalCollector;
+}
+
+/**
+ * Clear the global collector instance and clean up its signal handlers
+ */
+export function clearGlobalCollector(): void {
+	if (globalCollector) {
+		globalCollector.disableAutoWrite();
+	}
+	globalCollector = null;
+}

package/src/cli.ts

@@ -15,7 +15,7 @@ import type {
 } from './types';
 import { showBanner, generateBanner } from './banner';
 import { requireAuth, optionalAuth, requireOrg, optionalOrg as selectOptionalOrg } from './auth';
-import { listRegions, type RegionList } from '@agentuity/server';
+import { listRegions, type RegionList, ValidationOutputError } from '@agentuity/server';
 import enquirer from 'enquirer';
 import * as tui from './tui';
 import { parseArgsSchema, parseOptionsSchema, buildValidationInput } from './schema-parser';
@@ -26,6 +26,22 @@ import { getCommand } from './command-prefix';
 import { isValidateMode, outputValidation, type ValidationResult } from './output';
 import { StructuredError } from '@agentuity/core';
 
+/**
+ * Check if an error is a CLI input validation error (Zod error from schema parsing),
+ * and not an API response validation error (ValidationOutputError).
+ */
+function isCLIValidationError(error: unknown): boolean {
+	if (!error || typeof error !== 'object' || !('issues' in error)) {
+		return false;
+	}
+	// ValidationOutputError from API responses should NOT be treated as CLI validation errors
+	if (error instanceof ValidationOutputError) {
+		return false;
+	}
+	// Check for Zod error structure (has name 'ZodError' or is from SchemaValidationError)
+	return true;
+}
+
 const APIClientConfigError = StructuredError('APIClientConfigError');
 
 function createAPIClient(baseCtx: CommandContext, config: Config | null): APIClient {
@@ -1143,7 +1159,7 @@ async function registerSubcommand(
 						subcommand.webUrl
 					);
 				} catch (error) {
-					if (error && typeof error === 'object' && 'issues' in error) {
+					if (isCLIValidationError(error)) {
 						handleValidationError(error, getFullCommandPath(cmd), baseCtx);
 					}
 					handleProjectConfigError(
@@ -1322,7 +1338,7 @@ async function registerSubcommand(
 						subcommand.webUrl
 					);
 				} catch (error) {
-					if (error && typeof error === 'object' && 'issues' in error) {
+					if (isCLIValidationError(error)) {
 						handleValidationError(error, getFullCommandPath(cmd), baseCtx);
 					}
 					handleProjectConfigError(
@@ -1447,7 +1463,7 @@ async function registerSubcommand(
 						subcommand.webUrl
 					);
 				} catch (error) {
-					if (error && typeof error === 'object' && 'issues' in error) {
+					if (isCLIValidationError(error)) {
 						handleValidationError(error, getFullCommandPath(cmd), baseCtx);
 					}
 					handleProjectConfigError(

package/src/cmd/build/entry-generator.ts

@@ -85,10 +85,12 @@ export async function generateEntryFile(options: GenerateEntryOptions): Promise<
 	imports.push(`import { type LogLevel } from '@agentuity/core';`);
 
 	// Generate route mounting code for all discovered routes
+	// Sort route files for deterministic output
+	const sortedRouteFiles = [...routeFiles].sort();
 	const routeImportsAndMounts: string[] = [];
 	let routeIndex = 0;
 
-	for (const routeFile of routeFiles) {
+	for (const routeFile of sortedRouteFiles) {
 		// Convert src/api/auth/route.ts -> auth/route
 		const relativePath = routeFile.replace(/^src\/api\//, '').replace(/\.tsx?$/, '');
 

package/src/cmd/build/index.ts

@@ -6,6 +6,7 @@ import * as tui from '../../tui';
 import { getCommand } from '../../command-prefix';
 import { ErrorCode } from '../../errors';
 import { typecheck } from './typecheck';
+import { BuildReportCollector, setGlobalCollector, clearGlobalCollector } from '../../build-report';
 
 const BuildResponseSchema = z.object({
 	success: z.boolean().describe('Whether the build succeeded'),
@@ -36,6 +37,10 @@ export const command = createCommand({
 				.default(false)
 				.optional()
 				.describe('Skip typecheck after build'),
+			reportFile: z
+				.string()
+				.optional()
+				.describe('file path to save build report JSON with errors, warnings, and diagnostics'),
 		}),
 		response: BuildResponseSchema,
 	},
@@ -43,6 +48,14 @@ export const command = createCommand({
 	async handler(ctx) {
 		const { opts, projectDir, project } = ctx;
 
+		// Initialize build report collector if reportFile is specified
+		const collector = new BuildReportCollector();
+		if (opts.reportFile) {
+			collector.setOutputPath(opts.reportFile);
+			collector.enableAutoWrite();
+			setGlobalCollector(collector);
+		}
+
 		const absoluteProjectDir = resolve(projectDir);
 		const outDir = opts.outdir ? resolve(opts.outdir) : join(absoluteProjectDir, '.agentuity');
 
@@ -59,6 +72,7 @@ export const command = createCommand({
 				orgId: project?.orgId,
 				region: project?.region ?? 'local',
 				logger: ctx.logger,
+				collector,
 			});
 
 			// Copy profile-specific .env file AFTER bundling (bundler clears outDir first)
@@ -79,7 +93,10 @@ export const command = createCommand({
 			if (!opts.dev && !opts.skipTypeCheck) {
 				try {
 					tui.info('Running type check...');
-					const typeResult = await typecheck(absoluteProjectDir);
+					const endTypecheckDiagnostic = collector.startDiagnostic('typecheck');
+					const typeResult = await typecheck(absoluteProjectDir, { collector });
+					endTypecheckDiagnostic();
+
 					if (typeResult.success) {
 						tui.success('Type check passed');
 					} else {
@@ -88,10 +105,24 @@ export const command = createCommand({
 						console.error('');
 						const msg =
 							'errors' in typeResult ? 'Fix type errors before building' : 'Build error';
+
+						// Write report before fatal exit
+						if (opts.reportFile) {
+							await collector.forceWrite();
+						}
+						clearGlobalCollector();
 						tui.fatal(msg, ErrorCode.BUILD_FAILED);
 					}
 				} catch (error: unknown) {
 					const errorMsg = error instanceof Error ? error.message : String(error);
+					collector.addGeneralError('typescript', errorMsg, 'BUILD008');
+
+					// Write report before fatal exit
+					if (opts.reportFile) {
+						await collector.forceWrite();
+					}
+					clearGlobalCollector();
+
 					tui.error(`Type check failed to run: ${errorMsg}`);
 					tui.fatal(
 						'Unable to run TypeScript type checking. Ensure TypeScript is installed.',
@@ -102,6 +133,12 @@ export const command = createCommand({
 
 			tui.success('Build complete');
 
+			// Write final report on success
+			if (opts.reportFile) {
+				await collector.forceWrite();
+			}
+			clearGlobalCollector();
+
 			return {
 				success: true,
 				bundlePath: outDir,
@@ -109,11 +146,24 @@ export const command = createCommand({
 				dev: opts.dev || false,
 			};
 		} catch (error: unknown) {
+			// Add error to collector
 			if (error instanceof AggregateError) {
 				const ae = error as AggregateError;
 				for (const e of ae.errors) {
+					collector.addGeneralError('build', e.message, 'BUILD004');
 					tui.error(e.message);
 				}
+			} else {
+				collector.addGeneralError('build', String(error), 'BUILD004');
+			}
+
+			// Write report before fatal exit
+			if (opts.reportFile) {
+				await collector.forceWrite();
+			}
+			clearGlobalCollector();
+
+			if (error instanceof AggregateError) {
 				tui.fatal('Build failed', ErrorCode.BUILD_FAILED);
 			} else {
 				tui.fatal(`Build failed: ${error}`, ErrorCode.BUILD_FAILED);