@agentuity/cli 0.0.11 → 0.0.13

package/src/cli.ts

@@ -1,7 +1,7 @@
 import { Command } from 'commander';
 import type { CommandDefinition, SubcommandDefinition, CommandContext } from './types';
 import { showBanner } from './banner';
-import { requireAuth } from './auth';
+import { requireAuth, optionalAuth } from './auth';
 import { parseArgsSchema, parseOptionsSchema, buildValidationInput } from './schema-parser';
 
 export async function createCLI(version: string): Promise<Command> {
@@ -121,6 +121,46 @@ async function registerSubcommand(
 				};
 				await subcommand.handler(ctx);
 			}
+		} else if (subcommand.optionalAuth) {
+			const continueText =
+				typeof subcommand.optionalAuth === 'string' ? subcommand.optionalAuth : undefined;
+			const auth = await optionalAuth(baseCtx as CommandContext<false>, continueText);
+
+			if (subcommand.schema) {
+				try {
+					const input = buildValidationInput(subcommand.schema, args, options);
+					const ctx: Record<string, unknown> = {
+						...baseCtx,
+						...(auth ? { auth } : {}),
+					};
+					if (subcommand.schema.args) {
+						ctx.args = subcommand.schema.args.parse(input.args);
+					}
+					if (subcommand.schema.options) {
+						ctx.opts = subcommand.schema.options.parse(input.options);
+					}
+					await subcommand.handler(ctx as CommandContext);
+				} catch (error) {
+					if (error && typeof error === 'object' && 'issues' in error) {
+						baseCtx.logger.error('Validation error:');
+						const issues = (error as { issues: Array<{ path: string[]; message: string }> })
+							.issues;
+						for (const issue of issues) {
+							baseCtx.logger.error(`  ${issue.path.join('.')}: ${issue.message}`);
+						}
+						process.exit(1);
+					}
+					throw error;
+				}
+			} else if (auth) {
+				const ctx: CommandContext<true> = {
+					...baseCtx,
+					auth,
+				};
+				await subcommand.handler(ctx);
+			} else {
+				await subcommand.handler(baseCtx as CommandContext<false>);
+			}
 		} else {
 			if (subcommand.schema) {
 				try {
@@ -175,6 +215,16 @@ export async function registerCommands(
 						const auth = await requireAuth(baseCtx as CommandContext<false>);
 						const ctx: CommandContext<true> = { ...baseCtx, auth };
 						await cmdDef.handler!(ctx);
+					} else if (cmdDef.optionalAuth) {
+						const continueText =
+							typeof cmdDef.optionalAuth === 'string' ? cmdDef.optionalAuth : undefined;
+						const auth = await optionalAuth(baseCtx as CommandContext<false>, continueText);
+						if (auth) {
+							const ctx: CommandContext<true> = { ...baseCtx, auth };
+							await cmdDef.handler!(ctx);
+						} else {
+							await cmdDef.handler!(baseCtx as CommandContext<false>);
+						}
 					} else {
 						await cmdDef.handler!(baseCtx as CommandContext<false>);
 					}

package/src/cmd/auth/README.md

@@ -33,6 +33,34 @@ preferences:
    orgId: ''
 ```
 
+### `auth signup`
+
+Create a new Agentuity Cloud Platform account.
+
+```bash
+agentuity auth signup
+# or
+agentuity signup
+```
+
+**How it works:**
+
+1. Generates a random 5-character OTP locally (client-side)
+2. Displays a signup URL with the OTP code: `/sign-up?code=<otp>`
+3. User opens the URL in their browser and completes the signup process
+4. Polls `GET /cli/auth/signup/<otp>` every 2 seconds for up to 5 minutes
+5. Server returns 404 until signup is complete, then returns credentials
+6. Once complete, saves the API key, user ID, and expiration to config
+
+**Stored data:**
+
+```yaml
+auth:
+   api_key: 'your-api-key'
+   user_id: 'user-id'
+   expires: 1234567890
+```
+
 ### `auth logout`
 
 Logout of the Agentuity Cloud Platform by clearing authentication credentials.
@@ -55,6 +83,7 @@ The authentication flow uses the following API endpoints:
 
 - `GET /cli/auth/start` - Generate OTP for login
 - `POST /cli/auth/check` - Poll for login completion with OTP
+- `GET /cli/auth/signup/<otp>` - Poll for signup completion with client-generated OTP (returns 404 until complete)
 
 ## URL Configuration
 
@@ -80,13 +109,18 @@ This allows different profiles (e.g., `local`, `production`) to point to differe
 
 ## Implementation Details
 
-- **Generic API Client**: [../../api.ts](../../api.ts) provides the generic `APIClient` class for HTTP requests
-- **Auth-specific APIs**: [api.ts](./api.ts) provides `generateLoginOTP()` and `pollForLoginCompletion()` functions
+- **Generic API Client**: [../../api.ts](../../api.ts) provides the generic `APIClient` class and `APIError` for HTTP requests
+- **Auth-specific APIs**: [api.ts](./api.ts) provides:
+   - `generateLoginOTP()` and `pollForLoginCompletion()` for login flow
+   - `generateSignupOTP()` and `pollForSignupCompletion()` for signup flow
 - **Config Management**: [../../config.ts](../../config.ts) provides `saveAuth()`, `clearAuth()`, and `getAuth()` helpers
 - **Browser Opening**: Uses `Bun.spawn(['open', authURL])` on non-Windows platforms to auto-open browser
-- **Polling**: Polls every 2 seconds with 60-second timeout
+- **Polling**:
+   - Login: Polls every 2 seconds with 60-second timeout
+   - Signup: Polls every 2 seconds with 5-minute timeout, retries on 404 errors
 - **Error Handling**: All errors are caught and displayed to user with appropriate exit codes
    - `UpgradeRequiredError`: Shows upgrade instructions when CLI version is outdated
+   - `APIError`: Preserves HTTP status codes for proper retry logic (e.g., 404 during signup polling)
    - Generic API errors: Display the error message from the server
    - See [../../api-errors.md](../../api-errors.md) for details
 

package/src/cmd/auth/api.ts

@@ -1,4 +1,4 @@
-import { APIClient } from '@/api';
+import { APIClient, APIError } from '@/api';
 import type { Config } from '@/types';
 
 interface APIResponse<T> {
@@ -23,6 +23,18 @@ export interface LoginResult {
 	expires: Date;
 }
 
+interface SignupCompleteData {
+	userId: string;
+	apiKey: string;
+	expiresAt: number;
+}
+
+export interface SignupResult {
+	apiKey: string;
+	userId: string;
+	expires: Date;
+}
+
 export async function generateLoginOTP(apiUrl: string, config?: Config | null): Promise<string> {
 	const client = new APIClient(apiUrl, undefined, config);
 	const resp = await client.request<APIResponse<OTPStartData>>('GET', '/cli/auth/start');
@@ -64,8 +76,60 @@ export async function pollForLoginCompletion(
 			};
 		}
 
-		await new Promise((resolve) => setTimeout(resolve, 2000));
+		await Bun.sleep(2000);
 	}
 
 	throw new Error('Login timed out');
 }
+
+export function generateSignupOTP(): string {
+	const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+	let result = '';
+	const array = new Uint8Array(5);
+	crypto.getRandomValues(array);
+	for (let i = 0; i < 5; i++) {
+		result += chars[array[i] % chars.length];
+	}
+	return result;
+}
+
+export async function pollForSignupCompletion(
+	apiUrl: string,
+	otp: string,
+	config?: Config | null,
+	timeoutMs = 300000
+): Promise<SignupResult> {
+	const client = new APIClient(apiUrl, undefined, config);
+	const started = Date.now();
+
+	while (Date.now() - started < timeoutMs) {
+		try {
+			const resp = await client.request<APIResponse<SignupCompleteData>>(
+				'GET',
+				`/cli/auth/signup/${otp}`
+			);
+
+			if (!resp.success) {
+				throw new Error(resp.message);
+			}
+
+			if (resp.data) {
+				return {
+					apiKey: resp.data.apiKey,
+					userId: resp.data.userId,
+					expires: new Date(resp.data.expiresAt),
+				};
+			}
+		} catch (error) {
+			if (error instanceof APIError && error.status === 404) {
+				await Bun.sleep(2000);
+				continue;
+			}
+			throw error;
+		}
+
+		await Bun.sleep(2000);
+	}
+
+	throw new Error('Signup timed out');
+}

package/src/cmd/auth/index.ts

@@ -1,9 +1,10 @@
 import { createCommand } from '@/types';
 import { loginCommand } from './login';
 import { logoutCommand } from './logout';
+import { signupCommand } from './signup';
 
 export const command = createCommand({
 	name: 'auth',
 	description: 'Authentication and authorization related commands',
-	subcommands: [loginCommand, logoutCommand],
+	subcommands: [loginCommand, logoutCommand, signupCommand],
 });

package/src/cmd/auth/login.ts

@@ -15,9 +15,16 @@ export const loginCommand: SubcommandDefinition = {
 		const appUrl = getAppBaseURL(config);
 
 		try {
-			console.log('Generating login OTP...');
+			let otp: string | undefined;
+
+			await tui.spinner('Generating login one time code...', async () => {
+				otp = await generateLoginOTP(apiUrl, config);
+			});
+
+			if (!otp) {
+				return;
+			}
 
-			const otp = await generateLoginOTP(apiUrl, config);
 			const authURL = `${appUrl}/auth/cli`;
 
 			const copied = await tui.copyToClipboard(otp);
@@ -39,7 +46,8 @@ export const loginCommand: SubcommandDefinition = {
 			tui.newline();
 
 			if (process.platform === 'darwin') {
-				await tui.waitForAnyKey('Press Enter to open the URL...');
+				await tui.waitForAnyKey('Press any key to open the URL in your browser...');
+				tui.newline();
 				try {
 					Bun.spawn(['open', authURL], {
 						stdio: ['ignore', 'ignore', 'ignore'],

package/src/cmd/auth/signup.ts

@@ -0,0 +1,51 @@
+import type { SubcommandDefinition } from '@/types';
+import { getAPIBaseURL, getAppBaseURL, UpgradeRequiredError } from '@/api';
+import { saveAuth } from '@/config';
+import { generateSignupOTP, pollForSignupCompletion } from './api';
+import * as tui from '@/tui';
+
+export const signupCommand: SubcommandDefinition = {
+	name: 'signup',
+	description: 'Create a new Agentuity Cloud Platform account',
+	toplevel: true,
+
+	async handler(ctx) {
+		const { logger, config } = ctx;
+		const apiUrl = getAPIBaseURL(config);
+		const appUrl = getAppBaseURL(config);
+
+		try {
+			const otp = generateSignupOTP();
+
+			const signupURL = `${appUrl}/sign-up?code=${otp}`;
+
+			const bannerBody = `Please open the URL in your browser:\n\n${tui.link(signupURL)}\n\n${tui.muted('Once you have completed the signup process, you will be given a one-time password to complete the signup process.')}`;
+
+			tui.banner('Signup for Agentuity', bannerBody);
+			tui.newline();
+
+			await tui.spinner('Waiting for signup to complete...', async () => {
+				const result = await pollForSignupCompletion(apiUrl, otp, config);
+
+				await saveAuth({
+					apiKey: result.apiKey,
+					userId: result.userId,
+					expires: result.expires,
+				});
+			});
+
+			tui.newline();
+			tui.success('Welcome to Agentuity! You are now logged in');
+		} catch (error) {
+			if (error instanceof UpgradeRequiredError) {
+				const bannerBody = `${error.message}\n\nVisit: ${tui.link('https://agentuity.dev/CLI/installation')}`;
+				tui.banner('CLI Upgrade Required', bannerBody);
+				process.exit(1);
+			} else if (error instanceof Error) {
+				logger.fatal(`Signup failed: ${error.message}`);
+			} else {
+				logger.fatal('Signup failed');
+			}
+		}
+	},
+};

package/src/cmd/dev/index.ts

@@ -1,8 +1,8 @@
 import { createCommand } from '@/types';
 import { z } from 'zod';
-import { resolve } from 'node:path';
+import { resolve, join } from 'node:path';
 import { bundle } from '../bundle/bundler';
-import { existsSync } from 'node:fs';
+import { existsSync, FSWatcher, watch } from 'node:fs';
 import * as tui from '@/tui';
 
 export const command = createCommand({
@@ -13,71 +13,156 @@ export const command = createCommand({
 			dir: z.string().optional().describe('Root directory of the project'),
 		}),
 	},
+	optionalAuth: 'Continue without an account (local only)',
 
 	async handler(ctx) {
-		const { opts } = ctx;
+		const { opts, logger } = ctx;
+
 		const rootDir = resolve(opts.dir || process.cwd());
+		const appTs = join(rootDir, 'app.ts');
+		const srcDir = join(rootDir, 'src');
+		const mustHaves = [join(rootDir, 'package.json'), appTs, srcDir];
+		const missing: string[] = [];
+
+		for (const filename of mustHaves) {
+			if (!existsSync(filename)) {
+				missing.push(filename);
+			}
+		}
+
+		if (missing.length) {
+			tui.error(`${rootDir} does not appear to be a valid Agentuity project`);
+			for (const filename of missing) {
+				tui.bullet(`Missing ${filename}`);
+			}
+			process.exit(1);
+		}
+
 		const agentuityDir = resolve(rootDir, '.agentuity');
 		const appPath = resolve(agentuityDir, 'app.js');
 
-		try {
-			await tui.spinner('Building project...', async () => {
-				await bundle({
-					rootDir,
-					dev: true,
-				});
-			});
+		const watches = [appTs, srcDir];
+		const watchers: FSWatcher[] = [];
+		let failures = 0;
+		let running = false;
+		let pid = 0;
+		let failed = false;
+		let devServer: Bun.Subprocess | undefined;
 
-			tui.success('Build complete');
+		function failure(msg: string) {
+			failed = true;
+			failures++;
+			if (failures >= 5) {
+				tui.error(msg);
+				tui.fatal('too many failures, exiting');
+			} else {
+				setImmediate(() => tui.error(msg));
+			}
+		}
 
-			if (!existsSync(appPath)) {
-				tui.error(`App file not found: ${appPath}`);
-				process.exit(1);
+		const kill = () => {
+			running = false;
+			try {
+				// Kill the process group (negative PID kills entire group)
+				process.kill(-pid, 'SIGTERM');
+			} catch {
+				// Fallback: kill the direct process
+				try {
+					if (devServer) {
+						devServer.kill();
+					}
+				} catch {
+					// Ignore if already dead
+				}
+			} finally {
+				devServer = undefined;
 			}
+		};
 
-			tui.newline();
-			tui.info('Starting development server...');
-			tui.newline();
-
-			// Use shell to run in a process group for proper cleanup
-			// The 'exec' ensures the shell is replaced by the actual process
-			const devServer = Bun.spawn(['sh', '-c', `exec bun run "${appPath}"`], {
-				cwd: rootDir,
-				stdout: 'inherit',
-				stderr: 'inherit',
-				stdin: 'inherit',
-			});
-
-			// Handle signals to ensure entire process tree is killed
-			const cleanup = () => {
-				if (devServer.pid) {
-					try {
-						// Kill the process group (negative PID kills entire group)
-						process.kill(-devServer.pid, 'SIGTERM');
-					} catch {
-						// Fallback: kill the direct process
+		// Handle signals to ensure entire process tree is killed
+		const cleanup = () => {
+			if (pid && running) {
+				kill();
+			}
+			for (const watcher of watchers) {
+				watcher.close();
+			}
+			watchers.length = 0;
+			process.exit(0);
+		};
+
+		process.on('SIGINT', cleanup);
+		process.on('SIGTERM', cleanup);
+
+		async function restart() {
+			try {
+				if (running) {
+					tui.info('Restarting on file change');
+					kill();
+					return;
+				}
+				await Promise.all([
+					tui.runCommand({
+						command: 'tsc',
+						cmd: ['bunx', 'tsc', '--noEmit'],
+						cwd: rootDir,
+						clearOnSuccess: true,
+						truncate: false,
+						maxLinesOutput: 1,
+						maxLinesOnFailure: 15,
+					}),
+					tui.spinner('Building project', async () => {
 						try {
-							devServer.kill();
+							await bundle({
+								rootDir,
+								dev: true,
+							});
 						} catch {
-							// Ignore if already dead
+							failure('Build failed');
 						}
-					}
+					}),
+				]);
+
+				if (failed) {
+					return;
 				}
-				process.exit(0);
-			};
 
-			process.on('SIGINT', cleanup);
-			process.on('SIGTERM', cleanup);
+				if (!existsSync(appPath)) {
+					failure(`App file not found: ${appPath}`);
+					return;
+				}
 
-			const exitCode = await devServer.exited;
-			process.exit(exitCode);
-		} catch (error) {
-			if (error instanceof Error) {
-				tui.error(`Dev server failed: ${error.message}`);
-			} else {
-				tui.error('Dev server failed');
+				// Use shell to run in a process group for proper cleanup
+				// The 'exec' ensures the shell is replaced by the actual process
+				const devServer = Bun.spawn(['sh', '-c', `exec bun run "${appPath}"`], {
+					cwd: rootDir,
+					stdout: 'inherit',
+					stderr: 'inherit',
+					stdin: 'inherit',
+				});
+
+				running = true;
+				failed = false;
+				pid = devServer.pid;
+
+				const exitCode = await devServer.exited;
+				if (exitCode === 0) {
+					process.exit(exitCode);
+				}
+			} catch (error) {
+				if (error instanceof Error) {
+					failure(`Dev server failed: ${error.message}`);
+				} else {
+					failure('Dev server failed');
+				}
+			} finally {
+				running = false;
 			}
-			process.exit(1);
+		}
+		await restart();
+		for (const filename of watches) {
+			logger.trace('watching %s', filename);
+			watchers.push(watch(filename, { recursive: true }, restart));
 		}
 	},
 });

package/src/cmd/example/index.ts

@@ -8,6 +8,7 @@ import { versionSubcommand } from './version';
 import { createUserSubcommand } from './create-user';
 import { runCommandSubcommand } from './run-command';
 import { soundSubcommand } from './sound';
+import { optionalAuthSubcommand } from './optional-auth';
 
 export const command = createCommand({
 	name: 'example',
@@ -23,5 +24,6 @@ export const command = createCommand({
 		createUserSubcommand,
 		runCommandSubcommand,
 		soundSubcommand,
+		optionalAuthSubcommand,
 	],
 });

package/src/cmd/example/optional-auth.ts

@@ -0,0 +1,38 @@
+import type { SubcommandDefinition, CommandContext, AuthData } from '@/types';
+import * as tui from '@/tui';
+
+export const optionalAuthSubcommand: SubcommandDefinition = {
+	name: 'optional-auth',
+	description: 'Test optional authentication flow',
+	optionalAuth: 'Continue with local features only',
+	handler: async (ctx: CommandContext) => {
+		tui.newline();
+
+		// Type guard to check if auth is present
+		const ctxWithAuth = ctx as CommandContext<true>;
+		if ('auth' in ctx && ctxWithAuth.auth) {
+			const auth = ctxWithAuth.auth as AuthData;
+			// User chose to authenticate
+			tui.success('You are authenticated!');
+			tui.info(`User ID: ${auth.userId}`);
+			tui.info(`Session expires: ${auth.expires.toLocaleString()}`);
+			tui.newline();
+			tui.info('You can now access cloud features:');
+			tui.bullet('Deploy to production');
+			tui.bullet('Access remote resources');
+			tui.bullet('View team analytics');
+		} else {
+			// User chose to continue without auth
+			tui.info('Running in local mode (no authentication)');
+			tui.newline();
+			tui.info('Available local features:');
+			tui.bullet('Local development');
+			tui.bullet('Offline testing');
+			tui.bullet('Build and bundle');
+			tui.newline();
+			tui.warning('Some cloud features are unavailable without authentication');
+		}
+
+		tui.newline();
+	},
+};

package/src/cmd/example/sound.ts

@@ -6,9 +6,9 @@ export const soundSubcommand: SubcommandDefinition = {
 	name: 'sound',
 	description: 'Test completion sound',
 
-	async handler() {
+	handler() {
 		tui.info('Playing completion sound...');
-		await playSound();
+		playSound();
 		tui.success('Sound played!');
 	},
 };

package/src/cmd/project/create.ts

@@ -39,6 +39,7 @@ export const createProjectSubcommand = createSubcommand({
 		const { logger, opts } = ctx;
 		await runCreateFlow({
 			projectName: opts.name,
+			dir: opts.dir,
 			template: opts.template,
 			templateDir: opts.templateDir,
 			templateBranch: opts.templateBranch,