@agentuity/cli 0.0.108 → 0.0.110

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/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?$/, '');
 
@@ -237,7 +239,7 @@ if (isDevelopment()) {
 	// 404 for unmatched API/system routes
 	app.all('/_agentuity/*', (c: Context) => c.notFound());
 	app.all('/api/*', (c: Context) => c.notFound());
-	if (hasWorkbench) {
+	if (!hasWorkbench) {
 		app.all('/workbench/*', (c: Context) => c.notFound());
 	}
 	
@@ -272,7 +274,7 @@ if (isDevelopment()) {
 	// 404 for unmatched API/system routes (IMPORTANT: comes before SPA fallback)
 	app.all('/_agentuity/*', (c: Context) => c.notFound());
 	app.all('/api/*', (c: Context) => c.notFound());
-	if (hasWorkbench) {
+	if (!hasWorkbench) {
 		app.all('/workbench/*', (c: Context) => c.notFound());
 	}
 
@@ -457,6 +459,10 @@ app.use('/api/*', createAgentMiddleware(''));
 // Step 4: Import user's app.ts (runs createApp, gets state/config)
 await import('../../app.js');
 
+// Step 4.5: Import agent registry to ensure all agents are registered
+// This is needed for workbench metadata to return JSON schemas
+await import('./registry.js');
+
 // Step 5: Initialize providers
 const appState = getAppState();
 const appConfig = getAppConfig();

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

package/src/cmd/build/typecheck.ts

@@ -1,5 +1,6 @@
 import { parse, type GrammarItem } from '../../tsc-output-parser';
 import { formatTypeScriptErrors, hasErrors } from '../../typescript-errors';
+import type { BuildReportCollector } from '../../build-report';
 
 interface TypeError {
 	success: false;
@@ -18,13 +19,20 @@ interface TypeSuccess {
 
 type TypeResult = TypeError | TypeSuccess | TypeUnknownError;
 
+export interface TypecheckOptions {
+	/** Optional collector for structured error reporting */
+	collector?: BuildReportCollector;
+}
+
 /**
  * run the typescript compiler and result formatted results
  *
  * @param dir the absolute path to the directory containing the project (must have tsconfig.json in this folder)
+ * @param options optional configuration including error collector
  * @returns
  */
-export async function typecheck(dir: string): Promise<TypeResult> {
+export async function typecheck(dir: string, options?: TypecheckOptions): Promise<TypeResult> {
+	const { collector } = options ?? {};
 	const result = await Bun.$`bunx tsc --noEmit --skipLibCheck --pretty false`
 		.cwd(dir)
 		.quiet()
@@ -38,6 +46,11 @@ export async function typecheck(dir: string): Promise<TypeResult> {
 			success: true,
 		};
 	} else if (errors && hasErrors(errors)) {
+		// Add errors to collector if provided
+		if (collector) {
+			collector.addTypeScriptErrors(errors);
+		}
+
 		const formattedErrors = await formatTypeScriptErrors(errors, {
 			projectDir: dir,
 		});
@@ -47,6 +60,11 @@ export async function typecheck(dir: string): Promise<TypeResult> {
 			output: formattedErrors,
 		};
 	} else {
+		// Unknown error - add to collector as general error
+		if (collector) {
+			collector.addGeneralError('typescript', output || result.stderr.toString());
+		}
+
 		return {
 			success: false,
 			output: output || result.stderr.toString(),

package/src/cmd/build/vite/index.ts

@@ -1,7 +1,7 @@
 import type { Plugin } from 'vite';
 import { join } from 'node:path';
 import { createLogger } from '@agentuity/server';
-import type { LogLevel } from '../../../types';
+import type { LogLevel, DeployOptions } from '../../../types';
 import { discoverAgents, type AgentMetadata } from './agent-discovery';
 import { discoverRoutes, type RouteMetadata, type RouteInfo } from './route-discovery';
 import { generateAgentRegistry, generateRouteRegistry } from './registry-generator';
@@ -20,6 +20,7 @@ export interface AgentuityPluginOptions {
 	orgId?: string;
 	deploymentId?: string;
 	logLevel?: LogLevel;
+	deploymentOptions?: DeployOptions;
 }
 
 /**
@@ -42,6 +43,7 @@ export function agentuityPlugin(options: AgentuityPluginOptions): Plugin {
 		orgId = '',
 		deploymentId = '',
 		logLevel = 'info',
+		deploymentOptions,
 	} = options;
 	const logger = createLogger(logLevel);
 	const srcDir = join(rootDir, 'src');
@@ -153,6 +155,7 @@ export function agentuityPlugin(options: AgentuityPluginOptions): Plugin {
 				routes,
 				dev,
 				logger,
+				deploymentOptions,
 			});
 
 			// Write metadata file