JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 39
  • Score
    100M100P100Q73570F
  • 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 shell execution engine with adapters for local, SSH, Docker, and Kubernetes environments.

Install

pnpm add @xec-sh/core

Quick Start

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

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

// Variables are automatically escaped
const file = 'my file.txt';
await $`cat ${file}`;

// SSH execution with connection pooling
const ssh = $.ssh({ host: 'server.com', username: 'deploy' });
await ssh`uptime`;

// Docker container execution
await $.docker('my-container')`ps aux`;

// Kubernetes pod execution
const k8s = $.k8s({ namespace: 'production' });
await k8s.pod('app-pod')`hostname`;
// ProcessPromise methods
const result = await $`grep pattern file.txt`
  .nothrow()   // don't throw on non-zero exit
  .quiet()     // suppress output
  .timeout(5000);

// Consume output
const text = await $`cat file.txt`.text();
const data = await $`cat data.json`.json();
const lines = await $`ls`.lines();
const buf = await $`cat image.png`.buffer();

// Pipe commands
await $`cat access.log`.pipe($`grep 404`).pipe($`wc -l`);
import { parallel, within, withTempFile } from '@xec-sh/core';

// Parallel execution with concurrency limit
const results = await parallel([
  $`test-1.sh`, $`test-2.sh`, $`test-3.sh`
], { maxConcurrent: 2 });

// Scoped execution context
await within(async () => {
  $.defaults({ cwd: '/tmp', env: { NODE_ENV: 'test' } });
  await $`npm test`;
});

// Helpers
import { echo, sleep, glob, kill, parseDuration, expBackoff } from '@xec-sh/core';

await sleep(1000);
echo('output');
const files = await glob('**/*.ts');
const ms = parseDuration('5m');

API

Export Description
$ Default callable execution engine (template literal tag)
configure Configure the global engine
dispose Clean up the global engine
ExecutionEngine Core engine class
createCallableEngine Wrap an engine as a callable
LocalAdapter Local process adapter
SSHAdapter SSH adapter with connection pooling
DockerAdapter Docker container adapter
KubernetesAdapter Kubernetes pod adapter
DockerFluentAPI Fluent API for Docker lifecycle
DockerContainer Docker container management
parallel / ParallelEngine Parallel execution utilities
within / withinSync Scoped execution context
withTempDir / withTempFile Temporary file helpers
echo / sleep / glob / kill Shell-like helpers
parseDuration / expBackoff Duration and backoff utilities
retry / RetryError Retry with backoff
RuntimeDetector Detect Node.js, Bun, or Deno
SSHKeyValidator Validate SSH keys
SecurePasswordHandler Secure password handling
EnhancedEventEmitter Typed event emitter
pipeUtils Pipe composition utilities

Features

  • Template literal syntax $\cmd`` with automatic shell escaping
  • Adapters: local, SSH, Docker, Kubernetes, mock, remote Docker
  • SSH connection pooling and keep-alive
  • ProcessPromise with .text(), .json(), .lines(), .buffer(), .nothrow(), .quiet(), .timeout(), .signal(), .kill(), .pipe()
  • Pipe chaining between commands and adapters
  • Parallel execution with concurrency control
  • Automatic retry with exponential backoff
  • Streaming output and async iteration
  • within/withinSync for scoped configuration
  • Temp file and directory helpers
  • Shell helpers: echo, sleep, glob, kill, parseDuration, expBackoff
  • $.prefix / $.postfix / $.preferLocal configuration
  • $.defaults() for global configuration
  • Chainable methods: .cd(), .env(), .timeout(), .shell(), .retry()
  • Zero external runtime dependencies
  • Works on Node.js, Bun, and Deno

License

MIT