@agentuity/cli 0.0.60 → 0.0.62

package/src/cmd/project/delete.ts

@@ -13,12 +13,21 @@ export const deleteSubcommand = createSubcommand({
 	requires: { auth: true, apiClient: true },
 	idempotent: false,
 	examples: [
-		getCommand('project delete'),
-		getCommand('project delete proj_abc123def456'),
-		getCommand('project delete proj_abc123def456 --confirm'),
-		getCommand('project rm proj_abc123def456'),
-		getCommand('--explain project delete proj_abc123def456'),
-		getCommand('--dry-run project delete proj_abc123def456'),
+		{ command: getCommand('project delete'), description: 'Delete item' },
+		{ command: getCommand('project delete proj_abc123def456'), description: 'Delete item' },
+		{
+			command: getCommand('project delete proj_abc123def456 --confirm'),
+			description: 'Use confirm option',
+		},
+		{ command: getCommand('project rm proj_abc123def456'), description: 'Delete item' },
+		{
+			command: getCommand('--explain project delete proj_abc123def456'),
+			description: 'Delete item',
+		},
+		{
+			command: getCommand('--dry-run project delete proj_abc123def456'),
+			description: 'Delete item',
+		},
 	],
 	schema: {
 		args: z.object({

package/src/cmd/project/download.ts

@@ -13,9 +13,13 @@ import { tmpdir } from 'node:os';
 import { finished } from 'node:stream/promises';
 import { createGunzip } from 'node:zlib';
 import { extract, type Headers } from 'tar-fs';
-import type { Logger } from '@agentuity/core';
+import { StructuredError, type Logger } from '@agentuity/core';
 import * as tui from '../../tui';
 import { downloadWithSpinner } from '../../download';
+import { generateLLMPrompt as generateCLIPrompt } from '../ai/prompt/llm';
+import { generateLLMPrompt as generateAgentPrompt } from '../ai/prompt/agent';
+import { generateLLMPrompt as generateWebPrompt } from '../ai/prompt/web';
+import { generateLLMPrompt as generateAPIPrompt } from '../ai/prompt/api';
 import type { TemplateInfo } from './templates';
 
 const GITHUB_REPO = 'agentuity/sdk';
@@ -38,9 +42,16 @@ interface SetupOptions {
 	logger: Logger;
 }
 
+const TemplateDirectoryNotFoundError = StructuredError('TemplateDirectoryNotFoundError')<{
+	directory: string;
+}>();
+
 async function cleanup(sourceDir: string, dest: string) {
 	if (!existsSync(sourceDir)) {
-		throw new Error(`Template directory not found: ${sourceDir}`);
+		throw new TemplateDirectoryNotFoundError({
+			directory: sourceDir,
+			message: `Template directory not found: ${sourceDir}`,
+		});
 	}
 
 	tui.spinner(`📦 Copying template files...`, async () => {
@@ -68,7 +79,10 @@ export async function downloadTemplate(options: DownloadOptions): Promise<void>
 		const sourceDir = resolve(join(templateDir, template.directory));
 
 		if (!existsSync(sourceDir)) {
-			throw new Error(`Template directory not found: ${sourceDir}`);
+			throw new TemplateDirectoryNotFoundError({
+				directory: sourceDir,
+				message: `Template directory not found: ${sourceDir}`,
+			});
 		}
 
 		return cleanup(sourceDir, dest);
@@ -258,6 +272,33 @@ export async function setupProject(options: SetupOptions): Promise<void> {
 			clearOnSuccess: true,
 		});
 	}
+
+	// generate and write the AGENTS.md for the cli
+	const cliDir = join(dest, 'node_modules', '@agentuity', 'cli');
+	if (existsSync(cliDir)) {
+		const agentFile = join(cliDir, 'AGENTS.md');
+		const prompt = generateCLIPrompt();
+		await Bun.write(agentFile, prompt);
+	}
+
+	// generate and write AGENTS.md for each of the main folders
+	const agentsDir = join(dest, 'src', 'agents');
+	if (existsSync(agentsDir)) {
+		const agentsAPIFile = join(agentsDir, 'AGENTS.md');
+		await Bun.write(agentsAPIFile, generateAgentPrompt());
+	}
+
+	const apisDir = join(dest, 'src', 'apis');
+	if (existsSync(apisDir)) {
+		const agentsAPIsFile = join(apisDir, 'AGENTS.md');
+		await Bun.write(agentsAPIsFile, generateAPIPrompt());
+	}
+
+	const webDir = join(dest, 'src', 'web');
+	if (existsSync(webDir)) {
+		const agentsWebFile = join(webDir, 'AGENTS.md');
+		await Bun.write(agentsWebFile, generateWebPrompt());
+	}
 }
 
 async function replaceInFiles(dir: string, projectName: string, dirName: string): Promise<void> {

package/src/cmd/project/index.ts

@@ -3,10 +3,15 @@ import { createProjectSubcommand } from './create';
 import { listSubcommand } from './list';
 import { deleteSubcommand } from './delete';
 import { showSubcommand } from './show';
+import { getCommand } from '../../command-prefix';
 
 export const command = createCommand({
 	name: 'project',
 	description: 'Project related commands',
 	tags: ['fast', 'requires-auth'],
+	examples: [
+		{ command: getCommand('project create my-agent'), description: 'Create a new project' },
+		{ command: getCommand('project list'), description: 'List all projects' },
+	],
 	subcommands: [createProjectSubcommand, listSubcommand, deleteSubcommand, showSubcommand],
 });

package/src/cmd/project/list.ts

@@ -24,9 +24,12 @@ export const listSubcommand = createSubcommand({
 		response: ProjectListResponseSchema,
 	},
 	examples: [
-		getCommand('project list'),
-		getCommand('--json project list'),
-		getCommand('project ls'),
+		{ command: getCommand('project list'), description: 'List projects (human-readable)' },
+		{ command: getCommand('--json project list'), description: 'List projects in JSON format' },
+		{
+			command: getCommand('project ls'),
+			description: 'Alias for "project list" — list projects (human-readable)',
+		},
 	],
 
 	async handler(ctx) {

package/src/cmd/project/show.ts

@@ -19,9 +19,12 @@ export const showSubcommand = createSubcommand({
 	tags: ['read-only', 'fast', 'requires-auth', 'requires-project'],
 	requires: { auth: true, apiClient: true },
 	examples: [
-		getCommand('project show proj_abc123def456'),
-		getCommand('--json project show proj_abc123def456'),
-		getCommand('project get proj_abc123def456'),
+		{ command: getCommand('project show proj_abc123def456'), description: 'Show details' },
+		{
+			command: getCommand('--json project show proj_abc123def456'),
+			description: 'Show output in JSON format',
+		},
+		{ command: getCommand('project get proj_abc123def456'), description: 'Get item details' },
 	],
 	schema: {
 		args: z.object({

package/src/cmd/project/templates.ts

@@ -1,3 +1,5 @@
+import { StructuredError } from '@agentuity/core';
+
 const GITHUB_REPO = 'agentuity/sdk';
 const GITHUB_BRANCH = 'main';
 const TEMPLATES_JSON_PATH = 'templates/templates.json';
@@ -13,6 +15,9 @@ interface TemplatesManifest {
 	templates: TemplateInfo[];
 }
 
+const TemplateMissingConfigurationError = StructuredError('TemplateMissingConfigurationError');
+const TemplateDownloadError = StructuredError('TemplateDownloadError')<{ status: number }>();
+
 export async function fetchTemplates(localDir?: string, branch?: string): Promise<TemplateInfo[]> {
 	// Load from local directory if provided
 	if (localDir) {
@@ -22,7 +27,9 @@ export async function fetchTemplates(localDir?: string, branch?: string): Promis
 		const file = Bun.file(manifestPath);
 
 		if (!(await file.exists())) {
-			throw new Error(`templates.json not found at ${manifestPath}`);
+			throw new TemplateMissingConfigurationError({
+				message: `templates.json not found at ${manifestPath}`,
+			});
 		}
 
 		const manifest = (await file.json()) as TemplatesManifest;
@@ -40,7 +47,10 @@ export async function fetchTemplates(localDir?: string, branch?: string): Promis
 
 	const response = await fetch(url, { headers });
 	if (!response.ok) {
-		throw new Error(`Failed to fetch templates: ${response.statusText}`);
+		throw new TemplateDownloadError({
+			status: response.status,
+			message: `Failed to fetch templates: ${response.statusText}`,
+		});
 	}
 
 	const manifest = (await response.json()) as TemplatesManifest;

package/src/cmd/repl/index.ts

@@ -9,7 +9,7 @@ export const command = createCommand({
 	description: 'interactive REPL for testing',
 	tags: ['slow'],
 	idempotent: false,
-	examples: [getCommand('repl')],
+	examples: [{ command: getCommand('repl'), description: 'Run repl command' }],
 
 	async handler() {
 		// Define test commands

package/src/cmd/version/index.ts

@@ -11,7 +11,13 @@ export const command = createCommand({
 	name: 'version',
 	description: 'Display version information',
 	tags: ['read-only', 'fast'],
-	examples: [getCommand('version'), getCommand('--version')],
+	examples: [
+		{ command: getCommand('version'), description: 'Show the CLI semantic version' },
+		{
+			command: getCommand('--version'),
+			description: 'Display the current installed CLI version and build metadata',
+		},
+	],
 	schema: {
 		response: VersionResponseSchema,
 	},

package/src/command-prefix.ts

@@ -17,11 +17,13 @@ export function getCommandPrefix(): string {
 	const scriptPath = process.argv[1] || '';
 	const normalized = path.normalize(scriptPath);
 
+	// If we have AGENTUITY_CLI_VERSION set we are running from compiled binary OR
 	// If the script is in node_modules/.bin or a global bin directory, it's likely global
 	const isGlobal =
-		normalized.includes(`${path.sep}bin${path.sep}`) &&
-		!normalized.includes(`${path.sep}node_modules${path.sep}`) &&
-		!normalized.includes(path.join('packages', 'cli', 'bin'));
+		process.env.AGENTUITY_CLI_VERSION ||
+		(normalized.includes(`${path.sep}bin${path.sep}`) &&
+			!normalized.includes(`${path.sep}node_modules${path.sep}`) &&
+			!normalized.includes(path.join('packages', 'cli', 'bin')));
 
 	if (isGlobal) {
 		cachedPrefix = 'agentuity';

package/src/config.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { existsSync, mkdirSync } from 'node:fs';
-import type { Logger } from '@agentuity/core';
+import { StructuredError, type Logger } from '@agentuity/core';
 import {
 	BuildMetadataSchema,
 	type BuildMetadata,
@@ -609,11 +609,13 @@ export async function createProjectConfig(dir: string, config: InitialProjectCon
 	await Bun.write(join(vscodeDir, 'settings.json'), JSON.stringify(settings, null, 2));
 }
 
+const BuildMetadataNotFoundError = StructuredError('BuildMetadataNotFoundError');
+
 export async function loadBuildMetadata(dir: string): Promise<BuildMetadata> {
 	const filename = join(dir, 'agentuity.metadata.json');
 	const file = Bun.file(filename);
 	if (!(await file.exists())) {
-		throw new Error(`couldn't find ${filename}`);
+		throw new BuildMetadataNotFoundError({ message: `couldn't find ${filename}` });
 	}
 	const buffer = await file.text();
 	const config = JSON.parse(buffer);

package/src/crypto/box.ts

@@ -62,6 +62,7 @@
 import { createCipheriv, createDecipheriv, createECDH, randomBytes, KeyObject } from 'node:crypto';
 import { Readable, Writable } from 'node:stream';
 import { createHash } from 'node:crypto';
+import { StructuredError } from '@agentuity/core';
 
 const FRAME = 65519;
 const DEK_SIZE = 32;
@@ -87,13 +88,64 @@ function concatKDFSHA256(z: Buffer, keyDataLen: number, ...otherInfo: Buffer[]):
 	return h.digest();
 }
 
+const InvalidECPublicKeyError = StructuredError('InvalidECPublicKeyError', 'Invalid EC public key');
+const InvalidECPrivateKeyError = StructuredError(
+	'InvalidECPrivateKeyError',
+	'Invalid EC private key'
+);
+const InvalidDEKTooShortError = StructuredError(
+	'InvalidDEKTooShortError',
+	'Invalid DEK too short (wrapped)'
+);
+const InvalidDEKFormatError = StructuredError(
+	'InvalidDEKFormatError',
+	'Invalid DEK format (wrapped)'
+);
+const DEKUnwrappedFailedError = StructuredError('DEKUnwrappedFailedError', 'DEK unwrap failed');
+
+const InvalidKeyECOnlyError = StructuredError(
+	'InvalidKeyECOnlyError',
+	'Invalid Key: only EC keys supported'
+);
+const InvalidKeyP256OnlyError = StructuredError(
+	'InvalidKeyP256OnlyError',
+	'Invalid Key: only P-256 keys supported'
+);
+
+const InvalidCipherTextLengthError = StructuredError(
+	'InvalidCipherTextLengthError',
+	'ciphertext length exceeds uint16 limit'
+);
+
+const InvalidWrappedDEKLengthError = StructuredError(
+	'InvalidWrappedDEKLengthError',
+	'invalid wrapped DEK length'
+);
+
+const UnexpectedEOFChunkLengthError = StructuredError(
+	'UnexpectedEOFChunkLengthError',
+	'unexpected EOF reading chunk length'
+);
+
+const UnexpectedChunkTooLargeError = StructuredError(
+	'UnexpectedChunkTooLargeError',
+	'chunk too large'
+);
+
+const UnexpectedChunkTooShortError = StructuredError(
+	'UnexpectedChunkTooShortError',
+	'chunk too short for auth tag'
+);
+
+const UnexpectedEOFError = StructuredError('UnexpectedEOFError', 'unexpected EOF');
+
 function wrapDEKWithECDH(dek: Buffer, recipientPub: KeyObject): Buffer {
 	const ephemeral = createECDH('prime256v1');
 	ephemeral.generateKeys();
 
 	const jwk = recipientPub.export({ format: 'jwk' });
 	if (!jwk.x || !jwk.y) {
-		throw new Error('Invalid EC public key');
+		throw new InvalidECPublicKeyError();
 	}
 
 	const xBuf = Buffer.from(jwk.x, 'base64url');
@@ -116,7 +168,7 @@ function wrapDEKWithECDH(dek: Buffer, recipientPub: KeyObject): Buffer {
 
 function unwrapDEKWithECDH(wrapped: Buffer, recipientPriv: KeyObject): Buffer {
 	if (wrapped.length < PUBKEY_LEN + 12 + DEK_SIZE + GCM_TAG) {
-		throw new Error('wrapped DEK too short');
+		throw new InvalidDEKTooShortError();
 	}
 
 	const ephemeralPubBytes = wrapped.subarray(0, PUBKEY_LEN);
@@ -124,7 +176,7 @@ function unwrapDEKWithECDH(wrapped: Buffer, recipientPriv: KeyObject): Buffer {
 
 	const jwk = recipientPriv.export({ format: 'jwk' });
 	if (!jwk.d) {
-		throw new Error('Invalid EC private key');
+		throw new InvalidECPrivateKeyError();
 	}
 
 	const ecdh = createECDH('prime256v1');
@@ -139,14 +191,14 @@ function unwrapDEKWithECDH(wrapped: Buffer, recipientPriv: KeyObject): Buffer {
 
 		const nonceSize = 12;
 		if (remaining.length < nonceSize) {
-			throw new Error('invalid wrapped DEK format');
+			throw new InvalidDEKFormatError();
 		}
 
 		const nonce = remaining.subarray(0, nonceSize);
 		const ciphertextAndTag = remaining.subarray(nonceSize);
 
 		if (ciphertextAndTag.length < GCM_TAG) {
-			throw new Error('invalid wrapped DEK format');
+			throw new InvalidDEKFormatError();
 		}
 
 		const ciphertext = ciphertextAndTag.subarray(0, ciphertextAndTag.length - GCM_TAG);
@@ -158,8 +210,8 @@ function unwrapDEKWithECDH(wrapped: Buffer, recipientPriv: KeyObject): Buffer {
 		let plaintext: Buffer;
 		try {
 			plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
-		} catch (_err) {
-			throw new Error('DEK unwrap failed');
+		} catch (err) {
+			throw new DEKUnwrappedFailedError({ cause: err });
 		}
 
 		kek.fill(0);
@@ -182,11 +234,11 @@ export async function encryptFIPSKEMDEMStream(
 	dst: Writable
 ): Promise<number> {
 	if (pub.asymmetricKeyType !== 'ec') {
-		throw new Error('only EC keys supported');
+		throw new InvalidKeyECOnlyError();
 	}
 	const keyDetails = pub.asymmetricKeyDetails;
 	if (!keyDetails || keyDetails.namedCurve !== 'prime256v1') {
-		throw new Error('only P-256 keys supported');
+		throw new InvalidKeyP256OnlyError();
 	}
 
 	const dek = randomBytes(DEK_SIZE);
@@ -234,7 +286,7 @@ export async function encryptFIPSKEMDEMStream(
 			const ct = Buffer.concat([ciphertext, tag]);
 
 			if (ct.length > 0xffff) {
-				throw new Error('ciphertext length exceeds uint16 limit');
+				throw new InvalidCipherTextLengthError();
 			}
 
 			const ctLenBuf = Buffer.alloc(2);
@@ -264,11 +316,11 @@ export async function decryptFIPSKEMDEMStream(
 	dst: Writable
 ): Promise<number> {
 	if (priv.asymmetricKeyType !== 'ec') {
-		throw new Error('only EC keys supported');
+		throw new InvalidKeyECOnlyError();
 	}
 	const keyDetails = priv.asymmetricKeyDetails;
 	if (!keyDetails || keyDetails.namedCurve !== 'prime256v1') {
-		throw new Error('only P-256 keys supported');
+		throw new InvalidKeyP256OnlyError();
 	}
 
 	const it = src[Symbol.asyncIterator]();
@@ -279,7 +331,7 @@ export async function decryptFIPSKEMDEMStream(
 		const wrappedLen = lenBuf.readUInt16BE(0);
 
 		if (wrappedLen === 0 || wrappedLen > 200) {
-			throw new Error('invalid wrapped DEK length');
+			throw new InvalidWrappedDEKLengthError();
 		}
 
 		const wrapped = Buffer.alloc(wrappedLen);
@@ -305,19 +357,19 @@ export async function decryptFIPSKEMDEMStream(
 					break;
 				}
 				if (chunkLenRead < 2) {
-					throw new Error('unexpected EOF reading chunk length');
+					throw new UnexpectedEOFChunkLengthError();
 				}
 
 				const chunkLen = chunkLenBuf.readUInt16BE(0);
 				if (chunkLen > FRAME + GCM_TAG) {
-					throw new Error('chunk too large');
+					throw new UnexpectedChunkTooLargeError();
 				}
 
 				const cipherBuf = Buffer.alloc(chunkLen);
 				await readExact(it, src, cipherBuf);
 
 				if (cipherBuf.length < GCM_TAG) {
-					throw new Error('chunk too short for auth tag');
+					throw new UnexpectedChunkTooShortError();
 				}
 
 				const ciphertext = cipherBuf.subarray(0, cipherBuf.length - GCM_TAG);
@@ -438,7 +490,7 @@ async function readExact(
 	while (offset < buf.length) {
 		const result = await iterator.next();
 		if (result.done) {
-			throw new Error('unexpected EOF');
+			throw new UnexpectedEOFError();
 		}
 
 		const chunk = result.value;

package/src/download.ts

@@ -1,5 +1,6 @@
 import { Transform, Readable } from 'node:stream';
 import * as tui from './tui';
+import { APIError } from '@agentuity/server';
 
 export interface DownloadOptions {
 	url: string;
@@ -25,7 +26,12 @@ export async function downloadWithProgress(
 
 	const response = await fetch(url, { headers: requestHeaders });
 	if (!response.ok) {
-		throw new Error(`Download failed: ${response.statusText}`);
+		throw new APIError({
+			url,
+			status: response.status,
+			sessionId: response.headers.get('x-session-id'),
+			error: `Download failed: ${response.statusText}`,
+		});
 	}
 
 	const contentLength = parseInt(response.headers.get('content-length') || '0', 10);

package/src/env-util.ts

@@ -204,6 +204,9 @@ export function splitEnvAndSecrets(vars: EnvVars): {
 
 /**
  * Mask a secret value for display
+ * - For URLs with credentials: parses and masks username/password partially
+ * - For long strings: shows more context (first 6 and last 6 chars)
+ * - For short strings: shows generic masking
  */
 export function maskSecret(value: string): string {
 	if (!value) {
@@ -214,8 +217,47 @@ export function maskSecret(value: string): string {
 		return '***';
 	}
 
-	// Show first 4 and last 4 characters
-	return `${value.slice(0, 4)}...${value.slice(-4)}`;
+	// Try to parse as URL with credentials
+	try {
+		const url = new URL(value);
+
+		// If URL has username or password, mask them partially
+		if (url.username || url.password) {
+			let maskedAuth = '';
+
+			if (url.username) {
+				// Show first 2 and last 2 chars of username
+				const len = url.username.length;
+				if (len <= 4) {
+					maskedAuth = '***';
+				} else {
+					maskedAuth = `${url.username.slice(0, 2)}***${url.username.slice(-2)}`;
+				}
+			}
+
+			if (url.password) {
+				// Show first 3 and last 3 chars of password
+				const len = url.password.length;
+				if (len <= 6) {
+					maskedAuth += ':***';
+				} else {
+					maskedAuth += `:${url.password.slice(0, 3)}***${url.password.slice(-3)}`;
+				}
+			} else if (url.username) {
+				// Username but no password
+				maskedAuth += ':***';
+			}
+
+			// Reconstruct URL with masked credentials
+			const maskedUrl = `${url.protocol}//${maskedAuth}@${url.host}${url.pathname}${url.search}${url.hash}`;
+			return maskedUrl;
+		}
+	} catch {
+		// Not a valid URL, fall through to regular masking
+	}
+
+	// For long strings, show first 6 and last 6 characters for better context
+	return `${value.slice(0, 6)}...${value.slice(-6)}`;
 }
 
 /**

package/src/errors.ts

@@ -13,6 +13,7 @@ export enum ExitCode {
 	NETWORK_ERROR = 6,
 	FILE_ERROR = 7,
 	USER_CANCELLED = 8,
+	BUILD_FAILED = 9,
 }
 
 /**
@@ -68,6 +69,9 @@ export enum ErrorCode {
 
 	// User cancellation
 	USER_CANCELLED = 'USER_CANCELLED',
+
+	// Build failed error
+	BUILD_FAILED = 'BUILD_FAILED',
 }
 
 /**
@@ -121,6 +125,10 @@ export function getExitCode(errorCode: ErrorCode): ExitCode {
 		case ErrorCode.USER_CANCELLED:
 			return ExitCode.USER_CANCELLED;
 
+		// Build errors
+		case ErrorCode.BUILD_FAILED:
+			return ExitCode.BUILD_FAILED;
+
 		// Resource conflicts and other errors
 		case ErrorCode.RESOURCE_ALREADY_EXISTS:
 		case ErrorCode.RESOURCE_CONFLICT:
@@ -203,7 +211,7 @@ export function exitWithError(
 	if (errorFormat === 'json') {
 		console.error(formatErrorJSON(error));
 	} else {
-		console.error(formatErrorHuman(error));
+		logger.error(formatErrorHuman(error));
 	}
 	const exitCode = error.exitCode ?? getExitCode(error.code);
 	process.exit(exitCode);

package/src/index.ts

@@ -1,6 +1,11 @@
 export { createCLI, registerCommands } from './cli';
 export { validateRuntime, isBun } from './runtime';
-export { generateCLISchema, type CLISchema, type SchemaCommand } from './schema-generator';
+export {
+	generateCLISchema,
+	type CLISchema,
+	type SchemaCommand,
+	type SchemaExample,
+} from './schema-generator';
 export {
 	ErrorCode,
 	createError,

package/src/schema-generator.ts

@@ -31,13 +31,18 @@ export interface SchemaPagination {
 	};
 }
 
+export interface SchemaExample {
+	command: string;
+	description: string;
+}
+
 export interface SchemaCommand {
 	name: string;
 	description: string;
 	aliases?: string[];
 	arguments?: SchemaArgument[];
 	options?: SchemaOption[];
-	examples?: string[];
+	examples?: SchemaExample[];
 	response?: unknown;
 	idempotent?: boolean;
 	prerequisites?: string[];
@@ -280,6 +285,7 @@ export function generateCLISchema(
 			6: 'Network error (API unreachable or timeout)',
 			7: 'File system error (file read/write failed)',
 			8: 'User cancelled (operation aborted by user)',
+			9: 'Build failed',
 		},
 		globalOptions: [
 			{