@agentuity/cli 0.0.48 → 0.0.49

package/src/cmd/auth/ssh/list.ts

@@ -1,40 +1,56 @@
 import { createSubcommand } from '../../../types';
 import { listSSHKeys } from './api';
 import * as tui from '../../../tui';
-import { z } from 'zod';
 import { Table } from 'console-table-printer';
+import { getCommand } from '../../../command-prefix';
+import { ErrorCode } from '../../../errors';
+import { z } from 'zod';
+
+const SSHListResponseSchema = z.array(
+	z.object({
+		id: z.string().describe('SSH key ID'),
+		fingerprint: z.string().describe('SSH key fingerprint'),
+		keyType: z.string().describe('SSH key type (e.g., ssh-rsa, ssh-ed25519)'),
+		comment: z.string().optional().describe('SSH key comment'),
+		createdAt: z.string().optional().describe('Creation timestamp'),
+	})
+);
 
 export const listCommand = createSubcommand({
 	name: 'list',
 	aliases: ['ls'],
 	description: 'List all SSH keys on your account',
+	tags: ['read-only', 'fast', 'requires-auth'],
 	requires: { apiClient: true, auth: true },
+	idempotent: true,
+	examples: [
+		getCommand('auth ssh list'),
+		getCommand('auth ssh ls'),
+		getCommand('--json auth ssh list'),
+	],
 	schema: {
-		options: z.object({
-			format: z.enum(['text', 'json']).default('text').describe('output format'),
-		}),
+		response: SSHListResponseSchema,
 	},
 	async handler(ctx) {
-		const { logger, apiClient, opts } = ctx;
-		const format = opts.format;
+		const { logger, apiClient, options } = ctx;
 
 		if (!apiClient) {
-			logger.fatal('API client is not available');
+			logger.fatal('API client is not available', ErrorCode.INTERNAL_ERROR);
 		}
 
 		try {
 			const keys = await tui.spinner('Fetching SSH keys...', () => listSSHKeys(apiClient));
 
-			if (format === 'json') {
+			if (options.json) {
 				console.log(JSON.stringify(keys, null, 2));
-				return;
+				return keys;
 			}
 
 			tui.newline();
 
 			if (keys.length === 0) {
 				console.log('No SSH keys found');
-				return;
+				return [];
 			}
 
 			console.log(tui.bold('SSH Keys:'));
@@ -57,12 +73,13 @@ export const listCommand = createSubcommand({
 			}
 			table.printTable();
 
+			return keys;
 		} catch (error) {
 			logger.trace(error);
 			if (error instanceof Error) {
-				logger.fatal(`Failed to list SSH keys: ${error.message}`);
+				logger.fatal(`Failed to list SSH keys: ${error.message}`, ErrorCode.API_ERROR);
 			} else {
-				logger.fatal('Failed to list SSH keys');
+				logger.fatal('Failed to list SSH keys', ErrorCode.API_ERROR);
 			}
 		}
 	},

package/src/cmd/auth/whoami.ts

@@ -1,23 +1,36 @@
-import { z } from 'zod';
 import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { whoami } from '@agentuity/server';
+import { getCommand } from '../../command-prefix';
+import { z } from 'zod';
+
+const WhoamiResponseSchema = z.object({
+	userId: z.string().describe('Unique user identifier'),
+	firstName: z.string().describe('User first name'),
+	lastName: z.string().describe('User last name'),
+	organizations: z
+		.array(
+			z.object({
+				id: z.string().describe('Organization ID'),
+				name: z.string().describe('Organization name'),
+			})
+		)
+		.describe('Organizations the user belongs to'),
+});
 
 export const whoamiCommand = createSubcommand({
 	name: 'whoami',
 	description: 'Display information about the currently authenticated user',
+	tags: ['read-only', 'fast', 'requires-auth'],
 	requires: { auth: true, apiClient: true },
+	idempotent: true,
 	schema: {
-		options: z.object({
-			format: z
-				.enum(['json', 'table'])
-				.optional()
-				.describe('the output format: json, table (default)'),
-		}),
+		response: WhoamiResponseSchema,
 	},
+	examples: [getCommand('auth whoami'), getCommand('--json auth whoami')],
 
 	async handler(ctx) {
-		const { apiClient, opts, auth } = ctx;
+		const { apiClient, auth, options } = ctx;
 
 		if (!apiClient) {
 			throw new Error(
@@ -33,19 +46,15 @@ export const whoamiCommand = createSubcommand({
 			},
 		});
 
-		if (opts?.format === 'json') {
-			console.log(
-				JSON.stringify(
-					{
-						userId: auth?.userId,
-						firstName: user.firstName,
-						lastName: user.lastName,
-						organizations: user.organizations,
-					},
-					null,
-					2
-				)
-			);
+		const result = {
+			userId: auth?.userId || '',
+			firstName: user.firstName,
+			lastName: user.lastName,
+			organizations: user.organizations,
+		};
+
+		if (options.json) {
+			console.log(JSON.stringify(result, null, 2));
 		} else {
 			const fullName = `${user.firstName} ${user.lastName}`;
 
@@ -65,5 +74,7 @@ export const whoamiCommand = createSubcommand({
 			}
 			tui.newline();
 		}
+
+		return result;
 	},
 });

package/src/cmd/bundle/ast.ts

@@ -147,31 +147,51 @@ function generateRouteId(
 	return `route_${hashSHA1(projectId, deploymentId, type, method, filename, path, version)}`;
 }
 
+function generateStableAgentId(projectId: string, name: string): string {
+	return `agentid_${hashSHA1(projectId, name)}`.substring(0, 64);
+}
+
 type AcornParseResultType = ReturnType<typeof acornLoose.parse>;
 
 function augmentAgentMetadataNode(
+	projectId: string,
 	id: string,
 	name: string,
 	rel: string,
 	version: string,
 	ast: AcornParseResultType,
 	propvalue: ASTObjectExpression,
-	_filename: string
+	filename: string
 ): [string, Map<string, string>] {
 	const metadata = parseObjectExpressionToMap(propvalue);
 	if (!metadata.has('name')) {
-		metadata.set('name', name);
-		propvalue.properties.push(createObjectPropertyNode('name', name));
+		const location = ast.loc?.start ? ` on line ${ast.loc.start}` : '';
+		throw new Error(
+			`missing required metadata.name in ${filename}${location}. This Agent should have a unique and human readable name for this project.`
+		);
+	}
+	if (metadata.has('identifier') && name !== metadata.get('identifier')) {
+		const location = ast.loc?.start ? ` on line ${ast.loc.start}` : '';
+		throw new Error(
+			`metadata.identifier (${metadata.get('identifier')}) in ${filename}${location} is mismatched (${name}). This is an internal error.`
+		);
 	}
+	const descriptionNode = propvalue.properties.find((x) => x.key.name === 'description')?.value;
+	const description = descriptionNode ? (descriptionNode as ASTLiteral).value : '';
+	const agentId = generateStableAgentId(projectId, name);
 	metadata.set('version', version);
 	metadata.set('identifier', name);
 	metadata.set('filename', rel);
 	metadata.set('id', id);
+	metadata.set('agentId', agentId);
+	metadata.set('description', description);
 	propvalue.properties.push(
 		createObjectPropertyNode('id', id),
+		createObjectPropertyNode('agentId', agentId),
 		createObjectPropertyNode('version', version),
 		createObjectPropertyNode('identifier', name),
-		createObjectPropertyNode('filename', rel)
+		createObjectPropertyNode('filename', rel),
+		createObjectPropertyNode('description', description)
 	);
 
 	const newsource = generate(ast);
@@ -508,6 +528,7 @@ export async function parseAgentMetadata(
 						for (const prop of callargexp.properties) {
 							if (prop.key.type === 'Identifier' && prop.key.name === 'metadata') {
 								result = augmentAgentMetadataNode(
+									projectId,
 									id,
 									name,
 									rel,
@@ -562,6 +583,7 @@ export async function parseAgentMetadata(
 												prop.key.name === 'metadata'
 											) {
 												result = augmentAgentMetadataNode(
+													projectId,
 													id,
 													name,
 													rel,
@@ -615,7 +637,7 @@ export async function parseAgentMetadata(
 	if (await evalsFile.exists()) {
 		logger.trace(`Found evals file at ${evalsPath}, parsing...`);
 		const evalsSource = await evalsFile.text();
-		const transpiler = new Bun.Transpiler({ loader: 'ts' });
+		const transpiler = new Bun.Transpiler({ loader: 'ts', target: 'bun' });
 		const evalsContents = transpiler.transformSync(evalsSource);
 		const [, evals] = parseEvalMetadata(
 			rootDir,

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,6 +574,7 @@ 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>',
@@ -587,6 +610,7 @@ 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>',

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;