@agentuity/cli 0.0.48 → 0.0.50

package/src/cmd/bundle/index.ts

@@ -2,16 +2,29 @@ import { createCommand } from '../../types';
 import { z } from 'zod';
 import { bundle } from './bundler';
 import * as tui from '../../tui';
+import { getCommand } from '../../command-prefix';
+
+const BundleResponseSchema = z.object({
+	success: z.boolean().describe('Whether the bundle succeeded'),
+	bundlePath: z.string().describe('Path to the bundle directory'),
+	projectName: z.string().describe('Project name'),
+	dev: z.boolean().describe('Whether dev mode was enabled'),
+	size: z.number().optional().describe('Bundle size in bytes'),
+});
 
 export const command = createCommand({
 	name: 'bundle',
 	description: 'Bundle Agentuity application for deployment',
+	tags: ['read-only', 'slow', 'requires-project'],
 	aliases: ['build'],
 	optional: { project: true },
+	idempotent: false,
+	examples: [getCommand('bundle'), getCommand('bundle --dev'), getCommand('build')],
 	schema: {
 		options: z.object({
 			dev: z.boolean().optional().describe('Enable development mode'),
 		}),
+		response: BundleResponseSchema,
 	},
 
 	async handler(ctx) {
@@ -27,6 +40,13 @@ export const command = createCommand({
 			});
 
 			tui.success('Bundle complete');
+
+			return {
+				success: true,
+				bundlePath: `${projectDir}/.agentuity`,
+				projectName: project?.projectId || 'unknown',
+				dev: opts.dev || false,
+			};
 		} catch (error) {
 			if (error instanceof Error) {
 				tui.fatal(`Bundle failed: ${error.message}`);

package/src/cmd/bundle/plugin.ts

@@ -266,7 +266,7 @@ const AgentuityBundler: BunPlugin = {
 			string,
 			Map<string, string>
 		>();
-		const transpiler = new Bun.Transpiler({ loader: 'ts' });
+		const transpiler = new Bun.Transpiler({ loader: 'ts', target: 'bun' });
 		let routeDefinitions: BuildMetadata['routes'] = [];
 
 		build.onResolve({ filter: /\/route\.ts$/, namespace: 'file' }, async (args) => {
@@ -312,6 +312,16 @@ const AgentuityBundler: BunPlugin = {
 					md.set('parent', parentName);
 				}
 
+				const newAgentName = md.get('name');
+				for (const [, kv] of agentMetadata) {
+					const found = kv.get('name');
+					if (newAgentName === found) {
+						throw new Error(
+							`The agent in ${kv.get('filename')} and the agent in ${md.get('filename')} have the same name (${found}). Agent Names must be unique within a project.`
+						);
+					}
+				}
+
 				agentMetadata.set(md.get('identifier')!, md);
 			}
 			return {
@@ -413,6 +423,7 @@ const AgentuityBundler: BunPlugin = {
 							filename: md.get('filename')!,
 							identifier: md.get('identifier')!,
 							description: md.get('description') ?? '',
+							agentId: md.get('agentId')!,
 						};
 						if (isSubagent && parentName) {
 							agentDetail.parent = parentName;
@@ -473,20 +484,31 @@ const AgentuityBundler: BunPlugin = {
 					generateAgentRegistry(srcDir, agentInfo);
 				}
 
+				// create the workbench routes
+				inserts.push(`await (async() => {
+    const { createWorkbenchMetadataRoute, getRouter } = await import('@agentuity/runtime');
+    const router = getRouter()!;
+	router.get('/_agentuity/workbench/metadata.json', createWorkbenchMetadataRoute());
+})();`);
+
 				const file = Bun.file(args.path);
 				let contents = await file.text();
 				let inserted = false;
-				const index = contents.indexOf(' createApp(');
-				if (index > 0) {
-					const endSemi = contents.indexOf(');', index);
-					if (endSemi > 0) {
-						contents =
-							contents.slice(0, endSemi + 2) +
-							'\n\n' +
-							inserts.join('\n') +
-							contents.slice(endSemi + 2);
-						inserted = true;
-					}
+				let index = contents.indexOf(' createApp(');
+				if (index < 0) {
+					index = contents.indexOf(' createApp (');
+				}
+				if (index < 0) {
+					throw new Error(`couldn't find the required createApp function in ${args.path}`);
+				}
+				const endSemi = contents.indexOf(');', index);
+				if (endSemi > 0) {
+					contents =
+						contents.slice(0, endSemi + 2) +
+						'\n\n' +
+						inserts.join('\n') +
+						contents.slice(endSemi + 2);
+					inserted = true;
 				}
 				if (!inserted) {
 					contents += `\n${inserts.join('\n')}`;
@@ -552,9 +574,11 @@ const AgentuityBundler: BunPlugin = {
 						filename: v.get('filename')!,
 						id: v.get('id')!,
 						identifier: v.get('identifier')!,
+						agentId: v.get('agentId')!,
 						version: v.get('version')!,
 						name: v.get('name')!,
 						description: v.get('description') ?? '<no description provided>',
+						projectId,
 					};
 
 					const evalsStr = v.get('evals');
@@ -563,7 +587,17 @@ const AgentuityBundler: BunPlugin = {
 							`[plugin] Found evals string for agent ${agentData.name}, parsing...`
 						);
 						try {
-							agentData.evals = JSON.parse(evalsStr);
+							const parsedEvals = JSON.parse(evalsStr) as Array<
+								Omit<
+									NonNullable<BuildMetadata['agents'][number]['evals']>[number],
+									'agentIdentifier' | 'projectId'
+								>
+							>;
+							agentData.evals = parsedEvals.map((evalItem) => ({
+								...evalItem,
+								agentIdentifier: agentData.agentId,
+								projectId,
+							}));
 							logger.trace(
 								`[plugin] Successfully parsed ${agentData.evals?.length ?? 0} eval(s) for agent ${agentData.name}`
 							);
@@ -587,9 +621,11 @@ const AgentuityBundler: BunPlugin = {
 								filename: sub.get('filename')!,
 								id: sub.get('id')!,
 								identifier: sub.get('identifier')!,
+								agentId: sub.get('agentId')!,
 								version: sub.get('version')!,
 								name: sub.get('name')!,
 								description: sub.get('description') ?? '<no description provided>',
+								projectId,
 							};
 
 							// Add evals for subagents if any
@@ -599,7 +635,17 @@ const AgentuityBundler: BunPlugin = {
 									`[plugin] Found evals string for subagent ${subagentData.name}, parsing...`
 								);
 								try {
-									subagentData.evals = JSON.parse(subEvalsStr);
+									const parsedSubEvals = JSON.parse(subEvalsStr) as Array<
+										Omit<
+											NonNullable<BuildMetadata['agents'][number]['evals']>[number],
+											'agentIdentifier' | 'projectId'
+										>
+									>;
+									subagentData.evals = parsedSubEvals.map((evalItem) => ({
+										...evalItem,
+										agentIdentifier: subagentData.agentId,
+										projectId,
+									}));
 									logger.trace(
 										`[plugin] Successfully parsed ${subagentData.evals?.length ?? 0} eval(s) for subagent ${subagentData.name}`
 									);

package/src/cmd/capabilities/index.ts

@@ -0,0 +1,12 @@
+import type { CommandDefinition } from '../../types';
+import { createCommand } from '../../types';
+import { showSubcommand } from './show';
+
+export const capabilitiesCommand: CommandDefinition = createCommand({
+	name: 'capabilities',
+	description: 'Show CLI capabilities and available tasks',
+	tags: ['read-only', 'fast'],
+	subcommands: [showSubcommand],
+});
+
+export default capabilitiesCommand;

package/src/cmd/capabilities/show.ts

@@ -0,0 +1,256 @@
+import { createSubcommand } from '../../types';
+import type { CommandContext } from '../../types';
+import * as tui from '../../tui';
+import { getCommand } from '../../command-prefix';
+import { z } from 'zod';
+
+export interface Capability {
+	id: string;
+	name: string;
+	description: string;
+	commands: string[];
+	requiresAuth?: boolean;
+	requiresProject?: boolean;
+}
+
+export interface CapabilitiesResponse {
+	version: string;
+	capabilities: Capability[];
+	workflows: Array<{
+		name: string;
+		description: string;
+		steps: string[];
+	}>;
+}
+
+const CapabilitiesShowResponseSchema = z.object({
+	version: z.string().describe('CLI capabilities version'),
+	capabilities: z
+		.array(
+			z.object({
+				id: z.string().describe('Capability ID'),
+				name: z.string().describe('Capability name'),
+				description: z.string().describe('Description'),
+				commands: z.array(z.string()).describe('Available commands'),
+				requiresAuth: z.boolean().optional().describe('Requires authentication'),
+				requiresProject: z.boolean().optional().describe('Requires project'),
+			})
+		)
+		.describe('Available capabilities'),
+	workflows: z
+		.array(
+			z.object({
+				name: z.string().describe('Workflow name'),
+				description: z.string().describe('Workflow description'),
+				steps: z.array(z.string()).describe('Workflow steps'),
+			})
+		)
+		.describe('Common workflows'),
+});
+
+export const showSubcommand = createSubcommand({
+	name: 'show',
+	description: 'Display CLI capabilities',
+	tags: ['read-only', 'fast'],
+	examples: [getCommand('capabilities show'), getCommand('--json capabilities show')],
+	schema: {
+		response: CapabilitiesShowResponseSchema,
+	},
+	idempotent: true,
+	async handler(ctx: CommandContext) {
+		const { options } = ctx;
+
+		const capabilities: CapabilitiesResponse = {
+			version: '1.0.0',
+			capabilities: [
+				{
+					id: 'auth',
+					name: 'Authentication',
+					description: 'Login, logout, and manage API keys',
+					commands: ['auth login', 'auth logout', 'auth whoami', 'auth signup'],
+					requiresAuth: false,
+				},
+				{
+					id: 'ssh',
+					name: 'SSH Key Management',
+					description: 'Manage SSH keys for secure access',
+					commands: ['auth ssh list', 'auth ssh add', 'auth ssh delete'],
+					requiresAuth: true,
+				},
+				{
+					id: 'project',
+					name: 'Project Management',
+					description: 'Create, list, and manage projects',
+					commands: [
+						'project init',
+						'project list',
+						'project show',
+						'project download',
+						'project update',
+						'project delete',
+					],
+					requiresAuth: true,
+				},
+				{
+					id: 'deployment',
+					name: 'Deployment',
+					description: 'Deploy and manage applications',
+					commands: [
+						'bundle',
+						'cloud deploy',
+						'cloud deployment list',
+						'cloud deployment show',
+						'cloud deployment logs',
+						'cloud deployment rollback',
+					],
+					requiresAuth: true,
+					requiresProject: true,
+				},
+				{
+					id: 'secrets',
+					name: 'Secrets Management',
+					description: 'Store and retrieve secrets securely',
+					commands: ['secret list', 'secret set', 'secret get', 'secret delete'],
+					requiresAuth: true,
+					requiresProject: true,
+				},
+				{
+					id: 'env',
+					name: 'Environment Variables',
+					description: 'Manage environment variables',
+					commands: ['env list', 'env set', 'env get', 'env delete'],
+					requiresAuth: true,
+					requiresProject: true,
+				},
+				{
+					id: 'kv',
+					name: 'Key-Value Storage',
+					description: 'Store and retrieve key-value data',
+					commands: ['kv list', 'kv get', 'kv set', 'kv delete', 'kv stats'],
+					requiresAuth: true,
+					requiresProject: true,
+				},
+				{
+					id: 'objectstore',
+					name: 'Object Storage',
+					description: 'Manage object storage buckets and files',
+					commands: [
+						'objectstore list',
+						'objectstore upload',
+						'objectstore download',
+						'objectstore delete',
+					],
+					requiresAuth: true,
+					requiresProject: true,
+				},
+				{
+					id: 'resources',
+					name: 'Cloud Resources',
+					description: 'View and manage cloud resources',
+					commands: ['cloud resource list'],
+					requiresAuth: true,
+				},
+				{
+					id: 'config',
+					name: 'Configuration',
+					description: 'Manage CLI profiles and configuration',
+					commands: [
+						'profile list',
+						'profile create',
+						'profile delete',
+						'profile show',
+						'profile switch',
+					],
+				},
+				{
+					id: 'dev',
+					name: 'Development',
+					description: 'Local development server and REPL',
+					commands: ['dev', 'repl'],
+					requiresProject: true,
+				},
+				{
+					id: 'introspection',
+					name: 'CLI Introspection',
+					description: 'Discover CLI structure and capabilities',
+					commands: ['schema show', 'capabilities show', 'version'],
+				},
+			],
+			workflows: [
+				{
+					name: 'Initial Setup',
+					description: 'Get started with Agentuity',
+					steps: [
+						'auth signup',
+						'auth login',
+						'project init',
+						'secret set API_KEY <value>',
+						'dev',
+					],
+				},
+				{
+					name: 'Deploy Application',
+					description: 'Deploy your application to the cloud',
+					steps: ['bundle', 'cloud deploy', 'cloud deployment logs', 'cloud deployment show'],
+				},
+				{
+					name: 'Manage Secrets',
+					description: 'Configure application secrets',
+					steps: ['secret list', 'secret set <key> <value>', 'secret get <key>'],
+				},
+				{
+					name: 'SSH Key Setup',
+					description: 'Add SSH keys for secure access',
+					steps: ['auth ssh list', 'auth ssh add --file ~/.ssh/id_rsa.pub'],
+				},
+			],
+		};
+
+		if (options.json) {
+			console.log(JSON.stringify(capabilities, null, 2));
+		} else {
+			// Human-readable output
+			console.log(tui.bold('Agentuity CLI Capabilities'));
+			tui.newline();
+
+			console.log(tui.bold('Available Tasks:'));
+			tui.newline();
+
+			for (const cap of capabilities.capabilities) {
+				console.log(`  ${tui.bold(cap.name)}`);
+				console.log(`    ${cap.description}`);
+
+				const requirements: string[] = [];
+				if (cap.requiresAuth) requirements.push('requires authentication');
+				if (cap.requiresProject) requirements.push('requires project');
+				if (requirements.length > 0) {
+					console.log(`    ${tui.muted(`(${requirements.join(', ')})`)}`);
+				}
+
+				console.log(
+					`    ${tui.muted(`Commands: ${cap.commands.slice(0, 3).join(', ')}${cap.commands.length > 3 ? '...' : ''}`)}`
+				);
+				tui.newline();
+			}
+
+			console.log(tui.bold('Common Workflows:'));
+			tui.newline();
+
+			for (const workflow of capabilities.workflows) {
+				console.log(`  ${tui.bold(workflow.name)}`);
+				console.log(`    ${workflow.description}`);
+				console.log(`    ${tui.muted('Steps:')}`);
+				for (let i = 0; i < workflow.steps.length; i++) {
+					console.log(`      ${i + 1}. ${workflow.steps[i]}`);
+				}
+				tui.newline();
+			}
+
+			console.log(tui.muted('Tip: Use --json for machine-readable output'));
+		}
+
+		return capabilities;
+	},
+});
+
+export default showSubcommand;

package/src/cmd/cloud/deploy.ts

@@ -27,12 +27,45 @@ import {
 import { zipDir } from '../../utils/zip';
 import { encryptFIPSKEMDEMStream } from '../../crypto/box';
 import { checkCustomDomainForDNS } from './domain';
+import { getCommand } from '../../command-prefix';
+import { z } from 'zod';
+
+const DeployResponseSchema = z.object({
+	success: z.boolean().describe('Whether deployment succeeded'),
+	deploymentId: z.string().describe('Deployment ID'),
+	projectId: z.string().describe('Project ID'),
+	urls: z
+		.object({
+			deployment: z.string().describe('Deployment-specific URL'),
+			latest: z.string().describe('Latest/active deployment URL'),
+			custom: z.array(z.string()).optional().describe('Custom domain URLs'),
+		})
+		.optional()
+		.describe('Deployment URLs'),
+});
 
 export const deploySubcommand = createSubcommand({
 	name: 'deploy',
 	description: 'Deploy project to the Agentuity Cloud',
+	tags: [
+		'mutating',
+		'creates-resource',
+		'slow',
+		'api-intensive',
+		'requires-auth',
+		'requires-project',
+	],
+	examples: [
+		`${getCommand('cloud deploy')}                    # Deploy current project`,
+		`${getCommand('cloud deploy')} --log-level=debug  # Deploy with verbose output`,
+	],
 	toplevel: true,
+	idempotent: false,
 	requires: { auth: true, project: true, apiClient: true },
+	prerequisites: ['auth login'],
+	schema: {
+		response: DeployResponseSchema,
+	},
 
 	async handler(ctx) {
 		const { project, apiClient, projectDir, config, options } = ctx;
@@ -335,6 +368,27 @@ export const deploySubcommand = createSubcommand({
 					);
 				}
 			}
+
+			// Return deployment result (if available)
+			if (deployment && complete?.publicUrls) {
+				return {
+					success: true,
+					deploymentId: deployment.id,
+					projectId: project.projectId,
+					urls: {
+						deployment: complete.publicUrls.deployment,
+						latest: complete.publicUrls.latest,
+						custom: complete.publicUrls.custom,
+					},
+				};
+			}
+
+			// Fallback response
+			return {
+				success: false,
+				deploymentId: '',
+				projectId: project.projectId,
+			};
 		} catch (ex) {
 			tui.fatal(`unexpected error trying to deploy project. ${ex}`);
 		}

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

@@ -8,6 +8,7 @@ import { undeploySubcommand } from './undeploy';
 export const deploymentCommand = createCommand({
 	name: 'deployment',
 	description: 'Manage deployments',
+	tags: ['read-only', 'fast', 'requires-auth'],
 	aliases: ['deployments', 'dep'],
 	subcommands: [
 		listSubcommand,

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

@@ -3,19 +3,53 @@ import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { projectDeploymentList } from '@agentuity/server';
 import { resolveProjectId } from './utils';
-import { Table } from 'console-table-printer';
+import { getCommand } from '../../../command-prefix';
+import { ErrorCode } from '../../../errors';
+
+const DeploymentListResponseSchema = z.array(
+	z.object({
+		id: z.string().describe('Deployment ID'),
+		state: z.string().optional().describe('Current state of the deployment'),
+		active: z.boolean().describe('Whether this is the active deployment'),
+		createdAt: z.string().describe('Creation timestamp'),
+		message: z.string().optional().describe('Deployment message or description'),
+		tags: z.array(z.string()).describe('Deployment tags'),
+	})
+);
 
 export const listSubcommand = createSubcommand({
 	name: 'list',
 	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`,
+	],
 	aliases: ['ls'],
 	requires: { auth: true, apiClient: true },
 	optional: { project: true },
+	idempotent: true,
+	pagination: {
+		supported: true,
+		defaultLimit: 10,
+		maxLimit: 100,
+		parameters: {
+			limit: 'count',
+		},
+	},
 	schema: {
 		options: z.object({
 			'project-id': z.string().optional().describe('Project ID'),
-			count: z.coerce.number().default(10).describe('Number of deployments to list'),
+			count: z.coerce
+				.number()
+				.int()
+				.min(1)
+				.max(100)
+				.default(10)
+				.describe('Number of deployments to list (1–100)'),
 		}),
+		response: DeploymentListResponseSchema,
 	},
 	async handler(ctx) {
 		const projectId = resolveProjectId(ctx, { projectId: ctx.opts['project-id'] });
@@ -26,33 +60,40 @@ export const listSubcommand = createSubcommand({
 
 			if (deployments.length === 0) {
 				tui.info('No deployments found.');
-				return;
+				return [];
 			}
 
-			const table = new Table({
-				columns: [
-					{ name: 'ID', alignment: 'left' },
-					{ name: 'State', alignment: 'left' },
-					{ name: 'Active', alignment: 'center' },
-					{ name: 'Created', alignment: 'left' },
-					{ name: 'Message', alignment: 'left' },
-					{ name: 'Tags', alignment: 'left' },
-				],
-			});
+			const tableData = deployments.map((d) => ({
+				ID: d.id,
+				State: d.state || 'unknown',
+				Active: d.active ? 'Yes' : '',
+				Created: new Date(d.createdAt).toLocaleString(),
+				Message: d.message || '',
+				Tags: d.tags.join(', '),
+			}));
 
-			for (const d of deployments) {
-				table.addRow({
-					ID: d.id,
-					State: d.state || 'unknown',
-					Active: d.active ? 'Yes' : '',
-					Created: new Date(d.createdAt).toLocaleString(),
-					Message: d.message || '',
-					Tags: d.tags.join(', '),
-				});
-			}
-			table.printTable();
+			tui.table(tableData, [
+				{ name: 'ID', alignment: 'left' },
+				{ name: 'State', alignment: 'left' },
+				{ name: 'Active', alignment: 'center' },
+				{ name: 'Created', alignment: 'left' },
+				{ name: 'Message', alignment: 'left' },
+				{ name: 'Tags', alignment: 'left' },
+			]);
+
+			return deployments.map((d) => ({
+				id: d.id,
+				state: d.state,
+				active: d.active,
+				createdAt: d.createdAt,
+				message: d.message,
+				tags: d.tags,
+			}));
 		} catch (ex) {
-			tui.fatal(`Failed to list deployments: ${ex instanceof Error ? ex.message : String(ex)}`);
+			tui.fatal(
+				`Failed to list deployments: ${ex instanceof Error ? ex.message : String(ex)}`,
+				ErrorCode.API_ERROR
+			);
 		}
 	},
 });