@agentuity/cli 0.0.48 → 0.0.50

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

@@ -3,13 +3,28 @@ import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { projectDeploymentDelete } from '@agentuity/server';
 import { resolveProjectId } from './utils';
+import { getCommand } from '../../../command-prefix';
+
+const DeploymentRemoveResponseSchema = z.object({
+	success: z.boolean().describe('Whether the removal succeeded'),
+	projectId: z.string().describe('Project ID'),
+	deploymentId: z.string().describe('Deployment ID that was removed'),
+});
 
 export const removeSubcommand = createSubcommand({
 	name: 'remove',
 	description: 'Remove a specific deployment',
+	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth', 'requires-deployment'],
+	examples: [
+		`${getCommand('cloud deployment remove')} dep_abc123xyz        # Remove with confirmation`,
+		`${getCommand('cloud deployment remove')} dep_abc123xyz --force # Remove without confirmation`,
+		`${getCommand('cloud deployment remove')} deployment-2024-11-20 --project-id=proj_abc123xyz`,
+	],
 	aliases: ['rm', 'delete'],
+	idempotent: false,
 	requires: { auth: true, apiClient: true },
 	optional: { project: true },
+	prerequisites: ['cloud deploy'],
 	schema: {
 		args: z.object({
 			deployment_id: z.string().describe('Deployment ID'),
@@ -18,22 +33,31 @@ export const removeSubcommand = createSubcommand({
 			'project-id': z.string().optional().describe('Project ID'),
 			force: z.boolean().default(false).describe('Force removal without confirmation'),
 		}),
+		response: DeploymentRemoveResponseSchema,
 	},
 	async handler(ctx) {
 		const projectId = resolveProjectId(ctx, { projectId: ctx.opts['project-id'] });
 		const { apiClient, args, opts } = ctx;
 
 		if (!opts.force) {
-			const confirmed = await tui.confirm(`Are you sure you want to remove deployment ${args.deployment_id}?`);
+			const confirmed = await tui.confirm(
+				`Are you sure you want to remove deployment ${args.deployment_id}?`
+			);
 			if (!confirmed) {
 				tui.info('Operation cancelled');
-				return;
+				return { success: false, projectId, deploymentId: args.deployment_id };
 			}
 		}
 
 		try {
 			await projectDeploymentDelete(apiClient, projectId, args.deployment_id);
 			tui.success(`Deployment ${args.deployment_id} removed successfully.`);
+
+			return {
+				success: true,
+				projectId,
+				deploymentId: args.deployment_id,
+			};
 		} catch (ex) {
 			tui.fatal(`Failed to remove deployment: ${ex instanceof Error ? ex.message : String(ex)}`);
 		}

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

@@ -3,16 +3,39 @@ import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { projectDeploymentRollback, projectDeploymentList } from '@agentuity/server';
 import { resolveProjectId } from './utils';
+import { getCommand } from '../../../command-prefix';
+
+const DeploymentRollbackResponseSchema = z.object({
+	success: z.boolean().describe('Whether the rollback succeeded'),
+	projectId: z.string().describe('Project ID'),
+	targetDeploymentId: z.string().describe('Deployment ID that was rolled back to'),
+});
 
 export const rollbackSubcommand = createSubcommand({
 	name: 'rollback',
 	description: 'Rollback the latest to the previous deployment',
+	tags: [
+		'destructive',
+		'deletes-resource',
+		'updates-resource',
+		'slow',
+		'api-intensive',
+		'requires-auth',
+		'requires-deployment',
+	],
+	examples: [
+		`${getCommand('cloud deployment rollback')}                   # Rollback to previous deployment`,
+		`${getCommand('cloud deployment rollback')} --project-id=proj_abc123xyz`,
+	],
+	idempotent: false,
 	requires: { auth: true, apiClient: true },
 	optional: { project: true },
+	prerequisites: ['cloud deploy'],
 	schema: {
 		options: z.object({
 			'project-id': z.string().optional().describe('Project ID'),
 		}),
+		response: DeploymentRollbackResponseSchema,
 	},
 	async handler(ctx) {
 		const projectId = resolveProjectId(ctx, { projectId: ctx.opts['project-id'] });
@@ -23,17 +46,19 @@ export const rollbackSubcommand = createSubcommand({
 			const deployments = await projectDeploymentList(apiClient, projectId, 5);
 
 			// Find currently active
-			const activeIndex = deployments.findIndex(d => d.active);
+			const activeIndex = deployments.findIndex((d) => d.active);
 
 			let targetDeploymentId: string | undefined;
 
 			if (activeIndex === -1) {
 				// No active deployment.
-				const candidate = deployments.find(d => d.state === 'completed');
+				const candidate = deployments.find((d) => d.state === 'completed');
 				targetDeploymentId = candidate?.id;
 			} else {
 				// Has active deployment. Find the next completed one.
-				const candidate = deployments.slice(activeIndex + 1).find(d => d.state === 'completed');
+				const candidate = deployments
+					.slice(activeIndex + 1)
+					.find((d) => d.state === 'completed');
 				targetDeploymentId = candidate?.id;
 			}
 
@@ -44,11 +69,17 @@ export const rollbackSubcommand = createSubcommand({
 			const confirmed = await tui.confirm(`Rollback to deployment ${targetDeploymentId}?`);
 			if (!confirmed) {
 				tui.info('Operation cancelled');
-				return;
+				return { success: false, projectId, targetDeploymentId };
 			}
 
 			await projectDeploymentRollback(apiClient, projectId, targetDeploymentId!);
 			tui.success(`Rolled back to deployment ${targetDeploymentId}.`);
+
+			return {
+				success: true,
+				projectId,
+				targetDeploymentId,
+			};
 		} catch (ex) {
 			tui.fatal(`Failed to rollback: ${ex instanceof Error ? ex.message : String(ex)}`);
 		}

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

@@ -3,13 +3,33 @@ import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { projectDeploymentGet } from '@agentuity/server';
 import { resolveProjectId } from './utils';
+import { getCommand } from '../../../command-prefix';
+
+const DeploymentShowResponseSchema = z.object({
+	id: z.string().describe('Deployment ID'),
+	state: z.string().optional().describe('Deployment state'),
+	active: z.boolean().describe('Whether deployment is active'),
+	createdAt: z.string().describe('Creation timestamp'),
+	updatedAt: z.string().optional().describe('Last update timestamp'),
+	message: z.string().optional().describe('Deployment message'),
+	tags: z.array(z.string()).describe('Deployment tags'),
+	customDomains: z.array(z.string()).optional().describe('Custom domains'),
+	cloudRegion: z.string().optional().describe('Cloud region'),
+	metadata: z.any().optional().describe('Deployment metadata'),
+});
 
 export const showSubcommand = createSubcommand({
 	name: 'show',
 	description: 'Show details about a specific deployment',
+	tags: ['read-only', 'fast', 'requires-auth', 'requires-deployment'],
+	examples: [
+		`${getCommand('cloud deployment show')} dep_abc123xyz`,
+		`${getCommand('cloud deployment show')} deployment-2024-11-20 --project-id=proj_abc123xyz`,
+	],
 	aliases: ['get'],
 	requires: { auth: true, apiClient: true },
 	optional: { project: true },
+	prerequisites: ['cloud deploy'],
 	schema: {
 		args: z.object({
 			deployment_id: z.string().describe('Deployment ID'),
@@ -17,7 +37,9 @@ export const showSubcommand = createSubcommand({
 		options: z.object({
 			'project-id': z.string().optional().describe('Project ID'),
 		}),
+		response: DeploymentShowResponseSchema,
 	},
+	idempotent: true,
 	async handler(ctx) {
 		const projectId = resolveProjectId(ctx, { projectId: ctx.opts['project-id'] });
 		const { apiClient, args } = ctx;
@@ -49,10 +71,10 @@ export const showSubcommand = createSubcommand({
 			}
 
 			// Metadata
-			if (deployment.metadata?.origin?.commit) {
+			const origin = deployment.metadata?.origin;
+			if (origin?.commit) {
 				tui.newline();
 				tui.info('Origin Information');
-				const origin = deployment.metadata.origin;
 				if (origin.trigger) console.log(`  Trigger:  ${origin.trigger}`);
 				if (origin.provider) console.log(`  Provider: ${origin.provider}`);
 				if (origin.event) console.log(`  Event:    ${origin.event}`);
@@ -65,6 +87,19 @@ export const showSubcommand = createSubcommand({
 						console.log(`  Author:   ${origin.commit.author.name}`);
 				}
 			}
+
+			return {
+				id: deployment.id,
+				state: deployment.state,
+				active: deployment.active,
+				createdAt: deployment.createdAt,
+				updatedAt: deployment.updatedAt,
+				message: deployment.message,
+				tags: deployment.tags,
+				customDomains: deployment.customDomains,
+				cloudRegion: deployment.cloudRegion,
+				metadata: deployment.metadata,
+			};
 		} catch (ex) {
 			tui.fatal(`Failed to show deployment: ${ex instanceof Error ? ex.message : String(ex)}`);
 		}

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

@@ -3,12 +3,21 @@ import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { projectDeploymentUndeploy } from '@agentuity/server';
 import { resolveProjectId } from './utils';
+import { getCommand } from '../../../command-prefix';
 
 export const undeploySubcommand = createSubcommand({
 	name: 'undeploy',
 	description: 'Undeploy the latest deployment',
+	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth', 'requires-deployment'],
+	examples: [
+		`${getCommand('cloud deployment undeploy')}        # Undeploy with confirmation`,
+		`${getCommand('cloud deployment undeploy')} --force # Undeploy without confirmation`,
+		`${getCommand('cloud deployment undeploy')} --project-id=proj_abc123xyz`,
+	],
+	idempotent: false,
 	requires: { auth: true, apiClient: true },
 	optional: { project: true },
+	prerequisites: ['cloud deploy'],
 	schema: {
 		options: z.object({
 			'project-id': z.string().optional().describe('Project ID'),
@@ -20,7 +29,9 @@ export const undeploySubcommand = createSubcommand({
 		const { apiClient, opts } = ctx;
 
 		if (!opts.force) {
-			const confirmed = await tui.confirm('Are you sure you want to undeploy? This will stop the active deployment.');
+			const confirmed = await tui.confirm(
+				'Are you sure you want to undeploy? This will stop the active deployment.'
+			);
 			if (!confirmed) {
 				tui.info('Operation cancelled');
 				return;

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

@@ -1,6 +1,9 @@
-import { CommandContext } from '../../../types';
+import { ProjectConfig } from '../../../types';
 
-export function resolveProjectId(ctx: CommandContext<any, any>, options: { projectId?: string }): string {
+export function resolveProjectId(
+	ctx: { project?: ProjectConfig },
+	options: { projectId?: string }
+): string {
 	if (options.projectId) {
 		return options.projectId;
 	}

package/src/cmd/cloud/domain.ts

@@ -23,8 +23,9 @@ export async function checkCustomDomainForDNS(
 ): Promise<DNSResult[]> {
 	const suffix = config?.overrides?.api_url?.includes('agentuity.io')
 		? 'agentuity.io'
-		: 'agentuity.com';
-	const id = Bun.hash.xxHash64(`${projectId}latest`).toString(16);
+		: 'agentuity.cloud';
+	// FIXME: update to add the region into this
+	const id = Bun.hash.xxHash64(projectId).toString(16);
 	const proxy = `p${id}.${suffix}`;
 
 	return Promise.all(

package/src/cmd/cloud/index.ts

@@ -1,6 +1,7 @@
 import { createCommand } from '../../types';
 import { deploySubcommand } from './deploy';
 import { resourceSubcommand } from './resource';
+import { sessionCommand } from './session';
 import { sshSubcommand } from './ssh';
 import { scpSubcommand } from './scp';
 import { deploymentCommand } from './deployment';
@@ -8,5 +9,13 @@ import { deploymentCommand } from './deployment';
 export const command = createCommand({
 	name: 'cloud',
 	description: 'Cloud related commands',
-	subcommands: [deploySubcommand, resourceSubcommand, sshSubcommand, scpSubcommand, deploymentCommand],
+	tags: ['slow', 'requires-auth'],
+	subcommands: [
+		deploySubcommand,
+		resourceSubcommand,
+		sessionCommand,
+		sshSubcommand,
+		scpSubcommand,
+		deploymentCommand,
+	],
 });

package/src/cmd/cloud/resource/add.ts

@@ -4,16 +4,30 @@ import enquirer from 'enquirer';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { getCatalystAPIClient } from '../../../config';
+import { getCommand } from '../../../command-prefix';
 
 export const addSubcommand = createSubcommand({
 	name: 'add',
 	aliases: ['create'],
 	description: 'Add a cloud resource for an organization',
+	tags: ['mutating', 'creates-resource', 'slow', 'requires-auth', 'requires-deployment'],
+	idempotent: false,
 	requires: { auth: true, org: true, region: true },
+	examples: [
+		getCommand('cloud resource add'),
+		getCommand('cloud resource add --type database'),
+		getCommand('cloud resource add --type storage'),
+		getCommand('cloud resource create --type database'),
+	],
 	schema: {
 		options: z.object({
 			type: z.enum(['database', 'storage']).optional().describe('Resource type'),
 		}),
+		response: z.object({
+			success: z.boolean().describe('Whether creation succeeded'),
+			type: z.string().describe('Resource type (database or storage)'),
+			name: z.string().describe('Created resource name'),
+		}),
 	},
 
 	async handler(ctx) {
@@ -49,6 +63,11 @@ export const addSubcommand = createSubcommand({
 
 		if (created.length > 0) {
 			tui.success(`Created ${resourceType}: ${tui.bold(created[0].name)}`);
+			return {
+				success: true,
+				type: resourceType,
+				name: created[0].name,
+			};
 		} else {
 			tui.fatal('Failed to create resource');
 		}

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

@@ -4,18 +4,33 @@ import enquirer from 'enquirer';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { getCatalystAPIClient } from '../../../config';
+import { getCommand } from '../../../command-prefix';
 
 export const deleteSubcommand = createSubcommand({
 	name: 'delete',
 	description: 'Delete cloud resource(s) for an organization',
+	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth', 'requires-deployment'],
 	aliases: ['rm', 'del', 'remove'],
+	idempotent: false,
 	requires: { auth: true, org: true, region: true },
+	examples: [
+		getCommand('cloud resource delete'),
+		getCommand('cloud resource delete --type db --name my-database'),
+		getCommand('cloud resource delete --type s3 --name uploads'),
+		getCommand('--explain cloud resource delete --type db --name old-db'),
+		getCommand('--dry-run cloud resource rm --type s3 --name temp-bucket'),
+	],
 	schema: {
 		options: z.object({
 			type: z.enum(['db', 's3']).optional().describe('Resource type (db or s3)'),
 			name: z.string().optional().describe('Resource name to delete'),
 			confirm: z.boolean().optional().describe('Skip confirmation prompts'),
 		}),
+		response: z.object({
+			success: z.boolean().describe('Whether deletion succeeded'),
+			count: z.number().describe('Number of resources deleted'),
+			resources: z.array(z.string()).describe('Deleted resource names'),
+		}),
 	},
 
 	async handler(ctx) {
@@ -41,7 +56,7 @@ export const deleteSubcommand = createSubcommand({
 
 			if (resources.db.length === 0 && resources.s3.length === 0) {
 				tui.info('No resources found to delete');
-				return;
+				return { success: false, count: 0, resources: [] };
 			}
 
 			// Build choices for multi-select and resource map
@@ -81,7 +96,7 @@ export const deleteSubcommand = createSubcommand({
 
 		if (resourcesToDelete.length === 0) {
 			tui.info('No resources selected for deletion');
-			return;
+			return { success: false, count: 0, resources: [] };
 		}
 
 		// Confirm deletion
@@ -98,7 +113,7 @@ export const deleteSubcommand = createSubcommand({
 
 			if (!confirm.confirm) {
 				tui.info('Deletion cancelled');
-				return;
+				return { success: false, count: 0, resources: [] };
 			}
 		}
 
@@ -116,5 +131,11 @@ export const deleteSubcommand = createSubcommand({
 		} else {
 			tui.error('Failed to delete resources');
 		}
+
+		return {
+			success: deleted.length > 0,
+			count: deleted.length,
+			resources: deleted,
+		};
 	},
 });

package/src/cmd/cloud/resource/index.ts

@@ -1,11 +1,12 @@
-import type { SubcommandDefinition } from '../../../types';
+import { createCommand } from '../../../types';
 import { listSubcommand } from './list';
 import { addSubcommand } from './add';
 import { deleteSubcommand } from './delete';
 
-export const resourceSubcommand: SubcommandDefinition = {
+export const resourceSubcommand = createCommand({
 	name: 'resource',
 	aliases: ['resources'],
 	description: 'Manage cloud resources',
+	tags: ['fast', 'requires-auth', 'requires-deployment'],
 	subcommands: [listSubcommand, addSubcommand, deleteSubcommand],
-};
+});

package/src/cmd/cloud/resource/list.ts

@@ -3,24 +3,48 @@ import { listResources } from '@agentuity/server';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { getCatalystAPIClient } from '../../../config';
+import { getCommand } from '../../../command-prefix';
+
+const ResourceListResponseSchema = z.object({
+	db: z
+		.array(
+			z.object({
+				name: z.string().describe('Database name'),
+				url: z.string().optional().describe('Database connection URL'),
+			})
+		)
+		.describe('List of database resources'),
+	s3: z
+		.array(
+			z.object({
+				bucket_name: z.string().describe('Storage bucket name'),
+				access_key: z.string().optional().describe('S3 access key'),
+				secret_key: z.string().optional().describe('S3 secret key'),
+				region: z.string().optional().describe('S3 region'),
+				endpoint: z.string().optional().describe('S3 endpoint URL'),
+			})
+		)
+		.describe('List of storage resources'),
+});
 
 export const listSubcommand = createSubcommand({
 	name: 'list',
 	description: 'List cloud resources for an organization',
+	tags: ['read-only', 'fast', 'requires-auth'],
 	aliases: ['ls'],
 	requires: { auth: true, org: true, region: true },
+	idempotent: true,
+	examples: [
+		getCommand('cloud resource list'),
+		getCommand('--json cloud resource list'),
+		getCommand('cloud resource ls'),
+	],
 	schema: {
-		options: z.object({
-			format: z
-				.enum(['text', 'json'])
-				.optional()
-				.default('text')
-				.describe('Output format (text or json)'),
-		}),
+		response: ResourceListResponseSchema,
 	},
 
 	async handler(ctx) {
-		const { logger, opts, orgId, region, config, auth } = ctx;
+		const { logger, options, orgId, region, config, auth } = ctx;
 
 		const catalystClient = getCatalystAPIClient(config, logger, auth);
 
@@ -33,13 +57,13 @@ export const listSubcommand = createSubcommand({
 		});
 
 		// Output based on format
-		if (opts.format === 'json') {
+		if (options.json) {
 			console.log(JSON.stringify(resources, null, 2));
 		} else {
 			// Text table format
 			if (resources.db.length === 0 && resources.s3.length === 0) {
 				tui.info('No resources found');
-				return;
+				return { db: [], s3: [] };
 			}
 
 			if (resources.db.length > 0) {
@@ -65,5 +89,7 @@ export const listSubcommand = createSubcommand({
 				}
 			}
 		}
+
+		return resources;
 	},
 });

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

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { getIONHost } from '../../../config';
+import { getCommand } from '../../../command-prefix';
 
 const args = z.object({
 	source: z.string().describe('the source file'),
@@ -16,9 +17,27 @@ export const downloadCommand = createSubcommand({
 	name: 'download',
 	aliases: ['get'],
 	description: 'Download a file using security copy',
+	tags: ['read-only', 'slow', 'requires-auth', 'requires-deployment'],
+	idempotent: true,
+	examples: [
+		`${getCommand('cloud scp download')} /var/log/app.log          # Download to current directory`,
+		`${getCommand('cloud scp download')} /var/log/app.log ./logs/  # Download to specific path`,
+		`${getCommand('cloud scp download')} /app/config.json --identifier=proj_abc123xyz`,
+		`${getCommand('cloud scp download')} ~/logs/*.log ./logs/      # Download multiple files`,
+	],
 	requires: { apiClient: true, auth: true },
 	optional: { project: true },
-	schema: { args, options },
+	prerequisites: ['cloud deploy'],
+	schema: {
+		args,
+		options,
+		response: z.object({
+			success: z.boolean().describe('Whether download succeeded'),
+			source: z.string().describe('Remote source path'),
+			destination: z.string().describe('Local destination path'),
+			identifier: z.string().describe('Project or deployment identifier'),
+		}),
+	},
 
 	async handler(ctx) {
 		const { apiClient, args, opts, project, projectDir, config } = ctx;
@@ -49,6 +68,13 @@ export const downloadCommand = createSubcommand({
 				);
 				process.exit(spawn.exitCode ?? 1);
 			}
+
+			return {
+				success: true,
+				source: args.source,
+				destination,
+				identifier,
+			};
 		} catch (error) {
 			tui.error(
 				`SCP download error: ${error instanceof Error ? error.message : 'Unknown error'}`

package/src/cmd/cloud/scp/index.ts

@@ -1,9 +1,10 @@
-import type { SubcommandDefinition } from '../../../types';
+import { createCommand } from '../../../types';
 import { downloadCommand } from './download';
 import { uploadCommand } from './upload';
 
-export const scpSubcommand: SubcommandDefinition = {
+export const scpSubcommand = createCommand({
 	name: 'scp',
 	description: 'Secure Copy commands',
+	tags: ['slow', 'requires-auth', 'requires-deployment'],
 	subcommands: [downloadCommand, uploadCommand],
-};
+});

package/src/cmd/cloud/scp/upload.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { getIONHost } from '../../../config';
+import { getCommand } from '../../../command-prefix';
 
 const args = z.object({
 	source: z.string().describe('the source file'),
@@ -19,9 +20,27 @@ export const uploadCommand = createSubcommand({
 	name: 'upload',
 	aliases: ['cp', 'put'],
 	description: 'Upload a file using security copy',
+	tags: ['mutating', 'updates-resource', 'slow', 'requires-auth', 'requires-deployment'],
+	idempotent: false,
+	examples: [
+		`${getCommand('cloud scp upload')} ./config.json                # Upload to remote home directory`,
+		`${getCommand('cloud scp upload')} ./config.json /app/config.json # Upload to specific path`,
+		`${getCommand('cloud scp upload')} ./config.json --identifier=proj_abc123xyz`,
+		`${getCommand('cloud scp upload')} ./logs/*.log ~/logs/        # Upload multiple files`,
+	],
 	requires: { apiClient: true, auth: true },
-	schema: { args, options },
+	schema: {
+		args,
+		options,
+		response: z.object({
+			success: z.boolean().describe('Whether upload succeeded'),
+			source: z.string().describe('Local source path'),
+			destination: z.string().describe('Remote destination path'),
+			identifier: z.string().describe('Project or deployment identifier'),
+		}),
+	},
 	optional: { project: true },
+	prerequisites: ['cloud deploy'],
 
 	async handler(ctx) {
 		const { apiClient, args, opts, project, projectDir, config } = ctx;
@@ -52,6 +71,13 @@ export const uploadCommand = createSubcommand({
 				);
 				process.exit(spawn.exitCode ?? 1);
 			}
+
+			return {
+				success: true,
+				source: args.source,
+				destination,
+				identifier,
+			};
 		} catch (error) {
 			tui.error(`SCP upload error: ${error instanceof Error ? error.message : 'Unknown error'}`);
 			process.exit(1);