@agentuity/cli 0.0.109 → 0.0.111

package/src/cmd/build/vite-bundler.ts

@@ -12,6 +12,7 @@ import { runAllBuilds } from './vite/vite-builder';
 import { checkAndUpgradeDependencies } from '../../utils/dependency-checker';
 import { checkBunVersion } from '../../utils/bun-version-checker';
 import * as tui from '../../tui';
+import type { BuildReportCollector } from '../../build-report';
 
 const AppFileNotFoundError = StructuredError('AppFileNotFoundError');
 const BuildFailedError = StructuredError('BuildFailedError');
@@ -26,6 +27,8 @@ export interface ViteBundleOptions {
 	port?: number;
 	logger: Logger;
 	deploymentOptions?: DeployOptions;
+	/** Optional collector for structured error reporting */
+	collector?: BuildReportCollector;
 }
 
 /**
@@ -41,6 +44,7 @@ export async function viteBundle(options: ViteBundleOptions): Promise<{ output:
 		port = 3500,
 		logger,
 		deploymentOptions,
+		collector,
 	} = options;
 
 	const output: string[] = [];
@@ -52,8 +56,10 @@ export async function viteBundle(options: ViteBundleOptions): Promise<{ output:
 	// Verify app.ts exists
 	const appFile = join(rootDir, 'app.ts');
 	if (!(await Bun.file(appFile).exists())) {
+		const errorMessage = `App file not found at expected location: ${appFile}`;
+		collector?.addGeneralError('build', errorMessage, 'BUILD001');
 		throw new AppFileNotFoundError({
-			message: `App file not found at expected location: ${appFile}`,
+			message: errorMessage,
 		});
 	}
 
@@ -63,16 +69,20 @@ export async function viteBundle(options: ViteBundleOptions): Promise<{ output:
 		.then((s) => s.isDirectory())
 		.catch(() => false);
 	if (!srcDirExists) {
+		const errorMessage = `Source directory not found: ${srcDir}`;
+		collector?.addGeneralError('build', errorMessage, 'BUILD002');
 		throw new BuildFailedError({
-			message: `Source directory not found: ${srcDir}`,
+			message: errorMessage,
 		});
 	}
 
 	// Check and upgrade @agentuity/* dependencies if needed
 	const upgradeResult = await checkAndUpgradeDependencies(rootDir, logger);
 	if (upgradeResult.failed.length > 0 && process.stdin.isTTY) {
+		const errorMessage = `Failed to upgrade dependencies: ${upgradeResult.failed.join(', ')}`;
+		collector?.addGeneralError('build', errorMessage, 'BUILD003');
 		throw new BuildFailedError({
-			message: `Failed to upgrade dependencies: ${upgradeResult.failed.join(', ')}`,
+			message: errorMessage,
 		});
 	}
 
@@ -90,6 +100,7 @@ export async function viteBundle(options: ViteBundleOptions): Promise<{ output:
 			deploymentId,
 			logger,
 			deploymentOptions,
+			collector,
 		});
 
 		if (result.client.included) {
@@ -106,8 +117,10 @@ export async function viteBundle(options: ViteBundleOptions): Promise<{ output:
 
 		return { output };
 	} catch (error) {
+		const errorMessage = `Build failed: ${error instanceof Error ? error.message : String(error)}`;
+		collector?.addGeneralError('build', errorMessage, 'BUILD004');
 		throw new BuildFailedError({
-			message: `Build failed: ${error instanceof Error ? error.message : String(error)}`,
+			message: errorMessage,
 		});
 	}
 }

package/src/cmd/cloud/deploy.ts

@@ -8,7 +8,14 @@ import { isRunningFromExecutable } from '../upgrade';
 import { createSubcommand, DeployOptionsSchema } from '../../types';
 import { getUserAgent } from '../../api';
 import * as tui from '../../tui';
-import { saveProjectDir, getDefaultConfigDir, loadProjectSDKKey } from '../../config';
+import {
+	saveProjectDir,
+	getDefaultConfigDir,
+	loadProjectSDKKey,
+	updateProjectConfig,
+} from '../../config';
+import { getProjectGithubStatus } from '../integration/api';
+import { runGitLink } from '../git/link';
 import {
 	runSteps,
 	stepSuccess,
@@ -45,6 +52,7 @@ import { getCommand } from '../../command-prefix';
 import * as domain from '../../domain';
 import { ErrorCode } from '../../errors';
 import { typecheck } from '../build/typecheck';
+import { BuildReportCollector, setGlobalCollector, clearGlobalCollector } from '../../build-report';
 
 const DeploymentCancelledError = StructuredError(
 	'DeploymentCancelled',
@@ -93,7 +101,12 @@ export const deploySubcommand = createSubcommand({
 		options: z.intersection(
 			DeployOptionsSchema,
 			z.object({
-				saveTypeErrors: z.string().optional().describe('file path to save typecheck errors'),
+				reportFile: z
+					.string()
+					.optional()
+					.describe(
+						'file path to save build report JSON with errors, warnings, and diagnostics'
+					),
 			})
 		),
 		response: DeployResponseSchema,
@@ -102,6 +115,14 @@ export const deploySubcommand = createSubcommand({
 	async handler(ctx) {
 		const { project, apiClient, projectDir, config, options, logger, opts } = ctx;
 
+		// Initialize build report collector if reportFile is specified
+		const collector = new BuildReportCollector();
+		if (opts.reportFile) {
+			collector.setOutputPath(opts.reportFile);
+			collector.enableAutoWrite();
+			setGlobalCollector(collector);
+		}
+
 		let deployment: Deployment | undefined;
 		let build: BuildMetadata | undefined;
 		let instructions: DeploymentInstructions | undefined;
@@ -149,6 +170,76 @@ export const deploySubcommand = createSubcommand({
 		try {
 			await saveProjectDir(projectDir);
 
+			// Check GitHub status and prompt for setup if not linked
+			// Skip in non-TTY environments (CI, automated runs) to prevent hanging
+			const hasTTY = process.stdin.isTTY && process.stdout.isTTY;
+			if (!useExistingDeployment && !project.skipGitSetup && hasTTY) {
+				try {
+					const githubStatus = await getProjectGithubStatus(apiClient, project.projectId);
+
+					if (githubStatus.linked && githubStatus.autoDeploy) {
+						// GitHub is already set up with auto-deploy, tell user to push instead
+						tui.newline();
+						tui.info(
+							`This project is linked to ${tui.bold(githubStatus.repoFullName ?? 'GitHub')} with automatic deployments enabled.`
+						);
+						tui.newline();
+						tui.info(
+							`Push a commit to the ${tui.bold(githubStatus.branch ?? 'main')} branch to trigger a deployment.`
+						);
+						tui.newline();
+						throw new DeploymentCancelledError();
+					}
+
+					if (!githubStatus.linked) {
+						tui.newline();
+						const wantSetup = await tui.confirm(
+							'Would you like to set up automatic deployments from GitHub?'
+						);
+
+						if (wantSetup) {
+							const result = await runGitLink({
+								apiClient,
+								projectId: project.projectId,
+								orgId: project.orgId,
+								logger,
+								skipAlreadyLinkedCheck: true,
+								config,
+							});
+
+							if (result.linked && result.autoDeploy) {
+								// GitHub linked with auto-deploy, tell user to push instead
+								tui.newline();
+								tui.info('GitHub integration set up successfully!');
+								tui.newline();
+								tui.info('Push a commit to trigger your first deployment.');
+								tui.newline();
+								throw new DeploymentCancelledError();
+							} else if (result.linked) {
+								// Linked but auto-deploy disabled, continue with manual deploy
+								tui.newline();
+								tui.info('GitHub repository linked. Continuing with deployment...');
+								tui.newline();
+							}
+						} else {
+							await updateProjectConfig(projectDir, { skipGitSetup: true }, config);
+							tui.newline();
+							tui.info(
+								`Skipping GitHub setup. Run ${tui.bold(getCommand('git link'))} later to enable it.`
+							);
+							tui.newline();
+						}
+					}
+				} catch (err) {
+					// Re-throw intentional cancellations
+					if (err instanceof DeploymentCancelledError) {
+						throw err;
+					}
+					// Log other errors as non-fatal and continue
+					logger.trace('Failed to check GitHub status: %s', err);
+				}
+			}
+
 			await runSteps(
 				[
 					!project.deployment?.domains?.length
@@ -239,8 +330,13 @@ export const deploySubcommand = createSubcommand({
 							}
 							let capturedOutput: string[] = [];
 							const rootDir = resolve(projectDir);
+
+							// Run typecheck with collector for error reporting
+							const endTypecheckDiagnostic = collector.startDiagnostic('typecheck');
 							const started = Date.now();
-							const typeResult = await typecheck(rootDir);
+							const typeResult = await typecheck(rootDir, { collector });
+							endTypecheckDiagnostic();
+
 							if (typeResult.success) {
 								capturedOutput.push(
 									tui.muted(
@@ -248,9 +344,10 @@ export const deploySubcommand = createSubcommand({
 									)
 								);
 							} else {
-								if ('errors' in typeResult && opts.saveTypeErrors) {
-									const f = Bun.file(opts.saveTypeErrors);
-									await f.write(JSON.stringify(typeResult.errors));
+								// Errors already added to collector by typecheck()
+								// Write report before returning error
+								if (opts.reportFile) {
+									await collector.forceWrite();
 								}
 								return stepError('Typecheck failed\n\n' + typeResult.output);
 							}
@@ -264,6 +361,7 @@ export const deploySubcommand = createSubcommand({
 									region: project.region,
 									logger: ctx.logger,
 									deploymentOptions: opts,
+									collector,
 								});
 								capturedOutput = [...capturedOutput, ...bundleResult.output];
 								build = await loadBuildMetadata(join(projectDir, '.agentuity'));
@@ -275,6 +373,10 @@ export const deploySubcommand = createSubcommand({
 								return stepSuccess(capturedOutput.length > 0 ? capturedOutput : undefined);
 							} catch (ex) {
 								const _ex = ex as Error;
+								// Write report before returning error
+								if (opts.reportFile) {
+									await collector.forceWrite();
+								}
 								return stepError(
 									_ex.message ?? 'Error building your project',
 									_ex,
@@ -294,6 +396,8 @@ export const deploySubcommand = createSubcommand({
 								return stepError('deployment instructions were null');
 							}
 
+							// Start diagnostic for zip/encrypt phase
+							const endZipDiagnostic = collector.startDiagnostic('zip-package');
 							progress(5);
 							ctx.logger.trace('Starting deployment zip creation');
 							// zip up the assets folder
@@ -319,8 +423,11 @@ export const deploySubcommand = createSubcommand({
 							});
 							ctx.logger.trace(`Deployment zip created: ${deploymentZip}`);
 
+							endZipDiagnostic();
+
 							progress(20);
 							// Encrypt the deployment zip using the public key from deployment
+							const endEncryptDiagnostic = collector.startDiagnostic('encrypt');
 							const encryptedZip = join(tmpdir(), `${deployment.id}.enc.zip`);
 							try {
 								ctx.logger.trace('Creating public key');
@@ -348,8 +455,11 @@ export const deploySubcommand = createSubcommand({
 									dst.end();
 								});
 								ctx.logger.trace('Stream finished');
+								endEncryptDiagnostic();
 
 								progress(50);
+								// Start code upload diagnostic
+								const endCodeUploadDiagnostic = collector.startDiagnostic('code-upload');
 								ctx.logger.trace(`Uploading deployment to ${instructions.deployment}`);
 								const zipfile = Bun.file(encryptedZip);
 								const fileSize = await zipfile.size;
@@ -364,8 +474,15 @@ export const deploySubcommand = createSubcommand({
 								});
 								ctx.logger.trace(`Upload response: ${resp.status}`);
 								if (!resp.ok) {
-									return stepError(`Error uploading deployment: ${await resp.text()}`);
+									endCodeUploadDiagnostic();
+									const errorMsg = `Error uploading deployment: ${await resp.text()}`;
+									collector.addGeneralError('deploy', errorMsg, 'DEPLOY002');
+									if (opts.reportFile) {
+										await collector.forceWrite();
+									}
+									return stepError(errorMsg);
 								}
+								endCodeUploadDiagnostic();
 
 								progress(70);
 								ctx.logger.trace('Consuming response body');
@@ -385,11 +502,17 @@ export const deploySubcommand = createSubcommand({
 							progress(80);
 							let bytes = 0;
 							if (build?.assets) {
+								// Start CDN upload diagnostic
+								const endCdnUploadDiagnostic = collector.startDiagnostic('cdn-upload');
 								ctx.logger.trace(`Uploading ${build.assets.length} assets`);
 								if (!instructions.assets) {
-									return stepError(
-										'server did not provide asset upload URLs; upload aborted'
-									);
+									const errorMsg =
+										'server did not provide asset upload URLs; upload aborted';
+									collector.addGeneralError('deploy', errorMsg, 'DEPLOY006');
+									if (opts.reportFile) {
+										await collector.forceWrite();
+									}
+									return stepError(errorMsg);
 								}
 
 								// Workaround for Bun crash in compiled executables (https://github.com/agentuity/sdk/issues/191)
@@ -452,11 +575,17 @@ export const deploySubcommand = createSubcommand({
 									const resps = await Promise.all(promises);
 									for (const r of resps) {
 										if (!r.ok) {
-											return stepError(`error uploading asset: ${await r.text()}`);
+											const errorMsg = `error uploading asset: ${await r.text()}`;
+											collector.addGeneralError('deploy', errorMsg, 'DEPLOY006');
+											if (opts.reportFile) {
+												await collector.forceWrite();
+											}
+											return stepError(errorMsg);
 										}
 									}
 								}
 								ctx.logger.trace('Asset uploads complete');
+								endCdnUploadDiagnostic();
 								progress(95);
 							}
 
@@ -503,6 +632,7 @@ export const deploySubcommand = createSubcommand({
 			const dashboard = `${appUrl}/r/${deployment.id}`;
 
 			// Poll for deployment status with optional log streaming
+			const endDeploymentWaitDiagnostic = collector.startDiagnostic('deployment-wait');
 			const pollInterval = 500;
 			const maxAttempts = 600;
 			let attempts = 0;
@@ -615,11 +745,16 @@ export const deploySubcommand = createSubcommand({
 							},
 						})
 						.then(() => {
+							endDeploymentWaitDiagnostic();
 							tui.success('Your project was deployed!');
 						})
-						.catch((ex) => {
+						.catch(async (ex) => {
+							endDeploymentWaitDiagnostic();
 							// Handle cancellation
 							if (ex instanceof DeploymentCancelledError) {
+								if (opts.reportFile) {
+									await collector.forceWrite();
+								}
 								tui.warning('Deployment cancelled');
 								process.exit(130); // Standard exit code for SIGINT
 							}
@@ -628,6 +763,18 @@ export const deploySubcommand = createSubcommand({
 								exwithmessage.message === 'Deployment failed'
 									? ''
 									: exwithmessage.toString();
+
+							// Add error to collector
+							const isTimeout = exwithmessage.message === 'Deployment timed out';
+							collector.addGeneralError(
+								'deploy',
+								msg || 'Deployment failed',
+								isTimeout ? 'DEPLOY003' : 'DEPLOY004'
+							);
+							if (opts.reportFile) {
+								await collector.forceWrite();
+							}
+
 							tui.error(`Your deployment failed to start${msg ? `: ${msg}` : ''}`);
 							if (logs.length) {
 								const logsDir = join(getDefaultConfigDir(), 'logs');
@@ -687,9 +834,22 @@ export const deploySubcommand = createSubcommand({
 						},
 					});
 
+					endDeploymentWaitDiagnostic();
 					tui.success('Your project was deployed!');
 				}
 			} catch (ex) {
+				endDeploymentWaitDiagnostic();
+				const exwithmessage = ex as { message: string };
+				const isTimeout = exwithmessage?.message === 'Deployment timed out';
+				collector.addGeneralError(
+					'deploy',
+					exwithmessage?.message || String(ex),
+					isTimeout ? 'DEPLOY003' : 'DEPLOY004'
+				);
+				if (opts.reportFile) {
+					await collector.forceWrite();
+				}
+
 				const lines = [`${ex}`, ''];
 				lines.push(
 					`${tui.ICONS.arrow} ${
@@ -741,6 +901,12 @@ export const deploySubcommand = createSubcommand({
 				});
 			}
 
+			// Write final report on success
+			if (opts.reportFile) {
+				await collector.forceWrite();
+			}
+			clearGlobalCollector();
+
 			return {
 				success: true,
 				deploymentId: deployment.id,
@@ -756,6 +922,11 @@ export const deploySubcommand = createSubcommand({
 					: undefined,
 			};
 		} catch (ex) {
+			collector.addGeneralError('deploy', String(ex), 'DEPLOY004');
+			if (opts.reportFile) {
+				await collector.forceWrite();
+			}
+			clearGlobalCollector();
 			tui.fatal(`unexpected error trying to deploy project. ${ex}`);
 		}
 	},

package/src/cmd/cloud/deployment/show.ts

@@ -36,7 +36,6 @@ const DeploymentShowResponseSchema = z.object({
 						.object({
 							number: z.number(),
 							url: z.string().optional(),
-							commentId: z.string().optional(),
 						})
 						.optional(),
 				})

package/src/cmd/cloud/sandbox/create.ts

@@ -4,6 +4,12 @@ import * as tui from '../../../tui';
 import { createSandboxClient, parseFileArgs } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxCreate } from '@agentuity/server';
+import { StructuredError } from '@agentuity/core';
+
+const InvalidMetadataError = StructuredError(
+	'InvalidMetadataError',
+	'Metadata must be a valid JSON object'
+);
 
 const SandboxCreateResponseSchema = z.object({
 	sandboxId: z.string().describe('Unique sandbox identifier'),
@@ -55,6 +61,7 @@ export const createSubcommand = createCommand({
 				.array(z.string())
 				.optional()
 				.describe('Apt packages to install (can be specified multiple times)'),
+			metadata: z.string().optional().describe('JSON object of user-defined metadata'),
 		}),
 		response: SandboxCreateResponseSchema,
 	},
@@ -77,6 +84,20 @@ export const createSubcommand = createCommand({
 		const files = parseFileArgs(opts.file);
 		const hasFiles = files.length > 0;
 
+		let metadata: Record<string, unknown> | undefined;
+		if (opts.metadata) {
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(opts.metadata);
+			} catch {
+				throw new InvalidMetadataError();
+			}
+			if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+				throw new InvalidMetadataError();
+			}
+			metadata = parsed as Record<string, unknown>;
+		}
+
 		const result = await sandboxCreate(client, {
 			options: {
 				resources:
@@ -93,6 +114,7 @@ export const createSubcommand = createCommand({
 				command: hasFiles ? { exec: [], files } : undefined,
 				snapshot: opts.snapshot,
 				dependencies: opts.dependency,
+				metadata,
 			},
 			orgId,
 		});

package/src/cmd/cloud/sandbox/delete.ts

@@ -14,7 +14,7 @@ const SandboxDeleteResponseSchema = z.object({
 
 export const deleteSubcommand = createCommand({
 	name: 'delete',
-	aliases: ['del', 'rm', 'remove', 'destroy'],
+	aliases: ['del', 'remove', 'destroy'],
 	description: 'Delete a sandbox',
 	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth'],
 	requires: { auth: true, region: true, org: true },
@@ -25,11 +25,7 @@ export const deleteSubcommand = createCommand({
 			description: 'Delete a sandbox',
 		},
 		{
-			command: getCommand('cloud sandbox rm abc123'),
-			description: 'Delete using alias',
-		},
-		{
-			command: getCommand('cloud sandbox rm abc123 --confirm'),
+			command: getCommand('cloud sandbox delete abc123 --confirm'),
 			description: 'Delete without confirmation prompt',
 		},
 	],

package/src/cmd/cloud/sandbox/download.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { writeFileSync } from 'node:fs';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createSandboxClient } from './util';
+import { getCommand } from '../../../command-prefix';
+import { sandboxDownloadArchive } from '@agentuity/server';
+
+export const downloadSubcommand = createCommand({
+	name: 'download',
+	aliases: ['dl'],
+	description: 'Download files from a sandbox as a compressed archive',
+	tags: ['slow', 'requires-auth'],
+	requires: { auth: true, region: true, org: true },
+	examples: [
+		{
+			command: getCommand('cloud sandbox download sbx_abc123 ./backup.tar.gz'),
+			description: 'Download sandbox files as tar.gz archive',
+		},
+		{
+			command: getCommand('cloud sandbox download sbx_abc123 ./backup.zip --format zip'),
+			description: 'Download sandbox files as zip archive',
+		},
+		{
+			command: getCommand('cloud sandbox download sbx_abc123 ./backup.tar.gz --path /subdir'),
+			description: 'Download only a specific directory',
+		},
+	],
+	schema: {
+		args: z.object({
+			sandboxId: z.string().describe('The sandbox ID'),
+			output: z.string().describe('Output file path for the archive'),
+		}),
+		options: z.object({
+			path: z.string().optional().describe('Path in sandbox to download (defaults to root)'),
+			format: z
+				.enum(['zip', 'tar.gz'])
+				.default('tar.gz')
+				.optional()
+				.describe('Archive format (zip or tar.gz)'),
+		}),
+		response: z.object({
+			success: z.boolean(),
+			output: z.string(),
+			bytes: z.number(),
+		}),
+	},
+
+	async handler(ctx) {
+		const { args, opts, options, auth, region, logger, orgId } = ctx;
+
+		const client = createSandboxClient(logger, auth, region);
+		const format = opts.format || 'tar.gz';
+
+		const stream = await sandboxDownloadArchive(client, {
+			sandboxId: args.sandboxId,
+			path: opts.path || '.',
+			format,
+			orgId,
+		});
+
+		const chunks: Uint8Array[] = [];
+		const reader = stream.getReader();
+
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			chunks.push(value);
+		}
+
+		const totalBytes = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+		const buffer = new Uint8Array(totalBytes);
+		let offset = 0;
+		for (const chunk of chunks) {
+			buffer.set(chunk, offset);
+			offset += chunk.length;
+		}
+
+		writeFileSync(args.output, buffer);
+
+		if (!options.json) {
+			tui.success(`Downloaded ${formatSize(totalBytes)} to ${args.output}`);
+		}
+
+		return { success: true, output: args.output, bytes: totalBytes };
+	},
+});
+
+function formatSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} bytes`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+
+export default downloadSubcommand;