@agentuity/cli 0.0.59 → 0.0.61

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

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+import { listResources, deleteResources, APIError } from '@agentuity/server';
+import enquirer from 'enquirer';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { getCatalystAPIClient } from '../../../config';
+import { getCommand } from '../../../command-prefix';
+import { isDryRunMode, outputDryRun } from '../../../explain';
+import { ErrorCode } from '../../../errors';
+
+export const deleteSubcommand = createSubcommand({
+	name: 'delete',
+	aliases: ['rm', 'del'],
+	description: 'Delete a database resource',
+	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth', 'requires-deployment'],
+	idempotent: false,
+	requires: { auth: true, org: true, region: true },
+	examples: [
+		{ command: getCommand('cloud db delete my-database'), description: 'Delete item' },
+		{ command: getCommand('cloud db rm my-database'), description: 'Delete item' },
+		{ command: getCommand('cloud db delete'), description: 'Delete item' },
+		{ command: getCommand('--dry-run cloud db delete my-database'), description: 'Delete item' },
+	],
+	schema: {
+		args: z.object({
+			name: z.string().optional().describe('Database name to delete'),
+		}),
+		options: z.object({
+			confirm: z.boolean().optional().describe('Skip confirmation prompts'),
+		}),
+		response: z.object({
+			success: z.boolean().describe('Whether deletion succeeded'),
+			name: z.string().describe('Deleted database name'),
+		}),
+	},
+
+	async handler(ctx) {
+		const { logger, args, opts, config, orgId, region, auth, options } = ctx;
+
+		const catalystClient = getCatalystAPIClient(config, logger, auth);
+
+		let dbName = args.name;
+
+		if (!dbName) {
+			const resources = await tui.spinner({
+				message: `Fetching databases for ${orgId} in ${region}`,
+				clearOnSuccess: true,
+				callback: async () => {
+					return listResources(catalystClient, orgId, region!);
+				},
+			});
+
+			if (resources.db.length === 0) {
+				tui.info('No databases found to delete');
+				return { success: false, name: '' };
+			}
+
+			const response = await enquirer.prompt<{ db: string }>({
+				type: 'select',
+				name: 'db',
+				message: 'Select database to delete:',
+				choices: resources.db.map((db) => ({
+					name: db.name,
+					message: db.name,
+				})),
+			});
+
+			dbName = response.db;
+		}
+
+		// Handle dry-run mode
+		if (isDryRunMode(options)) {
+			outputDryRun(`Would delete database: ${dbName}`, options);
+			if (!options.json) {
+				tui.newline();
+				tui.info('[DRY RUN] Database deletion skipped');
+			}
+			return {
+				success: false,
+				name: dbName,
+			};
+		}
+
+		if (!opts.confirm) {
+			tui.warning(`You are about to delete database: ${tui.bold(dbName)}`);
+
+			const confirm = await enquirer.prompt<{ confirm: boolean }>({
+				type: 'confirm',
+				name: 'confirm',
+				message: 'Are you sure you want to delete this database?',
+				initial: false,
+			});
+
+			if (!confirm.confirm) {
+				tui.info('Deletion cancelled');
+				return { success: false, name: dbName };
+			}
+		}
+
+		try {
+			const deleted = await tui.spinner({
+				message: `Deleting database ${dbName}`,
+				clearOnSuccess: true,
+				callback: async () => {
+					return deleteResources(catalystClient, orgId, region!, [
+						{ type: 'db', name: dbName },
+					]);
+				},
+			});
+
+			if (deleted.length > 0) {
+				tui.success(`Deleted database: ${tui.bold(deleted[0])}`);
+				return {
+					success: true,
+					name: deleted[0],
+				};
+			} else {
+				tui.error('Failed to delete database');
+				return { success: false, name: dbName };
+			}
+		} catch (ex) {
+			if (ex instanceof APIError) {
+				if (ex.status === 404) {
+					tui.fatal(
+						`database with the name "${dbName}" doesn't exist.`,
+						ErrorCode.INVALID_ARGUMENT
+					);
+				}
+			}
+			throw ex;
+		}
+	},
+});

package/src/cmd/cloud/db/get.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+import { listResources } from '@agentuity/server';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { getCatalystAPIClient } from '../../../config';
+import { getCommand } from '../../../command-prefix';
+import { ErrorCode } from '../../../errors';
+
+const DBGetResponseSchema = z.object({
+	name: z.string().describe('Database name'),
+	url: z.string().optional().describe('Database connection URL'),
+});
+
+export const getSubcommand = createSubcommand({
+	name: 'get',
+	aliases: ['show'],
+	description: 'Show details about a specific database',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true, org: true, region: true },
+	idempotent: true,
+	examples: [
+		{ command: `${getCommand('cloud db get')} my-database`, description: 'Get database details' },
+		{
+			command: `${getCommand('cloud db show')} my-database`,
+			description: 'Show database information',
+		},
+		{
+			command: `${getCommand('cloud db get')} my-database --show-credentials`,
+			description: 'Get database with credentials',
+		},
+	],
+	schema: {
+		args: z.object({
+			name: z.string().describe('Database name'),
+		}),
+		options: z.object({
+			showCredentials: z
+				.boolean()
+				.optional()
+				.describe(
+					'Show credentials in plain text (default: masked in terminal, unmasked in JSON)'
+				),
+		}),
+		response: DBGetResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { logger, args, opts, options, orgId, region, config, auth } = ctx;
+
+		const catalystClient = getCatalystAPIClient(config, logger, auth);
+
+		const resources = await tui.spinner({
+			message: `Fetching database ${args.name}`,
+			clearOnSuccess: true,
+			callback: async () => {
+				return listResources(catalystClient, orgId, region);
+			},
+		});
+
+		const db = resources.db.find((d) => d.name === args.name);
+
+		if (!db) {
+			tui.fatal(`Database '${args.name}' not found`, ErrorCode.RESOURCE_NOT_FOUND);
+		}
+
+		// Mask credentials in terminal output by default, unless --show-credentials is passed
+		const shouldShowCredentials = opts.showCredentials === true;
+		const shouldMask = !options.json && !shouldShowCredentials;
+
+		if (!options.json) {
+			console.log(tui.bold('Name: ') + db.name);
+			if (db.url) {
+				const displayUrl = shouldMask ? tui.maskSecret(db.url) : db.url;
+				console.log(tui.bold('URL:  ') + displayUrl);
+			}
+		}
+
+		return {
+			name: db.name,
+			url: db.url ?? undefined,
+		};
+	},
+});

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

@@ -0,0 +1,19 @@
+import { createCommand } from '../../../types';
+import { createSubcommand } from './create';
+import { listSubcommand } from './list';
+import { deleteSubcommand } from './delete';
+import { getSubcommand } from './get';
+import { sqlSubcommand } from './sql';
+import { getCommand } from '../../../command-prefix';
+
+export const dbCommand = createCommand({
+	name: 'db',
+	aliases: ['database'],
+	description: 'Manage database resources',
+	tags: ['slow', 'requires-auth', 'requires-deployment'],
+	examples: [
+		{ command: getCommand('cloud db list'), description: 'List all databases' },
+		{ command: getCommand('cloud db sql "SELECT * FROM users"'), description: 'Run SQL query' },
+	],
+	subcommands: [createSubcommand, listSubcommand, getSubcommand, deleteSubcommand, sqlSubcommand],
+});

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

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import { listResources } from '@agentuity/server';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { getCatalystAPIClient } from '../../../config';
+import { getCommand } from '../../../command-prefix';
+
+const DBListResponseSchema = z.object({
+	databases: z
+		.array(
+			z.object({
+				name: z.string().describe('Database name'),
+				url: z.string().optional().describe('Database connection URL'),
+			})
+		)
+		.describe('List of database resources'),
+});
+
+export const listSubcommand = createSubcommand({
+	name: 'list',
+	aliases: ['ls'],
+	description: 'List database resources',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true, org: true, region: true },
+	idempotent: true,
+	examples: [
+		{ command: getCommand('cloud db list'), description: 'List items' },
+		{ command: getCommand('--json cloud db list'), description: 'Show output in JSON format' },
+		{ command: getCommand('cloud db ls'), description: 'List items' },
+		{
+			command: getCommand('cloud db list --show-credentials'),
+			description: 'Use show credentials option',
+		},
+	],
+	schema: {
+		options: z.object({
+			showCredentials: z
+				.boolean()
+				.optional()
+				.describe(
+					'Show credentials in plain text (default: masked in terminal, unmasked in JSON)'
+				),
+			nameOnly: z.boolean().optional().describe('Print the name only'),
+		}),
+		response: DBListResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { logger, opts, options, orgId, region, config, auth } = ctx;
+
+		const catalystClient = getCatalystAPIClient(config, logger, auth);
+
+		const resources = await tui.spinner({
+			message: `Fetching databases for ${orgId} in ${region}`,
+			clearOnSuccess: true,
+			callback: async () => {
+				return listResources(catalystClient, orgId, region);
+			},
+		});
+
+		// Mask credentials in terminal output by default, unless --show-credentials is passed
+		const shouldShowCredentials = opts.showCredentials === true;
+		const shouldMask = !options.json && !shouldShowCredentials;
+
+		if (!options.json) {
+			if (resources.db.length === 0) {
+				tui.info('No databases found');
+			} else {
+				if (!opts.nameOnly) {
+					tui.info(tui.bold('Databases'));
+					tui.newline();
+				}
+				for (const db of resources.db) {
+					if (opts.nameOnly) {
+						console.log(db.name);
+						continue;
+					}
+					console.log(tui.bold(db.name));
+					if (db.url) {
+						const displayUrl = shouldMask ? tui.maskSecret(db.url) : db.url;
+						console.log(` URL: ${tui.muted(displayUrl)}`);
+					}
+					tui.newline();
+				}
+			}
+		}
+
+		return {
+			databases: resources.db.map((db) => ({
+				name: db.name,
+				url: db.url ?? undefined,
+			})),
+		};
+	},
+});

package/src/cmd/cloud/db/sql.ts

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+import { SQL } from 'bun';
+import { listResources, type ResourceList } from '@agentuity/server';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { getCatalystAPIClient } from '../../../config';
+import { getCommand } from '../../../command-prefix';
+import { ErrorCode } from '../../../errors';
+
+interface DatabaseResource {
+	name: string;
+	username?: string | null;
+	password?: string | null;
+	url?: string | null;
+}
+
+const DBSQLResponseSchema = z.object({
+	rows: z.array(z.record(z.string(), z.unknown())).describe('Query results'),
+	rowCount: z.number().describe('Number of rows returned'),
+	executionTime: z.number().optional().describe('Query execution time in ms'),
+});
+
+export const sqlSubcommand = createSubcommand({
+	name: 'sql',
+	aliases: ['exec', 'query'],
+	description: 'Execute SQL query on a database',
+	tags: ['slow', 'requires-auth'],
+	requires: { auth: true, org: true, region: true },
+	idempotent: false,
+	examples: [
+		{
+			command: `${getCommand('cloud db sql')} my-database "SELECT * FROM users LIMIT 10"`,
+			description: 'Execute SQL query',
+		},
+		{
+			command: `${getCommand('cloud db exec')} my-database "SELECT COUNT(*) FROM orders" --json`,
+			description: 'Execute query with JSON output',
+		},
+		{
+			command: `${getCommand('cloud db query')} my-database "SELECT * FROM products WHERE price > 100"`,
+			description: 'Query with filter',
+		},
+	],
+	schema: {
+		args: z.object({
+			name: z.string().describe('Database name'),
+			query: z.string().describe('SQL query to execute'),
+		}),
+		options: z.object({}),
+		response: DBSQLResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { logger, args, options, orgId, region, config, auth } = ctx;
+
+		const catalystClient = getCatalystAPIClient(config, logger, auth);
+
+		const resources: ResourceList = await tui.spinner({
+			message: `Fetching database ${args.name}`,
+			clearOnSuccess: true,
+			callback: async () => {
+				return listResources(catalystClient, orgId, region);
+			},
+		});
+
+		const db: DatabaseResource | undefined = resources.db.find(
+			(d: DatabaseResource) => d.name === args.name
+		);
+
+		if (!db) {
+			tui.fatal(`Database '${args.name}' not found`, ErrorCode.RESOURCE_NOT_FOUND);
+		}
+
+		if (!db.url) {
+			tui.fatal(`Database '${args.name}' has no connection URL`, ErrorCode.RUNTIME_ERROR);
+		}
+
+		let database: SQL | undefined;
+		let rows: Record<string, unknown>[];
+		let executionTime: number | undefined;
+
+		try {
+			// Add sslmode=require if not already present in URL
+			let connectionUrl = db.url;
+			if (!connectionUrl.includes('sslmode=') && !connectionUrl.includes('ssl=')) {
+				const separator = connectionUrl.includes('?') ? '&' : '?';
+				connectionUrl = `${connectionUrl}${separator}sslmode=require`;
+			}
+
+			database = new SQL(connectionUrl);
+
+			const startTime = performance.now();
+			const result = await tui.spinner({
+				message: `Executing query on ${args.name}`,
+				clearOnSuccess: true,
+				callback: async () => {
+					return database!.unsafe(args.query);
+				},
+			});
+			executionTime = performance.now() - startTime;
+
+			rows = result;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			tui.fatal(`Query execution failed: ${message}`, ErrorCode.RUNTIME_ERROR);
+		} finally {
+			if (database) {
+				await database.close();
+			}
+		}
+
+		if (!options.json) {
+			if (rows.length === 0) {
+				tui.info('No rows returned');
+			} else {
+				if (process.stdout.isTTY) {
+					tui.newline();
+					tui.success(
+						`Query returned ${rows.length} row${rows.length !== 1 ? 's' : ''} (${executionTime?.toFixed(2)}ms):`
+					);
+					tui.newline();
+				}
+
+				tui.table(rows);
+			}
+		}
+
+		return {
+			rows,
+			rowCount: rows.length,
+			executionTime,
+		};
+	},
+});

package/src/cmd/cloud/deploy.ts

@@ -57,9 +57,15 @@ export const deploySubcommand = createSubcommand({
 		'requires-project',
 	],
 	examples: [
-		`${getCommand('cloud deploy')}                    # Deploy current project`,
-		`${getCommand('cloud deploy')} --log-level=debug  # Deploy with verbose output`,
-		`${getCommand('cloud deploy')} --tag a --tag b    # Deploy with specific tags`,
+		{ command: getCommand('cloud deploy'), description: 'Deploy current project' },
+		{
+			command: getCommand('cloud deploy --log-level=debug'),
+			description: 'Deploy with verbose output',
+		},
+		{
+			command: getCommand('cloud deploy --tag a --tag b'),
+			description: 'Deploy with specific tags',
+		},
 	],
 	toplevel: true,
 	idempotent: false,

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

@@ -5,12 +5,17 @@ import { showSubcommand } from './show';
 import { removeSubcommand } from './remove';
 import { rollbackSubcommand } from './rollback';
 import { undeploySubcommand } from './undeploy';
+import { getCommand } from '../../../command-prefix';
 
 export const deploymentCommand = createCommand({
 	name: 'deployment',
 	description: 'Manage deployments',
 	tags: ['read-only', 'fast', 'requires-auth'],
 	aliases: ['deployments', 'dep'],
+	examples: [
+		{ command: getCommand('cloud deployment list'), description: 'List all deployments' },
+		{ command: getCommand('cloud deployment logs <id>'), description: 'Show deployment logs' },
+	],
 	subcommands: [
 		listSubcommand,
 		logsSubcommand,

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

@@ -22,9 +22,18 @@ export const listSubcommand = createSubcommand({
 	description: 'List deployments',
 	tags: ['read-only', 'slow', 'requires-auth'],
 	examples: [
-		`${getCommand('cloud deployment list')}           # List 10 most recent deployments`,
-		`${getCommand('cloud deployment list')} --count=25 # List 25 most recent deployments`,
-		`${getCommand('cloud deployment list')} --project-id=proj_abc123xyz`,
+		{
+			command: getCommand('cloud deployment list'),
+			description: 'List 10 most recent deployments',
+		},
+		{
+			command: getCommand('cloud deployment list --count=25'),
+			description: 'List 25 most recent deployments',
+		},
+		{
+			command: getCommand('cloud deployment list --project-id=proj_abc123xyz'),
+			description: 'List deployments for specific project',
+		},
 	],
 	aliases: ['ls'],
 	requires: { auth: true, apiClient: true },

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

@@ -12,10 +12,22 @@ export const logsSubcommand = createSubcommand({
 	description: 'View logs for a specific deployment',
 	tags: ['read-only', 'fast', 'requires-auth', 'requires-deployment'],
 	examples: [
-		`${getCommand('cloud deployment logs')} deploy_abc123xyz`,
-		`${getCommand('cloud deployment logs')} deploy_abc123xyz --limit=50`,
-		`${getCommand('cloud deployment logs')} deploy_abc123xyz --no-timestamps  # hide timestamps`,
-		`${getCommand('cloud deployment logs')} deploy_abc123xyz --project-id=proj_abc123xyz`,
+		{
+			command: getCommand('cloud deployment logs deploy_abc123xyz'),
+			description: 'View logs for deployment',
+		},
+		{
+			command: getCommand('cloud deployment logs deploy_abc123xyz --limit=50'),
+			description: 'Limit to 50 log entries',
+		},
+		{
+			command: getCommand('cloud deployment logs deploy_abc123xyz --no-timestamps'),
+			description: 'Hide timestamps',
+		},
+		{
+			command: getCommand('cloud deployment logs deploy_abc123xyz --project-id=proj_abc123xyz'),
+			description: 'View logs with specific project',
+		},
 	],
 	requires: { auth: true, apiClient: true },
 	optional: { project: true },

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

@@ -4,7 +4,6 @@ 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'),
@@ -16,9 +15,20 @@ export const removeSubcommand = createSubcommand({
 	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`,
+		{
+			command: getCommand('cloud deployment remove dep_abc123xyz'),
+			description: 'Remove with confirmation',
+		},
+		{
+			command: getCommand('cloud deployment remove dep_abc123xyz --force'),
+			description: 'Remove without confirmation',
+		},
+		{
+			command: getCommand(
+				'cloud deployment remove deployment-2024-11-20 --project-id=proj_abc123xyz'
+			),
+			description: 'Remove deployment from specific project',
+		},
 	],
 	aliases: ['rm', 'delete'],
 	idempotent: false,

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

@@ -4,7 +4,6 @@ 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'),
@@ -24,8 +23,14 @@ export const rollbackSubcommand = createSubcommand({
 		'requires-deployment',
 	],
 	examples: [
-		`${getCommand('cloud deployment rollback')}                   # Rollback to previous deployment`,
-		`${getCommand('cloud deployment rollback')} --project-id=proj_abc123xyz`,
+		{
+			command: getCommand('cloud deployment rollback'),
+			description: 'Rollback to previous deployment',
+		},
+		{
+			command: getCommand('cloud deployment rollback --project-id=proj_abc123xyz'),
+			description: 'Rollback specific project',
+		},
 	],
 	idempotent: false,
 	requires: { auth: true, apiClient: true },

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

@@ -55,8 +55,14 @@ export const showSubcommand = createSubcommand({
 	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`,
+		{
+			command: `${getCommand('cloud deployment show')} dep_abc123xyz`,
+			description: 'Show deployment details by ID',
+		},
+		{
+			command: `${getCommand('cloud deployment show')} deployment-2024-11-20 --project-id=proj_abc123xyz`,
+			description: 'Show deployment for specific project',
+		},
 	],
 	aliases: ['get'],
 	requires: { auth: true, apiClient: true },

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

@@ -4,15 +4,23 @@ 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`,
+		{
+			command: getCommand('cloud deployment undeploy'),
+			description: 'Undeploy with confirmation',
+		},
+		{
+			command: getCommand('cloud deployment undeploy --force'),
+			description: 'Undeploy without confirmation',
+		},
+		{
+			command: getCommand('cloud deployment undeploy --project-id=proj_abc123xyz'),
+			description: 'Undeploy specific project',
+		},
 	],
 	idempotent: false,
 	requires: { auth: true, apiClient: true },

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

@@ -1,5 +1,11 @@
+import { StructuredError } from '@agentuity/core';
 import { ProjectConfig } from '../../../types';
 
+const ProjectIDRequiredError = StructuredError(
+	'ProjectIDRequiredError',
+	'Project ID is required. Use --project-id or run from a project directory.'
+);
+
 export function resolveProjectId(
 	ctx: { project?: ProjectConfig },
 	options: { projectId?: string }
@@ -10,5 +16,5 @@ export function resolveProjectId(
 	if (ctx.project?.projectId) {
 		return ctx.project.projectId;
 	}
-	throw new Error('Project ID is required. Use --project-id or run from a project directory.');
+	throw new ProjectIDRequiredError();
 }