@agentuity/cli 0.0.6

package/src/cli.ts

@@ -0,0 +1,198 @@
+import { Command } from 'commander';
+import type { CommandDefinition, SubcommandDefinition, CommandContext } from './types';
+import { showBanner } from './banner';
+import { requireAuth } from './auth';
+import { parseArgsSchema, parseOptionsSchema, buildValidationInput } from './schema-parser';
+
+export async function createCLI(version: string): Promise<Command> {
+	const program = new Command();
+
+	program
+		.name('agentuity')
+		.description('Agentuity CLI')
+		.version(version, '-V, --version', 'Display version')
+		.helpOption('-h, --help', 'Display help');
+
+	program
+		.option('--config <path>', 'Config file path', '~/.config/agentuity/config.yaml')
+		.option('--log-level <level>', 'Log level', 'info')
+		.option('--log-timestamp', 'Show timestamps in log output', false)
+		.option('--no-log-prefix', 'Hide log level prefixes', false)
+		.option('--color-scheme <scheme>', 'Color scheme: light or dark');
+
+	const skipVersionCheckOption = program.createOption(
+		'--skip-version-check',
+		'Skip version compatibility check (dev only)'
+	);
+	skipVersionCheckOption.hideHelp();
+	program.addOption(skipVersionCheckOption);
+
+	program.action(() => {
+		showBanner(version);
+		program.help();
+	});
+
+	return program;
+}
+
+async function registerSubcommand(
+	parent: Command,
+	subcommand: SubcommandDefinition,
+	baseCtx: CommandContext,
+	hidden?: boolean
+): Promise<void> {
+	const cmd = parent.command(subcommand.name, { hidden }).description(subcommand.description);
+
+	if (subcommand.aliases) {
+		cmd.aliases(subcommand.aliases);
+	}
+
+	// Auto-generate arguments and options from schemas
+	if (subcommand.schema?.args) {
+		const parsed = parseArgsSchema(subcommand.schema.args);
+		for (const argMeta of parsed.metadata) {
+			let argSyntax: string;
+			if (argMeta.variadic) {
+				argSyntax = argMeta.optional ? `[${argMeta.name}...]` : `<${argMeta.name}...>`;
+			} else {
+				argSyntax = argMeta.optional ? `[${argMeta.name}]` : `<${argMeta.name}>`;
+			}
+			cmd.argument(argSyntax);
+		}
+	}
+
+	if (subcommand.schema?.options) {
+		const parsed = parseOptionsSchema(subcommand.schema.options);
+		for (const opt of parsed) {
+			const flag = opt.name.replace(/([A-Z])/g, '-$1').toLowerCase();
+			const desc = opt.description || '';
+			if (opt.type === 'boolean') {
+				// Support negatable boolean options (--no-flag) when they have a default
+				if (opt.hasDefault) {
+					cmd.option(`--no-${flag}`, desc);
+				}
+				cmd.option(`--${flag}`, desc);
+			} else if (opt.type === 'number') {
+				cmd.option(`--${flag} <${opt.name}>`, desc, parseFloat);
+			} else {
+				cmd.option(`--${flag} <${opt.name}>`, desc);
+			}
+		}
+	}
+
+	cmd.action(async (...rawArgs: unknown[]) => {
+		const cmdObj = rawArgs[rawArgs.length - 1] as { opts: () => Record<string, unknown> };
+		const options = cmdObj.opts();
+		const args = rawArgs.slice(0, -1);
+
+		if (subcommand.requiresAuth) {
+			const auth = await requireAuth(baseCtx as CommandContext<false>);
+
+			if (subcommand.schema) {
+				try {
+					const input = buildValidationInput(subcommand.schema, args, options);
+					const ctx: Record<string, unknown> = {
+						...baseCtx,
+						auth,
+					};
+					if (subcommand.schema.args) {
+						ctx.args = subcommand.schema.args.parse(input.args);
+					}
+					if (subcommand.schema.options) {
+						ctx.opts = subcommand.schema.options.parse(input.options);
+					}
+					await subcommand.handler(ctx as CommandContext);
+				} catch (error) {
+					if (error && typeof error === 'object' && 'issues' in error) {
+						baseCtx.logger.error('Validation error:');
+						const issues = (error as { issues: Array<{ path: string[]; message: string }> })
+							.issues;
+						for (const issue of issues) {
+							baseCtx.logger.error(`  ${issue.path.join('.')}: ${issue.message}`);
+						}
+						process.exit(1);
+					}
+					throw error;
+				}
+			} else {
+				const ctx: CommandContext<true> = {
+					...baseCtx,
+					auth,
+				};
+				await subcommand.handler(ctx);
+			}
+		} else {
+			if (subcommand.schema) {
+				try {
+					const input = buildValidationInput(subcommand.schema, args, options);
+					const ctx: Record<string, unknown> = {
+						...baseCtx,
+					};
+					if (subcommand.schema.args) {
+						ctx.args = subcommand.schema.args.parse(input.args);
+					}
+					if (subcommand.schema.options) {
+						ctx.opts = subcommand.schema.options.parse(input.options);
+					}
+					await subcommand.handler(ctx as CommandContext);
+				} catch (error) {
+					if (error && typeof error === 'object' && 'issues' in error) {
+						baseCtx.logger.error('Validation error:');
+						const issues = (error as { issues: Array<{ path: string[]; message: string }> })
+							.issues;
+						for (const issue of issues) {
+							baseCtx.logger.error(`  ${issue.path.join('.')}: ${issue.message}`);
+						}
+						process.exit(1);
+					}
+					throw error;
+				}
+			} else {
+				await subcommand.handler(baseCtx as CommandContext<false>);
+			}
+		}
+	});
+}
+
+export async function registerCommands(
+	program: Command,
+	commands: CommandDefinition[],
+	baseCtx: CommandContext
+): Promise<void> {
+	for (const cmdDef of commands) {
+		if (cmdDef.subcommands) {
+			const cmd = program
+				.command(cmdDef.name, { hidden: cmdDef.hidden })
+				.description(cmdDef.description);
+
+			if (cmdDef.aliases) {
+				cmd.aliases(cmdDef.aliases);
+			}
+
+			if (cmdDef.handler) {
+				cmd.action(async () => {
+					if (cmdDef.requiresAuth) {
+						const auth = await requireAuth(baseCtx as CommandContext<false>);
+						const ctx: CommandContext<true> = { ...baseCtx, auth };
+						await cmdDef.handler!(ctx);
+					} else {
+						await cmdDef.handler!(baseCtx as CommandContext<false>);
+					}
+				});
+			} else {
+				cmd.action(() => cmd.help());
+			}
+
+			for (const sub of cmdDef.subcommands) {
+				await registerSubcommand(cmd, sub, baseCtx);
+			}
+		} else {
+			await registerSubcommand(
+				program,
+				cmdDef as unknown as SubcommandDefinition,
+				baseCtx,
+				cmdDef.hidden
+			);
+		}
+	}
+}

package/src/cmd/auth/README.md

@@ -0,0 +1,95 @@
+# Authentication Commands
+
+The auth command provides authentication and authorization functionality for the Agentuity Platform.
+
+## Commands
+
+### `auth login`
+
+Login to the Agentuity Platform using a browser-based authentication flow.
+
+```bash
+agentuity auth login
+# or
+agentuity login
+```
+
+**How it works:**
+
+1. Generates a one-time password (OTP) by calling `/cli/auth/start`
+2. Displays the OTP and authentication URL to the user
+3. Automatically opens the browser to the auth URL (on supported platforms)
+4. Polls `/cli/auth/check` every 2 seconds for up to 60 seconds
+5. Once authenticated, saves the API key, user ID, and expiration to config
+
+**Stored data:**
+
+```yaml
+auth:
+   api_key: 'your-api-key'
+   user_id: 'user-id'
+   expires: 1234567890
+preferences:
+   orgId: ''
+```
+
+### `auth logout`
+
+Logout of the Agentuity Cloud Platform by clearing authentication credentials.
+
+```bash
+agentuity auth logout
+# or
+agentuity logout
+```
+
+**What it does:**
+
+- Clears `auth.api_key`, `auth.user_id`, and sets `auth.expires` to current time
+- Clears `preferences.orgId`
+- Writes changes to the active profile config file
+
+## API Endpoints
+
+The authentication flow uses the following API endpoints:
+
+- `GET /cli/auth/start` - Generate OTP for login
+- `POST /cli/auth/check` - Poll for login completion with OTP
+
+## URL Configuration
+
+The API and App URLs are determined in the following priority order:
+
+1. **Environment Variables** (highest priority)
+   - `AGENTUITY_API_URL` - Override the API base URL
+   - `AGENTUITY_APP_URL` - Override the app base URL
+
+2. **Config File Overrides**
+
+   ```yaml
+   overrides:
+      api_url: https://api.agentuity.io
+      app_url: https://app.agentuity.io
+   ```
+
+3. **Default Values** (lowest priority)
+   - API URL: `https://api.agentuity.com`
+   - App URL: `https://app.agentuity.com`
+
+This allows different profiles (e.g., `local`, `production`) to point to different environments.
+
+## Implementation Details
+
+- **Generic API Client**: [../../api.ts](../../api.ts) provides the generic `APIClient` class for HTTP requests
+- **Auth-specific APIs**: [api.ts](./api.ts) provides `generateLoginOTP()` and `pollForLoginCompletion()` functions
+- **Config Management**: [../../config.ts](../../config.ts) provides `saveAuth()`, `clearAuth()`, and `getAuth()` helpers
+- **Browser Opening**: Uses `Bun.spawn(['open', authURL])` on non-Windows platforms to auto-open browser
+- **Polling**: Polls every 2 seconds with 60-second timeout
+- **Error Handling**: All errors are caught and displayed to user with appropriate exit codes
+   - `UpgradeRequiredError`: Shows upgrade instructions when CLI version is outdated
+   - Generic API errors: Display the error message from the server
+   - See [../../api-errors.md](../../api-errors.md) for details
+
+## Architecture
+
+Each command has its own `api.ts` file for command-specific API methods and types. The generic `APIClient` class and URL helpers are in the root `api.ts` file, promoting reusability while keeping command-specific logic isolated.

package/src/cmd/auth/api.ts

@@ -0,0 +1,71 @@
+import { APIClient } from '@/api';
+import type { Config } from '@/types';
+
+interface APIResponse<T> {
+	success: boolean;
+	message: string;
+	data?: T;
+}
+
+interface OTPStartData {
+	otp: string;
+}
+
+interface OTPCompleteData {
+	apiKey: string;
+	userId: string;
+	expires: number;
+}
+
+export interface LoginResult {
+	apiKey: string;
+	userId: string;
+	expires: Date;
+}
+
+export async function generateLoginOTP(apiUrl: string, config?: Config | null): Promise<string> {
+	const client = new APIClient(apiUrl, undefined, config);
+	const resp = await client.request<APIResponse<OTPStartData>>('GET', '/cli/auth/start');
+
+	if (!resp.success) {
+		throw new Error(resp.message);
+	}
+
+	if (!resp.data) {
+		throw new Error('No OTP returned from server');
+	}
+
+	return resp.data.otp;
+}
+
+export async function pollForLoginCompletion(
+	apiUrl: string,
+	otp: string,
+	config?: Config | null,
+	timeoutMs = 60000
+): Promise<LoginResult> {
+	const client = new APIClient(apiUrl, undefined, config);
+	const started = Date.now();
+
+	while (Date.now() - started < timeoutMs) {
+		const resp = await client.request<APIResponse<OTPCompleteData>>('POST', '/cli/auth/check', {
+			otp,
+		});
+
+		if (!resp.success) {
+			throw new Error(resp.message);
+		}
+
+		if (resp.data) {
+			return {
+				apiKey: resp.data.apiKey,
+				userId: resp.data.userId,
+				expires: new Date(resp.data.expires),
+			};
+		}
+
+		await new Promise((resolve) => setTimeout(resolve, 2000));
+	}
+
+	throw new Error('Login timed out');
+}

package/src/cmd/auth/index.ts

@@ -0,0 +1,9 @@
+import { createCommand } from '@/types';
+import { loginCommand } from './login';
+import { logoutCommand } from './logout';
+
+export const command = createCommand({
+	name: 'auth',
+	description: 'Authentication and authorization related commands',
+	subcommands: [loginCommand, logoutCommand],
+});

package/src/cmd/auth/login.ts

@@ -0,0 +1,76 @@
+import type { SubcommandDefinition } from '@/types';
+import { getAPIBaseURL, getAppBaseURL, UpgradeRequiredError } from '@/api';
+import { saveAuth } from '@/config';
+import { generateLoginOTP, pollForLoginCompletion } from './api';
+import * as tui from '@/tui';
+
+export const loginCommand: SubcommandDefinition = {
+	name: 'login',
+	description: 'Login to the Agentuity Platform using a browser-based authentication flow',
+	toplevel: true,
+
+	async handler(ctx) {
+		const { logger, config } = ctx;
+		const apiUrl = getAPIBaseURL(config);
+		const appUrl = getAppBaseURL(config);
+
+		try {
+			console.log('Generating login OTP...');
+
+			const otp = await generateLoginOTP(apiUrl, config);
+			const authURL = `${appUrl}/auth/cli`;
+
+			const copied = await tui.copyToClipboard(otp);
+
+			tui.newline();
+			if (copied) {
+				console.log(`Code copied to clipboard: ${tui.bold(otp)}`);
+			} else {
+				console.log('Copy the following code:');
+				tui.newline();
+				console.log(`  ${tui.bold(otp)}`);
+			}
+			tui.newline();
+			console.log('Then open the URL in your browser and paste the code:');
+			tui.newline();
+			console.log(`  ${tui.link(authURL)}`);
+			tui.newline();
+			console.log(tui.muted('This code will expire in 60 seconds'));
+			tui.newline();
+
+			if (process.platform === 'darwin') {
+				await tui.waitForAnyKey('Press Enter to open the URL...');
+				try {
+					Bun.spawn(['open', authURL], {
+						stdio: ['ignore', 'ignore', 'ignore'],
+					});
+				} catch {
+					// Ignore browser open errors
+				}
+			}
+
+			console.log('Waiting for login to complete...');
+
+			const result = await pollForLoginCompletion(apiUrl, otp, config);
+
+			await saveAuth({
+				apiKey: result.apiKey,
+				userId: result.userId,
+				expires: result.expires,
+			});
+
+			tui.newline();
+			tui.success('Welcome to Agentuity! You are now logged in');
+		} catch (error) {
+			if (error instanceof UpgradeRequiredError) {
+				const bannerBody = `${error.message}\n\nVisit: ${tui.link('https://agentuity.dev/CLI/installation')}`;
+				tui.banner('CLI Upgrade Required', bannerBody);
+				process.exit(1);
+			} else if (error instanceof Error) {
+				logger.fatal(`Login failed: ${error.message}`);
+			} else {
+				logger.fatal('Login failed');
+			}
+		}
+	},
+};

package/src/cmd/auth/logout.ts

@@ -0,0 +1,14 @@
+import type { SubcommandDefinition } from '@/types';
+import { clearAuth } from '@/config';
+import * as tui from '@/tui';
+
+export const logoutCommand: SubcommandDefinition = {
+	name: 'logout',
+	description: 'Logout of the Agentuity Cloud Platform',
+	toplevel: true,
+
+	async handler() {
+		await clearAuth();
+		tui.success('You have been logged out');
+	},
+};

package/src/cmd/bundle/ast.ts

@@ -0,0 +1,228 @@
+import * as acornLoose from 'acorn-loose';
+import { basename, dirname, relative } from 'node:path';
+import { generate } from 'astring';
+
+interface ASTNode {
+	type: string;
+}
+
+interface ASTNodeIdentifier extends ASTNode {
+	name: string;
+}
+
+interface ASTCallExpression extends ASTNode {
+	arguments: unknown[];
+	callee: {
+		name: string;
+	};
+}
+
+interface ASTPropertyNode {
+	type: string;
+	kind: string;
+	key: ASTNodeIdentifier;
+	value: ASTNode;
+}
+
+interface ASTObjectExpression extends ASTNode {
+	properties: ASTPropertyNode[];
+}
+
+interface ASTLiteral {
+	value: string;
+}
+
+function parseObjectExpressionToMap(expr: ASTObjectExpression): Map<string, string> {
+	const result = new Map<string, string>();
+	for (const prop of expr.properties) {
+		switch (prop.value.type) {
+			case 'Literal': {
+				const value = prop.value as unknown as ASTLiteral;
+				result.set(prop.key.name, value.value);
+				break;
+			}
+			default: {
+				console.warn(
+					'AST value type %s of metadata key: %s not supported',
+					prop.value.type,
+					prop.key.name
+				);
+			}
+		}
+	}
+	return result;
+}
+
+function createObjectPropertyNode(key: string, value: string) {
+	return {
+		type: 'Property',
+		kind: 'init',
+		key: {
+			type: 'Identifier',
+			name: key,
+		},
+		value: {
+			type: 'Literal',
+			value,
+		},
+	};
+}
+
+function createNewMetadataNode() {
+	return {
+		type: 'Property',
+		kind: 'init',
+		key: {
+			type: 'Identifier',
+			name: 'metadata',
+		},
+		value: {
+			type: 'ObjectExpression',
+			properties: [] as ASTPropertyNode[],
+		},
+	};
+}
+
+const projectId = process.env.AGENTUITY_CLOUD_PROJECT_ID ?? '';
+
+function hash(...val: string[]): string {
+	const hasher = new Bun.CryptoHasher('sha256');
+	val.forEach((val) => hasher.update(val));
+	return hasher.digest().toHex();
+}
+
+function getAgentId(identifier: string): string {
+	return hash(projectId, identifier);
+}
+
+type AcornParseResultType = ReturnType<typeof acornLoose.parse>;
+
+function augmentAgentMetadataNode(
+	id: string,
+	name: string,
+	rel: string,
+	version: string,
+	ast: AcornParseResultType,
+	propvalue: ASTObjectExpression
+): [string, Map<string, string>] {
+	const metadata = parseObjectExpressionToMap(propvalue);
+	if (!metadata.has('name')) {
+		metadata.set('name', name);
+		propvalue.properties.push(createObjectPropertyNode('name', name));
+	}
+	metadata.set('version', version);
+	metadata.set('identifier', name);
+	metadata.set('filename', rel);
+	metadata.set('id', id);
+	propvalue.properties.push(
+		createObjectPropertyNode('id', id),
+		createObjectPropertyNode('version', version),
+		createObjectPropertyNode('identifier', name),
+		createObjectPropertyNode('filename', rel)
+	);
+	const newsource = generate(ast);
+	return [newsource, metadata];
+}
+
+function createAgentMetadataNode(
+	id: string,
+	name: string,
+	rel: string,
+	version: string,
+	ast: AcornParseResultType,
+	callargexp: ASTObjectExpression
+): [string, Map<string, string>] {
+	const newmetadata = createNewMetadataNode();
+	const md = new Map<string, string>();
+	md.set('id', id);
+	md.set('version', version);
+	md.set('name', name);
+	md.set('identifier', name);
+	md.set('filename', rel);
+	for (const [key, value] of md) {
+		newmetadata.value.properties.push(createObjectPropertyNode(key, value));
+	}
+	callargexp.properties.push(newmetadata);
+	const newsource = generate(ast);
+	return [newsource, md];
+}
+
+export function parseAgentMetadata(
+	rootDir: string,
+	filename: string,
+	contents: string
+): [string, Map<string, string>] {
+	const ast = acornLoose.parse(contents, { ecmaVersion: 'latest', sourceType: 'module' });
+	let exportName: string | undefined;
+	const rel = relative(rootDir, filename);
+	const name = basename(dirname(filename));
+	const id = getAgentId(name);
+	const version = hash(contents);
+
+	for (const body of ast.body) {
+		if (body.type === 'ExportDefaultDeclaration') {
+			if (body.declaration?.type === 'CallExpression') {
+				const call = body.declaration as ASTCallExpression;
+				if (call.callee.name === 'createAgent') {
+					for (const callarg of call.arguments) {
+						const callargexp = callarg as ASTObjectExpression;
+						for (const prop of callargexp.properties) {
+							if (prop.key.type === 'Identifier' && prop.key.name === 'metadata') {
+								return augmentAgentMetadataNode(
+									id,
+									name,
+									rel,
+									version,
+									ast,
+									prop.value as ASTObjectExpression
+								);
+							}
+						}
+						return createAgentMetadataNode(id, name, rel, version, ast, callargexp);
+					}
+				}
+			}
+			const identifier = body.declaration as ASTNodeIdentifier;
+			exportName = identifier.name;
+			break;
+		}
+	}
+	if (!exportName) {
+		throw new Error(`could not find default export for ${filename} using ${rootDir}`);
+	}
+	for (const body of ast.body) {
+		if (body.type === 'VariableDeclaration') {
+			for (const vardecl of body.declarations) {
+				if (vardecl.type === 'VariableDeclarator' && vardecl.id.type === 'Identifier') {
+					const identifier = vardecl.id as ASTNodeIdentifier;
+					if (identifier.name === exportName) {
+						if (vardecl.init?.type === 'CallExpression') {
+							const call = vardecl.init as ASTCallExpression;
+							if (call.callee.name === 'createAgent') {
+								for (const callarg of call.arguments) {
+									const callargexp = callarg as ASTObjectExpression;
+									for (const prop of callargexp.properties) {
+										if (prop.key.type === 'Identifier' && prop.key.name === 'metadata') {
+											return augmentAgentMetadataNode(
+												id,
+												name,
+												rel,
+												version,
+												ast,
+												prop.value as ASTObjectExpression
+											);
+										}
+									}
+									return createAgentMetadataNode(id, name, rel, version, ast, callargexp);
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+	throw new Error(
+		`error parsing: ${filename}. could not find an proper createAgent defined in this file`
+	);
+}