JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 8
  • Score
    100M100P100Q48555F
  • License MIT

Universal shell execution engine

Package Exports

  • @xec-sh/core
  • @xec-sh/core/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@xec-sh/core) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@xec-sh/core

Universal execution engine providing a unified API for running commands across local, SSH, Docker, and Kubernetes environments.

Installation

npm install @xec-sh/core

Documentation

Features

  • Universal API - Same syntax works everywhere
  • Template Literals - Safe command interpolation with automatic escaping
  • Type Safety - Full TypeScript support with IntelliSense
  • Streaming - Real-time output without buffering
  • Connection Pooling - Automatic SSH connection reuse
  • Error Handling - Result-based pattern with detailed context

Basic Usage

import { $ } from '@xec-sh/core';

// Local execution
await $`echo "Hello, World!"`;

// Variables are automatically escaped
const filename = "file with spaces.txt";
await $`touch ${filename}`;

// Error handling
const result = await $`grep pattern file.txt`.nothrow();
if (!result.isSuccess()) {
  console.log('Pattern not found');
}

Execution Adapters

SSH

const ssh = $.ssh({ host: 'server.com', username: 'user' });

// Execute commands
await ssh`uname -a`;
await ssh`df -h`;

// File transfer
await ssh.uploadFile('./local.txt', '/remote/path.txt');
await ssh.downloadFile('/remote/file.txt', './local-copy.txt');

// SSH tunnels
const tunnel = await ssh.tunnel({
  localPort: 5433,
  remoteHost: 'localhost',
  remotePort: 5432
});

Docker

// Execute in existing container
const docker = $.docker({ container: 'my-app' });
await docker`ps aux`;

// Create new container
const container = await $.docker({ 
  image: 'node:18',
  name: 'test-container'
}).start();

await container.exec`npm test`;
await container.stop();
await container.remove();

Kubernetes

const k8s = $.k8s({ namespace: 'default' });
const pod = k8s.pod('my-app-pod');

// Execute commands
await pod.exec`hostname`;

// Stream logs
await pod.follow(line => console.log(line));

// Port forwarding
const forward = await pod.portForward(8080, 80);
console.log(`Access at localhost:${forward.localPort}`);

Advanced Features

Parallel Execution

import { parallel } from '@xec-sh/core';

const results = await parallel([
  $`npm install`,
  $`npm run build`,
  $`npm test`
], { maxConcurrent: 2 });

Configuration

// Global configuration
import { configure } from '@xec-sh/core';

configure({
  shell: '/bin/bash',
  timeout: 30000,
  env: { NODE_ENV: 'production' }
});

// Per-command configuration
await $`npm test`
  .cwd('/app')
  .env({ NODE_ENV: 'test' })
  .timeout(60000)
  .retry(3);

Event System

$.on('command:start', (event) => {
  console.log(`Starting: ${event.command}`);
});

$.on('command:error', (event) => {
  console.error(`Failed: ${event.error.message}`);
});

API Reference

Core Functions

  • $ - Main execution function
  • $.ssh() - SSH adapter
  • $.docker() - Docker adapter
  • $.k8s() - Kubernetes adapter
  • configure() - Global configuration
  • parallel() - Parallel execution

Utilities

  • escapeShellArg() - Shell argument escaping
  • quoteShellArg() - Shell argument quoting
  • RuntimeDetector - Runtime detection
  • ProcessPromise - Promise-based process handling

More Documentation

Contributing

See Contributing Guide

License

MIT © Xec Contributors