just-binary 2.9.8

package/dist/types.d.ts

@@ -0,0 +1,148 @@
+import type { IFileSystem } from "./fs/interface.js";
+import type { ExecutionLimits } from "./limits.js";
+import type { SecureFetch } from "./network/index.js";
+/**
+ * Lightweight interface for feature coverage tracking during fuzzing.
+ * Lives here to avoid circular dependencies between fuzzing → core modules.
+ */
+export interface FeatureCoverageWriter {
+    hit(feature: string): void;
+}
+export interface ExecResult {
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+    exitCode: number;
+    /** The final environment variables after execution (only set by BashEnv.exec) */
+    env?: Record<string, string>;
+}
+/** Result from BashEnv.exec() - always includes env */
+export interface BashExecResult extends ExecResult {
+    env: Record<string, string>;
+}
+/** Options for exec calls within commands (internal API) */
+export interface CommandExecOptions {
+    /** Environment variables to merge into the exec state */
+    env?: Record<string, string>;
+    /**
+     * Working directory for the exec.
+     * Required to prevent bugs where subcommands run in the wrong directory.
+     * Always pass `ctx.cwd` from the calling command's context.
+     */
+    cwd: string;
+    /**
+     * Standard input to pass to the subcommand.
+     * Optional - if not provided, stdin will be empty.
+     */
+    stdin?: Uint8Array;
+}
+/**
+ * Context provided to commands during execution.
+ *
+ * ## Field Availability
+ *
+ * **Always available (core fields):**
+ * - `fs`, `cwd`, `env`, `stdin`
+ *
+ * **Available when running via BashEnv interpreter:**
+ * - `exec` - For commands like `xargs`, `bash -c` that need to run subcommands
+ * - `getRegisteredCommands` - For the `help` command to list available commands
+ *
+ * **Conditionally available based on configuration:**
+ * - `fetch` - Only when `network` option is configured in BashEnv
+ * - `sleep` - Only when a custom sleep function is provided (e.g., for testing)
+ */
+/**
+ * Performance trace event for profiling command execution
+ */
+export interface TraceEvent {
+    /** Event category (e.g., "find", "grep") */
+    category: string;
+    /** Event name (e.g., "readdir", "stat", "eval") */
+    name: string;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Optional details (e.g., path, count) */
+    details?: Record<string, unknown>;
+}
+/**
+ * Trace callback function for receiving performance events
+ */
+export type TraceCallback = (event: TraceEvent) => void;
+export interface CommandContext {
+    /** Virtual filesystem interface for file operations */
+    fs: IFileSystem;
+    /** Current working directory */
+    cwd: string;
+    /** Environment variables - uses Map to prevent prototype pollution */
+    env: Map<string, Uint8Array>;
+    /**
+     * Exported environment variables only.
+     * Used by commands like printenv and env that should only show exported vars.
+     * In bash, only exported variables are passed to child processes.
+     */
+    exportedEnv?: Record<string, string>;
+    /** Standard input content */
+    stdin: Uint8Array;
+    /**
+     * Execution limits configuration.
+     * Available when running commands via BashEnv interpreter.
+     */
+    limits?: Required<ExecutionLimits>;
+    /**
+     * Performance trace callback for profiling.
+     * If provided, commands emit timing events for analysis.
+     */
+    trace?: TraceCallback;
+    /**
+     * Execute a subcommand (e.g., for `xargs`, `bash -c`).
+     * Available when running commands via BashEnv interpreter.
+     *
+     * @param command - The command string to execute
+     * @param options - Required options including `cwd` to prevent directory bugs
+     */
+    exec?: (command: string, options: CommandExecOptions) => Promise<ExecResult>;
+    /**
+     * Secure fetch function for network requests (e.g., for `curl`).
+     * Only available when `network` option is configured in BashEnv.
+     */
+    fetch?: SecureFetch;
+    /**
+     * Returns names of all registered commands.
+     * Available when running commands via BashEnv interpreter.
+     * Used by the `help` command.
+     */
+    getRegisteredCommands?: () => string[];
+    /**
+     * Custom sleep implementation.
+     * If provided, used instead of real setTimeout.
+     * Useful for testing with mock clocks.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * File descriptors map for here-docs and process substitution.
+     * Maps FD numbers to their content (e.g., 3 -> "content from 3<<EOF").
+     * Note: FD 0 content is in `stdin`, but may also appear here for consistency.
+     */
+    fileDescriptors?: Map<number, string>;
+    /**
+     * Whether xpg_echo shopt is enabled.
+     * When true, echo interprets backslash escapes by default (like echo -e).
+     */
+    xpgEcho?: boolean;
+    /**
+     * Current command substitution nesting depth.
+     * Used to prevent stack exhaustion from deeply nested $(...).
+     */
+    substitutionDepth?: number;
+    /**
+     * Feature coverage writer for fuzzing instrumentation.
+     * When provided, commands emit coverage hits for analysis.
+     */
+    coverage?: FeatureCoverageWriter;
+}
+export interface Command {
+    name: string;
+    execute(args: Uint8Array[], ctx: CommandContext): Promise<ExecResult>;
+}
+export type CommandRegistry = Map<string, Command>;
+export type { IFileSystem };

package/dist/utils/args.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Lightweight argument parser for command implementations.
+ *
+ * Handles common patterns:
+ * - Boolean flags: -n, --number
+ * - Combined short flags: -rn (same as -r -n)
+ * - Value options: -k VALUE, -kVALUE, --key=VALUE, --key VALUE
+ * - Positional arguments
+ * - Unknown option detection
+ */
+import type { ExecResult } from "../types.js";
+export type ArgType = "boolean" | "string" | "number";
+export interface ArgDef {
+    /** Short form without dash, e.g., "n" for -n */
+    short?: string;
+    /** Long form without dashes, e.g., "number" for --number */
+    long?: string;
+    /** Type of the argument */
+    type: ArgType;
+    /** Default value */
+    default?: boolean | string | number;
+}
+export interface ParsedArgs<T extends Record<string, ArgDef>> {
+    /** Parsed flag/option values */
+    flags: {
+        [K in keyof T]: T[K]["type"] extends "boolean" ? boolean : T[K]["default"] extends number | string ? T[K]["type"] extends "number" ? number : string : T[K]["type"] extends "number" ? number | undefined : string | undefined;
+    };
+    /** Positional arguments (non-flag arguments) */
+    positional: string[];
+}
+export type ParseResult<T extends Record<string, ArgDef>> = {
+    ok: true;
+    result: ParsedArgs<T>;
+} | {
+    ok: false;
+    error: ExecResult;
+};
+/**
+ * Parse command arguments according to the provided definitions.
+ *
+ * @param cmdName - Command name for error messages
+ * @param args - Arguments to parse
+ * @param defs - Argument definitions
+ * @returns Parsed arguments or error result
+ *
+ * @example
+ * const defs = {
+ *   reverse: { short: "r", long: "reverse", type: "boolean" as const },
+ *   count: { short: "n", long: "lines", type: "number" as const, default: 10 },
+ * };
+ * const result = parseArgs("head", args, defs);
+ * if (!result.ok) return result.error;
+ * const { flags, positional } = result.result;
+ */
+export declare function parseArgs<T extends Record<string, ArgDef>>(cmdName: string, args: string[], defs: T): ParseResult<T>;

package/dist/utils/bytes.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Byte utilities for the Uint8Array-based I/O pipeline.
+ *
+ * The interpreter uses Uint8Array for all I/O (stdout, stderr, stdin).
+ * Commands that process text decode at entry and encode at exit.
+ * Redirections write bytes directly — no encoding guessing.
+ *
+ * Note: Explicit return type annotations are required on encode, concat,
+ * and trimTrailingNewlines because TS 5.7+ made Uint8Array generic over
+ * its buffer type. Without annotations, TextEncoder.encode() and
+ * Uint8Array.prototype.subarray() infer Uint8Array<ArrayBufferLike>,
+ * which is not assignable to the Uint8Array (= Uint8Array<ArrayBuffer>)
+ * used in ExecResult and other interfaces.
+ */
+/** Empty byte array — reuse instead of allocating new Uint8Array(0) */
+export declare const EMPTY: Uint8Array;
+/** Encode a string to UTF-8 bytes */
+export declare function encode(s: string): Uint8Array;
+/** Decode UTF-8 bytes to a string */
+export declare function decode(bytes: Uint8Array): string;
+/** Concatenate two byte arrays. Fast path: if either is empty, return the other without copying. */
+export declare function concat(a: Uint8Array, b: Uint8Array): Uint8Array;
+/** Check if a byte array is empty (zero length) */
+export declare function isEmpty(bytes: Uint8Array): boolean;
+/** Convenience: decode an array of Uint8Array args to string[] via UTF-8 */
+export declare function decodeArgs(args: Uint8Array[]): string[];
+/** Get an env value as a decoded string, or return the fallback (default "") */
+export declare function envGet(env: Map<string, Uint8Array>, key: string, fallback?: string): string;
+/** Set an env value from a string (encodes to UTF-8) */
+export declare function envSet(env: Map<string, Uint8Array>, key: string, value: string): void;
+/**
+ * Create a Map<string, string> adapter over a Map<string, Uint8Array>.
+ * Decodes on read and encodes on write, so mutations propagate to the backing store.
+ * Used at the boundary between the Uint8Array-based interpreter env and the
+ * string-based Command interface (until Phase 4 migrates commands).
+ */
+export declare function createStringEnvAdapter(backing: Map<string, Uint8Array>): Map<string, string>;
+/** Remove trailing newline bytes (0x0A) from the end */
+export declare function trimTrailingNewlines(bytes: Uint8Array): Uint8Array;

package/dist/utils/constants.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared constants for the bash environment.
+ */
+/**
+ * Default batch size for parallel I/O operations.
+ *
+ * This value is used across multiple commands (find, ls, tree, du, etc.) to
+ * control how many filesystem operations are performed concurrently. A larger
+ * value provides more parallelism but uses more memory; a smaller value is
+ * more conservative.
+ *
+ * 100 is a good default that provides significant parallelism without
+ * overwhelming the system or using excessive memory.
+ */
+export declare const DEFAULT_BATCH_SIZE = 100;

package/dist/utils/file-reader.d.ts

@@ -0,0 +1,67 @@
+/**
+ * File reading utilities for command implementations.
+ *
+ * Provides common patterns for reading from files or stdin,
+ * including parallel batch reading for performance.
+ */
+import type { CommandContext, ExecResult } from "../types.js";
+export interface ReadFilesOptions {
+    /** Command name for error messages */
+    cmdName: string;
+    /** If true, "-" in file list means stdin */
+    allowStdinMarker?: boolean;
+    /** If true, stop on first error. If false, collect errors and continue */
+    stopOnError?: boolean;
+    /** Number of files to read in parallel (default: 100). Set to 1 for sequential. */
+    batchSize?: number;
+}
+export interface FileContent {
+    /** File name (or "-" for stdin, or "" if stdin with no files) */
+    filename: string;
+    /** File content */
+    content: Uint8Array;
+}
+export interface ReadFilesResult {
+    /** Successfully read files */
+    files: FileContent[];
+    /** Error messages (e.g., "cmd: file: No such file or directory\n") */
+    stderr: string;
+    /** 0 if all files read successfully, 1 if any errors */
+    exitCode: number;
+}
+/**
+ * Read content from files or stdin.
+ *
+ * If files array is empty, reads from stdin.
+ * If files contains "-", reads stdin at that position.
+ *
+ * @example
+ * const result = await readFiles(ctx, files, { cmdName: "cat" });
+ * if (result.exitCode !== 0 && options.stopOnError) {
+ *   return { stdout: "", stderr: result.stderr, exitCode: result.exitCode };
+ * }
+ * for (const { filename, content } of result.files) {
+ *   // process content
+ * }
+ */
+export declare function readFiles(ctx: CommandContext, files: string[], options: ReadFilesOptions): Promise<ReadFilesResult>;
+/**
+ * Read and concatenate all files into a single string.
+ *
+ * Useful for commands like sort and uniq that process all input together.
+ *
+ * @example
+ * const result = await readAndConcat(ctx, files, { cmdName: "sort" });
+ * if (!result.ok) return result.error;
+ * const lines = result.content.split("\n");
+ */
+export declare function readAndConcat(ctx: CommandContext, files: string[], options: {
+    cmdName: string;
+    allowStdinMarker?: boolean;
+}): Promise<{
+    ok: true;
+    content: Uint8Array;
+} | {
+    ok: false;
+    error: ExecResult;
+}>;

package/dist/utils/glob.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared glob pattern matching utilities.
+ *
+ * Used by grep, find, and other commands that need glob matching.
+ */
+export interface MatchGlobOptions {
+    /** Case-insensitive matching */
+    ignoreCase?: boolean;
+    /** Strip surrounding quotes from pattern before matching */
+    stripQuotes?: boolean;
+}
+/**
+ * Match a filename against a glob pattern.
+ *
+ * Supports:
+ * - `*` matches any sequence of characters
+ * - `?` matches any single character
+ * - `[...]` character classes
+ *
+ * @param name - The filename to test
+ * @param pattern - The glob pattern
+ * @param options - Matching options
+ * @returns true if the name matches the pattern
+ */
+export declare function matchGlob(name: string, pattern: string, options?: MatchGlobOptions | boolean): boolean;

package/package.json

@@ -0,0 +1,115 @@
+{
+  "name": "just-binary",
+  "version": "2.9.8",
+  "description": "A simulated bash environment with virtual filesystem",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hinkik/just-binary.git"
+  },
+  "homepage": "https://github.com/hinkik/just-binary#readme",
+  "bugs": {
+    "url": "https://github.com/hinkik/just-binary/issues"
+  },
+  "type": "module",
+  "main": "dist/bundle/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/bundle/browser.js",
+      "import": "./dist/bundle/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/bundle/browser.js"
+    }
+  },
+  "files": [
+    "dist/bundle/",
+    "dist/bin/",
+    "dist/*.d.ts",
+    "dist/ast/*.d.ts",
+    "dist/commands/**/*.d.ts",
+    "dist/fs/**/*.d.ts",
+    "dist/interpreter/**/*.d.ts",
+    "dist/network/**/*.d.ts",
+    "dist/parser/*.d.ts",
+    "dist/sandbox/*.d.ts",
+    "dist/utils/*.d.ts",
+    "README.md",
+    "dist/AGENTS.md"
+  ],
+  "bin": {
+    "just-binary": "./dist/bin/just-bash.js",
+    "just-binary-shell": "./dist/bin/shell/shell.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [],
+  "author": "hinkik",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.10",
+    "fast-check": "^3.23.2",
+    "@types/ini": "^4.1.1",
+    "@types/node": "^25.0.3",
+    "@types/papaparse": "^5.5.2",
+    "@types/sprintf-js": "^1.1.4",
+    "@types/sql.js": "^1.4.9",
+    "@types/turndown": "^5.0.6",
+    "@vitest/coverage-v8": "^4.0.18",
+    "esbuild": "^0.27.2",
+    "knip": "^5.41.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "compressjs": "^1.0.3",
+    "diff": "^8.0.2",
+    "fast-xml-parser": "^5.3.3",
+    "file-type": "^21.2.0",
+    "ini": "^6.0.0",
+    "minimatch": "^10.1.1",
+    "modern-tar": "^0.7.3",
+    "papaparse": "^5.5.3",
+    "pyodide": "^0.27.0",
+    "re2js": "^1.2.1",
+    "smol-toml": "^1.6.0",
+    "sprintf-js": "^1.1.3",
+    "sql.js": "^1.13.0",
+    "turndown": "^7.2.2",
+    "yaml": "^2.8.2"
+  },
+  "optionalDependencies": {
+    "@mongodb-js/zstd": "^7.0.0",
+    "node-liblzma": "^2.0.3"
+  },
+  "packageManager": "pnpm@8.15.9+sha512.499434c9d8fdd1a2794ebf4552b3b25c0a633abcee5bb15e7b5de90f32f47b513aca98cd5cfd001c31f0db454bc3804edccd578501e4ca293a6816166bbd9f81",
+  "scripts": {
+    "build": "rm -rf dist && tsc && pnpm build:lib && pnpm build:browser && pnpm build:cli && pnpm build:shell && pnpm build:worker && pnpm build:clean && sed '1,/^-->/d' AGENTS.npm.md > dist/AGENTS.md",
+    "build:clean": "find dist -name '*.test.js' -delete && find dist -name '*.test.d.ts' -delete",
+    "build:worker": "esbuild src/commands/python3/worker.ts --bundle --platform=node --format=esm --outfile=src/commands/python3/worker.js --external:pyodide && cp src/commands/python3/worker.js dist/commands/python3/worker.js && mkdir -p dist/bin/chunks && cp src/commands/python3/worker.js dist/bin/chunks/worker.js && mkdir -p dist/bundle/chunks && cp src/commands/python3/worker.js dist/bundle/chunks/worker.js",
+    "build:lib": "esbuild dist/index.js --bundle --splitting --platform=node --format=esm --minify --outdir=dist/bundle --chunk-names=chunks/[name]-[hash] --external:diff --external:minimatch --external:sprintf-js --external:turndown --external:sql.js --external:pyodide --external:@mongodb-js/zstd --external:node-liblzma --external:compressjs",
+    "build:browser": "esbuild dist/browser.js --bundle --platform=browser --format=esm --minify --outfile=dist/bundle/browser.js --external:diff --external:minimatch --external:sprintf-js --external:turndown --external:node:* --external:@mongodb-js/zstd --external:node-liblzma --external:compressjs --define:__BROWSER__=true",
+    "build:cli": "esbuild dist/cli/just-bash.js --bundle --splitting --platform=node --format=esm --minify --outdir=dist/bin --entry-names=[name] --chunk-names=chunks/[name]-[hash] --banner:js='#!/usr/bin/env node' --external:sql.js --external:pyodide --external:@mongodb-js/zstd --external:node-liblzma --external:compressjs",
+    "build:shell": "esbuild dist/cli/shell.js --bundle --splitting --platform=node --format=esm --minify --outdir=dist/bin/shell --entry-names=[name] --chunk-names=chunks/[name]-[hash] --banner:js='#!/usr/bin/env node' --external:sql.js --external:pyodide --external:@mongodb-js/zstd --external:node-liblzma --external:compressjs",
+    "validate": "pnpm lint && pnpm knip && pnpm typecheck &&  pnpm build && pnpm test:run && pnpm test:dist",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "knip": "knip",
+    "test": "vitest",
+    "test:run": "vitest run --exclude src/security/fuzzing/",
+    "test:dist": "vitest run src/cli/just-bash.bundle.test.ts",
+    "test:unit": "vitest run --config vitest.unit.config.ts",
+    "test:comparison": "vitest run --config vitest.comparison.config.ts",
+    "test:comparison:record": "RECORD_FIXTURES=1 vitest run --config vitest.comparison.config.ts",
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:unit": "vitest run --config vitest.unit.config.ts --coverage",
+    "test:fuzz": "vitest run src/security/fuzzing/",
+    "test:fuzz:long": "FUZZ_RUNS=10000 vitest run src/security/fuzzing/",
+    "shell": "npx tsx src/cli/shell.ts",
+    "dev:exec": "npx tsx src/cli/exec.ts"
+  }
+}