@agentuity/cli 1.0.0 → 1.0.2

package/src/ai-help.ts

@@ -0,0 +1,391 @@
+/**
+ * AI Help Generator - dashdash specification implementation
+ *
+ * Generates AI-optimized help output in dashdash format (https://github.com/visionik/dashdash)
+ * for improved discoverability and usability by AI agents.
+ */
+
+import type { CLISchema, SchemaCommand } from './schema-generator';
+
+export interface DashdashConfig {
+	name: string;
+	description: string;
+	accessLevel: 'read' | 'browse' | 'interact' | 'full';
+	webUrl: string;
+	apiUrl: string;
+	docsUrl: string;
+	mcpUrl?: string;
+	homepage: string;
+	repository: string;
+}
+
+const DEFAULT_CONFIG: DashdashConfig = {
+	name: 'agentuity',
+	description: `CLI for building, deploying, and managing AI agents on the Agentuity platform.
+  Use when user asks to create agents, deploy projects, or interact with Agentuity cloud services.`,
+	accessLevel: 'interact',
+	webUrl: 'https://app.agentuity.com',
+	apiUrl: 'https://api.agentuity.com',
+	docsUrl: 'https://agentuity.dev',
+	homepage: 'https://agentuity.com',
+	repository: 'https://github.com/agentuity/sdk',
+};
+
+/**
+ * Generate dashdash-compliant AI help output
+ */
+export function generateAIHelp(schema: CLISchema, config: DashdashConfig = DEFAULT_CONFIG): string {
+	const frontMatter = buildFrontMatter(schema, config);
+	const content = buildContent(schema, config);
+
+	return `${frontMatter}\n${content}`;
+}
+
+/**
+ * Build YAML front matter per dashdash spec
+ */
+function buildFrontMatter(schema: CLISchema, config: DashdashConfig): string {
+	const lines = [
+		'---',
+		`name: ${config.name}`,
+		'description: >',
+		...config.description.split('\n').map((line) => `  ${line.trim()}`),
+		'',
+		'spec-url: https://github.com/visionik/dashdash',
+		'spec-version: 0.2.0',
+		'',
+		'subcommand-help: true',
+		`access-level: ${config.accessLevel}`,
+		'',
+		`web-url: ${config.webUrl}`,
+		`api-url: ${config.apiUrl}`,
+		`mcp-url: ${config.mcpUrl ?? 'none'}`,
+		'',
+		'install:',
+		'  npm: "@agentuity/cli"',
+		'  bun: "@agentuity/cli"',
+		'',
+		'requires:',
+		'  auth:',
+		'    - api-key',
+		'  env:',
+		'    - AGENTUITY_API_KEY',
+		'',
+		'invocation:',
+		'  model-invocable: true',
+		'  user-invocable: true',
+		'',
+		`homepage: ${config.homepage}`,
+		`repository: ${config.repository}`,
+		`content-version: ${schema.version}`,
+		'---',
+	];
+
+	return lines.join('\n');
+}
+
+/**
+ * Build markdown content
+ */
+function buildContent(schema: CLISchema, config: DashdashConfig): string {
+	const sections = [
+		buildHeader(config),
+		buildWhenToUse(),
+		buildQuickReference(schema),
+		buildCommandReference(schema),
+		buildGlobalOptions(schema),
+		buildAuthentication(),
+		buildExitCodes(schema),
+		buildAlternativeAccess(config),
+	];
+
+	return sections.join('\n\n');
+}
+
+function buildHeader(config: DashdashConfig): string {
+	return `# ${config.name}
+
+> ${config.description.split('\n')[0]?.trim()}`;
+}
+
+function buildWhenToUse(): string {
+	return `## When to Use
+
+Use this CLI when the user asks to:
+- Create, build, or deploy AI agents
+- Manage Agentuity projects and organizations
+- Access cloud services (KV, Vector, Postgres, Storage, Sandboxes)
+- Debug or troubleshoot agent deployments
+- Run agents locally in development mode
+- Manage environment variables and secrets
+- View deployment logs or rollback deployments
+
+Do NOT use this CLI for:
+- Non-Agentuity projects or general Node.js/Bun development
+- General file operations (use filesystem tools instead)
+- Non-AI/agent related tasks
+- Direct database queries (use the SDK or cloud console)`;
+}
+
+/**
+ * Build Quick Reference with 15-20 most common operations
+ */
+function buildQuickReference(schema: CLISchema): string {
+	const quickCommands = collectQuickReferenceCommands(schema);
+
+	const lines = ['## Quick Reference', ''];
+
+	for (const cmd of quickCommands) {
+		lines.push(`- **${cmd.label}:** \`${cmd.command}\``);
+	}
+
+	return lines.join('\n');
+}
+
+interface QuickCommand {
+	label: string;
+	command: string;
+	priority: number;
+}
+
+/**
+ * Collect the most important commands for quick reference
+ */
+function collectQuickReferenceCommands(schema: CLISchema): QuickCommand[] {
+	const commands: QuickCommand[] = [];
+
+	// Define priority commands explicitly for better curation
+	const priorityCommands: Array<{ path: string; label: string; priority: number }> = [
+		{ path: 'login', label: 'Login', priority: 1 },
+		{ path: 'project create', label: 'Create project', priority: 2 },
+		{ path: 'dev', label: 'Run locally', priority: 3 },
+		{ path: 'deploy', label: 'Deploy', priority: 4 },
+		{ path: 'cloud logs', label: 'View logs', priority: 5 },
+		{ path: 'cloud sandbox list', label: 'List sandboxes', priority: 6 },
+		{ path: 'cloud sandbox create', label: 'Create sandbox', priority: 7 },
+		{ path: 'cloud sandbox exec', label: 'Execute in sandbox', priority: 8 },
+		{ path: 'cloud kv get', label: 'KV get', priority: 9 },
+		{ path: 'cloud kv set', label: 'KV set', priority: 10 },
+		{ path: 'cloud vector search', label: 'Vector search', priority: 11 },
+		{ path: 'cloud db list', label: 'List databases', priority: 12 },
+		{ path: 'cloud db exec', label: 'Execute SQL', priority: 13 },
+		{ path: 'env list', label: 'List env vars', priority: 14 },
+		{ path: 'env set', label: 'Set env var', priority: 15 },
+		{ path: 'cloud deployment list', label: 'List deployments', priority: 16 },
+		{ path: 'cloud deployment rollback', label: 'Rollback deployment', priority: 17 },
+		{ path: 'project list', label: 'List projects', priority: 18 },
+		{ path: 'auth whoami', label: 'Show current user', priority: 19 },
+		{ path: 'version', label: 'Show version', priority: 20 },
+	];
+
+	// Build command signatures from schema
+	const commandMap = buildCommandMap(schema.commands);
+
+	for (const pc of priorityCommands) {
+		const schemaCmd = commandMap.get(pc.path);
+		if (schemaCmd) {
+			const signature = buildCommandSignature(pc.path, schemaCmd);
+			commands.push({
+				label: pc.label,
+				command: `agentuity ${signature}`,
+				priority: pc.priority,
+			});
+		} else {
+			// Fallback for commands that might not be in schema yet
+			commands.push({
+				label: pc.label,
+				command: `agentuity ${pc.path}`,
+				priority: pc.priority,
+			});
+		}
+	}
+
+	return commands.sort((a, b) => a.priority - b.priority);
+}
+
+/**
+ * Build a map of command paths to their schema definitions
+ */
+function buildCommandMap(
+	commands: SchemaCommand[],
+	prefix: string = ''
+): Map<string, SchemaCommand> {
+	const map = new Map<string, SchemaCommand>();
+
+	for (const cmd of commands) {
+		const path = prefix ? `${prefix} ${cmd.name}` : cmd.name;
+		map.set(path, cmd);
+
+		if (cmd.subcommands) {
+			const subMap = buildCommandMap(cmd.subcommands, path);
+			for (const [subPath, subCmd] of subMap) {
+				map.set(subPath, subCmd);
+			}
+		}
+	}
+
+	return map;
+}
+
+/**
+ * Build a command signature with arguments
+ */
+function buildCommandSignature(path: string, cmd: SchemaCommand): string {
+	let signature = path;
+
+	if (cmd.arguments) {
+		for (const arg of cmd.arguments) {
+			if (arg.variadic) {
+				signature += arg.required ? ` <${arg.name}...>` : ` [${arg.name}...]`;
+			} else {
+				signature += arg.required ? ` <${arg.name}>` : ` [${arg.name}]`;
+			}
+		}
+	}
+
+	return signature;
+}
+
+/**
+ * Build full command reference
+ */
+function buildCommandReference(schema: CLISchema): string {
+	const lines = ['## Command Reference', ''];
+
+	for (const cmd of schema.commands) {
+		lines.push(...buildCommandSection(cmd, 'agentuity'));
+	}
+
+	return lines.join('\n');
+}
+
+/**
+ * Build a command section recursively
+ */
+function buildCommandSection(cmd: SchemaCommand, prefix: string, depth: number = 3): string[] {
+	const lines: string[] = [];
+	const fullPath = `${prefix} ${cmd.name}`;
+	const heading = '#'.repeat(Math.min(depth, 6));
+
+	// Skip hidden/internal commands
+	if (cmd.tags?.includes('hidden') || cmd.skipSkill) {
+		return lines;
+	}
+
+	lines.push(`${heading} ${fullPath}`);
+	lines.push('');
+	lines.push(cmd.description);
+	lines.push('');
+
+	// Arguments
+	if (cmd.arguments && cmd.arguments.length > 0) {
+		lines.push('**Arguments:**');
+		for (const arg of cmd.arguments) {
+			const req = arg.required ? '(required)' : '(optional)';
+			lines.push(`- \`${arg.name}\` ${req}${arg.description ? ` - ${arg.description}` : ''}`);
+		}
+		lines.push('');
+	}
+
+	// Options
+	if (cmd.options && cmd.options.length > 0) {
+		lines.push('**Options:**');
+		for (const opt of cmd.options) {
+			const flag = `--${camelToKebab(opt.name)}`;
+			const defaultVal = opt.default !== undefined ? ` (default: ${JSON.stringify(opt.default)})` : '';
+			lines.push(`- \`${flag}\`${defaultVal}${opt.description ? ` - ${opt.description}` : ''}`);
+		}
+		lines.push('');
+	}
+
+	// Requirements
+	const reqs: string[] = [];
+	if (cmd.requires?.auth) reqs.push('authentication');
+	if (cmd.requires?.project) reqs.push('project');
+	if (cmd.requires?.org) reqs.push('organization');
+	if (cmd.requires?.region) reqs.push('region');
+
+	if (reqs.length > 0) {
+		lines.push(`**Requires:** ${reqs.join(', ')}`);
+		lines.push('');
+	}
+
+	// Examples
+	if (cmd.examples && cmd.examples.length > 0) {
+		lines.push('**Examples:**');
+		lines.push('```bash');
+		for (const ex of cmd.examples.slice(0, 3)) {
+			lines.push(`# ${ex.description}`);
+			lines.push(ex.command);
+		}
+		lines.push('```');
+		lines.push('');
+	}
+
+	// Subcommands
+	if (cmd.subcommands && cmd.subcommands.length > 0) {
+		for (const sub of cmd.subcommands) {
+			lines.push(...buildCommandSection(sub, fullPath, depth + 1));
+		}
+	}
+
+	return lines;
+}
+
+/**
+ * Build global options section
+ */
+function buildGlobalOptions(schema: CLISchema): string {
+	const lines = ['## Global Options', '', 'These options can be used with any command:', ''];
+
+	for (const opt of schema.globalOptions) {
+		const flag = `--${camelToKebab(opt.name)}`;
+		const defaultVal = opt.default !== undefined ? ` (default: ${JSON.stringify(opt.default)})` : '';
+		lines.push(`- \`${flag}\`${defaultVal}${opt.description ? ` - ${opt.description}` : ''}`);
+	}
+
+	return lines.join('\n');
+}
+
+function buildAuthentication(): string {
+	return `## Authentication
+
+Most commands require authentication. Set the \`AGENTUITY_API_KEY\` environment variable or run:
+
+\`\`\`bash
+agentuity login
+\`\`\`
+
+To check your current authentication status:
+
+\`\`\`bash
+agentuity auth whoami
+\`\`\``;
+}
+
+function buildExitCodes(schema: CLISchema): string {
+	const lines = ['## Exit Codes', ''];
+
+	for (const [code, description] of Object.entries(schema.exitCodes)) {
+		lines.push(`- \`${code}\` - ${description}`);
+	}
+
+	return lines.join('\n');
+}
+
+function buildAlternativeAccess(config: DashdashConfig): string {
+	return `## Alternative Access Methods
+
+- **Web Console:** ${config.webUrl}
+- **API Documentation:** ${config.docsUrl}`;
+}
+
+/**
+ * Convert camelCase to kebab-case
+ */
+function camelToKebab(str: string): string {
+	return str
+		.replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+		.replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+		.toLowerCase();
+}

package/src/api.ts

@@ -101,5 +101,5 @@ export function getGravityDevModeURL(region: string, config?: Config | null): st
 	if (config?.name === 'local') {
 		return 'grpc://gravity.agentuity.io:8443';
 	}
-	return `grpc://gravity-${region}.agentuity.cloud`;
+	return 'grpc://devmode-us.agentuity.com';
 }

package/src/auth.ts

@@ -1,7 +1,8 @@
 import enquirer from 'enquirer';
 import { getDefaultConfigPath, getAuth, saveConfig, loadConfig, saveOrgId } from './config';
+import { getResourceInfo, type ResourceType } from './cache';
 import { getCommand } from './command-prefix';
-import type { CommandContext, AuthData } from './types';
+import type { CommandContext, AuthData, Config } from './types';
 import * as tui from './tui';
 import { defaultProfileName } from './config';
 import { listOrganizations } from '@agentuity/server';
@@ -11,6 +12,119 @@ export function isTTY(): boolean {
 	return process.stdin.isTTY === true && process.stdout.isTTY === true;
 }
 
+const ORG_ID_ENV_VAR = 'AGENTUITY_CLOUD_ORG_ID';
+const NON_INTERACTIVE_ORG_ERROR =
+	'Cannot select organization in non-interactive mode. ' +
+	`Use --org-id, set ${ORG_ID_ENV_VAR}, or run interactively.`;
+
+const RESOURCE_PREFIXES: Array<{ prefix: string; type: ResourceType }> = [
+	{ prefix: 'sbx_', type: 'sandbox' },
+	{ prefix: 'proj_', type: 'project' },
+	{ prefix: 'db_', type: 'db' },
+	{ prefix: 'deploy_', type: 'deployment' },
+	{ prefix: 'machine_', type: 'machine' },
+	{ prefix: 'que_', type: 'queue' },
+	{ prefix: 'vec_', type: 'vector' },
+	{ prefix: 'kv_', type: 'kv' },
+	{ prefix: 'stream_', type: 'stream' },
+];
+
+function getResourceTypeFromId(id: string): ResourceType | undefined {
+	for (const entry of RESOURCE_PREFIXES) {
+		if (id.startsWith(entry.prefix)) {
+			return entry.type;
+		}
+	}
+	return undefined;
+}
+
+function collectPrefixedIds(values?: Record<string, unknown> | unknown[]): string[] {
+	if (!values) {
+		return [];
+	}
+	const ids = new Set<string>();
+	const addValue = (value: unknown) => {
+		if (typeof value === 'string') {
+			const resourceType = getResourceTypeFromId(value);
+			if (resourceType) {
+				ids.add(value);
+			}
+			return;
+		}
+		if (Array.isArray(value)) {
+			for (const entry of value) {
+				if (typeof entry === 'string') {
+					const resourceType = getResourceTypeFromId(entry);
+					if (resourceType) {
+						ids.add(entry);
+					}
+				}
+			}
+		}
+	};
+
+	for (const value of Object.values(values)) {
+		addValue(value);
+	}
+
+	return Array.from(ids);
+}
+
+export function hasPrefixedResourceId(
+	args?: Record<string, unknown> | unknown[],
+	opts?: Record<string, unknown> | unknown[]
+): boolean {
+	return collectPrefixedIds(args).length > 0 || collectPrefixedIds(opts).length > 0;
+}
+
+async function resolveCachedOrgId(ctx: {
+	config: Config | null;
+	args?: Record<string, unknown> | unknown[];
+	opts?: Record<string, unknown> | unknown[];
+}): Promise<string | undefined> {
+	const profileName = ctx.config?.name ?? defaultProfileName;
+	const candidateIds = [...collectPrefixedIds(ctx.args), ...collectPrefixedIds(ctx.opts)];
+
+	for (const candidateId of candidateIds) {
+		const resourceType = getResourceTypeFromId(candidateId);
+		if (!resourceType) {
+			continue;
+		}
+		const cachedInfo = await getResourceInfo(resourceType, profileName, candidateId);
+		if (cachedInfo?.orgId) {
+			return cachedInfo.orgId;
+		}
+	}
+
+	return undefined;
+}
+
+export async function resolveOrgIdWithoutPrompt(ctx: {
+	options: { orgId?: string };
+	config: Config | null;
+	args?: Record<string, unknown> | unknown[];
+	opts?: Record<string, unknown> | unknown[];
+}): Promise<string | undefined> {
+	const { options, config, args, opts } = ctx;
+	const envOrgId = process.env[ORG_ID_ENV_VAR];
+	const flagOrgId = options.orgId && options.orgId !== envOrgId ? options.orgId : undefined;
+
+	if (flagOrgId) {
+		return flagOrgId;
+	}
+
+	if (envOrgId) {
+		return envOrgId;
+	}
+
+	const preferredOrgId = config?.preferences?.orgId;
+	if (preferredOrgId) {
+		return preferredOrgId;
+	}
+
+	return resolveCachedOrgId({ config, args, opts });
+}
+
 export async function hasLoggedInBefore(): Promise<boolean> {
 	const configPath = getDefaultConfigPath();
 	return await Bun.file(configPath).exists();
@@ -231,11 +345,37 @@ export async function requireOrg(
 	ctx: CommandContext & { apiClient: APIClientType },
 	autoSelect?: boolean
 ): Promise<string> {
-	const { options, config, apiClient } = ctx;
+	const { options, config, apiClient, args, opts } = ctx as CommandContext & {
+		apiClient: APIClientType;
+		args?: Record<string, unknown>;
+		opts?: Record<string, unknown>;
+	};
+	const interactive = isTTY();
+	const envOrgId = process.env[ORG_ID_ENV_VAR];
+	const flagOrgId = options.orgId && options.orgId !== envOrgId ? options.orgId : undefined;
+
+	// 1. --org-id flag
+	if (flagOrgId) {
+		return flagOrgId;
+	}
+
+	// 2. Environment variable
+	if (envOrgId) {
+		return envOrgId;
+	}
+
+	// 3. Config preference (TTY: prompt with pre-selected, non-TTY: use directly)
+	const preferredOrgId = config?.preferences?.orgId;
+	if (preferredOrgId && (!interactive || autoSelect)) {
+		return preferredOrgId;
+	}
 
-	// Check if org is provided via --org-id flag
-	if (options.orgId) {
-		return options.orgId;
+	// Cache lookup for prefixed resource IDs
+	if (!preferredOrgId) {
+		const cachedOrgId = await resolveCachedOrgId({ config, args, opts });
+		if (cachedOrgId) {
+			return cachedOrgId;
+		}
 	}
 
 	// Fetch organizations
@@ -251,13 +391,33 @@ export async function requireOrg(
 		tui.fatal('No organizations found for your account');
 	}
 
-	// Use selectOrganization which handles single org and prompting
-	// Pass the saved preference as initial selection
-	// Pass autoSelect to skip prompting when --confirm is used
-	const orgId = await tui.selectOrganization(orgs, config?.preferences?.orgId, autoSelect);
+	// 4. Single-org auto-select
+	if (orgs.length === 1 && orgs[0]) {
+		const orgId = orgs[0].id;
+		if (orgId !== preferredOrgId) {
+			await saveOrgId(orgId);
+		}
+		return orgId;
+	}
+
+	// Auto-select mode (--confirm flag or explicit autoSelect)
+	if (autoSelect) {
+		const orgId = await tui.selectOrganization(orgs, preferredOrgId, true);
+		if (orgId !== preferredOrgId) {
+			await saveOrgId(orgId);
+		}
+		return orgId;
+	}
+
+	// 5. Interactive prompt (TTY) / Error (no TTY)
+	if (!interactive) {
+		return tui.fatal(NON_INTERACTIVE_ORG_ERROR);
+	}
+
+	const orgId = await tui.selectOrganization(orgs, preferredOrgId, false);
 
 	// Save selected org to config if different
-	if (orgId !== config?.preferences?.orgId) {
+	if (orgId !== preferredOrgId) {
 		await saveOrgId(orgId);
 	}
 
@@ -268,7 +428,15 @@ export async function optionalOrg(
 	ctx: CommandContext & { apiClient?: APIClientType; auth?: AuthData },
 	autoSelect?: boolean
 ): Promise<string | undefined> {
-	const { options, config, apiClient, auth } = ctx;
+	const { options, config, apiClient, auth, args, opts } = ctx as CommandContext & {
+		apiClient?: APIClientType;
+		auth?: AuthData;
+		args?: Record<string, unknown>;
+		opts?: Record<string, unknown>;
+	};
+	const interactive = isTTY();
+	const envOrgId = process.env[ORG_ID_ENV_VAR];
+	const flagOrgId = options.orgId && options.orgId !== envOrgId ? options.orgId : undefined;
 
 	// If not authenticated or no API client, skip org selection
 	if (!auth || !apiClient) {
@@ -282,9 +450,28 @@ export async function optionalOrg(
 
 	// Note: --no-register check is handled in cli.ts before calling this function
 
-	// Check if org is provided via --org-id flag
-	if (options.orgId) {
-		return options.orgId;
+	// 1. --org-id flag
+	if (flagOrgId) {
+		return flagOrgId;
+	}
+
+	// 2. Environment variable
+	if (envOrgId) {
+		return envOrgId;
+	}
+
+	// 3. Config preference (TTY: prompt with pre-selected, non-TTY: use directly)
+	const preferredOrgId = config?.preferences?.orgId;
+	if (preferredOrgId && (!interactive || autoSelect)) {
+		return preferredOrgId;
+	}
+
+	// Cache lookup for prefixed resource IDs
+	if (!preferredOrgId) {
+		const cachedOrgId = await resolveCachedOrgId({ config, args, opts });
+		if (cachedOrgId) {
+			return cachedOrgId;
+		}
 	}
 
 	// Fetch organizations
@@ -300,12 +487,34 @@ export async function optionalOrg(
 		return undefined;
 	}
 
+	// 4. Single-org auto-select
+	if (orgs.length === 1 && orgs[0]) {
+		const orgId = orgs[0].id;
+		if (orgId !== preferredOrgId) {
+			await saveOrgId(orgId);
+		}
+		return orgId;
+	}
+
+	// Auto-select mode (--confirm flag or explicit autoSelect)
+	if (autoSelect) {
+		const orgId = await tui.selectOrganization(orgs, preferredOrgId, true);
+		if (orgId !== preferredOrgId) {
+			await saveOrgId(orgId);
+		}
+		return orgId;
+	}
+
+	// 5. Interactive prompt (TTY) / Error (no TTY)
+	if (!interactive) {
+		return tui.fatal(NON_INTERACTIVE_ORG_ERROR);
+	}
+
 	// Prompt for org selection (use saved preference as initial/default)
-	// Pass autoSelect to skip prompting when --confirm is used
-	const orgId = await tui.selectOrganization(orgs, config?.preferences?.orgId, autoSelect);
+	const orgId = await tui.selectOrganization(orgs, preferredOrgId, false);
 
 	// Save selected org to config if different
-	if (orgId !== config?.preferences?.orgId) {
+	if (orgId !== preferredOrgId) {
 		await saveOrgId(orgId);
 	}
 

package/src/banner.ts

@@ -7,6 +7,7 @@ import {
 	getDisplayWidth,
 	stripAnsi,
 } from './tui';
+import { getExecutingAgent } from './agent-detection';
 
 export function generateBanner(version?: string, compact?: true): string {
 	const _version = version ?? getVersion();
@@ -83,5 +84,9 @@ export function generateBanner(version?: string, compact?: true): string {
 }
 
 export function showBanner(version?: string, compact?: true): void {
+	// Skip banner when running from an AI coding agent
+	if (getExecutingAgent()) {
+		return;
+	}
 	console.log(generateBanner(version, compact));
 }