@defai.digital/automatosx 5.2.2 → 5.3.1

package/CHANGELOG.md

@@ -5,6 +5,202 @@ All notable changes to AutomatosX will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.3.1] - 2025-10-14
+
+### 🪟 Windows CLI Provider Detection & Enhanced Robustness
+
+**This patch release fixes critical Windows compatibility issues and adds robust provider detection with security enhancements.**
+
+#### Added
+
+- **Windows CLI Provider Detection** (Phase 1):
+  - Cross-platform CLI provider detector (`src/core/cli-provider-detector.ts`)
+  - Windows-specific detection using `where.exe` + PATH×PATHEXT fallback
+  - Unix detection using `which` command
+  - Detection caching for performance (< 1ms cached lookups)
+  - Support for `.CMD`, `.BAT`, `.EXE`, `.COM` extensions on Windows
+
+- **ENV Variable Override** (Phase 2):
+  - `CLAUDE_CLI` - Override Claude CLI path
+  - `GEMINI_CLI` - Override Gemini CLI path
+  - `CODEX_CLI` - Override Codex CLI path
+  - Three-layer detection: ENV → Config → PATH
+  - `ax status` shows ENV variable status with validation
+
+- **Provider Configuration** (Phase 2):
+  - `customPath` - Custom CLI path in provider config
+  - `versionArg` - Custom version check argument
+  - `minVersion` - Minimum required version (semantic versioning)
+
+- **Version Validation**:
+  - Semantic version parsing and comparison
+  - Automatic CLI version detection via `--version`
+  - Warning logs when version requirement not met
+  - Permissive behavior (allows if version check fails)
+
+- **Cross-Platform CI** (Phase 3):
+  - GitHub Actions workflows for Ubuntu, macOS, Windows
+  - Automatic testing on all platforms
+  - Coverage report artifacts
+  - 30-minute timeout for Windows tests
+
+#### Fixed
+
+- **Critical**: Windows CLI provider detection failures (GitHub Issue #1)
+  - Providers now detected correctly on Windows using `where.exe`
+  - Fallback to PATH×PATHEXT scanning if `where.exe` fails
+  - Standard PATH detection works on all platforms
+
+- **Provider Detection**:
+  - Enhanced `BaseProvider.checkCLIAvailabilityEnhanced()` with version validation
+  - Proper fallback chain: ENV → customPath → PATH
+  - Graceful degradation on detection failures
+
+- **CI Configuration**:
+  - Artifact upload paths corrected (coverage/ only)
+  - Removed non-existent test-results/ path
+  - Added `if-no-files-found: warn` for graceful handling
+
+- **Documentation**:
+  - Async error handling documentation for `detectAll()`
+  - Clear usage examples with proper error handling
+  - JSDoc annotations updated with `@throws` tags
+
+#### Security
+
+- **Path Traversal Protection**:
+  - Added validation to reject `..` (parent directory) patterns
+  - Added validation to reject `~` (home directory) shortcuts
+  - Security warnings logged for suspicious paths
+  - Read-only validation (no writes, minimal risk)
+
+#### Changed
+
+- **Provider Detection Priority**:
+  1. ENV variables (highest priority)
+  2. Config `customPath` (second priority)
+  3. Standard PATH detection (fallback)
+  4. Version validation (if `minVersion` set)
+
+#### Performance
+
+- **Detection Caching**: First call ~100-500ms, cached calls < 1ms
+- **Version Check Overhead**: +100-200ms when `minVersion` configured
+- **Path Validation**: +0.1-0.5ms per path (negligible)
+- **Overall Impact**: < 1% overhead
+
+#### Documentation
+
+- Added comprehensive JSDoc for all new APIs
+- Added usage examples for ENV variables
+- Added Windows-specific troubleshooting
+- Added version validation configuration guide
+- **README.md**: Enhanced with tested platforms (macOS 15, Ubuntu 24.04, Windows 10/11)
+- **README.md**: Simplified Windows Support section with clearer quick-start instructions
+- **Windows Setup Guide** (NEW): Complete installation walkthrough for Windows users
+- **Windows Troubleshooting**: Updated to v5.3.1 with provider detection solutions
+
+#### Testing
+
+- **1,670 tests passing** (100% pass rate)
+- **0 TypeScript errors** (strict mode)
+- **Cross-platform CI**: Ubuntu, macOS, Windows
+- **2 Windows-specific tests** (PATH×PATHEXT detection)
+
+#### Related
+
+- Fixes: GitHub Issue #1 (Windows CLI provider detection)
+- PRD: `tmp/PRD-WINDOWS-CLI-DETECTION.md`
+- Reports: `tmp/PHASE{1,2,3}-COMPLETION-REPORT.md`
+- Code Review: `tmp/CODE-REVIEW-REPORT.md`
+- Bug Fixes: `tmp/BUG-FIX-COMPLETION-REPORT.md`
+
+---
+
+## [5.3.0] - 2025-10-14
+
+### 🚀 Stage Execution & Checkpoint System
+
+**This release introduces a checkpoint-based stage execution system for fault-tolerant, long-running workflows with interactive, streaming, and hybrid execution modes.**
+
+#### Added
+
+- **Stage Execution System**:
+  - `StageExecutionController` - Orchestrates multi-stage execution with checkpoint support
+  - `CheckpointManager` - JSON-based checkpoint persistence with automatic cleanup
+  - `ProgressChannel` - Event-based real-time progress tracking
+  - `PromptManager` - User interaction prompts with timeout handling
+  - **Commands**:
+    - `ax resume <run-id>` - Resume execution from saved checkpoint
+    - `ax runs list` - List all checkpoint runs with filtering
+    - `ax runs show <run-id>` - Show detailed checkpoint information
+    - `ax runs delete <run-id>` - Delete checkpoint with confirmation
+
+- **Execution Modes**:
+  - `--interactive` - Pause between stages for user decisions
+  - `--streaming` - Real-time progress updates during execution
+  - `--hybrid` - Both interactive and streaming (shortcut for `--interactive --streaming`)
+  - `--resumable` - Enable checkpoint save for resume capability
+  - `--auto-continue` - Auto-confirm all checkpoints (CI-friendly mode)
+
+- **Configuration** (`automatosx.config.json`):
+  - `execution.stages.enabled` - Enable stage-based execution (opt-in)
+  - `execution.stages.autoSaveCheckpoint` - Auto-save checkpoints after each stage
+  - `execution.stages.checkpointPath` - Checkpoint storage directory
+  - `execution.stages.cleanupAfterDays` - Automatic checkpoint cleanup
+  - `execution.stages.prompts.autoConfirm` - Default auto-confirm behavior
+  - `execution.stages.progress.updateInterval` - Progress update frequency
+  - `execution.stages.progress.syntheticProgress` - Enable synthetic progress
+
+#### Fixed
+
+- **Critical**: Removed `argv.interactive || true` forcing all executions into interactive mode (src/cli/commands/run.ts:458)
+  - Now respects CLI flags: `--interactive`, `--streaming`, `--hybrid`, `--resumable` work correctly
+  - Fixes regression where flagship v5.3.0 features were broken
+
+- **Major**:
+  - Resume command now passes `memoryManager` to `StageExecutionController` for memory persistence (src/cli/commands/resume.ts:243-244)
+  - Config-driven automation settings now properly honored instead of being overridden by CLI defaults
+    - `autoSaveCheckpoint` uses config value when CLI flag not specified
+    - `autoConfirm` uses config value when CLI flag not specified
+  - Resume flow now preserves original `autoConfirm` choice from checkpoint instead of defaulting to `false`
+  - CLI options (`--interactive`, `--resumable`, `--auto-continue`, `--streaming`, `--hybrid`) no longer have hardcoded `default: false`, allowing proper config fallback
+
+- **Minor**:
+  - Removed duplicate spinner in streaming mode - `ProgressRenderer` now handles all visual feedback (src/core/stage-execution-controller.ts:1286)
+
+#### Technical Details
+
+- **New Core Modules**:
+  - `src/core/stage-execution-controller.ts` - Stage lifecycle, checkpoint integration, progress tracking
+  - `src/core/checkpoint-manager.ts` - Checkpoint CRUD, JSON persistence, automatic cleanup
+  - `src/core/progress-channel.ts` - Event-based progress updates with percentage tracking
+  - `src/core/prompt-manager.ts` - CLI user prompts with timeout and validation
+  - `src/cli/commands/resume.ts` - Resume from checkpoint with mode override support
+  - `src/cli/commands/runs.ts` - Checkpoint management (list, show, delete)
+  - `src/cli/renderers/progress-renderer.ts` - Real-time progress visualization
+  - `src/types/stage-execution.ts` - Complete type definitions for stage system
+
+- **Checkpoint Structure**:
+  ```
+  .automatosx/checkpoints/
+  └── <run-id>/
+      ├── checkpoint.json    # Checkpoint metadata and stage states
+      └── artifacts/         # Stage outputs and files
+  ```
+
+- **Benefits**:
+  - ✅ Fault tolerance: Resume from failure points
+  - ✅ Long-running workflows: Execute multi-hour tasks safely
+  - ✅ User control: Pause and review between stages
+  - ✅ Real-time feedback: Monitor progress during execution
+  - ✅ Audit trail: Complete execution history with artifacts
+
+#### Known Limitations
+
+- Test coverage for new features (StageExecutionController, CheckpointManager, resume, runs) is minimal
+  - Recommendation: Add comprehensive tests before production use
+
 ## [5.2.2] - 2025-10-14
 
 ### 🧪 Quality & Maintenance Release

package/README.md

@@ -7,9 +7,9 @@
 [![npm version](https://img.shields.io/npm/v/@defai.digital/automatosx.svg)](https://www.npmjs.com/package/@defai.digital/automatosx)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue.svg)](https://www.typescriptlang.org/)
-[![Tests](https://img.shields.io/badge/tests-1,259%20passing-brightgreen.svg)](#)
+[![Tests](https://img.shields.io/badge/tests-1,657%20passing-brightgreen.svg)](#)
 
-**Status**: ✅ Production Ready · v5.2.2 · October 2025
+**Status**: ✅ Production Ready · v5.3.0 · October 2025
 
 Looking for answers? See the [FAQ](FAQ.md).
 
@@ -278,7 +278,7 @@ npm install -g @defai.digital/automatosx
 
 ```bash
 ax --version
-# Should show: 5.1.0 (or later)
+# Should show: 5.3.0 (or later)
 ```
 
 > **Windows Users**: If `ax` command not found, see [Windows Troubleshooting](docs/troubleshooting/windows-troubleshooting.md)
@@ -332,6 +332,62 @@ ax list agents
 
 ---
 
+### 🪟 Windows Support (Fully Tested)
+
+**AutomatosX v5.3.1+ fully supports Windows 10 & 11** with automatic CLI provider detection.
+
+#### Quick Start for Windows Users
+
+**Most users don't need any configuration** - AutomatosX automatically detects provider CLIs installed via npm:
+
+```bash
+# 1. Install providers (if not already installed)
+npm install -g @anthropic-ai/claude-cli
+npm install -g @google/generative-ai-cli
+npm install -g openai
+
+# 2. Verify detection
+ax status
+```
+
+**If providers are not detected**, you can manually specify paths:
+
+**Windows (Command Prompt)**:
+```cmd
+set CLAUDE_CLI=C:\Users\YourName\AppData\Roaming\npm\claude.cmd
+set GEMINI_CLI=C:\Users\YourName\AppData\Roaming\npm\gemini.cmd
+ax status
+```
+
+**Windows (PowerShell)**:
+```powershell
+$env:CLAUDE_CLI="C:\Users\YourName\AppData\Roaming\npm\claude.cmd"
+$env:GEMINI_CLI="C:\Users\YourName\AppData\Roaming\npm\gemini.cmd"
+ax status
+```
+
+#### How Provider Detection Works
+
+AutomatosX uses a **three-layer detection system**:
+
+1. **ENV Variables** (highest priority) - `CLAUDE_CLI`, `GEMINI_CLI`, `CODEX_CLI`
+2. **Config File** - Custom paths in `automatosx.config.json`
+3. **PATH Detection** (automatic) - Standard system PATH
+   - **Windows**: Uses `where.exe` + PATH×PATHEXT scanning
+   - **Unix/macOS**: Uses `which` command
+
+#### Windows-Specific Help
+
+Having issues on Windows? See our comprehensive guides:
+
+- 📖 **[Windows Setup Guide](docs/troubleshooting/windows-setup.md)** - Complete Windows installation walkthrough
+- 🔧 **[Windows Troubleshooting](docs/troubleshooting/windows-troubleshooting.md)** - Common Windows issues and solutions
+- ⚙️ **[Advanced Configuration](docs/guide/configuration.md)** - Custom paths, version requirements, and more
+
+> **💡 Quick Tip**: Run `ax status --verbose` to see exactly which paths are being detected and used.
+
+---
+
 ### Step 3: Run Your First Agent
 
 **Terminal Mode** (any platform):
@@ -426,6 +482,26 @@ ax mcp
 
 ---
 
+## ⏱️ Stage Checkpoints & Run History
+
+AutomatosX 5.3 introduces stage-aware checkpoints so you can pause long-running agent workflows, inspect intermediate outputs, and resume exactly where the run stopped.
+
+### Enable resumable runs
+- CLI: `ax run <agent> "<task>" --resumable` (add `--interactive` or `--hybrid` for live approval)
+- Config: set `execution.stages.enabled` to `true` in `automatosx.config.json` to make stage checkpoints the default. Combine with `execution.stages.autoSaveCheckpoint` to persist after every stage.
+
+When a stage finishes, AutomatosX stores a checkpoint under `.automatosx/checkpoints/<run-id>/` (artifacts, logs, and metadata). The CLI prints the UUID so you can resume or inspect it later.
+
+### Manage checkpoints
+- `ax resume <run-id>` — Resume a saved run. Flags such as `--interactive`, `--streaming`, `--hybrid`, or `--auto-continue` override the saved execution mode.
+- `ax runs list [--status running|paused|completed|failed|aborted] [--agent <name>] [--limit <n>]` — Review recent checkpoints with progress and status.
+- `ax runs show <run-id> [--artifacts]` — Inspect stage history, retry counts, and generated artifacts before resuming.
+- `ax runs delete <run-id> [--force]` — Remove stale checkpoints or clear sensitive artifacts once a run is finalized.
+
+Set `execution.stages.cleanupAfterDays` to control automatic pruning (default 7 days). For an end-to-end guide, see [Checkpoints & Run History](docs/guide/checkpoints-and-resume.md).
+
+---
+
 ## 📚 Documentation
 
 ### Getting Started
@@ -441,6 +517,7 @@ ax mcp
 - **[Multi-Agent Orchestration](docs/guide/multi-agent-orchestration.md)** - Natural language delegation
 - **[Team Configuration](docs/guide/team-configuration.md)** - Team-based agent organization
 - **[Agent Templates](docs/guide/agent-templates.md)** - Quick agent creation
+- **[Checkpoints & Run History](docs/guide/checkpoints-and-resume.md)** - Manage resumable runs and checkpoint storage
 
 ### Tutorials
 - **[Memory Management](docs/tutorials/memory-management.md)** - Hands-on memory system guide
@@ -578,12 +655,20 @@ I need Daisy to analyze the data    # Need expression
 
 ## 🛠️ Production-Ready
 
-✅ **1,259 tests passing** (100% pass rate)
+✅ **1,670 tests passing** (100% pass rate)
 ✅ **TypeScript strict mode** (zero errors)
 ✅ **~56% test coverage** (comprehensive testing)
 ✅ **458KB bundle** (99.9% smaller than v3.x)
 ✅ **< 1ms memory search** (62x faster than v3.x)
 
+### Tested Platforms
+
+AutomatosX has been thoroughly tested across multiple operating systems:
+
+- ✅ **macOS**: macOS 15+ (tested on macOS 15)
+- ✅ **Ubuntu**: Ubuntu 24.04 LTS
+- ✅ **Windows**: Windows 10 & Windows 11
+
 ### Performance Metrics
 
 ```