@agentuity/cli 1.0.1 → 1.0.3

package/src/cmd/project/add/storage.ts

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+import { listResources } from '@agentuity/server';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createPrompt } from '../../../tui';
+import { getCatalystAPIClient } from '../../../config';
+import { getCommand } from '../../../command-prefix';
+import { isDryRunMode, outputDryRun } from '../../../explain';
+import { ErrorCode } from '../../../errors';
+import { addResourceEnvVars } from '../../../env-util';
+
+export const storageSubcommand = createSubcommand({
+	name: 'storage',
+	aliases: ['bucket', 's3'],
+	description: 'Link an existing storage bucket to the current project',
+	tags: ['mutating', 'fast', 'requires-auth', 'requires-project'],
+	idempotent: true,
+	requires: { auth: true, org: true, region: true, project: true },
+	examples: [
+		{
+			command: getCommand('project add storage'),
+			description: 'Select a storage bucket interactively',
+		},
+		{
+			command: getCommand('project add bucket my-bucket'),
+			description: 'Link a specific bucket by name',
+		},
+		{
+			command: getCommand('--dry-run project add storage my-bucket'),
+			description: 'Preview linking without making changes',
+		},
+	],
+	schema: {
+		args: z.object({
+			name: z.string().optional().describe('Storage bucket name to link'),
+		}),
+		options: z.object({}),
+		response: z.object({
+			success: z.boolean().describe('Whether linking succeeded'),
+			name: z.string().describe('Linked bucket name'),
+		}),
+	},
+
+	async handler(ctx) {
+		const { logger, args, orgId, region, auth, options, projectDir } = ctx;
+
+		if (isDryRunMode(options)) {
+			const message = args.name
+				? `Would link storage bucket "${args.name}" to project in ${projectDir}`
+				: `Would prompt to select a storage bucket to link to project in ${projectDir}`;
+			outputDryRun(message, options);
+			if (!options.json) {
+				tui.newline();
+				tui.info('[DRY RUN] Storage linking skipped');
+			}
+			return {
+				success: false,
+				name: args.name || 'dry-run-bucket',
+			};
+		}
+
+		const catalystClient = getCatalystAPIClient(logger, auth, region);
+
+		const resources = await tui.spinner({
+			message: 'Fetching storage buckets',
+			clearOnSuccess: true,
+			callback: async () => {
+				return listResources(catalystClient, orgId, region);
+			},
+		});
+
+		const availableBuckets = resources.s3.filter((bucket) => !bucket.internal);
+
+		if (availableBuckets.length === 0) {
+			tui.fatal(
+				'No storage buckets available. Create one first with: ' +
+					tui.bold(getCommand('cloud storage create')),
+				ErrorCode.RESOURCE_NOT_FOUND
+			);
+		}
+
+		let selectedBucket: (typeof availableBuckets)[0] | undefined;
+
+		if (args.name) {
+			selectedBucket = availableBuckets.find((bucket) => bucket.bucket_name === args.name);
+			if (!selectedBucket) {
+				const availableNames = availableBuckets.map((bucket) => bucket.bucket_name).join(', ');
+				tui.fatal(
+					`Storage bucket "${args.name}" not found. Available buckets: ${availableNames}`,
+					ErrorCode.RESOURCE_NOT_FOUND
+				);
+			}
+		} else {
+			const isHeadless = !process.stdin.isTTY || !process.stdout.isTTY;
+			if (isHeadless) {
+				tui.fatal(
+					'Bucket name is required in non-interactive mode. Usage: ' +
+						tui.bold(getCommand('project add storage <name>')),
+					ErrorCode.MISSING_ARGUMENT
+				);
+			}
+
+			const prompt = createPrompt();
+			const selected = await prompt.select<string>({
+				message: 'Select a storage bucket to link',
+				options: availableBuckets.map((bucket) => ({
+					value: bucket.bucket_name,
+					label: `${tui.tuiColors.primary(bucket.bucket_name)}`,
+				})),
+			});
+
+			// Ensure stdin is paused so process can exit
+			if (process.stdin.isTTY) {
+				process.stdin.pause();
+			}
+
+			if (!selected) {
+				tui.fatal('Operation cancelled', ErrorCode.USER_CANCELLED);
+			}
+
+			selectedBucket = availableBuckets.find((bucket) => bucket.bucket_name === selected);
+		}
+
+		if (!selectedBucket) {
+			tui.fatal('Failed to select storage bucket', ErrorCode.INTERNAL_ERROR);
+		}
+
+		if (selectedBucket.env && Object.keys(selectedBucket.env).length > 0) {
+			await addResourceEnvVars(projectDir, selectedBucket.env);
+			if (!options.json) {
+				tui.success(`Linked storage bucket: ${tui.bold(selectedBucket.bucket_name)}`);
+				tui.info('Environment variables written to .env');
+			}
+		} else {
+			if (!options.json) {
+				tui.warning(
+					`Storage bucket "${selectedBucket.bucket_name}" has no environment variables to add`
+				);
+			}
+		}
+
+		return {
+			success: true,
+			name: selectedBucket.bucket_name,
+		};
+	},
+});

package/src/cmd/project/auth/init.ts

@@ -73,14 +73,14 @@ export const initSubcommand = createSubcommand({
 		if (!databaseUrl) {
 			// Check .env file
 			const envPath = path.join(projectDir, '.env');
-		if (fs.existsSync(envPath)) {
-			const envContent = fs.readFileSync(envPath, 'utf-8');
-			const match = envContent.match(/^DATABASE_URL=(.+)$/m);
-			if (match?.[1]) {
-				databaseUrl = match[1].trim().replace(/^["']|["']$/g, '');
+			if (fs.existsSync(envPath)) {
+				const envContent = fs.readFileSync(envPath, 'utf-8');
+				const match = envContent.match(/^DATABASE_URL=(.+)$/m);
+				if (match?.[1]) {
+					databaseUrl = match[1].trim().replace(/^["']|["']$/g, '');
+				}
 			}
 		}
-		}
 
 		// Show database picker (with existing as first option if configured)
 		const dbInfo = await selectOrCreateDatabase({

package/src/cmd/project/index.ts

@@ -5,6 +5,7 @@ import { listSubcommand } from './list';
 import { deleteSubcommand } from './delete';
 import { showSubcommand } from './show';
 import { authCommand } from './auth';
+import { addCommand } from './add';
 import { getCommand } from '../../command-prefix';
 
 export const command = createCommand({
@@ -16,6 +17,11 @@ export const command = createCommand({
 		{ command: getCommand('project import'), description: 'Import an existing project' },
 		{ command: getCommand('project list'), description: 'List all projects' },
 		{ command: getCommand('project auth init'), description: 'Set up Agentuity Auth' },
+		{ command: getCommand('project add database'), description: 'Link an existing database' },
+		{
+			command: getCommand('project add storage'),
+			description: 'Link an existing storage bucket',
+		},
 	],
 	subcommands: [
 		createProjectSubcommand,
@@ -24,5 +30,6 @@ export const command = createCommand({
 		deleteSubcommand,
 		showSubcommand,
 		authCommand,
+		addCommand,
 	],
 });

package/src/cmd/project/reconcile.ts

@@ -222,6 +222,30 @@ async function selectRegion(regions: RegionList, defaultRegion?: string): Promis
 		return firstRegion.region;
 	}
 
+	// Check for non-interactive mode before prompting
+	const isNonInteractive = !process.stdin.isTTY || !process.stdout.isTTY;
+	if (isNonInteractive) {
+		// In non-interactive mode, validate defaultRegion against available regions
+		if (defaultRegion) {
+			const isValidRegion = regions.some((r) => r.region === defaultRegion);
+			if (isValidRegion) {
+				return defaultRegion;
+			}
+			const supportedRegions = regions.map((r) => r.region).join(', ');
+			tui.fatal(
+				`Region "${defaultRegion}" is not supported. ` +
+					`Available regions: ${supportedRegions}. ` +
+					'Use --region flag or set AGENTUITY_REGION environment variable with a valid region.'
+			);
+		}
+		const supportedRegions = regions.map((r) => r.region).join(', ');
+		tui.fatal(
+			'Cannot select region in non-interactive mode. ' +
+				`Available regions: ${supportedRegions}. ` +
+				'Use --region flag or set AGENTUITY_REGION environment variable.'
+		);
+	}
+
 	// Build options from API regions
 	const options = regions.map((r) => ({
 		value: r.region,
@@ -255,6 +279,22 @@ async function textPrompt(options: {
 	initial?: string;
 	validate?: (value: string) => boolean | string;
 }): Promise<string> {
+	// Check for non-interactive mode before prompting
+	const isNonInteractive = !process.stdin.isTTY || !process.stdout.isTTY;
+	if (isNonInteractive) {
+		// In non-interactive mode, use initial value if available and valid
+		if (options.initial) {
+			const validationResult = options.validate?.(options.initial);
+			if (validationResult === true || validationResult === undefined) {
+				return options.initial;
+			}
+		}
+		tui.fatal(
+			'Cannot prompt for input in non-interactive mode. ' +
+				'Use --name flag to specify the project name.'
+		);
+	}
+
 	const prompt = createPrompt();
 	return prompt.text({
 		message: options.message,

package/src/cmd/support/report.ts

@@ -335,11 +335,11 @@ export default createSubcommand({
 			// Debug: log the response
 			logger.debug('Upload response received', { uploadResponse });
 
-		if (!uploadResponse.success) {
-			const errorMsg = uploadResponse.message || 'Failed to create upload URL';
-			logger.error('Upload URL creation failed', { uploadResponse, errorMsg });
-			throw new UploadUrlCreationError({ message: errorMsg });
-		}
+			if (!uploadResponse.success) {
+				const errorMsg = uploadResponse.message || 'Failed to create upload URL';
+				logger.error('Upload URL creation failed', { uploadResponse, errorMsg });
+				throw new UploadUrlCreationError({ message: errorMsg });
+			}
 
 			const { presigned_url, url: reportUrl, report_id: reportId } = uploadResponse.data;
 

package/src/cmd/support/system.ts

@@ -7,7 +7,7 @@ import { getLatestLogSession } from '../../internal-logger';
 import * as tui from '../../tui';
 import { getVersion, getPackageName } from '../../version';
 import { getAuth } from '../../config';
-import { isExecutingFromAgent } from '../../agent-detection';
+import { getExecutingAgent } from '../../agent-detection';
 
 const argsSchema = z.object({});
 
@@ -77,7 +77,7 @@ export default createSubcommand({
 		}
 
 		// Get detected agent (if any)
-		const detectedAgent = await isExecutingFromAgent();
+		const detectedAgent = getExecutingAgent();
 
 		// Gather system information
 		const systemInfo = {

package/src/config.ts

@@ -1,12 +1,8 @@
 import { z } from 'zod';
 import { existsSync, mkdirSync } from 'node:fs';
 import { StructuredError, type Logger } from '@agentuity/core';
-import {
-	BuildMetadataSchema,
-	type BuildMetadata,
-	getServiceUrls,
-	APIClient as ServerAPIClient,
-} from '@agentuity/server';
+import { BuildMetadataSchema, type BuildMetadata, getServiceUrls } from '@agentuity/server';
+import { APIClient as ServerAPIClient } from '@agentuity/server';
 import { YAML } from 'bun';
 import { join, extname, basename, resolve, normalize } from 'node:path';
 import { homedir } from 'node:os';
@@ -15,6 +11,7 @@ import JSON5 from 'json5';
 import type { Config, Profile, AuthData } from './types';
 import { ConfigSchema, ProjectSchema } from './types';
 import * as tui from './tui';
+import { getCatalystUrl } from './catalyst';
 import {
 	isMacOS,
 	saveAuthToKeychain,
@@ -51,8 +48,21 @@ export async function saveProfile(path: string): Promise<void> {
 	await writeFile(getProfilePath(), path, { mode: 0o600 });
 }
 
-export async function getProfile(): Promise<string> {
-	// Check environment variable first
+export async function getProfile(profileFromFlag?: string): Promise<string> {
+	// Check --profile flag first (highest priority)
+	if (profileFromFlag) {
+		const flagProfilePath = join(getDefaultConfigDir(), `${profileFromFlag}.yaml`);
+		const flagFile = Bun.file(flagProfilePath);
+		if (await flagFile.exists()) {
+			return flagProfilePath;
+		}
+		// If --profile flag was explicitly provided but file doesn't exist, throw an error
+		throw new Error(
+			`Profile '${profileFromFlag}' not found. Expected file at: ${flagProfilePath}`
+		);
+	}
+
+	// Check environment variable second
 	if (process.env.AGENTUITY_PROFILE) {
 		const profileName = process.env.AGENTUITY_PROFILE;
 		const envProfilePath = join(getDefaultConfigDir(), `${profileName}.yaml`);
@@ -127,12 +137,16 @@ function expandTilde(path: string): string {
 
 let cachedConfig: Config | null | undefined;
 
-export async function loadConfig(customPath?: string, skipCache = false): Promise<Config | null> {
+export async function loadConfig(
+	customPath?: string,
+	skipCache = false,
+	profileFromFlag?: string
+): Promise<Config | null> {
 	// Use cache if available and not skipped
 	if (!skipCache && cachedConfig !== undefined) {
 		return cachedConfig;
 	}
-	const configPath = customPath ? expandTilde(customPath) : await getProfile();
+	const configPath = customPath ? expandTilde(customPath) : await getProfile(profileFromFlag);
 
 	try {
 		const file = Bun.file(configPath);
@@ -359,6 +373,13 @@ export async function saveOrgId(orgId: string): Promise<void> {
 	await saveConfig(config);
 }
 
+export async function saveProjectId(projectId: string): Promise<void> {
+	const config = await getOrInitConfig();
+	config.preferences = config.preferences || {};
+	(config.preferences as Record<string, unknown>).projectId = projectId;
+	await saveConfig(config);
+}
+
 export async function clearOrgId(): Promise<void> {
 	const config = await getOrInitConfig();
 	if (config.preferences) {
@@ -367,6 +388,14 @@ export async function clearOrgId(): Promise<void> {
 	}
 }
 
+export async function clearProjectId(): Promise<void> {
+	const config = await getOrInitConfig();
+	if (config.preferences) {
+		delete (config.preferences as Record<string, unknown>).projectId;
+		await saveConfig(config);
+	}
+}
+
 export async function saveRegion(region: string): Promise<void> {
 	const config = await getOrInitConfig();
 	config.preferences = config.preferences || {};
@@ -739,8 +768,7 @@ export function getCatalystAPIClient(
 	region: string,
 	orgId?: string
 ) {
-	const serviceUrls = getServiceUrls(region);
-	const catalystUrl = serviceUrls.catalyst;
+	const catalystUrl = getCatalystUrl(region);
 	const headers: Record<string, string> = {};
 	if (orgId) {
 		headers['x-agentuity-orgid'] = orgId;

package/src/errors.ts

@@ -82,6 +82,9 @@ export enum ErrorCode {
 
 	// Upgrade of the software is required to continue
 	UPGRADE_REQUIRED = 'UPGRADE_REQUIRED',
+
+	// Payment required - user needs to upgrade their plan
+	PAYMENT_REQUIRED = 'PAYMENT_REQUIRED',
 }
 
 /**
@@ -147,6 +150,10 @@ export function getExitCode(errorCode: ErrorCode): ExitCode {
 		case ErrorCode.MALWARE_DETECTED:
 			return ExitCode.SECURITY_ERROR;
 
+		// Payment required - user needs to upgrade their plan
+		case ErrorCode.PAYMENT_REQUIRED:
+			return ExitCode.GENERAL_ERROR;
+
 		// Resource conflicts and other errors
 		case ErrorCode.RESOURCE_ALREADY_EXISTS:
 		case ErrorCode.RESOURCE_CONFLICT:

package/src/index.ts

@@ -1,4 +1,13 @@
 export { createCLI, registerCommands } from './cli';
+export { generateAIHelp, type DashdashConfig } from './ai-help';
+export {
+	getExecutingAgent,
+	getAgentEnv,
+	getAgentDisplayName,
+	KNOWN_AGENTS,
+	AGENT_DISPLAY_NAMES,
+	type KnownAgent,
+} from './agent-detection';
 export { validateRuntime, isBun } from './runtime';
 export { ensureBunOnPath } from './bun-path';
 export { isGitAvailable, getDefaultBranch } from './git-helper';
@@ -73,6 +82,7 @@ export {
 	getAuth,
 } from './config';
 export { APIClient, getAPIBaseURL, getAppBaseURL } from './api';
+export { getCatalystUrl } from './catalyst';
 export {
 	ConsoleLogger,
 	createLogger,
@@ -111,6 +121,7 @@ export type {
 	Profile,
 	AuthData,
 	CommandSchemas,
+	ResourceSelectionRule,
 	BuildPhase,
 	BuildContext,
 	BuildConfig,

package/src/repl.ts

@@ -1030,7 +1030,10 @@ async function readLine(
 		const searchHistory = (query: string, startFrom: number): number => {
 			for (let i = startFrom - 1; i >= 0; i--) {
 				const historyEntry = history[i];
-				if (historyEntry !== undefined && historyEntry.toLowerCase().includes(query.toLowerCase())) {
+				if (
+					historyEntry !== undefined &&
+					historyEntry.toLowerCase().includes(query.toLowerCase())
+				) {
 					return i;
 				}
 			}

package/src/tui/box.ts

@@ -201,8 +201,10 @@ export function note(message: string, title = ''): void {
 
 /**
  * Draw an error box with red border
+ * @param withGuide - If true (default), shows guide bar at top and connector at bottom for use in flows.
+ *                    If false, renders as a standalone box with proper corners.
  */
-export function errorBox(title: string, message: string): void {
+export function errorBox(title: string, message: string, withGuide = true): void {
 	const termWidth = getTerminalWidth();
 	const maxWidth = termWidth - 3;
 	const boxWidth = Math.min(60, maxWidth);
@@ -212,15 +214,22 @@ export function errorBox(title: string, message: string): void {
 
 	const lines: string[] = [];
 
-	// Title line with error symbol
-	const errorSymbol = colors.error('✗');
+	// Top border with title
+	const errorSymbol = colors.error(symbols.error);
 	const titleText = colors.error(title);
 	const titleTextWidth = 1 + stringWidth(title); // symbol + title
 	const barsNeeded = Math.max(innerWidth - titleTextWidth - 3, 1);
-	const titleLine = `${errorSymbol}  ${titleText} ${colors.error(symbols.barH.repeat(barsNeeded) + symbols.cornerTR)}`;
 
-	lines.push(colors.error(symbols.bar));
-	lines.push(titleLine);
+	if (withGuide) {
+		// Guide style: bar at top, then title line without top-left corner
+		lines.push(colors.error(symbols.bar));
+		const titleLine = `${errorSymbol}  ${titleText} ${colors.error(symbols.barH.repeat(barsNeeded) + symbols.cornerTR)}`;
+		lines.push(titleLine);
+	} else {
+		// Standalone style: title line with top-left corner
+		const titleLine = `${colors.error(symbols.cornerTL)}${errorSymbol} ${titleText} ${colors.error(symbols.barH.repeat(barsNeeded) + symbols.cornerTR)}`;
+		lines.push(titleLine);
+	}
 
 	// Empty line
 	const emptyLine = `${colors.error(symbols.bar)}${' '.repeat(contentWidth)}${colors.error(symbols.bar)}`;
@@ -244,9 +253,15 @@ export function errorBox(title: string, message: string): void {
 	lines.push(emptyLine);
 
 	// Bottom border
-	lines.push(
-		colors.error(symbols.connect + symbols.barH.repeat(innerWidth - 1) + symbols.cornerBR)
-	);
+	if (withGuide) {
+		lines.push(
+			colors.error(symbols.connect + symbols.barH.repeat(innerWidth - 1) + symbols.cornerBR)
+		);
+	} else {
+		lines.push(
+			colors.error(symbols.cornerBL + symbols.barH.repeat(innerWidth - 1) + symbols.cornerBR)
+		);
+	}
 
 	console.log(lines.join('\n'));
 }

package/src/tui/colors.ts

@@ -1,6 +1,7 @@
 /**
  * Color utilities for TUI components using existing tui.ts color system
  */
+import { getExecutingAgent } from '../agent-detection';
 
 // ANSI escape codes for additional colors not in main tui.ts
 const RESET = '\x1b[0m';
@@ -17,6 +18,36 @@ const BG_CYAN = '\x1b[46m';
 const BLACK = '\x1b[30m';
 const WHITE = '\x1b[37m';
 
+/**
+ * Check if colors should be used.
+ * Disabled for: AI agents, CI, NO_COLOR, dumb terminals, non-TTY, piped output.
+ * FORCE_COLOR=1 overrides all checks.
+ */
+function shouldUseColors(): boolean {
+	// FORCE_COLOR overrides all checks
+	if (process.env.FORCE_COLOR === '1') {
+		return true;
+	}
+	// Disable for AI coding agents
+	if (getExecutingAgent()) {
+		return false;
+	}
+	// Disable for NO_COLOR, CI, dumb terminals, or non-TTY
+	if (process.env.NO_COLOR) {
+		return false;
+	}
+	if (process.env.CI) {
+		return false;
+	}
+	if (process.env.TERM === 'dumb') {
+		return false;
+	}
+	if (!process.stdout.isTTY) {
+		return false;
+	}
+	return true;
+}
+
 /**
  * Detect if terminal is in dark mode
  */
@@ -27,29 +58,55 @@ function isDarkMode(): boolean {
 	return true;
 }
 
-export const colors = {
-	// State colors - using simple ANSI codes (consistent with tui.ts approach)
-	active: (text: string) => `${CYAN}${text}${RESET}`,
-	completed: (text: string) => `${GRAY}${text}${RESET}`,
-	error: (text: string) => `${RED}${text}${RESET}`,
-	warning: (text: string) => `${YELLOW}${text}${RESET}`,
-	success: (text: string) => `${GREEN}${text}${RESET}`,
-	info: (text: string) => `${BLUE}${text}${RESET}`,
-
-	// Text formatting
-	muted: (text: string) => `${DIM}${text}${RESET}`,
-	bold: (text: string) => `${BOLD}${text}${RESET}`,
-	underline: (text: string) => `${UNDERLINE}${text}${RESET}`,
-	reset: (text: string) => `${RESET}${text}`,
-
-	// Semantic colors
-	primary: (text: string) => `${CYAN}${text}${RESET}`,
-	secondary: (text: string) => `${GRAY}${text}${RESET}`,
-	link: (text: string) => `${CYAN}${UNDERLINE}${text}${RESET}`,
-
-	// Inversed colors (adapt to light/dark mode)
-	inverseCyan: (text: string) => {
-		const dark = isDarkMode();
-		return dark ? `${BG_CYAN}${BLACK}${text}${RESET}` : `${BG_CYAN}${WHITE}${text}${RESET}`;
-	},
-};
+// No-op color function for when colors are disabled
+const noColor = (text: string) => text;
+
+function createColors() {
+	if (!shouldUseColors()) {
+		return {
+			active: noColor,
+			completed: noColor,
+			error: noColor,
+			warning: noColor,
+			success: noColor,
+			info: noColor,
+			muted: noColor,
+			bold: noColor,
+			underline: noColor,
+			reset: noColor,
+			primary: noColor,
+			secondary: noColor,
+			link: noColor,
+			inverseCyan: noColor,
+		};
+	}
+
+	return {
+		// State colors - using simple ANSI codes (consistent with tui.ts approach)
+		active: (text: string) => `${CYAN}${text}${RESET}`,
+		completed: (text: string) => `${GRAY}${text}${RESET}`,
+		error: (text: string) => `${RED}${text}${RESET}`,
+		warning: (text: string) => `${YELLOW}${text}${RESET}`,
+		success: (text: string) => `${GREEN}${text}${RESET}`,
+		info: (text: string) => `${BLUE}${text}${RESET}`,
+
+		// Text formatting
+		muted: (text: string) => `${DIM}${text}${RESET}`,
+		bold: (text: string) => `${BOLD}${text}${RESET}`,
+		underline: (text: string) => `${UNDERLINE}${text}${RESET}`,
+		reset: (text: string) => `${RESET}${text}`,
+
+		// Semantic colors
+		primary: (text: string) => `${CYAN}${text}${RESET}`,
+		secondary: (text: string) => `${GRAY}${text}${RESET}`,
+		link: (text: string) => `${CYAN}${UNDERLINE}${text}${RESET}`,
+
+		// Inversed colors (adapt to light/dark mode)
+		inverseCyan: (text: string) => {
+			const dark = isDarkMode();
+			return dark ? `${BG_CYAN}${BLACK}${text}${RESET}` : `${BG_CYAN}${WHITE}${text}${RESET}`;
+		},
+	};
+}
+
+export const colors = createColors();