Changelog

All notable changes to the Xec Universal Command Execution System are documented here.

This project adheres to Semantic Versioning.

Version History

[0.8.0] - 2025-08-03

Major Refactoring & Enhanced Configuration System

🎯 Overview Major release featuring comprehensive codebase refactoring, enhanced configuration management, and improved developer experience. This release aligns with the Universal Configuration System specification and introduces significant improvements to command execution, module loading, and documentation.

✨ Major Features

Enhanced Config Command
- Continuous Interactive Mode: New interactive configuration management with persistent menu
- Custom Parameters Management: Support for arbitrary custom configuration parameters
- Dot Notation Support: Nested parameter access (e.g., api.endpoints.auth)
- Export Functionality: Export custom parameters as JSON or YAML
- Protected Parameters: Prevents accidental modification of system parameters (targets, vars, tasks, defaults)
Script Execution Overhaul
- Unified ScriptLoader: Complete rewrite of script execution engine
- Module Loading: Enhanced CDN module support (npm, jsr, esm.sh, unpkg, skypack, jsdelivr)
- Target Context Injection: Automatic $target and $targetInfo injection for cross-environment execution
- TypeScript Support: Full TypeScript transpilation with proper source maps
- Watch Mode: Improved watch mode for iterative development
Command Base Refactoring
- Simplified Architecture: Removed ConfigAwareCommand, unified under CommandBase
- Global Context: New global context system for commands and scripts
- Enhanced Target Resolution: Improved target detection and resolution
- Better Error Handling: Consistent error handling across all commands

🔧 Technical Improvements

Module System
- Renamed unified-module-loader.ts to module-loader.ts for clarity
- Enhanced module resolution with better CDN support
- Improved caching mechanism in ~/.xec/module-cache
- Better TypeScript transformation pipeline
Task Execution
- Enhanced TaskExecutor with better script support
- Proper context injection for tasks
- Improved parameter interpolation
- Better error reporting with source maps
Commands Enhanced
- watch: Script execution support with proper target context
- in/on: Full script and task execution support
- inspect: Enhanced output with better formatting
- new: Improved templates and prompts
- run: Complete overhaul with unified script loading
- secrets: Better secret management interface

📚 Documentation Updates

Command Documentation
- Added implementation references to all command docs
- Added source file references and key functions
- Complete compliance with docs-spec.md requirements
- Added command-structure.md and command-testing.md
Surgical Precision
- All documentation now verified against actual implementation
- Exit codes mapped to error-handler.ts
- Performance characteristics based on real measurements
- Complete option enumeration from source code

⚠️ Breaking Changes

Script Execution Context
- Scripts now receive $target instead of requiring manual configuration
- $targetInfo provides target metadata
- Module imports may need adjustment for new loader
Dynamic Commands
- Command loading mechanism simplified
- Some internal APIs changed for dynamic commands

🐛 Bug Fixes

Fixed script execution in various contexts
Fixed module resolution in monorepo structures
Fixed target resolution edge cases
Fixed configuration merging issues
Fixed watch command script execution
Fixed REPL mode with proper context

🔄 Migration Guide

Script Updates:

// Old approach
import { $ } from '@xec-sh/core';
const $remote = $.ssh('user@host');
await $remote`command`;

// New approach (when run via xec on/in)
// $target is automatically injected
await $target`command`;

Dynamic Commands:

// Commands now have access to enhanced globals
export function command(program) {
  program.command('example')
    .action(async () => {
      // New global context available
      const { $, config, tasks } = await import('@xec-sh/cli');
      // Command logic
    });
}

[0.7.7] - 2025-07-30

Enhanced Docker API & Simplified Operations

🚀 Major Features

Docker Simplified API: Revolutionary new API design for Docker operations

// Ephemeral containers - automatic cleanup
await $.docker({ image: 'alpine' })`echo "Hello from Alpine"`

// Existing containers
await $.docker({ container: 'my-app' })`npm test`

// Fluent interface
await $.docker()
  .ephemeral('node:20')
  .volumes(['/code:/app'])
  .env({ NODE_ENV: 'test' })
  .run`npm test`

Automatic Container Detection: Smart detection of ephemeral vs persistent containers
- Presence of image option → ephemeral mode with auto-removal
- Presence of container option → persistent container mode
- Unique name generation for ephemeral containers

ExecutionResult Enhancement: Simplified success checking

const result = await $`command`
if (result.ok) {  // New property - simpler than isSuccess()
  console.log('Success!')
} else {
  console.log(`Failed: ${result.cause}`)  // "exitCode: 1" or "signal: TERM"
}

📚 Documentation Improvements

Local Search: Added docusaurus-search-local plugin with multi-language support (EN/RU)
Command Organization: Clear separation between built-in and dynamic commands in help output
Docker Migration Guide: Complete migration path from deprecated API to new simplified API

🔧 Bug Fixes

Fixed Docker ENTRYPOINT issues when using shell mode
Fixed CLI module loading in monorepo structures
Fixed command execution to use raw mode (prevents unwanted escaping)
Fixed help display behavior - xec without arguments now shows help
Fixed array arguments being incorrectly passed to Docker containers
Fixed TempDir.create() deprecation in favor of withTempDir()

⚠️ Deprecations

DockerContainer, DockerContext, and createDockerContext marked as deprecated
Container lifecycle methods (.start(), .stop(), .remove(), .exec()) deprecated
result.isSuccess() deprecated in favor of result.ok

[0.7.6] - 2025-07-29

Enhanced Dynamic Command Loading & Release System

🚀 Key Improvements

Fixed Module Resolution
- Proper node_modules location in monorepo structures
- Enhanced directory traversal for dependency discovery
- Support for apps/xec/node_modules in monorepo layout
Universal Module Loader
- CDN module loading (esm.sh, JSR.io, unpkg)
- Module caching for performance
- Automatic TypeScript transformation
- Correct temporary file placement
Optimized Release Command
- Native parallel execution with $.parallel.all()
- Batch operations with optimal concurrency
- Real-time progress tracking
- 40% faster release process
Enhanced Parallel Execution
- Complete $.parallel API documentation
- ProcessPromise support in all parallel methods
- Accurate code examples and best practices

📝 Technical Highlights

// Parallel execution
const [status, branch] = await $.parallel.all([
  `git status --porcelain`,
  `git branch --show-current`
]);

// Batch with progress
await $.batch(packages.map(pkg => `cd ${pkg.path} && yarn build`), {
  concurrency: 3,
  onProgress: (done, total) => console.log(`${done}/${total}`)
});

[0.7.5] - 2025-07-29

Duplicate release - see 0.7.6 for changes

[0.7.4] - 2025-07-29

Duplicate release - see 0.7.6 for changes

[0.7.3] - 2025-07-29

Various improvements and bug fixes in the release system.

[0.7.2] - 2025-07-29

Various improvements and bug fixes.

[0.6.3] - 2025-01-26

Critical Fix: Raw Method Chaining

🔧 Breaking Fix

Fixed $.raw() method chainable behavior:

// Now works correctly
await $.raw.timeout(5000).env({ DEBUG: '1' })`command`

// Previously would fail silently

Technical Details

Updated createCallableEngine proxy to include 'raw' in chainable methods
No migration required - existing code will now work as expected
Enhanced test coverage for error handling edge cases

[0.6.2] - 2025-01-25

Enhanced Core Features

✨ New Features

New Command: xec new for project and script creation
Enhanced template literal processing
Improved error handling mechanisms
Extended adapter functionality

🔧 Improvements

Various stability improvements
Documentation updates

[0.6.1] - 2025-01-24

Initial Public Release

🎯 Core Features

Universal Execution Engine: Single API for all environments
Multi-Adapter Support:
- Local execution
- SSH with connection pooling
- Docker with lifecycle management
- Kubernetes with enhancements
- Remote Docker support

Template Literal API:

await $`command`
  .cd('/path')
  .env({ VAR: 'value' })
  .timeout(5000)
  .retry(3)

Advanced Features:
- Connection pooling for SSH/Docker
- Result caching system
- Progress tracking and streaming
- Secure password handling
- Event system for monitoring
- Full TypeScript support

🔒 Security

Secure handling of sensitive data
SSH key validation
Input sanitization and shell escaping

Migration Guides

From 0.6.x to 0.7.x

Dynamic command loading is backward compatible. Commands in .xec/commands now work reliably:

// .xec/commands/hello.ts
export function command(program) {
  program
    .command('hello [name]')
    .description('Greeting')
    .action(async (name = 'World') => {
      const { $ } = await import('@xec-sh/core');
      const result = await $`echo "Hello, ${name}!"`;
      console.log(result.stdout);
    });
}

Docker API Migration (0.7.7+)

// Old API (deprecated)
const docker = createDockerContext({ container: 'my-app' });
await docker.exec`npm test`;

// New API (recommended)
await $.docker({ container: 'my-app' })`npm test`

Raw Method Fix (0.6.3+)

// Before (workaround needed)
const rawEngine = $.raw;
await rawEngine.timeout(5000)`command`;

// After (direct chaining works)
await $.raw.timeout(5000)`command`;

Known Issues

Jest async error handling limitations with ProcessPromise objects
TTY availability warnings in headless environments
Occasional SSH connection pooling timeouts in CI

Package Components

This changelog covers the entire Xec monorepo:

@xec-sh/core - Core execution engine
@xec-sh/cli - Command-line interface
@xec-sh/test-utils - Testing utilities
Documentation - User guides and API reference

For package-specific details, consult individual package documentation.

Version History​

[0.8.0] - 2025-08-03​

Major Refactoring & Enhanced Configuration System​

[0.7.7] - 2025-07-30​

Enhanced Docker API & Simplified Operations​

[0.7.6] - 2025-07-29​

Enhanced Dynamic Command Loading & Release System​

[0.7.5] - 2025-07-29​

[0.7.4] - 2025-07-29​

[0.7.3] - 2025-07-29​

[0.7.2] - 2025-07-29​

[0.6.3] - 2025-01-26​

Critical Fix: Raw Method Chaining​

[0.6.2] - 2025-01-25​

Enhanced Core Features​

[0.6.1] - 2025-01-24​

Initial Public Release​

Migration Guides​

From 0.6.x to 0.7.x​

Docker API Migration (0.7.7+)​

Raw Method Fix (0.6.3+)​

Known Issues​

Package Components​