@agentuity/cli 0.0.101 → 0.0.102

package/src/cmd/project/template-flow.ts

@@ -29,12 +29,14 @@ import {
 	filterAgentuitySdkKeys,
 	splitEnvAndSecrets,
 } from '../../env-util';
+import { promptForDNS } from '../../domain';
 
 type ResourcesTypes = z.infer<typeof Resources>;
 
 interface CreateFlowOptions {
 	projectName?: string;
 	dir?: string;
+	domains?: string[];
 	template?: string;
 	templateDir?: string;
 	templateBranch?: string;
@@ -63,6 +65,7 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 		orgId: selectedOrgId,
 		region,
 		apiClient,
+		domains,
 	} = options;
 
 	// Fetch available templates
@@ -105,7 +108,8 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 	if (!projectName && !skipPrompts) {
 		projectName = await prompt.text({
 			message: 'What is the name of your project?',
-			initial: 'My First Agent',
+			hint: 'The name must be unique for your organization',
+			initial: '',
 			validate: async (value: string) => {
 				if (!value || value.trim().length === 0) {
 					return 'Project name is required';
@@ -249,6 +253,7 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 	}
 
 	const resourceConfig: ResourcesTypes = Resources.parse({});
+	let _domains = domains;
 
 	if (auth && apiClient && catalystClient && orgId && region && !skipPrompts) {
 		// Fetch resources for selected org and region using Catalyst API
@@ -265,8 +270,8 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 		const db_action = await prompt.select({
 			message: 'Create SQL Database?',
 			options: [
-				{ value: 'Create New', label: 'Create a new (free)' },
 				{ value: 'Skip', label: 'Skip or Setup later' },
+				{ value: 'Create New', label: 'Create a new database' },
 				...resources.db.map((db) => ({
 					value: db.name,
 					label: `Use database: ${tui.tuiColors.primary(db.name)}`,
@@ -277,8 +282,8 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 		const s3_action = await prompt.select({
 			message: 'Create Storage Bucket?',
 			options: [
-				{ value: 'Create New', label: 'Create a new (free)' },
 				{ value: 'Skip', label: 'Skip or Setup later' },
+				{ value: 'Create New', label: 'Create a new bucket' },
 				...resources.s3.map((bucket) => ({
 					value: bucket.bucket_name,
 					label: `Use bucket: ${tui.tuiColors.primary(bucket.bucket_name)}`,
@@ -286,6 +291,22 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 			],
 		});
 
+		if (!domains?.length) {
+			const customDns = await prompt.text({
+				message: 'Setup custom DNS?',
+				hint: 'Enter a domain name or press Enter to skip',
+				validate: (val: string) =>
+					val === ''
+						? true
+						: /^(?=.{1,253}$)(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[A-Za-z]{2,63}$/.test(
+								val
+							),
+			});
+			if (customDns) {
+				_domains = [customDns];
+			}
+		}
+
 		const choices = { db_action, s3_action };
 		switch (choices.s3_action) {
 			case 'Create New': {
@@ -329,9 +350,9 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 		}
 	}
 
-	if (auth && apiClient && orgId) {
-		let projectId: string | undefined;
+	let projectId: string | undefined;
 
+	if (auth && apiClient && orgId) {
 		const cloudRegion = region ?? process.env.AGENTUITY_REGION ?? 'usc';
 
 		const pkgJsonPath = resolve(dest, 'package.json');
@@ -355,6 +376,7 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 					tags: tags.length > 0 ? tags : undefined,
 					orgId,
 					cloudRegion,
+					domains: _domains,
 				});
 				projectId = project.id;
 				return createProjectConfig(dest, {
@@ -363,6 +385,7 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 					sdkKey: project.sdkKey,
 					deployment: {
 						resources: resourceConfig,
+						domains: _domains,
 					},
 					region: cloudRegion,
 				});
@@ -426,6 +449,15 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 	}
 
 	playSound();
+
+	if (process.stdin.isTTY && !skipPrompts && _domains?.length && projectId) {
+		tui.newline();
+		const ok = await tui.confirm('Would you like to configure DNS now?', true);
+		if (ok) {
+			tui.newline();
+			await promptForDNS(projectId, _domains, config);
+		}
+	}
 }
 
 /**

package/src/cmd/setup/index.ts

@@ -9,6 +9,7 @@ export const command = createCommand({
 	description: 'Display first-run setup information (internal use)',
 	hidden: true,
 	skipUpgradeCheck: true,
+	skipSkill: true,
 	tags: ['read-only', 'fast'],
 	optional: { auth: true },
 	schema: {

package/src/cmd/upgrade/index.ts

@@ -6,9 +6,39 @@ import { ErrorCode, createError, exitWithError } from '../../errors';
 import * as tui from '../../tui';
 import { downloadWithProgress } from '../../download';
 import { $ } from 'bun';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { tmpdir } from 'node:os';
 import { randomUUID } from 'node:crypto';
+import { access, constants } from 'node:fs/promises';
+import { StructuredError } from '@agentuity/core';
+
+export const PermissionError = StructuredError('PermissionError')<{
+	binaryPath: string;
+	reason: string;
+}>();
+
+async function checkWritePermission(binaryPath: string): Promise<void> {
+	try {
+		await access(binaryPath, constants.W_OK);
+	} catch {
+		throw new PermissionError({
+			binaryPath,
+			reason: `Cannot write to ${binaryPath}. You may need to run with elevated permissions (e.g., sudo) or reinstall to a user-writable location.`,
+			message: `Permission denied: Cannot write to ${binaryPath}`,
+		});
+	}
+
+	const parentDir = dirname(binaryPath);
+	try {
+		await access(parentDir, constants.W_OK);
+	} catch {
+		throw new PermissionError({
+			binaryPath,
+			reason: `Cannot write to directory ${parentDir}. You may need to run with elevated permissions (e.g., sudo) or reinstall to a user-writable location.`,
+			message: `Permission denied: Cannot write to directory ${parentDir}`,
+		});
+	}
+}
 
 const UpgradeOptionsSchema = z.object({
 	force: z.boolean().optional().describe('Force upgrade even if version is the same'),
@@ -316,7 +346,7 @@ export const command = createCommand({
 				};
 			}
 
-			// Confirm upgrade
+			// Show version info
 			if (!force) {
 				tui.info(`Current version: ${tui.muted(normalizedCurrent)}`);
 				tui.info(`Latest version:  ${tui.bold(normalizedLatest)}`);
@@ -328,7 +358,43 @@ export const command = createCommand({
 				}
 				tui.success(`Release notes:   ${tui.link(getReleaseUrl(latestVersion))}`);
 				tui.newline();
+			}
 
+			// Check write permissions before prompting - fail early with helpful message
+			try {
+				await checkWritePermission(currentBinaryPath);
+			} catch (error) {
+				if (error instanceof PermissionError) {
+					tui.error('Unable to upgrade: permission denied');
+					tui.newline();
+					tui.warning(`The CLI binary at ${tui.bold(error.binaryPath)} is not writable.`);
+					tui.newline();
+					if (process.env.AGENTUITY_RUNTIME) {
+						console.log('You cannot self-upgrade the agentuity cli in the cloud runtime.');
+						console.log('The runtime will automatically update the cli and other software');
+						console.log('within a day or so. If you need assistance, please contact us');
+						console.log('at support@agentuity.com.');
+					} else {
+						console.log('To fix this, you can either:');
+						console.log(
+							`  1. Run with elevated permissions: ${tui.muted('sudo agentuity upgrade')}`
+						);
+						console.log(`  2. Reinstall to a user-writable location`);
+					}
+					tui.newline();
+					exitWithError(
+						createError(ErrorCode.PERMISSION_DENIED, 'Upgrade failed: permission denied', {
+							path: error.binaryPath,
+						}),
+						logger,
+						options.errorFormat
+					);
+				}
+				throw error;
+			}
+
+			// Confirm upgrade
+			if (!force) {
 				const shouldUpgrade = await tui.confirm('Do you want to upgrade?', true);
 
 				if (!shouldUpgrade) {
@@ -383,13 +449,11 @@ export const command = createCommand({
 				message,
 			};
 		} catch (error) {
-			// Parse validation errors to extract stdout/stderr if present
 			let errorDetails: Record<string, unknown> = {
 				error: error instanceof Error ? error.message : 'Unknown error',
 			};
 
 			if (error instanceof Error && error.message.includes('Binary validation failed')) {
-				// Extract stdout/stderr from validation error
 				const match = error.message.match(
 					/Failed with exit code (\d+)\n(stdout: .+\n)?(stderr: .+)?/s
 				);

package/src/domain.ts

@@ -0,0 +1,273 @@
+import type { Config } from './types';
+import { StructuredError } from '@agentuity/core';
+import * as tui from './tui';
+
+interface BaseDNSResult {
+	domain: string;
+	target: string;
+	recordType: string;
+}
+
+interface DNSSuccess extends BaseDNSResult {
+	success: true;
+}
+
+interface DNSPending extends BaseDNSResult {
+	success: true;
+	pending: true;
+}
+
+interface DNSMissing extends BaseDNSResult {
+	success: false;
+	pending: false;
+}
+
+interface DNSError extends BaseDNSResult {
+	success: false;
+	error: string;
+}
+
+interface DNSMisconfigured extends BaseDNSResult {
+	success: false;
+	misconfigured: string;
+}
+
+export type DNSResult = DNSSuccess | DNSPending | DNSMissing | DNSError | DNSMisconfigured;
+export type DNSFailed = DNSPending | DNSMissing | DNSError | DNSMisconfigured;
+
+export function isMisconfigured(x: DNSResult): x is DNSMisconfigured {
+	return 'misconfigured' in x && !!x.misconfigured;
+}
+
+export function isMissing(x: DNSResult): x is DNSMissing {
+	return 'pending' in x && x.pending === false && 'success' in x && x.success === false;
+}
+
+export function isError(x: DNSResult): x is DNSError {
+	return 'error' in x && !!x.error;
+}
+
+export function isPending(x: DNSResult): x is DNSPending {
+	return 'pending' in x && x.pending === true && x.success === true;
+}
+
+export function isSuccess(x: DNSResult): x is DNSSuccess {
+	return x.success == true && !('pending' in x) && !('error' in x) && !('misconfigured' in x);
+}
+
+const timeoutMs = 5000;
+
+const DNSTimeoutError = StructuredError(
+	'DNSTimeoutError',
+	`DNS lookup timed out after ${timeoutMs}ms`
+);
+
+interface CFRecord {
+	Answer?: {
+		data: string;
+	}[];
+}
+
+async function fetchDNSRecord(name: string, type: string): Promise<string | null> {
+	const params = new URLSearchParams();
+	params.set('name', name);
+	params.set('type', type);
+	const res = await fetch(`https://cloudflare-dns.com/dns-query?${params.toString()}`, {
+		headers: {
+			Accept: 'application/dns-json',
+		},
+	});
+	if (res.ok) {
+		const result = (await res.json()) as CFRecord;
+		if (result?.Answer?.length) {
+			return result.Answer[0].data.replace(/\.$/, ''); // DNS records end with . so we remove that
+		}
+	}
+	return null;
+}
+
+const LOCAL_DNS = 'agentuity.io';
+const PRODUCTION_DNS = 'agentuity.run';
+
+/**
+ * This function will check for each of the custom domains and make sure they are correctly
+ * configured in DNS
+ *
+ * @param projectId the project id
+ * @param config Config
+ * @param domains array of domains to check
+ * @returns
+ */
+export async function checkCustomDomainForDNS(
+	projectId: string,
+	domains: string[],
+	config?: Config | null
+): Promise<DNSResult[]> {
+	const suffix = config?.overrides?.api_url?.includes('agentuity.io') ? LOCAL_DNS : PRODUCTION_DNS;
+	const id = Bun.hash.xxHash64(projectId).toString(16);
+	const proxy = `p${id}.${suffix}`;
+
+	return Promise.all(
+		domains.map(async (domain) => {
+			try {
+				let timeoutId: Timer | undefined;
+
+				const timeoutPromise = new Promise<never>((_, reject) => {
+					timeoutId = setTimeout(() => {
+						reject(new DNSTimeoutError());
+					}, timeoutMs);
+				});
+
+				const result = await Promise.race([
+					fetchDNSRecord(domain, 'CNAME'),
+					timeoutPromise,
+				]).finally(() => {
+					if (timeoutId) clearTimeout(timeoutId);
+				});
+
+				if (result) {
+					if (result === proxy) {
+						return {
+							domain,
+							target: proxy,
+							recordType: 'CNAME',
+							success: true,
+						} as DNSSuccess;
+					}
+					return {
+						domain,
+						target: proxy,
+						recordType: 'CNAME',
+						success: false,
+						misconfigured: `CNAME record is ${result}`,
+					} as DNSMisconfigured;
+				}
+			} catch (ex) {
+				const _ex = ex as { code: string; message?: string };
+				if (_ex.message?.includes('timed out')) {
+					return {
+						domain,
+						target: proxy,
+						recordType: 'CNAME',
+						success: false,
+						error: `DNS lookup timed out after 5 seconds. Please check your DNS configuration.`,
+					} as DNSError;
+				}
+				if (_ex.code !== 'ENOTFOUND') {
+					const errMsg =
+						ex instanceof Error
+							? ex.message
+							: typeof ex === 'string'
+								? ex
+								: JSON.stringify(ex);
+					return {
+						domain,
+						target: proxy,
+						recordType: 'CNAME',
+						success: false,
+						error: errMsg,
+					} as DNSError;
+				}
+			}
+			return {
+				domain,
+				success: false,
+				target: proxy,
+				recordType: 'CNAME',
+				pending: false,
+			} as DNSMissing;
+		})
+	);
+}
+
+export async function promptForDNS(
+	projectId: string,
+	domains: string[],
+	config?: Config,
+	resumeFn?: () => () => void
+) {
+	let paused = false;
+	let resume: (() => void) | undefined;
+	for (;;) {
+		const result = await checkCustomDomainForDNS(projectId, domains, config);
+		const failed = result.filter((x): x is DNSFailed => !isSuccess(x));
+		if (failed.length) {
+			const records: {
+				domain: string;
+				type: string;
+				target: string;
+				status: string;
+			}[] = [];
+			result.forEach((r) => {
+				if (isSuccess(r)) {
+					records.push({
+						domain: r.domain,
+						type: r.recordType,
+						target: r.target,
+						status: tui.colorSuccess(`${tui.ICONS.success} Configured`),
+					});
+				}
+			});
+			if (!paused) {
+				resume = resumeFn?.();
+				paused = true;
+			}
+			tui.error(
+				`You have ${tui.plural(failed.length, 'a ', '')}DNS configuration ${tui.plural(failed.length, 'issue', 'issues')} that must be resolved before deploying:`
+			);
+			for (const r of failed) {
+				if (isError(r)) {
+					resume?.();
+					throw new Error(r.error);
+				} else if (isMisconfigured(r)) {
+					records.push({
+						domain: r.domain,
+						type: r.recordType,
+						target: r.target,
+						status: tui.colorWarning(`${tui.ICONS.error} ${r.misconfigured}`),
+					});
+				} else if (isPending(r)) {
+					records.push({
+						domain: r.domain,
+						type: r.recordType,
+						target: r.target,
+						status: tui.colorWarning('⌛️ Pending'),
+					});
+				} else if (isMissing(r)) {
+					records.push({
+						domain: r.domain,
+						type: r.recordType,
+						target: r.target,
+						status: tui.colorError(`${tui.ICONS.error} Missing`),
+					});
+				}
+			}
+
+			let linesShown = 2; // header + footer
+			for (const record of records) {
+				console.log();
+				console.log(`${tui.colorInfo('Domain:')}  ${tui.colorPrimary(record.domain)}`);
+				console.log(`${tui.colorInfo('Type:')}    ${tui.colorPrimary(record.type)}`);
+				console.log(`${tui.colorInfo('Target:')}  ${tui.colorPrimary(record.target)}`);
+				console.log(`${tui.colorInfo('Status:')}  ${tui.colorPrimary(record.status)}`);
+				console.log();
+				linesShown += 6;
+			}
+
+			// await tui.waitForAnyKey('Press any key to check again or ctrl+c to cancel...');
+			await tui.spinner({
+				message: 'Checking again in 5s...',
+				clearOnSuccess: true,
+				callback: () => {
+					return Bun.sleep(5000);
+				},
+			});
+			tui.clearLastLines(linesShown);
+			linesShown = 0;
+			continue;
+		}
+		tui.clearLastLines(1);
+		resume?.();
+		break;
+	}
+}

package/src/schema-generator.ts

@@ -48,6 +48,8 @@ export interface SchemaCommand {
 	prerequisites?: string[];
 	pagination?: SchemaPagination;
 	tags?: string[];
+	skipSkill?: boolean;
+	toplevel?: boolean;
 	subcommands?: SchemaCommand[];
 	requires?: {
 		auth?: boolean;
@@ -121,6 +123,13 @@ function extractCommandSchema(def: CommandDefinition): SchemaCommand {
 		schema.tags = (def as any).tags;
 	}
 
+	// Extract skipSkill
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((def as any).skipSkill !== undefined) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		schema.skipSkill = (def as any).skipSkill;
+	}
+
 	// Extract requires/optional
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	const d = def as any;
@@ -202,6 +211,20 @@ function extractSubcommandSchema(def: SubcommandDefinition): SchemaCommand {
 		schema.tags = (def as any).tags;
 	}
 
+	// Extract skipSkill
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((def as any).skipSkill !== undefined) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		schema.skipSkill = (def as any).skipSkill;
+	}
+
+	// Extract toplevel
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((def as any).toplevel !== undefined) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		schema.toplevel = (def as any).toplevel;
+	}
+
 	// Extract requires/optional
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	const d = def as any;

package/src/steps.ts

@@ -8,6 +8,7 @@
 import type { ColorScheme } from './terminal';
 import type { LogLevel } from './types';
 import { ValidationInputError, ValidationOutputError, type IssuesType } from '@agentuity/server';
+import { clearLastLines } from './tui';
 
 // Spinner frames
 const FRAMES = ['◐', '◓', '◑', '◒'];
@@ -210,7 +211,7 @@ function enablePauseResume(
  * Pause step rendering for interactive input
  * Returns resume function
  */
-export function pauseStepUI(): () => void {
+export function pauseStepUI(clear = false): () => void {
 	if (!process.stdout.isTTY || !getTotalLinesFn) {
 		return () => {}; // No-op if not TTY or not in step context
 	}
@@ -232,8 +233,16 @@ export function pauseStepUI(): () => void {
 	}) as typeof process.stderr.write;
 
 	// Show cursor and add newline for separation
-	process.stdout.write('\x1B[?25h');
-	process.stdout.write('\n');
+	if (clear) {
+		const lines = getTotalLinesFn();
+		if (lines) {
+			clearLastLines(lines + 1, originalStdoutWrite);
+		}
+	}
+	originalStdoutWrite('\x1B[?25h');
+	if (!clear) {
+		originalStdoutWrite('\n');
+	}
 
 	// Return resume function
 	return () => {
@@ -244,8 +253,10 @@ export function pauseStepUI(): () => void {
 		process.stderr.write = originalStderrWrite;
 
 		// Restore cursor to saved position (where steps began)
-		process.stdout.write('\x1B[u'); // Restore cursor position
-		process.stdout.write('\x1B[0J'); // Clear from saved position to end of screen
+		if (!clear) {
+			process.stdout.write('\x1B[u'); // Restore cursor position
+			process.stdout.write('\x1B[0J'); // Clear from saved position to end of screen
+		}
 		process.stdout.write('\x1B[?25l'); // Hide cursor
 
 		// Force immediate re-render (cursor already at step start)

package/src/tui/prompt.ts

@@ -13,7 +13,7 @@ interface KeypressEvent {
 export interface TextOptions {
 	message: string;
 	initial?: string;
-	placeholder?: string;
+	hint?: string;
 	validate?: (value: string) => boolean | string | Promise<boolean | string>;
 }
 
@@ -54,7 +54,6 @@ interface PromptState {
  */
 export class PromptFlow {
 	private states: PromptState[] = [];
-	private hasIntro = false;
 
 	/**
 	 * Display intro banner
@@ -62,7 +61,6 @@ export class PromptFlow {
 	intro(title: string): void {
 		console.log(`${colors.secondary(symbols.squareTL)}   ${colors.inverseCyan(` ⨺ ${title} `)}`);
 		console.log(colors.secondary(symbols.bar));
-		this.hasIntro = true;
 	}
 
 	/**
@@ -96,10 +94,16 @@ export class PromptFlow {
 			});
 
 			let hasError = false;
+			let hadValidationError = false;
 
 			const showPrompt = () => {
 				// Show prompt with active symbol
 				process.stdout.write(`${colors.active(symbols.active)}  ${message}\n`);
+				if (options.hint) {
+					process.stdout.write(
+						`${colors.secondary(symbols.bar)}  ${colors.muted(options.hint)}\n`
+					);
+				}
 				// Use readline's prompt for the input line
 				rl.prompt();
 			};
@@ -108,7 +112,8 @@ export class PromptFlow {
 
 			rl.on('line', async (input) => {
 				const trimmed = input.trim();
-				const value = trimmed.length > 0 ? trimmed : initial;
+				// After a validation error, require explicit input - don't fall back to initial
+				const value = trimmed.length > 0 ? trimmed : hadValidationError ? '' : initial;
 
 				// Validate
 				if (validate) {
@@ -129,6 +134,7 @@ export class PromptFlow {
 							// Use readline's prompt for the input line
 							rl.prompt();
 							hasError = true;
+							hadValidationError = true;
 							return;
 						}
 					} catch (error) {
@@ -156,7 +162,7 @@ export class PromptFlow {
 				}
 
 				// Clear all lines and show completed state
-				const linesToClear = hasError ? 3 : 2;
+				const linesToClear = hasError ? 4 : 3;
 				readline.moveCursor(process.stdout, 0, -linesToClear);
 				readline.clearScreenDown(process.stdout);