just-bash session-state fork

This repository is a focused fork of vercel-labs/just-bash. It adds an opt-in, JSON-safe session snapshot API for applications that need consecutive exec() calls to behave like prompts in one persistent shell.

The fork is based on the upstream just-bash@3.3.0 tag. It preserves the Apache-2.0 license and the default isolated execution behavior.

What this fork adds

• BashOptions.sessionState to opt into top-level state persistence.
• bash.snapshotState() to export synchronous interpreter state.
• bash.restoreState(snapshot) to restore state into a fresh Bash instance.
• Defensive cloning so snapshots do not share mutable interpreter references.
• Version and shape validation before restoration.
• Stateful synchronous fc, umask, and virtual ulimit builtins.
• Conformance tests for isolation, persistence, round trips, failures, and snapshot immutability.

The API captures variables and attributes, arrays, aliases, function ASTs, working-directory state, shell options, completion definitions, status, virtual process metadata, command hashes, descriptor tables, bounded command history, the file-creation mask, and virtual resource limits. It excludes background execution, active jobs, jobs, wait, kill, signals, process substitutions, call stacks, and other in-flight state.

Install from GitHub

This fork is not published to npm. Install the immutable package artifact from the GitHub release:

npm install https://github.com/cekrauseee/just-bash/releases/download/session-state-v3/just-bash-3.3.0.tgz

The session-state-v3 release contains the snapshot API plus stateful fc, umask, and virtual ulimit builtins. The release is immutable and is built from the feat/session-state-snapshots commit. Installing the monorepo Git SHA directly is not supported because npm installs the repository root rather than a workspace subdirectory.

Persistent session example

import { Bash } from "just-bash";

const first = new Bash({ sessionState: true });
await first.exec("export NAME=world; greet() { echo hello $NAME; }");

const stored = JSON.stringify(first.snapshotState());

const second = new Bash({ sessionState: true });
second.restoreState(JSON.parse(stored));

const result = await second.exec("greet");
console.log(result.stdout); // hello world

The host application owns persistence, schema migration, aggregate quotas, filesystem snapshots, concurrency, and transaction boundaries. The fork only serializes and restores interpreter state.

Documentation

• Project scope
• Architecture
• Development and release workflow
• Session-state contract
• Upstream package documentation

Upstream relationship

The change is intentionally small and isolated so it can be reviewed against upstream or proposed back later. The upstream remote should continue to point to https://github.com/vercel-labs/just-bash.git.

No npm package is published under the upstream just-bash name from this fork.