@agentuity/cli 1.0.1 → 1.0.3

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Package Overview
 
-Bun-native CLI framework for Agentuity applications. Provides command structure, auto-discovery, configuration management, and type-safe command options.
+Bun-native CLI framework for Agentuity applications. Provides command structure, auto-discovery, configuration management, TUI helpers, and type-safe command options.
 
 ## Commands
 
@@ -22,45 +22,61 @@ Bun-native CLI framework for Agentuity applications. Provides command structure,
 
 - **Command structure**: Each command is a directory in `src/cmd/` with `index.ts`
 - **Type safety**: Always define interfaces for command options (never `any`)
-- **TUI output**: Use `tui.*` helpers for formatted output (see `src/tui.md`)
+- **TUI output**: Use `tui.*` helpers for formatted output (header, info, success, warning, error, table, progress)
 - **Logging**: Use `ctx.logger`; `logger.fatal()` logs and exits with code 1
 - **Bun APIs**: Use `Bun.file(f).exists()` not `existsSync(f)`
+- **JSON mode**: Always check `isJSONMode()` for machine-readable output
+- **Auth**: Use `requireAuth(ctx)` or `optionalAuth(ctx)` for authenticated commands
 
-## Creating Commands
+## Key Patterns
+
+### Creating Commands
 
 ```typescript
 // src/cmd/deploy/index.ts
-import type { CommandDefinition, CommandContext } from '../../types';
-import { Command } from 'commander';
-
-interface DeployOptions {
-	force: boolean;
-	dryRun: boolean;
-}
+import { z } from 'zod';
+import { createCommand, type CommandContext } from '@agentuity/cli';
 
-export const deployCommand: CommandDefinition = {
+export default createCommand({
 	name: 'deploy',
 	description: 'Deploy to an environment',
-	register(program: Command, ctx: CommandContext) {
-		program
-			.command('deploy <environment>')
-			.option('-f, --force', 'Force deployment', false)
-			.option('--dry-run', 'Dry run mode', false)
-			.action(async (environment: string, options: DeployOptions) => {
-				ctx.logger.info(`Deploying to: ${environment}`);
-			});
+	schema: {
+		options: z.object({
+			force: z.boolean().optional().describe('Force deployment'),
+			dryRun: z.boolean().optional().describe('Dry run mode'),
+		}),
 	},
-};
+	async handler(ctx: CommandContext) {
+		const { opts, logger } = ctx;
+		logger.info(`Deploying with force=${opts.force}, dryRun=${opts.dryRun}`);
+	},
+});
+```
 
-export default deployCommand;
+### Output Modes
+
+```typescript
+import { isJSONMode, outputJSON, outputSuccess, createSuccessResponse } from '@agentuity/cli';
+
+if (isJSONMode()) {
+	outputJSON(createSuccessResponse({ data }));
+} else {
+	outputSuccess('Operation completed');
+}
 ```
 
-## Build Architecture
+## Important Exports
+
+- **CLI**: `createCLI`, `registerCommands`, `discoverCommands`
+- **Output**: `isJSONMode`, `outputJSON`, `outputSuccess`, `outputInfo`, `outputWarning`, `tui.*`
+- **Config**: `loadConfig`, `saveConfig`, `saveAuth`, `getAuth`, `clearAuth`
+- **Auth**: `requireAuth`, `optionalAuth`, `APIClient`
+- **Utils**: `runSteps`, `downloadGitHubTarball`, `createRepl`, `showBanner`
 
-See [docs/build-architecture.md](docs/build-architecture.md) for Vite + Bun build system details.
+See `src/index.ts` for complete exports.
 
 ## Publishing
 
 1. Run `bun run build`
 2. Test CLI with `bun bin/cli.ts`
-3. Depends on `@agentuity/core` and `commander`
+3. Depends on `@agentuity/core`, `@agentuity/server`, and `commander`

package/bin/cli.ts

@@ -8,7 +8,7 @@ if (versionArgs.length === 1 && ['version', '-v', '--version', '-V'].includes(ve
 	process.exit(0);
 }
 
-import { ConsoleLogger } from '@agentuity/server';
+import { ConsoleLogger, getAppBaseURL } from '@agentuity/server';
 import { isStructuredError } from '@agentuity/core';
 import { createCLI, registerCommands } from '../src/cli';
 import { validateRuntime } from '../src/runtime';
@@ -20,6 +20,7 @@ import { getVersion, getPackageName } from '../src/version';
 
 import type { CommandContext, LogLevel } from '../src/types';
 import { generateCLISchema } from '../src/schema-generator';
+import { generateAIHelp } from '../src/ai-help';
 import { setOutputOptions } from '../src/output';
 import type { GlobalOptions } from '../src/types';
 import { ensureBunOnPath } from '../src/bun-path';
@@ -28,12 +29,7 @@ import { closeDatabase } from '../src/cache';
 import { createInternalLogger } from '../src/internal-logger';
 import { createCompositeLogger } from '../src/composite-logger';
 import { getAuth } from '../src/config';
-import {
-	startAgentDetection,
-	isExecutingFromAgent,
-	onAgentDetected,
-	flushAgentDetection,
-} from '../src/agent-detection';
+import { getExecutingAgent } from '../src/agent-detection';
 
 /**
  * Extract --dir flag from process.argv before command parsing
@@ -95,10 +91,6 @@ process.on('SIGTERM', () => {
 validateRuntime();
 await ensureBunOnPath();
 
-// Start agent detection early (non-blocking) so it runs in the background
-// while the rest of CLI initialization happens
-startAgentDetection();
-
 // Preprocess arguments to convert --help=json to --help json
 // Commander.js doesn't support --option=value syntax for optional values
 const preprocessedArgs = process.argv.slice(2).flatMap((arg) => {
@@ -132,6 +124,21 @@ if (
 	exit(0);
 }
 
+// Check for --ai-help early (dashdash format for AI agents)
+// This runs before auth/validation per dashdash spec "eager" requirement
+if (preprocessedArgs.includes('--ai-help')) {
+	const version = getVersion();
+	const program = await createCLI(version);
+	const commands = await discoverCommands();
+	const cliSchema = generateCLISchema(program, commands, version);
+	const aiHelp = generateAIHelp(cliSchema);
+	console.log(aiHelp);
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const exit = (globalThis as any).AGENTUITY_PROCESS_EXIT || process.exit;
+	closeDatabase();
+	exit(0);
+}
+
 const version = getVersion();
 const program = await createCLI(version);
 
@@ -228,12 +235,11 @@ if (shouldSkipInternalLogging) {
 	// Set session ID in environment so forked child processes can share the same log file
 	process.env.AGENTUITY_INTERNAL_SESSION_ID = internalLogger.getSessionId();
 
-	// Register callback to update session with detected agent (non-blocking)
-	onAgentDetected((agent) => {
-		if (agent) {
-			internalLogger.setDetectedAgent(agent);
-		}
-	});
+	// Set detected agent in session logs
+	const detectedAgent = getExecutingAgent();
+	if (detectedAgent) {
+		internalLogger.setDetectedAgent(detectedAgent);
+	}
 }
 
 // Create composite logger that writes to both console and internal log
@@ -244,7 +250,7 @@ if (earlyOpts.skipVersionCheck) {
 	process.env.AGENTUITY_SKIP_VERSION_CHECK = '1';
 }
 
-const config = await loadConfig(earlyOpts.config);
+const config = await loadConfig(earlyOpts.config, false, earlyOpts.profile);
 
 // Update internal logger with userId if available from auth (keychain or config)
 try {
@@ -260,7 +266,7 @@ const ctx = {
 	config,
 	logger,
 	options: earlyOpts,
-	isExecutingFromAgent,
+	getExecutingAgent,
 };
 
 // Set global output options for utilities to use
@@ -293,8 +299,6 @@ await registerCommands(program, commands, ctx as unknown as CommandContext);
 
 try {
 	await program.parseAsync(process.argv);
-	// Flush agent detection to ensure it's written to session logs before exit
-	await flushAgentDetection();
 } catch (error) {
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	const exit = (globalThis as any).AGENTUITY_PROCESS_EXIT || process.exit;
@@ -322,7 +326,28 @@ try {
 		closeDatabase();
 		exit(0);
 	}
-	const errorWithMessage = error as { message?: string };
+	const errorWithMessage = error as { message?: string; statusCode?: number; _tag?: string };
+
+	// Handle payment required (402) errors with a friendly TUI message
+	if (
+		isStructuredError(error) &&
+		((errorWithMessage._tag === 'ServiceException' && errorWithMessage.statusCode === 402) ||
+			errorWithMessage._tag === 'PaymentRequiredError')
+	) {
+		const { errorBox, link, newline } = await import('../src/tui');
+		const overrides = config?.overrides as { app_url?: string } | undefined;
+		const appBaseUrl = getAppBaseURL(undefined, overrides);
+		const billingUrl = `${appBaseUrl}/billing`;
+		newline();
+		errorBox(
+			'Out of Credit',
+			`Your organization is out of credit.\n\nPlease add more here:\n${link(billingUrl)}`,
+			false // standalone box, not connected to a guide
+		);
+		closeDatabase();
+		exit(1);
+	}
+
 	if (isStructuredError(error)) {
 		logger.error(error);
 	} else {

package/dist/agent-detection.d.ts

@@ -1,6 +1,6 @@
 /**
  * Map of process names to internal agent short names.
- * The key is the process name (or substring) that appears in the parent process command line.
+ * The key is the process name (or substring) that appears in the parent process path or command line.
  * The value is the internal short name used to identify the agent.
  *
  * Process names verified via `agentuity cloud sandbox run --runtime <agent>:latest`:
@@ -18,54 +18,39 @@
 export declare const KNOWN_AGENTS: [string, string][];
 export type KnownAgent = (typeof KNOWN_AGENTS)[number][1];
 /**
- * Start agent detection immediately (non-blocking).
- * Call this early in CLI startup to begin detection in the background.
+ * Display names for known agents (human-friendly names)
  */
-export declare function startAgentDetection(): void;
+export declare const AGENT_DISPLAY_NAMES: Record<string, string>;
 /**
- * Register a callback to be invoked when agent detection completes.
- * If detection has already completed, the callback is invoked immediately.
- * This is non-blocking and does not return a promise.
- *
- * @example
- * ```typescript
- * onAgentDetected((agent) => {
- *   if (agent) {
- *     console.log(`Detected agent: ${agent}`);
- *   }
- * });
- * ```
- */
-export declare function onAgentDetected(callback: (agent: string | undefined) => void): void;
-/**
- * Get the cached detection result synchronously.
- * Returns undefined if detection hasn't completed yet or no agent was detected.
- * Returns null if detection hasn't started or completed yet.
- *
- * Use this for synchronous access when you don't want to wait for detection.
- */
-export declare function getDetectedAgent(): string | undefined | null;
-/**
- * Wait for agent detection to complete and ensure all callbacks have been invoked.
- * Call this before CLI exit to ensure the detected agent is written to session logs.
- *
- * This is a no-op if detection hasn't started or has already completed.
+ * Get the display name for an agent ID
  */
-export declare function flushAgentDetection(): Promise<void>;
+export declare function getAgentDisplayName(agentId: string): string;
 /**
- * Check if the CLI is being executed from a known coding agent.
- * Returns the agent name if detected, undefined otherwise.
+ * Get the executing agent if the CLI is being run from a known coding agent.
+ * Returns the agent ID if detected, undefined otherwise.
  *
- * This function returns immediately if detection has already completed,
- * otherwise it awaits the detection promise started by startAgentDetection().
+ * This function runs synchronously using FFI for fast process path resolution.
+ * Results are cached after the first call.
  *
  * @example
  * ```typescript
- * const agent = await isExecutingFromAgent();
+ * const agent = getExecutingAgent();
  * if (agent) {
  *   logger.debug(`Running from agent: ${agent}`);
  * }
  * ```
  */
-export declare function isExecutingFromAgent(): Promise<string | undefined>;
+export declare function getExecutingAgent(): string | undefined;
+/**
+ * Get environment variables to pass to subprocesses for agent detection.
+ * This allows child processes to skip re-detection by using the cached result.
+ *
+ * @example
+ * ```typescript
+ * const proc = Bun.spawn(['bun', 'run', 'dev'], {
+ *   env: { ...process.env, ...getAgentEnv() },
+ * });
+ * ```
+ */
+export declare function getAgentEnv(): Record<string, string>;
 //# sourceMappingURL=agent-detection.d.ts.map

package/dist/agent-detection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-detection.d.ts","sourceRoot":"","sources":["../src/agent-detection.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAgB1C,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAiI1D;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAkB1C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,GAAG,IAAI,CAanF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,GAAG,IAAI,CAE5D;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAIzD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAaxE"}
+{"version":3,"file":"agent-detection.d.ts","sourceRoot":"","sources":["../src/agent-detection.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAiB1C,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAatD,CAAC;AAEF;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3D;AA4cD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAStD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMpD"}