@agentuity/cli 1.0.10 → 1.0.12

package/src/cmd/project/domain/check.ts

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { getCommand } from '../../../command-prefix';
+import { loadProjectConfig } from '../../../config';
+import { isJSONMode } from '../../../output';
+import {
+	checkCustomDomainForDNS,
+	isSuccess,
+	isPending,
+	isMissing,
+	isMisconfigured,
+	isError,
+} from '../../../domain';
+
+export const checkSubcommand = createSubcommand({
+	name: 'check',
+	description: 'Check DNS configuration for custom domains',
+	tags: ['read-only', 'slow', 'requires-auth', 'requires-project'],
+	requires: { auth: true, project: true },
+	idempotent: true,
+	examples: [
+		{
+			command: getCommand('project domain check'),
+			description: 'Check all configured domains',
+		},
+		{
+			command: getCommand('project domain check --domain example.com'),
+			description: 'Check a specific domain',
+		},
+	],
+	schema: {
+		options: z.object({
+			domain: z.string().optional().describe('Specific domain to check'),
+		}),
+		response: z.object({
+			domains: z.array(
+				z.object({
+					domain: z.string(),
+					recordType: z.string(),
+					target: z.string(),
+					status: z.string(),
+					success: z.boolean(),
+				})
+			),
+		}),
+	},
+
+	async handler(ctx) {
+		const { opts, options, projectDir, config, project } = ctx;
+		const jsonMode = isJSONMode(options);
+
+		// Determine which domains to check
+		let domainsToCheck: string[];
+
+		if (opts?.domain) {
+			domainsToCheck = [opts.domain.toLowerCase().trim()];
+		} else {
+			const projectConfig = await loadProjectConfig(projectDir, config);
+			domainsToCheck = projectConfig.deployment?.domains ?? [];
+		}
+
+		if (domainsToCheck.length === 0) {
+			if (!jsonMode) {
+				tui.info('No custom domains configured for this project');
+				tui.info(`Use ${tui.bold(getCommand('project add domain <domain>'))} to add one`);
+			}
+			return { domains: [] };
+		}
+
+		const results = jsonMode
+			? await checkCustomDomainForDNS(project.projectId, domainsToCheck, config)
+			: await tui.spinner({
+					message: `Checking DNS for ${domainsToCheck.length} ${tui.plural(domainsToCheck.length, 'domain', 'domains')}`,
+					clearOnSuccess: true,
+					callback: () => checkCustomDomainForDNS(project.projectId, domainsToCheck, config),
+				});
+
+		const domainResults = results.map((r) => {
+			let status: string;
+			let statusRaw: string;
+			let success = false;
+
+			if (isSuccess(r)) {
+				status = tui.colorSuccess(`${tui.ICONS.success} Configured`);
+				statusRaw = 'configured';
+				success = true;
+			} else if (isPending(r)) {
+				status = tui.colorWarning('⏳ Pending');
+				statusRaw = 'pending';
+			} else if (isMisconfigured(r)) {
+				status = tui.colorWarning(`${tui.ICONS.warning} ${r.misconfigured}`);
+				statusRaw = 'misconfigured';
+			} else if (isError(r)) {
+				status = tui.colorError(`${tui.ICONS.error} ${r.error}`);
+				statusRaw = 'error';
+			} else if (isMissing(r)) {
+				status = tui.colorError(`${tui.ICONS.error} Missing`);
+				statusRaw = 'missing';
+			} else {
+				status = tui.colorError(`${tui.ICONS.error} Unknown`);
+				statusRaw = 'unknown';
+			}
+
+			return {
+				domain: r.domain,
+				recordType: r.recordType,
+				target: r.target,
+				status,
+				statusRaw,
+				success,
+			};
+		});
+
+		if (!jsonMode) {
+			tui.newline();
+			for (const r of domainResults) {
+				console.log(`  ${tui.colorInfo('Domain:')}  ${tui.colorPrimary(r.domain)}`);
+				console.log(`  ${tui.colorInfo('Type:')}    ${tui.colorPrimary(r.recordType)}`);
+				console.log(`  ${tui.colorInfo('Target:')}  ${tui.colorPrimary(r.target)}`);
+				console.log(`  ${tui.colorInfo('Status:')}  ${r.status}`);
+				console.log();
+			}
+
+			const allGood = domainResults.every((r) => r.success);
+			if (allGood) {
+				tui.success('All domains are correctly configured');
+			} else {
+				const failCount = domainResults.filter((r) => !r.success).length;
+				tui.warning(
+					`${failCount} ${tui.plural(failCount, 'domain has', 'domains have')} DNS issues — add a CNAME record pointing to the target shown above`
+				);
+			}
+		}
+
+		return {
+			domains: domainResults.map((r) => ({
+				domain: r.domain,
+				recordType: r.recordType,
+				target: r.target,
+				status: r.statusRaw,
+				success: r.success,
+			})),
+		};
+	},
+});

package/src/cmd/project/domain/index.ts

@@ -0,0 +1,20 @@
+import { createCommand } from '../../../types';
+import { checkSubcommand } from './check';
+import { getCommand } from '../../../command-prefix';
+
+export const domainCommand = createCommand({
+	name: 'domain',
+	description: 'Manage custom domains for the project',
+	tags: ['fast', 'requires-auth'],
+	examples: [
+		{
+			command: getCommand('project domain check'),
+			description: 'Check DNS for all custom domains',
+		},
+		{
+			command: getCommand('project domain check --domain example.com'),
+			description: 'Check DNS for a specific domain',
+		},
+	],
+	subcommands: [checkSubcommand],
+});

package/src/cmd/project/hostname/get.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { projectHostnameGet } from '@agentuity/server';
+import { getCommand } from '../../../command-prefix';
+import { isJSONMode } from '../../../output';
+
+const HostnameGetResponseSchema = z.object({
+	hostname: z.string().nullable().describe('The vanity hostname'),
+	url: z.string().nullable().describe('The full URL'),
+});
+
+export const getSubcommand = createSubcommand({
+	name: 'get',
+	description: 'Show the current vanity hostname for the project',
+	tags: ['read-only', 'fast', 'requires-auth', 'requires-project'],
+	requires: { auth: true, apiClient: true, project: true },
+	idempotent: true,
+	examples: [
+		{
+			command: getCommand('project hostname get'),
+			description: 'Show current hostname',
+		},
+	],
+	schema: {
+		response: HostnameGetResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { apiClient, project, options } = ctx;
+		const jsonMode = isJSONMode(options);
+
+		const result = jsonMode
+			? await projectHostnameGet(apiClient, { projectId: project.projectId })
+			: await tui.spinner('Fetching hostname', () => {
+					return projectHostnameGet(apiClient, { projectId: project.projectId });
+				});
+
+		if (!jsonMode) {
+			if (result.hostname) {
+				tui.success(`Hostname: ${tui.bold(result.hostname)}`);
+				tui.info(`URL: ${result.url}`);
+			} else {
+				tui.info('No vanity hostname set for this project');
+				tui.info(`Use ${tui.bold(getCommand('project hostname set <hostname>'))} to set one`);
+			}
+		}
+
+		return {
+			hostname: result.hostname,
+			url: result.url,
+		};
+	},
+});

package/src/cmd/project/hostname/index.ts

@@ -0,0 +1,18 @@
+import { createCommand } from '../../../types';
+import { getSubcommand } from './get';
+import { setSubcommand } from './set';
+import { getCommand } from '../../../command-prefix';
+
+export const hostnameCommand = createCommand({
+	name: 'hostname',
+	description: 'Manage the project vanity hostname on agentuity.run',
+	tags: ['fast', 'requires-auth'],
+	examples: [
+		{ command: getCommand('project hostname get'), description: 'Show current hostname' },
+		{
+			command: getCommand('project hostname set my-cool-api'),
+			description: 'Set a custom hostname',
+		},
+	],
+	subcommands: [getSubcommand, setSubcommand],
+});

package/src/cmd/project/hostname/set.ts

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { projectHostnameSet } from '@agentuity/server';
+import { getCommand } from '../../../command-prefix';
+import { isJSONMode } from '../../../output';
+import { ErrorCode } from '../../../errors';
+
+// Client-side reserved names list (mirrors server-side list)
+const RESERVED_NAMES = new Set([
+	'app',
+	'api',
+	'catalyst',
+	'pulse',
+	'streams',
+	'registry',
+	'ion',
+	'status',
+	'admin',
+	'www',
+	'mail',
+	'dns',
+	'console',
+	'dashboard',
+	'docs',
+	'help',
+	'support',
+	'billing',
+	'test',
+	'staging',
+	'dev',
+	'prod',
+	'ns0',
+	'ns1',
+	'ns2',
+]);
+
+const HostnameSetResponseSchema = z.object({
+	hostname: z.string().describe('The vanity hostname that was set'),
+	url: z.string().describe('The full URL'),
+});
+
+export const setSubcommand = createSubcommand({
+	name: 'set',
+	description: 'Set a custom vanity hostname for the project on agentuity.run',
+	tags: ['mutating', 'fast', 'requires-auth', 'requires-project'],
+	requires: { auth: true, apiClient: true, project: true },
+	examples: [
+		{
+			command: getCommand('project hostname set my-cool-api'),
+			description: 'Set a custom hostname',
+		},
+	],
+	schema: {
+		args: z.object({
+			hostname: z.string().describe('the vanity hostname (e.g., my-cool-api)'),
+		}),
+		response: HostnameSetResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, apiClient, project, options, logger } = ctx;
+		const jsonMode = isJSONMode(options);
+
+		const hostname = args.hostname.toLowerCase().trim();
+
+		// Client-side validation: DNS label regex
+		const hostnameRegex = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+		if (!hostnameRegex.test(hostname)) {
+			logger.fatal(
+				'Invalid hostname: must contain only lowercase letters, numbers, and hyphens, and must start and end with a letter or number',
+				ErrorCode.VALIDATION_FAILED
+			);
+		}
+
+		// Max 63 chars (DNS label limit)
+		if (hostname.length > 63) {
+			logger.fatal(
+				'Invalid hostname: must be 63 characters or fewer',
+				ErrorCode.VALIDATION_FAILED
+			);
+		}
+
+		// Must not match reserved hash patterns
+		const reservedHashPattern = /^[dp][a-f0-9]{16}$/;
+		if (reservedHashPattern.test(hostname)) {
+			logger.fatal(
+				'Invalid hostname: this pattern is reserved for internal use',
+				ErrorCode.VALIDATION_FAILED
+			);
+		}
+
+		// Must not be a reserved name
+		if (RESERVED_NAMES.has(hostname)) {
+			logger.fatal(
+				`Invalid hostname: "${hostname}" is a reserved name`,
+				ErrorCode.VALIDATION_FAILED
+			);
+		}
+
+		const result = jsonMode
+			? await projectHostnameSet(apiClient, {
+					projectId: project.projectId,
+					hostname,
+				})
+			: await tui.spinner('Setting hostname', () => {
+					return projectHostnameSet(apiClient, {
+						projectId: project.projectId,
+						hostname,
+					});
+				});
+
+		if (!jsonMode) {
+			tui.success(`Hostname set: ${tui.bold(result.url)}`);
+			tui.info('Hostname will be active after next deployment');
+		}
+
+		return {
+			hostname: result.hostname,
+			url: result.url,
+		};
+	},
+});

package/src/cmd/project/index.ts

@@ -6,6 +6,8 @@ import { deleteSubcommand } from './delete';
 import { showSubcommand } from './show';
 import { authCommand } from './auth';
 import { addCommand } from './add';
+import { hostnameCommand } from './hostname';
+import { domainCommand } from './domain';
 import { getCommand } from '../../command-prefix';
 
 export const command = createCommand({
@@ -22,6 +24,14 @@ export const command = createCommand({
 			command: getCommand('project add storage'),
 			description: 'Link an existing storage bucket',
 		},
+		{
+			command: getCommand('project hostname get'),
+			description: 'Show current vanity hostname',
+		},
+		{
+			command: getCommand('project domain check'),
+			description: 'Check DNS for custom domains',
+		},
 	],
 	subcommands: [
 		createProjectSubcommand,
@@ -31,5 +41,7 @@ export const command = createCommand({
 		showSubcommand,
 		authCommand,
 		addCommand,
+		hostnameCommand,
+		domainCommand,
 	],
 });

package/src/cmd/upgrade/index.ts

@@ -4,7 +4,6 @@ import { getCommand } from '../../command-prefix';
 import { z } from 'zod';
 import { ErrorCode, createError, exitWithError } from '../../errors';
 import * as tui from '../../tui';
-import { $ } from 'bun';
 import { tmpdir } from 'node:os';
 import { getInstallationType, type InstallationType } from '../../utils/installation-type';
 
@@ -84,14 +83,17 @@ async function performBunUpgrade(
 	const { installWithRetry } = await import('./npm-availability');
 
 	try {
+		const { spawnWithTimeout } = await import('./npm-availability');
+
 		await installWithRetry(
 			async () => {
 				// Use bun to install the specific version globally
 				// Run from tmpdir to avoid interference from any local package.json/node_modules
-				const result = await $`bun add -g @agentuity/cli@${npmVersion}`
-					.cwd(tmpdir())
-					.quiet()
-					.nothrow();
+				// spawnWithTimeout kills the process if it exceeds 30s (INSTALL_TIMEOUT_MS)
+				const result = await spawnWithTimeout(
+					['bun', 'add', '-g', `@agentuity/cli@${npmVersion}`],
+					{ cwd: tmpdir(), timeout: 30_000 }
+				);
 				return { exitCode: result.exitCode, stderr: result.stderr };
 			},
 			{ onRetry }
@@ -107,8 +109,10 @@ async function performBunUpgrade(
  * Verify the upgrade was successful by checking the installed version
  */
 async function verifyUpgrade(expectedVersion: string): Promise<void> {
-	// Run agentuity version to check the installed version
-	const result = await $`agentuity version`.quiet().nothrow();
+	const { spawnWithTimeout } = await import('./npm-availability');
+
+	// Run agentuity version to check the installed version (5s timeout — local command, sub-second normally)
+	const result = await spawnWithTimeout(['agentuity', 'version'], { timeout: 5_000 });
 
 	if (result.exitCode !== 0) {
 		throw new Error('Failed to verify upgrade - could not run agentuity version');
@@ -219,8 +223,12 @@ export const command = createCommand({
 
 			if (!isAvailable) {
 				tui.warning('The new version is not yet available on npm.');
-				tui.info('This can happen right after a release. Please try again in a few minutes.');
-				tui.info(`You can also run: ${tui.muted('bun add -g @agentuity/cli@latest')}`);
+				tui.info(
+					'This can happen right after a release. Please try again in a few minutes.'
+				);
+				tui.newline();
+				tui.info('You can also upgrade manually:');
+				console.log(`  ${tui.muted('curl -fsSL https://agentuity.sh | sh')}`);
 				return {
 					upgraded: false,
 					from: currentVersion,
@@ -301,6 +309,12 @@ export const command = createCommand({
 				installationType,
 			};
 
+			tui.newline();
+			tui.info('If the upgrade continues to fail, you can reinstall manually:');
+			tui.newline();
+			console.log(`  ${tui.muted('curl -fsSL https://agentuity.sh | sh')}`);
+			tui.newline();
+
 			exitWithError(
 				createError(ErrorCode.INTERNAL_ERROR, 'Upgrade failed', errorDetails),
 				logger,

package/src/cmd/upgrade/npm-availability.test.ts

@@ -0,0 +1,65 @@
+import { test, expect, beforeAll, afterAll } from 'bun:test';
+import { spawnWithTimeout } from './npm-availability';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// bun info requires a package.json in its cwd, and isVersionAvailableOnNpm
+// uses tmpdir() as cwd. Ensure a minimal package.json exists there for tests.
+const tmpPackageJson = join(tmpdir(), 'package.json');
+let createdPackageJson = false;
+
+beforeAll(async () => {
+	const file = Bun.file(tmpPackageJson);
+	if (!(await file.exists())) {
+		await Bun.write(file, '{}');
+		createdPackageJson = true;
+	}
+});
+
+afterAll(async () => {
+	if (createdPackageJson) {
+		const { unlink } = await import('node:fs/promises');
+		await unlink(tmpPackageJson).catch(() => {});
+	}
+});
+
+test('spawnWithTimeout kills process on timeout', async () => {
+	// spawn a command that hangs with a short timeout (500ms)
+	await expect(
+		spawnWithTimeout(['bun', '-e', 'setTimeout(()=>{},60000)'], { timeout: 500 })
+	).rejects.toThrow(/timed out/);
+});
+
+test('spawnWithTimeout returns result when command completes in time', async () => {
+	const result = await spawnWithTimeout(['bun', '-e', "console.log('hello')"], {
+		timeout: 5_000,
+	});
+	expect(result.exitCode).toBe(0);
+	expect(result.stdout.toString().trim()).toBe('hello');
+});
+
+test('spawnWithTimeout returns non-zero exit code without throwing', async () => {
+	const result = await spawnWithTimeout(['bun', '-e', 'process.exit(1)'], { timeout: 5_000 });
+	expect(result.exitCode).not.toBe(0);
+});
+
+test(
+	'isVersionAvailableOnNpm returns true for a known version',
+	async () => {
+		const { isVersionAvailableOnNpm } = await import('./npm-availability');
+		// Use a known-good old version that definitely exists
+		const result = await isVersionAvailableOnNpm('1.0.10');
+		expect(result).toBe(true);
+	},
+	15_000
+); // generous test timeout but the function itself has 10s subprocess timeout
+
+test(
+	'isVersionAvailableOnNpm returns false for non-existent version',
+	async () => {
+		const { isVersionAvailableOnNpm } = await import('./npm-availability');
+		const result = await isVersionAvailableOnNpm('999.999.999');
+		expect(result).toBe(false);
+	},
+	15_000
+);

package/src/cmd/upgrade/npm-availability.ts

@@ -3,11 +3,93 @@
  * Used to verify a version is available via bun's resolver before attempting upgrade.
  */
 
-import { $ } from 'bun';
 import { tmpdir } from 'node:os';
 
 const PACKAGE_SPEC = '@agentuity/cli';
 
+/** Default timeout for `bun info` subprocess calls (10 seconds) */
+const BUN_INFO_TIMEOUT_MS = 10_000;
+
+/** Default timeout for install (`bun add -g`) subprocess calls (30 seconds) */
+const INSTALL_TIMEOUT_MS = 30_000;
+
+/**
+ * Run a command via Bun.spawn with a timeout that kills the process.
+ * Returns { exitCode, stdout, stderr } similar to Bun's $ shell result.
+ */
+export async function spawnWithTimeout(
+	cmd: string[],
+	options: { cwd?: string; timeout: number }
+): Promise<{ exitCode: number; stdout: Buffer; stderr: Buffer }> {
+	const proc = Bun.spawn(cmd, {
+		cwd: options.cwd,
+		stdout: 'pipe',
+		stderr: 'pipe',
+	});
+
+	let timedOut = false;
+	const timer = setTimeout(() => {
+		timedOut = true;
+		proc.kill();
+	}, options.timeout);
+
+	try {
+		const [exitCode, stdoutBytes, stderrBytes] = await Promise.all([
+			proc.exited,
+			new Response(proc.stdout).arrayBuffer(),
+			new Response(proc.stderr).arrayBuffer(),
+		]);
+
+		if (timedOut) {
+			throw new Error(
+				`Command timed out after ${options.timeout}ms: ${cmd.join(' ')}`
+			);
+		}
+
+		return {
+			exitCode,
+			stdout: Buffer.from(stdoutBytes),
+			stderr: Buffer.from(stderrBytes),
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/**
+ * Sentinel error thrown exclusively by withTimeout so the retry loop can
+ * distinguish a genuine timeout from other failures (e.g. permission errors).
+ */
+class TimeoutError extends Error {
+	constructor(description: string, timeoutMs: number) {
+		super(`${description} timed out after ${timeoutMs}ms`);
+		this.name = 'TimeoutError';
+	}
+}
+
+/**
+ * Race a promise against a timeout. Unlike spawnWithTimeout (which kills a process),
+ * this is a generic wrapper for any async operation (e.g. the installFn callback).
+ *
+ * Throws a {@link TimeoutError} (not a plain Error) so callers can tell
+ * timeouts apart from other exceptions.
+ */
+async function withTimeout<T>(
+	promise: Promise<T>,
+	timeoutMs: number,
+	description: string
+): Promise<T> {
+	let timer: ReturnType<typeof setTimeout>;
+	const timeoutPromise = new Promise<never>((_, reject) => {
+		timer = setTimeout(() => reject(new TimeoutError(description, timeoutMs)), timeoutMs);
+	});
+	try {
+		return await Promise.race([promise, timeoutPromise]);
+	} finally {
+		clearTimeout(timer!);
+	}
+}
+
 /**
  * Check if a specific version of @agentuity/cli is resolvable by bun.
  * Uses `bun info` to verify bun's own resolver/CDN can see the version,
@@ -20,10 +102,10 @@ const PACKAGE_SPEC = '@agentuity/cli';
 export async function isVersionAvailableOnNpm(version: string): Promise<boolean> {
 	const normalizedVersion = version.replace(/^v/, '');
 	try {
-		const result = await $`bun info ${PACKAGE_SPEC}@${normalizedVersion} --json`
-			.cwd(tmpdir())
-			.quiet()
-			.nothrow();
+		const result = await spawnWithTimeout(
+			['bun', 'info', `${PACKAGE_SPEC}@${normalizedVersion}`, '--json'],
+			{ cwd: tmpdir(), timeout: BUN_INFO_TIMEOUT_MS }
+		);
 		if (result.exitCode !== 0) {
 			return false;
 		}
@@ -147,7 +229,22 @@ export async function installWithRetry(
 	let delay = initialDelayMs;
 
 	for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-		const result = await installFn();
+		let result: { exitCode: number; stderr: Buffer };
+		try {
+			result = await withTimeout(installFn(), INSTALL_TIMEOUT_MS, 'Install command');
+		} catch (error) {
+			// Only retry on timeouts — non-timeout errors (permissions, disk, etc.) are fatal
+			if (!(error instanceof TimeoutError)) {
+				throw error;
+			}
+			if (attempt === maxAttempts) {
+				throw error;
+			}
+			onRetry?.(attempt, delay);
+			await new Promise((resolve) => setTimeout(resolve, delay));
+			delay = Math.min(Math.round(delay * multiplier), maxDelayMs);
+			continue;
+		}
 
 		if (result.exitCode === 0) {
 			return result;

package/src/index.ts

@@ -102,7 +102,7 @@ export {
 	type CommandHandler,
 	type TableColumn,
 } from './repl';
-export { runSteps, stepSuccess, stepSkipped, stepError } from './steps';
+export { runSteps, stepSuccess, stepSkipped, stepError, StepInterruptError } from './steps';
 export { playSound } from './sound';
 export {
 	downloadWithProgress,