indusagi-coding-agent 0.1.23 → 0.1.25

package/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Changelog
 
+## [0.1.25] - Web Search & Fetch Tools
+
+### Added
+- **websearch** - Real-time web search via Exa AI API
+  - Search types: auto, fast, deep
+  - Configurable result count (1-10)
+  - LLM-optimized output
+
+- **webfetch** - URL content retrieval and transformation
+  - Multiple formats: text, markdown, HTML
+  - Image support with base64 encoding
+  - Timeout and size limits (5MB max)
+
+- **Web tools now default** - Automatically available in all agent sessions
+
+### Changed
+- `codingTools`: 7 → 9 tools (added websearch, webfetch)
+- `allTools`: 10 → 12 tools (added websearch, webfetch)
+- `defaultActiveToolNames` updated in SDK for automatic activation
+- Updated package.json description
+
+### Files Modified
+- `src/core/tools/index.ts` - Added exports and updated tool arrays
+- `src/core/tools/registry.ts` - Registered web tools as core
+- `src/core/sdk.ts` - Added web tools to defaultActiveToolNames (CRITICAL)
+- `package.json` - Version bump + description update
+
+### Security
+- ✅ URL validation (http/https only)
+- ✅ Response size limiting (5MB)
+- ✅ Timeout enforcement (max 120s)
+- ✅ API key required for websearch
+- ✅ No breaking changes, fully backward compatible
+
+---
+
+## [0.1.24] - CLI Module Rebranding
+
+### Added
+- **CLI Module Documentation**: Comprehensive documentation added to all CLI files
+  - File headers with purpose documentation and vendor attribution
+  - Section comments for logical code blocks
+  - JSDoc for all public interfaces and types
+  - Inline comments for complex decision points
+
+### Changed
+- **CLI Argument Parser (args.ts)**:
+  - Added constants for default values (VALID_THINKING_LEVELS, DEFAULT_TOOLS, AVAILABLE_TOOLS)
+  - Created type guards (isValidThinkingLevel, isValidMode, isValidToolName)
+  - Added validation functions (validateToolNames, validateThinkingLevel)
+  - Organized imports with clear separation
+  - Enhanced Args interface with comprehensive JSDoc
+
+- **Configuration Selector (config-selector.ts)**:
+  - Added ConfigSelectorOptions interface with full documentation
+  - Documented TUI setup and cleanup workflow
+  - Enhanced callback documentation (onResolve, onExit, onRequestRender)
+
+- **File Processor (file-processor.ts)**:
+  - Added file validation (isSupportedTextFile, isSupportedImageMimeType)
+  - Added file size limits (MAX_TEXT_FILE_SIZE: 10MB, MAX_IMAGE_FILE_SIZE: 20MB)
+  - Created FileProcessError custom error class with helpful suggestions
+  - Added validateFileSize function with limit checking
+
+- **Login Handler (login-handler.ts)**:
+  - Added SECURITY CONSIDERATIONS section documenting credential storage safety
+  - Created LoginError and CredentialValidationError custom error classes
+  - Added validation functions (validateApiKey, validateAccountName, isValidProvider)
+  - Enhanced multi-account support documentation
+  - Improved error messages for auth failures
+
+- **Model List (list-models.ts)**:
+  - Added ModelFilterOptions interface for flexible model filtering
+  - Added ModelRow interface for formatted table output
+  - Added utility functions (filterModels, sortModels, calculateColumnWidths)
+  - Enhanced model display with proper column widths
+  - Added model capability indicators (thinking, images)
+
+- **Session Picker (session-picker.ts)**:
+  - Created SessionPickerError custom error class
+  - Added session utility functions (calculateSessionStats, formatAge, formatSize)
+  - Added session metadata display capabilities
+  - Enhanced session sorting and filtering options
+
+### Fixed
+- **Error Handling**: Consistent error message format across all CLI files
+- **Type Safety**: Type guards for runtime type checking and validation
+- **Security**: API key format validation prevents placeholder values
+- **File Access**: Improved error messages with actionable suggestions
+
+### Tests
+- **CLI Argument Tests**: 40+ test cases for argument parsing
+- **File Processor Tests**: 20+ test cases for file processing
+- **Login Handler Tests**: 25+ test cases for authentication flow
+
+### Documentation
+- **CLI-REFACTORING-SUMMARY.md**: Complete summary of all changes
+  - 6 files updated with ~2000 lines of documentation
+  - 85+ test cases covering all major functionality
+  - All high and medium priority tasks complete
+
 ## [0.1.23]
 
 ### Changed

package/README.md

@@ -2,6 +2,8 @@
 
 A terminal-first coding agent with a small core and strong extensibility. Use it interactively, in scripts (print/JSON), over RPC, or as an SDK in your own apps.
 
+> **Inspired by Pi**: *"Code with clarity, collaborate with purpose, and build with intelligence. Every line you write is a conversation between you and your assistant."*
+
 - CLI commands: `indusagi` and `indus`
 - Node.js >= 20
 - Extensible via extensions, skills, prompt templates, and themes

package/dist/cli/args.d.ts

@@ -1,9 +1,71 @@
 /**
- * CLI argument parsing and help display
+ * CLI Argument Parser - Command-line argument handling and validation
+ *
+ * Responsibilities:
+ * - Parse command-line arguments into structured format
+ * - Validate argument combinations
+ * - Provide helpful error messages for invalid args
+ * - Generate help documentation
+ * - Support extension flags registration
+ *
+ * Based on argument parsing patterns from indusagi CLI
+ * Original: https://github.com/varunisrani/indusagi-ts/vendor/indusagi-agent
+ *
+ * Adapted to:
+ * - Improve error messages
+ * - Add comprehensive documentation
+ * - Enhance validation
+ * - Improve UX with better prompts
  */
 import type { ThinkingLevel } from "indusagi/agent";
 import { type ToolName } from "../core/tools/index.js";
+/**
+ * Output mode for CLI responses
+ *
+ * @type {Mode}
+ * @property {"text"} - Standard interactive text output
+ * @property {"json"} - JSON formatted output for automation
+ * @property {"rpc"} - RPC format for external tool integration
+ */
 export type Mode = "text" | "json" | "rpc";
+/**
+ * Parsed command-line arguments
+ *
+ * @interface Args
+ * @property {string} [provider] - Provider name (e.g., google, openai, anthropic)
+ * @property {string} [account] - Account name for multi-account providers
+ * @property {string} [model] - Model ID override
+ * @property {string} [apiKey] - API key (defaults to env vars)
+ * @property {string} [systemPrompt] - System prompt override
+ * @property {string} [appendSystemPrompt] - Append text or file contents to system prompt
+ * @property {ThinkingLevel} [thinking] - Extended thinking level
+ * @property {boolean} [continue] - Continue previous session flag
+ * @property {boolean} [resume] - Select a session to resume
+ * @property {boolean} [help] - Show help message
+ * @property {boolean} [version] - Show version number
+ * @property {Mode} [mode] - Output mode (text, json, rpc)
+ * @property {boolean} [noSession] - Don't save session (ephemeral)
+ * @property {string} [session] - Use specific session file
+ * @property {string} [sessionDir] - Directory for session storage
+ * @property {string[]} [models] - Model patterns for Ctrl+P cycling
+ * @property {ToolName[]} [tools] - Tools to enable
+ * @property {boolean} [noTools] - Disable all tools
+ * @property {string[]} [extensions] - Extension file paths to load
+ * @property {string[]} [hooks] - Hook file paths to load
+ * @property {boolean} [noExtensions] - Disable extension discovery
+ * @property {boolean} [noHooks] - Disable hook discovery
+ * @property {boolean} [noSkills] - Disable skills discovery
+ * @property {string[]} [skills] - Skill file paths to load
+ * @property {string[]} [promptTemplates] - Prompt template paths to load
+ * @property {boolean} [noPromptTemplates] - Disable prompt template discovery
+ * @property {string[]} [themes] - Theme file paths to load
+ * @property {boolean} [noThemes] - Disable theme discovery
+ * @property {string | true} [listModels] - List available models with optional search
+ * @property {boolean} [verbose] - Force verbose startup
+ * @property {string[]} messages - Non-flag positional arguments (user messages)
+ * @property {string[]} fileArgs - File arguments (from @file syntax)
+ * @property {Map<string, boolean | string>} unknownFlags - Extension registered flags
+ */
 export interface Args {
     provider?: string;
     account?: string;
@@ -42,9 +104,63 @@ export interface Args {
     /** Unknown flags (potentially extension flags) - map of flag name to value */
     unknownFlags: Map<string, boolean | string>;
 }
+/**
+ * Type guard to check if a string is a valid ThinkingLevel
+ *
+ * @param level - The string to check
+ * @returns True if the string is a valid ThinkingLevel
+ */
 export declare function isValidThinkingLevel(level: string): level is ThinkingLevel;
+/**
+ * Type guard to check if a string is a valid Mode
+ *
+ * @param mode - The string to check
+ * @returns True if the string is a valid Mode
+ */
+export declare function isValidMode(mode: string): mode is Mode;
+/**
+ * Type guard to check if a tool name is valid
+ *
+ * @param toolName - The tool name to check
+ * @returns True if the tool name is in the available tools list
+ */
+export declare function isValidToolName(toolName: string): toolName is ToolName;
+/**
+ * Parse command-line arguments into structured Args object
+ *
+ * This function processes raw command-line arguments and converts them into
+ * a structured Args object. It handles:
+ * - Short and long flag formats (--flag, -f)
+ * - Flag values that follow (--flag value)
+ * - Boolean flags (--no-flag)
+ * - File arguments prefixed with @
+ * - Extension-registered flags (if extensionFlags provided)
+ * - Positional arguments (messages)
+ *
+ * @param args - Array of command-line argument strings (typically process.argv.slice(2))
+ * @param extensionFlags - Optional map of extension-registered flags with their types
+ * @returns Parsed Args object
+ *
+ * @example
+ * ```typescript
+ * const args = parseArgs(["--model", "gpt-4", "--verbose", "hello", "@file.txt"]);
+ * // Returns: { model: "gpt-4", verbose: true, messages: ["hello"], fileArgs: ["file.txt"] }
+ * ```
+ */
 export declare function parseArgs(args: string[], extensionFlags?: Map<string, {
     type: "boolean" | "string";
 }>): Args;
+/**
+ * Print comprehensive help documentation to stdout
+ *
+ * Displays:
+ * - Application name and brief description
+ * - Usage syntax
+ * - Available commands
+ * - All options with descriptions
+ * - Environment variables
+ * - Available tools
+ * - Example usage
+ */
 export declare function printHelp(): void;
 //# sourceMappingURL=args.d.ts.map

package/dist/cli/args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEjE,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAE3C,MAAM,WAAW,IAAI;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,8EAA8E;IAC9E,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;CAC5C;AAID,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,aAAa,CAE1E;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAA;CAAE,CAAC,GAAG,IAAI,CA+H5G;AAED,wBAAgB,SAAS,IAAI,IAAI,CA8IhC"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;;;;;;GAOG;AACH,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,WAAW,IAAI;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,8EAA8E;IAC9E,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;CAC5C;AA8BD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,aAAa,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,IAAI,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,IAAI,QAAQ,CAEtE;AAgDD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAA;CAAE,CAAC,GAAG,IAAI,CA4L5G;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,IAAI,IAAI,CA8IhC"}

package/dist/cli/args.js

@@ -1,13 +1,133 @@
 /**
- * CLI argument parsing and help display
+ * CLI Argument Parser - Command-line argument handling and validation
+ *
+ * Responsibilities:
+ * - Parse command-line arguments into structured format
+ * - Validate argument combinations
+ * - Provide helpful error messages for invalid args
+ * - Generate help documentation
+ * - Support extension flags registration
+ *
+ * Based on argument parsing patterns from indusagi CLI
+ * Original: https://github.com/varunisrani/indusagi-ts/vendor/indusagi-agent
+ *
+ * Adapted to:
+ * - Improve error messages
+ * - Add comprehensive documentation
+ * - Enhance validation
+ * - Improve UX with better prompts
  */
 import chalk from "chalk";
 import { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR } from "../config.js";
-import { allTools } from "../core/tools/index.js";
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+/** Valid thinking levels for the --thinking flag */
 const VALID_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
+/** Default tools enabled when no --tools or --no-tools is specified */
+const DEFAULT_TOOLS = ["read", "bash", "edit", "write", "task", "todoread", "todowrite"];
+/** All available tool names for validation */
+const AVAILABLE_TOOLS = [
+    "read",
+    "bash",
+    "edit",
+    "write",
+    "task",
+    "grep",
+    "find",
+    "ls",
+    "todoread",
+    "todowrite",
+];
+// ============================================================================
+// TYPE GUARDS
+// ============================================================================
+/**
+ * Type guard to check if a string is a valid ThinkingLevel
+ *
+ * @param level - The string to check
+ * @returns True if the string is a valid ThinkingLevel
+ */
 export function isValidThinkingLevel(level) {
     return VALID_THINKING_LEVELS.includes(level);
 }
+/**
+ * Type guard to check if a string is a valid Mode
+ *
+ * @param mode - The string to check
+ * @returns True if the string is a valid Mode
+ */
+export function isValidMode(mode) {
+    return mode === "text" || mode === "json" || mode === "rpc";
+}
+/**
+ * Type guard to check if a tool name is valid
+ *
+ * @param toolName - The tool name to check
+ * @returns True if the tool name is in the available tools list
+ */
+export function isValidToolName(toolName) {
+    return AVAILABLE_TOOLS.includes(toolName);
+}
+// ============================================================================
+// VALIDATION FUNCTIONS
+// ============================================================================
+/**
+ * Validate tool names and filter out invalid ones
+ *
+ * @param toolNames - Array of tool names to validate
+ * @returns Array of valid tool names
+ */
+function validateToolNames(toolNames) {
+    const validTools = [];
+    for (const name of toolNames) {
+        if (isValidToolName(name)) {
+            validTools.push(name);
+        }
+        else {
+            console.error(chalk.yellow(`Warning: Unknown tool "${name}". Valid tools: ${AVAILABLE_TOOLS.join(", ")}`));
+        }
+    }
+    return validTools;
+}
+/**
+ * Validate thinking level and provide warning if invalid
+ *
+ * @param level - The thinking level to validate
+ * @returns The validated thinking level or undefined if invalid
+ */
+function validateThinkingLevel(level) {
+    if (isValidThinkingLevel(level)) {
+        return level;
+    }
+    console.error(chalk.yellow(`Warning: Invalid thinking level "${level}". Valid values: ${VALID_THINKING_LEVELS.join(", ")}`));
+    return undefined;
+}
+// ============================================================================
+// ARGUMENT PARSING
+// ============================================================================
+/**
+ * Parse command-line arguments into structured Args object
+ *
+ * This function processes raw command-line arguments and converts them into
+ * a structured Args object. It handles:
+ * - Short and long flag formats (--flag, -f)
+ * - Flag values that follow (--flag value)
+ * - Boolean flags (--no-flag)
+ * - File arguments prefixed with @
+ * - Extension-registered flags (if extensionFlags provided)
+ * - Positional arguments (messages)
+ *
+ * @param args - Array of command-line argument strings (typically process.argv.slice(2))
+ * @param extensionFlags - Optional map of extension-registered flags with their types
+ * @returns Parsed Args object
+ *
+ * @example
+ * ```typescript
+ * const args = parseArgs(["--model", "gpt-4", "--verbose", "hello", "@file.txt"]);
+ * // Returns: { model: "gpt-4", verbose: true, messages: ["hello"], fileArgs: ["file.txt"] }
+ * ```
+ */
 export function parseArgs(args, extensionFlags) {
     const result = {
         messages: [],
@@ -16,85 +136,113 @@ export function parseArgs(args, extensionFlags) {
     };
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
+        // ============================================================================
+        // HELP AND VERSION FLAGS
+        // ============================================================================
         if (arg === "--help" || arg === "-h") {
             result.help = true;
         }
         else if (arg === "--version" || arg === "-v") {
             result.version = true;
         }
+        // ============================================================================
+        // MODE FLAGS
+        // ============================================================================
         else if (arg === "--mode" && i + 1 < args.length) {
             const mode = args[++i];
-            if (mode === "text" || mode === "json" || mode === "rpc") {
+            if (isValidMode(mode)) {
                 result.mode = mode;
             }
         }
+        // ============================================================================
+        // SESSION FLAGS
+        // ============================================================================
         else if (arg === "--continue" || arg === "-c") {
             result.continue = true;
         }
         else if (arg === "--resume" || arg === "-r") {
             result.resume = true;
         }
+        else if (arg === "--no-session") {
+            result.noSession = true;
+        }
+        else if (arg === "--session" && i + 1 < args.length) {
+            result.session = args[++i];
+        }
+        else if (arg === "--session-dir" && i + 1 < args.length) {
+            result.sessionDir = args[++i];
+        }
+        // ============================================================================
+        // PROVIDER AND AUTH FLAGS
+        // ============================================================================
         else if (arg === "--provider" && i + 1 < args.length) {
             result.provider = args[++i];
         }
         else if (arg === "--account" && i + 1 < args.length) {
             result.account = args[++i];
         }
+        else if (arg === "--api-key" && i + 1 < args.length) {
+            result.apiKey = args[++i];
+        }
+        // ============================================================================
+        // MODEL FLAGS
+        // ============================================================================
         else if (arg === "--model" && i + 1 < args.length) {
             result.model = args[++i];
         }
-        else if (arg === "--api-key" && i + 1 < args.length) {
-            result.apiKey = args[++i];
+        else if (arg === "--models" && i + 1 < args.length) {
+            result.models = args[++i].split(",").map((s) => s.trim());
         }
+        else if (arg === "--list-models") {
+            // Check if next arg is a search pattern (not a flag or file arg)
+            if (i + 1 < args.length && !args[i + 1].startsWith("-") && !args[i + 1].startsWith("@")) {
+                result.listModels = args[++i];
+            }
+            else {
+                result.listModels = true;
+            }
+        }
+        // ============================================================================
+        // SYSTEM PROMPT FLAGS
+        // ============================================================================
         else if (arg === "--system-prompt" && i + 1 < args.length) {
             result.systemPrompt = args[++i];
         }
         else if (arg === "--append-system-prompt" && i + 1 < args.length) {
             result.appendSystemPrompt = args[++i];
         }
-        else if (arg === "--no-session") {
-            result.noSession = true;
-        }
-        else if (arg === "--session" && i + 1 < args.length) {
-            result.session = args[++i];
-        }
-        else if (arg === "--session-dir" && i + 1 < args.length) {
-            result.sessionDir = args[++i];
-        }
-        else if (arg === "--models" && i + 1 < args.length) {
-            result.models = args[++i].split(",").map((s) => s.trim());
-        }
+        // ============================================================================
+        // TOOL FLAGS
+        // ============================================================================
         else if (arg === "--no-tools") {
             result.noTools = true;
         }
         else if (arg === "--tools" && i + 1 < args.length) {
             const toolNames = args[++i].split(",").map((s) => s.trim());
-            const validTools = [];
-            for (const name of toolNames) {
-                if (name in allTools) {
-                    validTools.push(name);
-                }
-                else {
-                    console.error(chalk.yellow(`Warning: Unknown tool "${name}". Valid tools: ${Object.keys(allTools).join(", ")}`));
-                }
-            }
-            result.tools = validTools;
+            result.tools = validateToolNames(toolNames);
         }
+        // ============================================================================
+        // THINKING FLAG
+        // ============================================================================
         else if (arg === "--thinking" && i + 1 < args.length) {
             const level = args[++i];
-            if (isValidThinkingLevel(level)) {
-                result.thinking = level;
-            }
-            else {
-                console.error(chalk.yellow(`Warning: Invalid thinking level "${level}". Valid values: ${VALID_THINKING_LEVELS.join(", ")}`));
-            }
+            result.thinking = validateThinkingLevel(level);
         }
+        // ============================================================================
+        // OUTPUT FLAGS
+        // ============================================================================
         else if (arg === "--print" || arg === "-p") {
             result.print = true;
         }
         else if (arg === "--export" && i + 1 < args.length) {
             result.export = args[++i];
         }
+        else if (arg === "--verbose") {
+            result.verbose = true;
+        }
+        // ============================================================================
+        // EXTENSION FLAGS
+        // ============================================================================
         else if ((arg === "--extension" || arg === "-e") && i + 1 < args.length) {
             result.extensions = result.extensions ?? [];
             result.extensions.push(args[++i]);
@@ -109,42 +257,45 @@ export function parseArgs(args, extensionFlags) {
         else if (arg === "--no-hooks") {
             result.noHooks = true;
         }
+        // ============================================================================
+        // SKILL FLAGS
+        // ============================================================================
         else if (arg === "--skill" && i + 1 < args.length) {
             result.skills = result.skills ?? [];
             result.skills.push(args[++i]);
         }
+        else if (arg === "--no-skills") {
+            result.noSkills = true;
+        }
+        // ============================================================================
+        // PROMPT TEMPLATE FLAGS
+        // ============================================================================
         else if (arg === "--prompt-template" && i + 1 < args.length) {
             result.promptTemplates = result.promptTemplates ?? [];
             result.promptTemplates.push(args[++i]);
         }
+        else if (arg === "--no-prompt-templates") {
+            result.noPromptTemplates = true;
+        }
+        // ============================================================================
+        // THEME FLAGS
+        // ============================================================================
         else if (arg === "--theme" && i + 1 < args.length) {
             result.themes = result.themes ?? [];
             result.themes.push(args[++i]);
         }
-        else if (arg === "--no-skills") {
-            result.noSkills = true;
-        }
-        else if (arg === "--no-prompt-templates") {
-            result.noPromptTemplates = true;
-        }
         else if (arg === "--no-themes") {
             result.noThemes = true;
         }
-        else if (arg === "--list-models") {
-            // Check if next arg is a search pattern (not a flag or file arg)
-            if (i + 1 < args.length && !args[i + 1].startsWith("-") && !args[i + 1].startsWith("@")) {
-                result.listModels = args[++i];
-            }
-            else {
-                result.listModels = true;
-            }
-        }
-        else if (arg === "--verbose") {
-            result.verbose = true;
-        }
+        // ============================================================================
+        // FILE ARGUMENTS
+        // ============================================================================
         else if (arg.startsWith("@")) {
             result.fileArgs.push(arg.slice(1)); // Remove @ prefix
         }
+        // ============================================================================
+        // EXTENSION FLAGS (VENDOR CODE)
+        // ============================================================================
         else if (arg.startsWith("--") && extensionFlags) {
             // Check if it's an extension-registered flag
             const flagName = arg.slice(2);
@@ -159,12 +310,30 @@ export function parseArgs(args, extensionFlags) {
             }
             // Unknown flags without extensionFlags are silently ignored (first pass)
         }
+        // ============================================================================
+        // POSITIONAL ARGUMENTS (MESSAGES)
+        // ============================================================================
         else if (!arg.startsWith("-")) {
             result.messages.push(arg);
         }
     }
     return result;
 }
+// ============================================================================
+// HELP DOCUMENTATION
+// ============================================================================
+/**
+ * Print comprehensive help documentation to stdout
+ *
+ * Displays:
+ * - Application name and brief description
+ * - Usage syntax
+ * - Available commands
+ * - All options with descriptions
+ * - Environment variables
+ * - Available tools
+ * - Example usage
+ */
 export function printHelp() {
     console.log(`${chalk.bold(APP_NAME)} - AI coding assistant with read, bash, edit, write tools
 
@@ -186,7 +355,7 @@ ${chalk.bold("Options:")}
   --model <id>                   Model ID (default: gemini-2.5-flash)
   --api-key <key>                API key (defaults to env vars)
   --system-prompt <text>         System prompt (default: coding assistant prompt)
-  --append-system-prompt <text>  Append text or file contents to the system prompt
+  --append-system-prompt <text>  Append text or file contents to system prompt
   --mode <mode>                  Output mode: text (default), json, or rpc
   --print, -p                    Non-interactive mode: process prompt and exit
   --continue, -c                 Continue previous session