@agentuity/cli 3.0.0-alpha.7 → 3.0.0-beta.0

package/src/cmd/ai/prompt/llm.ts

@@ -1,368 +0,0 @@
-import { createSubcommand } from '../../../types';
-import type { CommandContext } from '../../../types';
-import { getCommand } from '../../../command-prefix';
-
-export const llmSubcommand = createSubcommand({
-	name: 'llm',
-	description: 'Generate a comprehensive prompt for LLM agents',
-	tags: ['read-only', 'fast'],
-	idempotent: true,
-	examples: [{ command: getCommand('prompt llm'), description: 'Run llm command' }],
-	async handler(_ctx: CommandContext) {
-		const prompt = generateLLMPrompt();
-		console.log(prompt);
-	},
-});
-
-export function generateLLMPrompt(): string {
-	return `# Agentuity CLI - Agent Usage Guide
-
-## Overview
-
-The Agentuity CLI is an agent-friendly command-line interface for managing cloud deployments, projects, secrets, and infrastructure. It provides machine-readable output, introspection capabilities, and safety features designed for automated agent usage.
-
-## Key Principles for Agent Usage
-
-1. **Always use \`--json\` for machine-readable output**
-   - All commands support \`--json\` for structured output
-   - Errors are also output as JSON when using \`--error-format=json\` (automatically set with \`--json\`)
-
-2. **Use \`--explain\` before executing destructive operations**
-   - Preview what a command will do without executing it
-   - Provides structured explanation with steps, prerequisites, and warnings
-
-3. **Use \`--dry-run\` for safe exploration**
-   - Execute validation and planning without making changes
-   - Test commands safely before actual execution
-
-4. **Discover capabilities programmatically**
-   - Use \`${getCommand('--help=json')}\` to get the complete CLI schema
-   - Use \`${getCommand('capabilities show --json')}\` to discover available tasks
-   - Use \`${getCommand('schema show')}\` for detailed command metadata
-
-## Machine-Readable Modes
-
-### Global Flags
-
-- \`--json\`: Output in JSON format (machine-readable)
-- \`--quiet\`: Suppress non-essential output (only errors shown)
-- \`--no-progress\`: Disable progress indicators and spinners
-- \`--error-format json\`: Structured error output with error codes
-- \`--explain\`: Show what command would do without executing
-- \`--dry-run\`: Execute without making changes
-- \`--color never\`: Disable color output
-
-### Recommended Flag Combinations
-
-For agent usage:
-\`\`\`bash
-${getCommand('--json --quiet command')}
-\`\`\`
-
-For safe exploration:
-\`\`\`bash
-${getCommand('--explain command args')}
-${getCommand('--dry-run command args')}
-\`\`\`
-
-## Introspection Capabilities
-
-### 1. Schema Discovery
-
-Get the complete CLI schema with all commands, arguments, options, and requirements:
-
-\`\`\`bash
-${getCommand('--help=json')}
-${getCommand('schema show')}
-\`\`\`
-
-The schema includes:
-- Command names and descriptions
-- Arguments (type, required/optional, variadic)
-- Options (type, defaults, enums)
-- Authentication requirements
-- Project requirements
-- Examples
-
-### 2. Capabilities Discovery
-
-Get high-level tasks and workflows:
-
-\`\`\`bash
-${getCommand('capabilities show --json')}
-\`\`\`
-
-This returns:
-- Functional capabilities (auth, projects, deployment, secrets, etc.)
-- Common workflows with step-by-step instructions
-- Requirements for each capability (auth, project)
-
-### 3. Examples
-
-All commands include examples in their help text and schema:
-
-\`\`\`bash
-${getCommand('command subcommand --help')}
-\`\`\`
-
-## Error Handling
-
-### Structured Errors
-
-When using \`--json\` or \`--error-format=json\`, errors are structured:
-
-\`\`\`json
-{
-  "error": {
-    "code": "PROJECT_NOT_FOUND",
-    "message": "Invalid project folder",
-    "details": {},
-    "suggestions": [
-      "Use --dir to specify a different directory",
-      "Change to a directory containing agentuity.json",
-      "Run \\"${getCommand('project create')}\\" to create a new project"
-    ]
-  }
-}
-\`\`\`
-
-### Common Error Codes
-
-- \`VALIDATION_FAILED\`: Invalid arguments or options
-- \`AUTH_REQUIRED\`: Authentication needed
-- \`PROJECT_NOT_FOUND\`: No project configuration found
-- \`REGION_REQUIRED\`: Cloud region must be specified
-- \`RESOURCE_NOT_FOUND\`: Requested resource doesn't exist
-- \`PERMISSION_DENIED\`: Insufficient permissions
-
-### Error Recovery
-
-Always check error details and suggestions for recovery steps. Errors include actionable guidance.
-
-## Authentication Flow
-
-### Required for Most Operations
-
-Many commands require authentication. Check the schema's \`requires.auth\` field.
-
-### Authentication Commands
-
-\`\`\`bash
-# Check if authenticated
-${getCommand('auth whoami')}
-
-# Login (interactive)
-${getCommand('auth login')}
-
-# Signup (interactive)
-${getCommand('auth signup')}
-\`\`\`
-
-### Non-Interactive Environments
-
-In non-TTY environments:
-- Commands requiring interactive input will fail with clear error messages
-- Use API keys or pre-authenticate before running automated tasks
-- Some commands support \`--confirm\` to skip interactive prompts
-
-## Project Context
-
-### Project-Based Commands
-
-Commands requiring a project look for \`agentuity.json\` in the current directory.
-
-### Specifying Project Directory
-
-\`\`\`bash
-${getCommand('--dir /path/to/project command')}
-\`\`\`
-
-### Creating a Project
-
-\`\`\`bash
-${getCommand('project create')}
-\`\`\`
-
-## Common Workflows
-
-### 1. Initial Setup
-
-\`\`\`bash
-${getCommand('auth signup')}
-${getCommand('auth login')}
-${getCommand('project create')}
-${getCommand('env set API_KEY <value> --secret')}
-\`\`\`
-
-### 2. Deploy Application
-
-\`\`\`bash
-# Preview deployment
-${getCommand('--explain bundle')}
-
-# Test deployment (dry-run)
-${getCommand('--dry-run cloud deploy')}
-
-# Actual deployment
-${getCommand('bundle')}
-${getCommand('cloud deploy')}
-
-# Check deployment status
-${getCommand('--json cloud deployment show')}
-\`\`\`
-
-### 3. Manage Environment Variables & Secrets
-
-\`\`\`bash
-${getCommand('--json env list')}
-${getCommand('env set DATABASE_URL <value> --secret')}
-${getCommand('env get DATABASE_URL')}
-\`\`\`
-
-### 4. List Resources
-
-\`\`\`bash
-${getCommand('--json project list')}
-${getCommand('--json cloud deployment list')}
-${getCommand('--json kv list')}
-\`\`\`
-
-## Best Practices
-
-### 1. Always Validate First
-
-- Use \`--explain\` to understand what will happen
-- Use \`--dry-run\` for commands that mutate state
-- Check schema to understand command requirements
-
-### 2. Use Structured Output
-
-- Always use \`--json\` when parsing output programmatically
-- Parse error messages from structured error format
-- Never rely on human-readable text parsing
-
-### 3. Handle Non-Interactive Mode
-
-- Detect TTY status
-- Provide all required arguments upfront
-- Use \`--confirm\` or similar flags to skip prompts
-
-### 4. Check Requirements
-
-Before running a command, verify from schema:
-- Does it require authentication?
-- Does it require a project context?
-- Does it require organization or region selection?
-
-### 5. Progressive Enhancement
-
-Start with safe operations:
-1. Discover capabilities (\`capabilities show\`)
-2. Get schema for specific command (\`--help=json\`)
-3. Use \`--explain\` to preview
-4. Use \`--dry-run\` to test
-5. Execute actual command
-
-### 6. Error Recovery
-
-When an error occurs:
-1. Parse the error code
-2. Read the suggestions array
-3. Take corrective action
-4. Retry the operation
-
-## Agent Safety Guidelines
-
-### Destructive Operations
-
-For destructive operations (delete, remove, rollback):
-1. ALWAYS use \`--explain\` first
-2. ALWAYS use \`--dry-run\` before execution
-3. Verify the operation matches intent
-4. Only then execute the actual command
-
-### Confirmation Flags
-
-Many destructive commands support:
-- \`--confirm\`: Skip confirmation prompts (be careful!)
-- \`--no-confirm\`: Disable confirmation (dangerous!)
-
-### Non-Destructive Exploration
-
-These are always safe:
-- \`--help\`, \`--help=json\`
-- \`capabilities show\`
-- \`schema show\`
-- \`--explain\` (never executes)
-- \`--dry-run\` (no side effects)
-- List commands (\`list\`, \`ls\`)
-- Show commands (\`show\`, \`get\` without mutations)
-
-## Examples for Common Tasks
-
-### Discover All Commands
-
-\`\`\`bash
-${getCommand('--help=json')} | jq '.commands[].name'
-\`\`\`
-
-### Find Commands Requiring Auth
-
-\`\`\`bash
-${getCommand('--help=json')} | jq '.commands[] | select(.requires.auth == true) | .name'
-\`\`\`
-
-### Get Details About a Specific Command
-
-\`\`\`bash
-${getCommand('auth ssh delete --help')}
-${getCommand('--help=json')} | jq '.commands[] | select(.name == "auth")'
-\`\`\`
-
-### Test a Deployment
-
-\`\`\`bash
-${getCommand('--explain bundle')}
-${getCommand('--dry-run cloud deploy')}
-${getCommand('cloud deploy')}
-\`\`\`
-
-### Safe SSH Key Deletion
-
-\`\`\`bash
-${getCommand('--explain auth ssh delete abc123')}
-${getCommand('--dry-run auth ssh delete abc123')}
-${getCommand('auth ssh delete abc123')}
-\`\`\`
-
-## Version Information
-
-This prompt is for Agentuity CLI. Always check the version:
-
-\`\`\`bash
-${getCommand('version')}
-\`\`\`
-
-The CLI follows semantic versioning. Check schema compatibility across versions.
-
-## Getting Help
-
-- CLI Schema: \`${getCommand('--help=json')}\`
-- Capabilities: \`${getCommand('capabilities show')}\`
-- Command Help: \`${getCommand('command --help')}\`
-- Examples: Included in help text for all commands
-
-## Summary
-
-The Agentuity CLI is designed for agent-friendly usage with:
-- Complete introspection via \`--help=json\` and \`schema\` commands
-- Machine-readable output via \`--json\`
-- Safety features via \`--explain\` and \`--dry-run\`
-- Structured errors with recovery suggestions
-- Comprehensive examples for all commands
-
-Always start with discovery (\`capabilities\`, \`schema\`), use safety features (\`--explain\`, \`--dry-run\`), and rely on structured output (\`--json\`) for reliable automation.
-`;
-}
-
-export default llmSubcommand;

package/src/cmd/ai/prompt/version.ts

@@ -1,62 +0,0 @@
-/**
- * Prompt file versioning utilities.
- *
- * Hash format at end of file: <!-- prompt_hash: [hash] -->
- *
- * - hash: SHA256 of file content (excluding the hash line)
- *
- * This allows detecting if the source template has changed.
- */
-
-const HASH_REGEX = /\n?<!-- prompt_hash: ([a-f0-9]+) -->\n?$/;
-
-/**
- * Compute SHA256 hash of content using Bun's built-in hasher.
- */
-export function computeHash(content: string): string {
-	const hasher = new Bun.CryptoHasher('sha256');
-	hasher.update(content);
-	return hasher.digest().toHex();
-}
-
-/**
- * Strip the hash comment from content.
- */
-export function stripHashComment(content: string): string {
-	return content.replace(HASH_REGEX, '');
-}
-
-/**
- * Extract hash from file content.
- * Returns null if no hash comment found.
- */
-export function extractHash(content: string): string | null {
-	const match = content.match(HASH_REGEX);
-	return match?.[1] ?? null;
-}
-
-/**
- * Generate content with hash comment appended.
- * Ensures the output ends with a newline for POSIX compliance and Prettier compatibility.
- */
-export function appendHashComment(content: string): string {
-	const hash = computeHash(content);
-	return `${content}\n<!-- prompt_hash: ${hash} -->\n`;
-}
-
-/**
- * Check if a file needs to be updated based on hash comparison.
- *
- * @param fileContent - Current file content (with hash comment)
- * @param sourceContent - Source template content (without hash comment)
- * @returns true if file needs to be updated (hashes differ)
- */
-export function needsUpdate(fileContent: string, sourceContent: string): boolean {
-	const fileHash = extractHash(fileContent);
-	if (!fileHash) {
-		return true;
-	}
-
-	const sourceHash = computeHash(sourceContent);
-	return fileHash !== sourceHash;
-}

package/src/cmd/ai/prompt/web.ts

@@ -1,31 +0,0 @@
-import { createSubcommand } from '../../../types';
-import type { CommandContext } from '../../../types';
-import { getCommand } from '../../../command-prefix';
-import { appendHashComment } from './version';
-import webPromptContent from './web.md' with { type: 'text' };
-
-export const webSubcommand = createSubcommand({
-	name: 'web',
-	description: 'Generate a comprehensive prompt for LLM agents for the web folder',
-	tags: ['read-only', 'fast'],
-	idempotent: true,
-	examples: [{ command: getCommand('prompt web'), description: 'Run web command' }],
-	async handler(_ctx: CommandContext) {
-		const prompt = generateLLMPrompt();
-		console.log(prompt);
-	},
-});
-
-/**
- * Get the raw prompt content without hash.
- */
-export function getPromptContent(): string {
-	return webPromptContent;
-}
-
-/**
- * Generate the web prompt with hash comment.
- */
-export function generateLLMPrompt(): string {
-	return appendHashComment(webPromptContent);
-}

package/src/cmd/ai/schema/generate.ts

@@ -1,64 +0,0 @@
-import { z } from 'zod';
-import { createSubcommand, type CommandContext } from '../../../types';
-import { getCommand } from '../../../command-prefix';
-import { ProjectSchema } from '../../../types';
-
-interface MergedSchema {
-	type?: string;
-	properties?: Record<string, unknown>;
-	required?: string[];
-	additionalProperties?: boolean | Record<string, unknown>;
-	[key: string]: unknown;
-}
-
-export const generateSubcommand = createSubcommand({
-	name: 'generate',
-	description: 'Generate a JSON schema for the agentuity.json config file',
-	tags: ['read-only', 'fast'],
-	idempotent: true,
-	examples: [{ command: getCommand('schema generate'), description: 'Run generate command' }],
-	async handler(_ctx: CommandContext) {
-		const o = z.toJSONSchema(ProjectSchema);
-		const { $schema, allOf, ...rest } = o;
-
-		// Merge allOf schemas into a single schema
-		let mergedSchema: MergedSchema = { ...rest };
-		if (allOf && Array.isArray(allOf)) {
-			const properties: Record<string, unknown> = {};
-			const required: string[] = [];
-
-			for (const subSchema of allOf) {
-				if (subSchema.properties) {
-					Object.assign(properties, subSchema.properties);
-				}
-				if (subSchema.required && Array.isArray(subSchema.required)) {
-					required.push(...subSchema.required);
-				}
-			}
-
-			mergedSchema = {
-				type: 'object',
-				properties,
-				required: [...new Set(required)],
-				additionalProperties: false,
-			};
-		}
-
-		if (!mergedSchema.properties) {
-			mergedSchema.properties = {};
-		}
-		mergedSchema.properties['$schema'] = {
-			type: 'string',
-		};
-
-		const schema = {
-			$schema,
-			$id: 'https://agentuity.dev/schema/cli/v1/agentuity.json',
-			$comment: 'The agentuity.json configuration schema',
-			...mergedSchema,
-		};
-		console.log(JSON.stringify(schema, null, 2));
-	},
-});
-
-export default generateSubcommand;

package/src/cmd/ai/schema/index.ts

@@ -1,15 +0,0 @@
-import type { CommandDefinition } from '../../../types';
-import { createCommand } from '../../../types';
-import { showSubcommand } from './show';
-import { generateSubcommand } from './generate';
-import { getCommand } from '../../../command-prefix';
-
-export const schemaCommand: CommandDefinition = createCommand({
-	name: 'schema',
-	description: 'Output CLI schema in machine-readable format',
-	tags: ['read-only', 'fast'],
-	examples: [{ command: getCommand('ai schema show'), description: 'Show CLI schema as JSON' }],
-	subcommands: [showSubcommand, generateSubcommand],
-});
-
-export default schemaCommand;

package/src/cmd/ai/schema/show.ts

@@ -1,30 +0,0 @@
-import { createSubcommand, type CommandContext } from '../../../types';
-import { ErrorCode } from '../../../errors';
-import { getCommand } from '../../../command-prefix';
-
-export const showSubcommand = createSubcommand({
-	name: 'show',
-	description: 'Display the complete CLI schema',
-	tags: ['read-only', 'fast'],
-	idempotent: true,
-	examples: [
-		{ command: getCommand('schema show'), description: 'Show details' },
-		{ command: getCommand('--json schema show'), description: 'Show output in JSON format' },
-	],
-	async handler(ctx: CommandContext) {
-		const { logger } = ctx;
-
-		// Access the schema stored in the global context
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		const schema = (global as any).__CLI_SCHEMA__;
-
-		if (!schema) {
-			logger.fatal('Schema not available. This is a CLI bug.', ErrorCode.INTERNAL_ERROR);
-		}
-
-		// Always output JSON (this command is primarily for machine consumption)
-		console.log(JSON.stringify(schema, null, 2));
-	},
-});
-
-export default showSubcommand;

package/src/cmd/auth/README.md

@@ -1,129 +0,0 @@
-# Authentication Commands
-
-The auth command provides authentication and authorization functionality for the Agentuity Platform.
-
-## Commands
-
-### `auth login`
-
-Login to the Agentuity Platform using a browser-based authentication flow.
-
-```bash
-agentuity auth login
-# or
-agentuity login
-```
-
-**How it works:**
-
-1. Generates a one-time password (OTP) by calling `/cli/auth/start`
-2. Displays the OTP and authentication URL to the user
-3. Automatically opens the browser to the auth URL (on supported platforms)
-4. Polls `/cli/auth/check` every 2 seconds for up to 60 seconds
-5. Once authenticated, 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
-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.
-
-```bash
-agentuity auth logout
-# or
-agentuity logout
-```
-
-**What it does:**
-
-- Clears `auth.api_key`, `auth.user_id`, and sets `auth.expires` to current time
-- Clears `preferences.orgId`
-- Writes changes to the active profile config file
-
-## API Endpoints
-
-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
-
-The API and App URLs are determined in the following priority order:
-
-1. **Environment Variables** (highest priority)
-   - `AGENTUITY_API_URL` - Override the API base URL
-   - `AGENTUITY_APP_URL` - Override the app base URL
-
-2. **Config File Overrides**
-
-   ```yaml
-   overrides:
-      api_url: https://api.agentuity.io
-      app_url: https://app.agentuity.io
-   ```
-
-3. **Default Values** (lowest priority)
-   - API URL: `https://api.agentuity.com`
-   - App URL: `https://app.agentuity.com`
-
-This allows different profiles (e.g., `local`, `production`) to point to different environments.
-
-## Implementation Details
-
-- **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**:
-   - 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
-
-## Architecture
-
-Each command has its own `api.ts` file for command-specific API methods and types. The generic `APIClient` class and URL helpers are in the root `api.ts` file, promoting reusability while keeping command-specific logic isolated.