@cowasm/coreutils

@cowasm/coreutils provides WebAssembly ports of 54 essential FreeBSD Unix command-line utilities, enabling traditional Unix tools to run in browser and server JavaScript environments. This package compiles C source code to WebAssembly, offering cross-platform compatibility for file system operations, text processing, and system utilities within the CoWasm ecosystem.

Package Information

• Package Name: @cowasm/coreutils
• Package Type: npm
• Language: C (compiled to WebAssembly)
• Installation: npm install @cowasm/coreutils

Core Imports

const { path } = require("@cowasm/coreutils");

For ES modules:

import { path } from "@cowasm/coreutils";

Basic Usage

const { path } = require("@cowasm/coreutils");
const { join } = require("path");

// Get the path to WebAssembly binaries
const wasmBinPath = path; // Points to dist/wasm directory
const lsBinary = join(wasmBinPath, "bin", "ls");

// Use with a WebAssembly runtime (e.g., @cowasm/posix-wasm)
// The exact execution method depends on your WebAssembly runtime

Architecture

@cowasm/coreutils is built around these key components:

• WebAssembly Compilation: C source code from FreeBSD coreutils compiled to WASM
• Path Export: Simple API providing location of compiled WebAssembly binaries
• POSIX Compatibility: Designed to work with POSIX-compliant WebAssembly runtimes
• Build System: Comprehensive Makefile-based build system for cross-compilation
• CoWasm Integration: Optimized for use within the CoWasm collaborative computing ecosystem

Capabilities

Package API

The package exports a single path property pointing to the WebAssembly binaries directory.

/**
 * Path to the WebAssembly binaries directory
 */
exports.path: string;

File Operations

Essential file system operations including listing, copying, moving, and permission management.

// Available WebAssembly binaries in dist/wasm/bin/:
// ls, cat, cp, mv, rm, rmdir, mkdir, chmod, ln, touch, stat

File Operations

Text Processing

Comprehensive text processing utilities for filtering, searching, formatting, and transforming text data.

// Available WebAssembly binaries in dist/wasm/bin/:
// grep, head, tail, cut, sort, uniq, wc, tr, fmt, fold, expand, unexpand, nl, paste, join, comm, csplit

Text Processing

System Utilities

System information and environment utilities for inspecting and managing system state.

// Available WebAssembly binaries in dist/wasm/bin/:
// uname, id, logname, env, date, tty, du, which

System Utilities

Path Utilities

Path manipulation and resolution utilities for working with file and directory paths.

// Available WebAssembly binaries in dist/wasm/bin/:
// basename, dirname, readlink, realpath, pathchk

Path Utilities

Logic and Math Utilities

Mathematical operations and logical testing utilities.

// Available WebAssembly binaries in dist/wasm/bin/:
// expr, factor, seq, test, false

Logic and Math

Miscellaneous Utilities

Additional utility programs for various specialized tasks.

// Available WebAssembly binaries in dist/wasm/bin/:
// sleep, mktemp, xargs, yes, pr, tee, find, tsort

Miscellaneous Utilities

Types

interface CoreutilsExports {
  /** Path to the WebAssembly binaries directory (dist/wasm) */
  path: string;
}

Known Limitations

Some utilities have known issues in the WebAssembly environment:

• tail -f: Follow mode not supported (requires epoll implementation)
• split: Non-functional and excluded from build due to freopen limitations
• expand: File input mode broken (freopen issues) - stdin input works
• fold: File input mode broken (freopen issues) - stdin input works
• nl: File input mode broken (freopen issues) - stdin input works
• env: execvp functionality limited in WebAssembly context

Build Requirements

Building from source requires:

• CoWasm build environment: @cowasm/posix-wasm, @cowasm/bzip2, @cowasm/zlib
• Zig compiler: For WebAssembly compilation
• Make: GNU Make for build orchestration
• Build command: npm run build or make -j8 all

Runtime Requirements

• WebAssembly runtime: Supports WASI (WebAssembly System Interface)
• File system access: Virtual file system for I/O operations
• CoWasm environment: Recommended for full compatibility