@agentuity/cli 0.0.104 → 0.0.106

package/src/cli.ts

@@ -141,10 +141,17 @@ async function executeOrValidate(
 /**
  * Format a user-friendly message for a validation issue
  */
-function formatValidationIssueMessage(field: string, message: string): string {
+function formatValidationIssueMessage(
+	field: string,
+	message: string,
+	isArg: boolean = false
+): string {
 	// Detect "expected X, received undefined" pattern (missing required value)
 	if (message.includes('received undefined')) {
 		if (field && field !== 'unknown') {
+			if (isArg) {
+				return `Missing required argument: <${field}>`;
+			}
 			return `Missing required option: --${field}`;
 		}
 		return 'Missing required value';
@@ -155,6 +162,9 @@ function formatValidationIssueMessage(field: string, message: string): string {
 	if (typeMatch) {
 		const [, expected, received] = typeMatch;
 		if (field && field !== 'unknown') {
+			if (isArg) {
+				return `Invalid value for <${field}>: expected ${expected}, got ${received}`;
+			}
 			return `Invalid value for --${field}: expected ${expected}, got ${received}`;
 		}
 		return `Invalid value: expected ${expected}, got ${received}`;
@@ -162,25 +172,69 @@ function formatValidationIssueMessage(field: string, message: string): string {
 
 	// Default: include the field name if we have it
 	if (field && field !== 'unknown') {
+		if (isArg) {
+			return `<${field}>: ${message}`;
+		}
 		return `--${field}: ${message}`;
 	}
 	return message;
 }
 
+/**
+ * Custom error class to wrap ZodErrors with context about whether they are for args or options
+ */
+class SchemaValidationError extends Error {
+	constructor(
+		public readonly originalError: unknown,
+		public readonly isArg: boolean
+	) {
+		super('Schema validation error');
+	}
+}
+
+/**
+ * Parse args schema and wrap any ZodError with context
+ */
+function parseArgs<T>(schema: { parse: (input: unknown) => T }, input: unknown): T {
+	try {
+		return schema.parse(input);
+	} catch (error) {
+		if (error && typeof error === 'object' && 'issues' in error) {
+			throw new SchemaValidationError(error, true);
+		}
+		throw error;
+	}
+}
+
+/**
+ * Parse options schema (no wrapping needed, isArg defaults to false)
+ */
+function parseOptions<T>(schema: { parse: (input: unknown) => T }, input: unknown): T {
+	return schema.parse(input);
+}
+
 function handleValidationError(
 	error: unknown,
 	commandName: string,
 	baseCtx: { options: GlobalOptions; logger: Logger }
 ): never {
-	if (error && typeof error === 'object' && 'issues' in error) {
-		const issues = (error as { issues: Array<{ path: string[]; message: string }> }).issues;
+	// Unwrap SchemaValidationError to get context about whether it's an arg or option
+	let actualError = error;
+	let isArg = false;
+	if (error instanceof SchemaValidationError) {
+		actualError = error.originalError;
+		isArg = error.isArg;
+	}
+
+	if (actualError && typeof actualError === 'object' && 'issues' in actualError) {
+		const issues = (actualError as { issues: Array<{ path: string[]; message: string }> }).issues;
 
 		const formattedIssues = issues.map((issue) => {
 			const field = issue.path?.length ? issue.path.join('.') : 'unknown';
 			return {
 				field,
 				message: issue.message,
-				formatted: formatValidationIssueMessage(field, issue.message),
+				formatted: formatValidationIssueMessage(field, issue.message, isArg),
 			};
 		});
 
@@ -227,6 +281,22 @@ type Normalized = {
 	optionalRegion: boolean;
 };
 
+/**
+ * Get the full command path for a command (e.g., "cloud sandbox snapshot delete")
+ * Uses Commander's _getCommandAndAncestors to traverse the command hierarchy.
+ */
+function getFullCommandPath(cmd: Command): string {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const ancestors = (cmd as any)._getCommandAndAncestors() as Command[];
+	// ancestors is [current, parent, grandparent, ...root] - reverse and skip root program name
+	const names = ancestors.map((c) => c.name()).reverse();
+	// Skip the first entry if it's the root program (usually empty or 'agentuity')
+	if (names.length > 1 && (names[0] === '' || names[0] === 'agentuity')) {
+		return names.slice(1).join(' ');
+	}
+	return names.join(' ');
+}
+
 function normalizeReqs(def: CommandDefinition | SubcommandDefinition): Normalized {
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	const d: any = def as any;
@@ -802,6 +872,7 @@ async function registerSubcommand(
 
 	if (subcommand.schema?.options) {
 		const parsed = parseOptionsSchema(subcommand.schema.options);
+		const aliases = subcommand.schema.aliases ?? {};
 		for (const opt of parsed) {
 			const flag = opt.name
 				.replace(/([a-z0-9])([A-Z])/g, '$1-$2')
@@ -814,8 +885,15 @@ async function registerSubcommand(
 			}
 
 			const desc = opt.description || '';
-			// Add short flag alias for verbose
-			const flagSpec = flag === 'verbose' ? `-v, --${flag}` : `--${flag}`;
+			// Build flag spec with aliases (check both camelCase and kebab-case names)
+			const optAliases = aliases[opt.name] ?? aliases[flag] ?? [];
+			let flagSpec = `--${flag}`;
+			if (flag === 'verbose') {
+				flagSpec = `-v, --${flag}`;
+			} else if (optAliases.length > 0) {
+				const shortFlags = optAliases.map((a) => `-${a}`).join(', ');
+				flagSpec = `${shortFlags}, --${flag}`;
+			}
 			if (opt.type === 'boolean') {
 				if (opt.hasDefault) {
 					const defaultValue =
@@ -1019,10 +1097,10 @@ async function registerSubcommand(
 						ctx.projectDir = projectDir;
 					}
 					if (subcommand.schema.args) {
-						ctx.args = subcommand.schema.args.parse(input.args);
+						ctx.args = parseArgs(subcommand.schema.args, input.args);
 					}
 					if (subcommand.schema.options) {
-						ctx.opts = subcommand.schema.options.parse(input.options);
+						ctx.opts = parseOptions(subcommand.schema.options, input.options);
 					}
 					if (normalized.requiresAPIClient) {
 						// Recreate apiClient with auth credentials
@@ -1059,14 +1137,14 @@ async function registerSubcommand(
 					}
 					await executeOrValidate(
 						ctx as CommandContext,
-						`${parent.name()} ${subcommand.name}`,
+						getFullCommandPath(cmd),
 						subcommand.handler,
 						!!subcommand.schema?.response,
 						subcommand.webUrl
 					);
 				} catch (error) {
 					if (error && typeof error === 'object' && 'issues' in error) {
-						handleValidationError(error, `${parent.name()} ${subcommand.name}`, baseCtx);
+						handleValidationError(error, getFullCommandPath(cmd), baseCtx);
 					}
 					handleProjectConfigError(
 						error,
@@ -1139,7 +1217,7 @@ async function registerSubcommand(
 							exitWithError(
 								createError(
 									ErrorCode.INTERNAL_ERROR,
-									`Command '${parent.name()} ${subcommand.name}' declares a response schema but returned no data. This is a bug in the command implementation.`
+									`Command '${getFullCommandPath(cmd)}' declares a response schema but returned no data. This is a bug in the command implementation.`
 								),
 								baseCtx.logger,
 								baseCtx.options.errorFormat
@@ -1192,10 +1270,10 @@ async function registerSubcommand(
 						ctx.projectDir = projectDir;
 					}
 					if (subcommand.schema.args) {
-						ctx.args = subcommand.schema.args.parse(input.args);
+						ctx.args = parseArgs(subcommand.schema.args, input.args);
 					}
 					if (subcommand.schema.options) {
-						ctx.opts = subcommand.schema.options.parse(input.options);
+						ctx.opts = parseOptions(subcommand.schema.options, input.options);
 					}
 					if (normalized.requiresAPIClient) {
 						// Recreate apiClient with auth credentials
@@ -1238,14 +1316,14 @@ async function registerSubcommand(
 					}
 					await executeOrValidate(
 						ctx as CommandContext,
-						`${parent.name()} ${subcommand.name}`,
+						getFullCommandPath(cmd),
 						subcommand.handler,
 						!!subcommand.schema?.response,
 						subcommand.webUrl
 					);
 				} catch (error) {
 					if (error && typeof error === 'object' && 'issues' in error) {
-						handleValidationError(error, `${parent.name()} ${subcommand.name}`, baseCtx);
+						handleValidationError(error, getFullCommandPath(cmd), baseCtx);
 					}
 					handleProjectConfigError(
 						error,
@@ -1314,7 +1392,7 @@ async function registerSubcommand(
 							exitWithError(
 								createError(
 									ErrorCode.INTERNAL_ERROR,
-									`Command '${parent.name()} ${subcommand.name}' declares a response schema but returned no data. This is a bug in the command implementation.`
+									`Command '${getFullCommandPath(cmd)}' declares a response schema but returned no data. This is a bug in the command implementation.`
 								),
 								baseCtx.logger,
 								baseCtx.options.errorFormat
@@ -1343,10 +1421,10 @@ async function registerSubcommand(
 						ctx.projectDir = projectDir;
 					}
 					if (subcommand.schema.args) {
-						ctx.args = subcommand.schema.args.parse(input.args);
+						ctx.args = parseArgs(subcommand.schema.args, input.args);
 					}
 					if (subcommand.schema.options) {
-						ctx.opts = subcommand.schema.options.parse(input.options);
+						ctx.opts = parseOptions(subcommand.schema.options, input.options);
 					}
 					if (normalized.requiresAPIClient && !ctx.apiClient) {
 						ctx.apiClient = createAPIClient(baseCtx, ctx.config as Config | null);
@@ -1363,14 +1441,14 @@ async function registerSubcommand(
 					}
 					await executeOrValidate(
 						ctx as CommandContext,
-						`${parent.name()} ${subcommand.name}`,
+						getFullCommandPath(cmd),
 						subcommand.handler,
 						!!subcommand.schema?.response,
 						subcommand.webUrl
 					);
 				} catch (error) {
 					if (error && typeof error === 'object' && 'issues' in error) {
-						handleValidationError(error, `${parent.name()} ${subcommand.name}`, baseCtx);
+						handleValidationError(error, getFullCommandPath(cmd), baseCtx);
 					}
 					handleProjectConfigError(
 						error,
@@ -1426,7 +1504,7 @@ async function registerSubcommand(
 							exitWithError(
 								createError(
 									ErrorCode.INTERNAL_ERROR,
-									`Command '${parent.name()} ${subcommand.name}' declares a response schema but returned no data. This is a bug in the command implementation.`
+									`Command '${getFullCommandPath(cmd)}' declares a response schema but returned no data. This is a bug in the command implementation.`
 								),
 								baseCtx.logger,
 								baseCtx.options.errorFormat

package/src/cmd/ai/prompt/api.md

@@ -311,40 +311,45 @@ return c.json({ data: 'value' }, 200, {
 ## Streaming Routes
 
 ```typescript
-import { createRouter } from '@agentuity/runtime';
+import { createRouter, stream, sse, websocket } from '@agentuity/runtime';
 
 const router = createRouter();
 
-// Stream response
-router.stream('/events', (c) => {
-	return new ReadableStream({
-		start(controller) {
-			controller.enqueue('event 1\n');
-			controller.enqueue('event 2\n');
-			controller.close();
-		},
-	});
-});
+// Stream response (use with POST)
+router.post(
+	'/events',
+	stream((c) => {
+		return new ReadableStream({
+			start(controller) {
+				controller.enqueue('event 1\n');
+				controller.enqueue('event 2\n');
+				controller.close();
+			},
+		});
+	})
+);
 
-// Server-Sent Events
-router.sse('/notifications', (c) => {
-	return (stream) => {
+// Server-Sent Events (use with GET)
+router.get(
+	'/notifications',
+	sse((c, stream) => {
 		stream.writeSSE({ data: 'Hello', event: 'message' });
 		stream.writeSSE({ data: 'World', event: 'message' });
-	};
-});
+	})
+);
 
-// WebSocket
-router.websocket('/ws', (c) => {
-	return (ws) => {
+// WebSocket (use with GET)
+router.get(
+	'/ws',
+	websocket((c, ws) => {
 		ws.onOpen(() => {
 			ws.send('Connected!');
 		});
 		ws.onMessage((event) => {
 			ws.send(`Echo: ${event.data}`);
 		});
-	};
-});
+	})
+);
 
 export default router;
 ```

package/src/cmd/ai/prompt/version.ts

@@ -8,7 +8,7 @@
  * This allows detecting if the source template has changed.
  */
 
-const HASH_REGEX = /\n?<!-- prompt_hash: ([a-f0-9]+) -->$/;
+const HASH_REGEX = /\n?<!-- prompt_hash: ([a-f0-9]+) -->\n?$/;
 
 /**
  * Compute SHA256 hash of content using Bun's built-in hasher.
@@ -37,10 +37,11 @@ export function extractHash(content: string): string | null {
 
 /**
  * Generate content with hash comment appended.
+ * Ensures the output ends with a newline for POSIX compliance and Prettier compatibility.
  */
 export function appendHashComment(content: string): string {
 	const hash = computeHash(content);
-	return `${content}\n<!-- prompt_hash: ${hash} -->`;
+	return `${content}\n<!-- prompt_hash: ${hash} -->\n`;
 }
 
 /**

package/src/cmd/build/ast.ts

@@ -1300,12 +1300,168 @@ export async function parseRoute(
 						const action = statement.expression.arguments[0];
 						let suffix = '';
 						let config: Record<string, unknown> | undefined;
+						// Supported HTTP methods that can be represented in BuildMetadata
+						const SUPPORTED_HTTP_METHODS = ['get', 'post', 'put', 'delete', 'patch'] as const;
+						type SupportedHttpMethod = (typeof SUPPORTED_HTTP_METHODS)[number];
+
+						const isSupportedHttpMethod = (m: string): m is SupportedHttpMethod =>
+							SUPPORTED_HTTP_METHODS.includes(m.toLowerCase() as SupportedHttpMethod);
+
 						switch (method) {
 							case 'use':
-							case 'on':
-							case 'all':
 							case 'route': {
-								// Skip Hono middleware/routing methods - they don't represent API routes
+								// Skip Hono middleware and sub-router mounting - they don't represent API routes
+								continue;
+							}
+							case 'on': {
+								// router.on(method | method[], path, handler)
+								// First arg is method(s), second arg is path
+								const methodArg = statement.expression.arguments[0];
+								const pathArg = statement.expression.arguments[1];
+
+								// Extract methods from first argument
+								const methods: SupportedHttpMethod[] = [];
+
+								if (methodArg && (methodArg as ASTLiteral).type === 'Literal') {
+									// Single method: router.on('GET', '/path', handler)
+									const raw = String((methodArg as ASTLiteral).value || '').toLowerCase();
+									if (isSupportedHttpMethod(raw)) {
+										methods.push(raw as SupportedHttpMethod);
+									}
+								} else if (methodArg && (methodArg as ASTNode).type === 'ArrayExpression') {
+									// Array of methods: router.on(['GET', 'POST'], '/path', handler)
+									const arr = methodArg as { elements: ASTNode[] };
+									for (const el of arr.elements) {
+										if (!el || (el as ASTLiteral).type !== 'Literal') continue;
+										const raw = String((el as ASTLiteral).value || '').toLowerCase();
+										if (isSupportedHttpMethod(raw)) {
+											methods.push(raw as SupportedHttpMethod);
+										}
+									}
+								}
+
+								// Skip if no supported methods or path is not a literal
+								if (
+									methods.length === 0 ||
+									!pathArg ||
+									(pathArg as ASTLiteral).type !== 'Literal'
+								) {
+									continue;
+								}
+
+								const pathSuffix = String((pathArg as ASTLiteral).value);
+
+								// Create a route entry for each method
+								for (const httpMethod of methods) {
+									const thepath = `${routePrefix}/${routeName}/${pathSuffix}`
+										.replaceAll(/\/{2,}/g, '/')
+										.replaceAll(/\/$/g, '');
+									const id = generateRouteId(
+										projectId,
+										deploymentId,
+										'api',
+										httpMethod,
+										rel,
+										thepath,
+										version
+									);
+
+									// Check if this route uses validator middleware
+									const validatorInfo = hasValidatorCall(statement.expression.arguments);
+									const routeConfig: Record<string, unknown> = {};
+									if (validatorInfo.hasValidator) {
+										routeConfig.hasValidator = true;
+										if (validatorInfo.agentVariable) {
+											routeConfig.agentVariable = validatorInfo.agentVariable;
+											const agentImportPath = importMap.get(validatorInfo.agentVariable);
+											if (agentImportPath) {
+												routeConfig.agentImportPath = agentImportPath;
+											}
+										}
+										if (validatorInfo.inputSchemaVariable) {
+											routeConfig.inputSchemaVariable =
+												validatorInfo.inputSchemaVariable;
+										}
+										if (validatorInfo.outputSchemaVariable) {
+											routeConfig.outputSchemaVariable =
+												validatorInfo.outputSchemaVariable;
+										}
+										if (validatorInfo.stream !== undefined) {
+											routeConfig.stream = validatorInfo.stream;
+										}
+									}
+
+									routes.push({
+										id,
+										method: httpMethod,
+										type: 'api',
+										filename: rel,
+										path: thepath,
+										version,
+										config: Object.keys(routeConfig).length > 0 ? routeConfig : undefined,
+									});
+								}
+								continue;
+							}
+							case 'all': {
+								// router.all(path, handler) - matches all HTTP methods
+								// First arg is path (same as get/post/etc.)
+								if (!action || (action as ASTLiteral).type !== 'Literal') {
+									continue;
+								}
+
+								const pathSuffix = String((action as ASTLiteral).value);
+
+								// Create a route entry for each supported method
+								for (const httpMethod of SUPPORTED_HTTP_METHODS) {
+									const thepath = `${routePrefix}/${routeName}/${pathSuffix}`
+										.replaceAll(/\/{2,}/g, '/')
+										.replaceAll(/\/$/g, '');
+									const id = generateRouteId(
+										projectId,
+										deploymentId,
+										'api',
+										httpMethod,
+										rel,
+										thepath,
+										version
+									);
+
+									// Check if this route uses validator middleware
+									const validatorInfo = hasValidatorCall(statement.expression.arguments);
+									const routeConfig: Record<string, unknown> = {};
+									if (validatorInfo.hasValidator) {
+										routeConfig.hasValidator = true;
+										if (validatorInfo.agentVariable) {
+											routeConfig.agentVariable = validatorInfo.agentVariable;
+											const agentImportPath = importMap.get(validatorInfo.agentVariable);
+											if (agentImportPath) {
+												routeConfig.agentImportPath = agentImportPath;
+											}
+										}
+										if (validatorInfo.inputSchemaVariable) {
+											routeConfig.inputSchemaVariable =
+												validatorInfo.inputSchemaVariable;
+										}
+										if (validatorInfo.outputSchemaVariable) {
+											routeConfig.outputSchemaVariable =
+												validatorInfo.outputSchemaVariable;
+										}
+										if (validatorInfo.stream !== undefined) {
+											routeConfig.stream = validatorInfo.stream;
+										}
+									}
+
+									routes.push({
+										id,
+										method: httpMethod,
+										type: 'api',
+										filename: rel,
+										path: thepath,
+										version,
+										config: Object.keys(routeConfig).length > 0 ? routeConfig : undefined,
+									});
+								}
 								continue;
 							}
 							case 'get':
@@ -1315,6 +1471,52 @@ export async function parseRoute(
 							case 'delete': {
 								if (action && (action as ASTLiteral).type === 'Literal') {
 									suffix = String((action as ASTLiteral).value);
+
+									// Check if any argument is a middleware function call (websocket, sse, stream, cron)
+									// New pattern: router.get('/ws', websocket((c, ws) => { ... }))
+									for (const arg of statement.expression.arguments) {
+										if ((arg as ASTCallExpression).type === 'CallExpression') {
+											const callExpr = arg as ASTCallExpression;
+											// Only handle simple Identifier callees (e.g., websocket(), sse())
+											// Skip MemberExpression callees (e.g., obj.method())
+											if (callExpr.callee.type !== 'Identifier') {
+												continue;
+											}
+											const calleeName = (callExpr.callee as ASTNodeIdentifier).name;
+											if (
+												calleeName === 'websocket' ||
+												calleeName === 'sse' ||
+												calleeName === 'stream'
+											) {
+												type = calleeName;
+												break;
+											}
+											if (calleeName === 'cron') {
+												type = 'cron';
+												// First argument to cron() is the schedule expression
+												if (callExpr.arguments && callExpr.arguments.length > 0) {
+													const cronArg = callExpr.arguments[0] as ASTLiteral;
+													if (cronArg.type === 'Literal') {
+														const expression = String(cronArg.value);
+														try {
+															parseCronExpression(expression, {
+																hasSeconds: false,
+															});
+														} catch (ex) {
+															throw new InvalidRouterConfigError({
+																filename,
+																cause: ex,
+																line: body.loc?.start?.line,
+																message: `invalid cron expression "${expression}" in ${filename} at line ${body.loc?.start?.line}`,
+															});
+														}
+														config = { expression };
+													}
+												}
+												break;
+											}
+										}
+									}
 								} else {
 									throw new InvalidRouterConfigError({
 										filename,
@@ -1327,6 +1529,8 @@ export async function parseRoute(
 							case 'stream':
 							case 'sse':
 							case 'websocket': {
+								// DEPRECATED: router.stream(), router.sse(), router.websocket()
+								// These methods now throw errors at runtime
 								type = method;
 								method = 'post';
 								const theaction = action as ASTLiteral;
@@ -1336,39 +1540,9 @@ export async function parseRoute(
 								}
 								break;
 							}
-							case 'sms': {
-								type = method;
-								method = 'post';
-								const theaction = action as ASTObjectExpression;
-								if (theaction.type === 'ObjectExpression') {
-									config = {};
-									theaction.properties.forEach((p) => {
-										if (p.value.type === 'Literal') {
-											const literal = p.value as ASTLiteral;
-											config![p.key.name] = literal.value;
-										}
-									});
-									const number = theaction.properties.find((p) => p.key.name === 'number');
-									if (number && number.value.type === 'Literal') {
-										const phoneNumber = number.value as ASTLiteral;
-										suffix = hash(String(phoneNumber.value));
-										break;
-									}
-								}
-								break;
-							}
-							case 'email': {
-								type = method;
-								method = 'post';
-								const theaction = action as ASTLiteral;
-								if (theaction.type === 'Literal') {
-									const email = String(theaction.value);
-									suffix = hash(email);
-									break;
-								}
-								break;
-							}
 							case 'cron': {
+								// DEPRECATED: router.cron()
+								// This method now throws errors at runtime
 								type = method;
 								method = 'post';
 								const theaction = action as ASTLiteral;
@@ -1437,8 +1611,11 @@ export async function parseRoute(
 							}
 						}
 
-						// For WebSocket/SSE routes that don't use validator(), fall back to exported schemas
-						if (!routeConfig.hasValidator && (type === 'websocket' || type === 'sse')) {
+						// For WebSocket/SSE/stream routes that don't use validator(), fall back to exported schemas
+						if (
+							!routeConfig.hasValidator &&
+							(type === 'websocket' || type === 'sse' || type === 'stream')
+						) {
 							if (!routeConfig.inputSchemaVariable && exportedInputSchemaName) {
 								routeConfig.inputSchemaVariable = exportedInputSchemaName;
 							}