just-binary 3.2.4 → 3.3.0

package/dist/limits.d.ts

@@ -35,6 +35,8 @@ export interface ExecutionLimits {
     maxHeredocSize?: number;
     /** Maximum command substitution nesting depth (default: 50) */
     maxSubstitutionDepth?: number;
+    /** Maximum number of concurrently running background jobs (default: 128) */
+    maxConcurrentJobs?: number;
 }
 /**
  * Resolve execution limits by merging user-provided limits with defaults.

package/dist/process/process-table.d.ts

@@ -0,0 +1,92 @@
+/**
+ * ProcessTable models machine-level process state independently from a shell.
+ *
+ * Bash instances are intentionally cheap, throwaway shells. A process table is
+ * kernel-like machine state, so callers may inject one table into many Bash
+ * instances and keep jobs alive while the shell objects come and go.
+ */
+export type JobSignal = "SIGTERM" | "SIGINT" | "SIGKILL" | "SIGSTOP" | "SIGCONT";
+export interface JobInfo {
+    pid: number;
+    command: string;
+    startedAt: number;
+    state: "running" | "done";
+    exitCode?: number;
+}
+export interface ListedJob extends JobInfo {
+    jobNumber: number;
+    marker: "+" | "-" | " ";
+}
+export interface ProcessTableOptions {
+    /** Observer called for every chunk a job writes, so a host can log per-job. */
+    onJobOutput?: (pid: number, fd: number, chunk: Uint8Array) => void;
+    /** Called when a job settles (SIGCHLD). */
+    onJobExit?: (pid: number, exitCode: number) => void;
+    /** Maximum time disposal waits for aborted runners to settle. */
+    disposeTimeoutMs?: number;
+}
+interface ListJobsOptions {
+    changedOnly?: boolean;
+    runningOnly?: boolean;
+    stoppedOnly?: boolean;
+}
+export type JobRunner = (pid: number, signal: AbortSignal) => Promise<number>;
+export declare class ProcessTable {
+    private readonly jobs;
+    private readonly reapedWaitStatuses;
+    private readonly reapedWaitLineages;
+    private readonly options;
+    private nextPid;
+    private nextLineageId;
+    private highestJobNumber;
+    private runningJobs;
+    private disposed;
+    private disposePromise?;
+    constructor(options?: ProcessTableOptions);
+    /**
+     * Start a job and return its PID without awaiting it.
+     *
+     * The record is installed before the runner is invoked, so another shell
+     * sharing this table can immediately inspect, kill, or wait for the job.
+     */
+    start(command: string, runner: JobRunner, lineageId?: number): number;
+    list(): JobInfo[];
+    /**
+     * Snapshot jobs for the `jobs` builtin and reap every completed job included
+     * in the snapshot. Markers are computed once for the complete table.
+     */
+    listJobs(selectedPids?: ReadonlySet<number>, options?: ListJobsOptions): ListedJob[];
+    get(pid: number): JobInfo | undefined;
+    /**
+     * Deliver one of the table's cooperative signals. A signal number preserves
+     * 128+n for terminating signals mapped onto a supported delivery mode.
+     * STOP/CONT are acknowledged no-ops because jobs have no stopped state.
+     */
+    kill(pid: number, reason: JobSignal, signalNumber?: number): boolean;
+    /**
+     * Wait for machine-level process state. With no PID this intentionally drains
+     * every job in the table; shell builtins must use waitForLineage instead.
+     */
+    wait(pid?: number): Promise<number>;
+    /** Wait for and reap only jobs launched by one top-level shell execution. */
+    waitForLineage(lineageId: number): Promise<number>;
+    /** Allocate an identity inherited by nested interpreters in one root exec. */
+    createLineageId(): number;
+    abortAll(reason?: JobSignal): void;
+    dispose(): Promise<void>;
+    /** Number of jobs that currently count toward the concurrency limit. */
+    get runningCount(): number;
+    /** Bash job number assigned to a PID, or undefined for an unknown PID. */
+    getJobNumber(pid: number): number | undefined;
+    /** Whether a PID is an active child or has a retained wait status. */
+    canWait(pid: number): boolean;
+    /** Resolve the numeric and current/previous job specs accepted by Bash. */
+    resolveJobSpec(spec: string): number | undefined;
+    /** Whether job channel wrappers need to report output to the host. */
+    get observesOutput(): boolean;
+    /** Report one output chunk. The table deliberately never retains it. */
+    observeOutput(pid: number, fd: number, chunk: Uint8Array): void;
+    private rememberWaitStatus;
+    private deleteJobs;
+}
+export {};

package/dist/sandbox/Command.d.ts

@@ -1,4 +1,5 @@
 import type { Bash } from "../Bash.js";
+import { type JobSignal, ProcessTable } from "../process/process-table.js";
 export interface OutputMessage {
     type: "stdout" | "stderr";
     data: string;
@@ -7,21 +8,33 @@ export interface OutputMessage {
 export declare class Command {
     readonly cmdId: string;
     readonly cwd: string;
+    /**
+     * Bash-specific process ID. This is not part of the Vercel Sandbox API.
+     */
+    readonly pid: number;
     readonly startedAt: Date;
     exitCode: number | undefined;
     private bashEnv;
     private cmdLine;
     private env?;
     private explicitCwd;
+    private processes;
+    private shellProcesses;
+    private logMessages;
+    private logReaders;
+    private logsComplete;
+    private stdoutDecoder;
+    private stderrDecoder;
     private resultPromise;
-    constructor(bashEnv: Bash, cmdLine: string, cwd: string, env?: Record<string, string>, explicitCwd?: boolean);
+    constructor(bashEnv: Bash, cmdLine: string, cwd: string, env?: Record<string, string>, explicitCwd?: boolean, processes?: ProcessTable, shellProcesses?: ProcessTable);
+    private appendLog;
     private execute;
     logs(): AsyncGenerator<OutputMessage, void, unknown>;
     wait(): Promise<CommandFinished>;
     output(): Promise<string>;
     stdout(): Promise<string>;
     stderr(): Promise<string>;
-    kill(): Promise<void>;
+    kill(signal?: JobSignal): Promise<void>;
 }
 export interface CommandFinished extends Command {
     exitCode: number;

package/dist/sandbox/Sandbox.d.ts

@@ -35,6 +35,11 @@ export interface WriteFilesInput {
 }
 export declare class Sandbox {
     private bashEnv;
+    private commandProcesses;
+    private baseShellProcesses;
+    private commandShellProcesses;
+    private stopped;
+    private stopPromise?;
     private constructor();
     static create(opts?: SandboxOptions): Promise<Sandbox>;
     runCommand(cmd: string, opts?: {

package/dist/types.d.ts

@@ -33,6 +33,12 @@ export interface CommandExecOptions {
     cwd: string;
     /** Standard input as a byte stream. Optional — defaults to an empty stream. */
     stdin?: ByteStream;
+    /**
+     * Abort signal for the nested execution. The parent execution's signal is
+     * always inherited automatically; pass a signal here to cancel the nested
+     * execution earlier than the parent (e.g. the timeout command).
+     */
+    signal?: AbortSignal;
 }
 export interface TraceEvent {
     category: string;
@@ -61,7 +67,13 @@ export interface CommandContext {
     exec?: (command: string, options: CommandExecOptions) => Promise<ExecResult>;
     fetch?: SecureFetch;
     getRegisteredCommands?: () => string[];
-    sleep?: (ms: number) => Promise<void>;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /**
+     * Abort signal for the current execution (from ExecOptions.signal).
+     * Long-running commands should check it before/after waits and pass it
+     * to cancellable operations.
+     */
+    signal?: AbortSignal;
     fileDescriptors?: Map<number, string>;
     xpgEcho?: boolean;
     substitutionDepth?: number;

package/dist/utils/abort.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AbortSignal composition utility.
+ *
+ * Used to inherit a parent execution's signal into nested exec calls
+ * (bash -c, xargs, timeout, command substitution via execFn) while still
+ * allowing the nested call to carry its own signal.
+ */
+/**
+ * Combine two optional AbortSignals into one that aborts when either does.
+ * Returns the other signal unchanged when only one is provided.
+ */
+export declare function combineAbortSignals(a: AbortSignal | undefined, b: AbortSignal | undefined): AbortSignal | undefined;

package/dist/utils/stream.d.ts

@@ -17,6 +17,11 @@ export type ByteStream = ReadableStream<Uint8Array>;
 export declare const CHUNK_SIZE: number;
 /** An empty stream that closes immediately. */
 export declare function emptyStream(): ByteStream;
+/**
+ * True when `stream` came from emptyStream() and so cannot yield bytes.
+ * A false answer proves nothing — an unmarked stream may still be empty.
+ */
+export declare function isKnownEmptyStream(stream: ByteStream): boolean;
 /** Wrap a single Uint8Array as a stream. Empty input → empty stream. */
 export declare function fromBytes(bytes: Uint8Array): ByteStream;
 /** Wrap an array of chunks as a stream. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "just-binary",
-  "version": "3.2.4",
+  "version": "3.3.0",
   "description": "A simulated bash environment with virtual filesystem",
   "repository": {
     "type": "git",
@@ -34,6 +34,7 @@
     "dist/interpreter/**/*.d.ts",
     "dist/network/**/*.d.ts",
     "dist/parser/*.d.ts",
+    "dist/process/**/*.d.ts",
     "dist/sandbox/*.d.ts",
     "dist/utils/*.d.ts",
     "README.md",

package/dist/bin/chunks/alias-DRSSCAUM.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{a,b,c,d}from"./chunk-D34QBGQ3.js";import"./chunk-DFAHK2EQ.js";import"./chunk-RAUBS6MJ.js";import"./chunk-463VWH7H.js";export{a as aliasCommand,c as flagsForFuzzing,b as unaliasCommand,d as unaliasFlagsForFuzzing};

package/dist/bin/chunks/awk2-GM5WBRLU.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{a,b}from"./chunk-FVFLR7NF.js";import"./chunk-CAXM2HMK.js";import"./chunk-SE4C7FJY.js";import"./chunk-XILOLP4K.js";import"./chunk-DFAHK2EQ.js";import"./chunk-RAUBS6MJ.js";import"./chunk-463VWH7H.js";export{a as awkCommand2,b as flagsForFuzzing};

package/dist/bin/chunks/base64-KLZ4B6VS.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{a,b}from"./chunk-D44C6YVE.js";import"./chunk-RUESYAVK.js";import"./chunk-7VWUKGDV.js";import"./chunk-DFAHK2EQ.js";import"./chunk-RAUBS6MJ.js";import"./chunk-463VWH7H.js";export{a as base64Command,b as flagsForFuzzing};

package/dist/bin/chunks/basename-XCXGYZPS.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{a,b}from"./chunk-44ROJVH3.js";import"./chunk-DFAHK2EQ.js";import"./chunk-RAUBS6MJ.js";import"./chunk-463VWH7H.js";export{a as basenameCommand,b as flagsForFuzzing};

package/dist/bin/chunks/bash-U2E2FSIE.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{a,b,c,d}from"./chunk-RFIBBYTO.js";import"./chunk-CAXM2HMK.js";import"./chunk-DFAHK2EQ.js";import"./chunk-RAUBS6MJ.js";import"./chunk-463VWH7H.js";export{a as bashCommand,c as flagsForFuzzing,b as shCommand,d as shFlagsForFuzzing};

package/dist/bin/chunks/cat-D4E4FTXJ.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{a,b}from"./chunk-PKKBPSVJ.js";import"./chunk-Z72PSRMX.js";import"./chunk-OBH7XN5N.js";import"./chunk-7VWUKGDV.js";import"./chunk-DFAHK2EQ.js";import"./chunk-RAUBS6MJ.js";import"./chunk-463VWH7H.js";export{a as catCommand,b as flagsForFuzzing};

package/dist/bin/chunks/chmod-OY5CP5QF.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{a,b}from"./chunk-446TXLPR.js";import"./chunk-DFAHK2EQ.js";import"./chunk-RAUBS6MJ.js";import"./chunk-463VWH7H.js";export{a as chmodCommand,b as flagsForFuzzing};