λgitsite

~ober/jerboa-shell

Imported from ~/mine/jerboa-shell

download snapshot

about

# jerboa-shell

`jerboa-shell` is `jsh`: a compact shell written in Jerboa Scheme. It focuses
on familiar bash/zsh-style command execution: parsing, expansion, builtins,
redirection, pipelines, jobs, history, completion, and POSIX process behavior.

Security posture, threat model, native-boundary notes, and release evidence are
tracked in `SECURITY.md`, `docs/threat-model.md`, `docs/ffi-boundary.md`, and
`docs/release-evidence.md`. `jsh` is a shell, not a sandbox.

## Build

```sh
make jsh-macos
./jsh-macos -c 'echo ok'
```

The build uses `jerbuild` from Jerboa. The Makefile prefers `./jerbuild`, then
`.jerboa/bin/jerbuild`, then `jerbuild` on `PATH`; if none are available it
fetches the configured Jerboa release tool.

The default targets build only the bare shell. To open the optional-feature
menu, fetch the extras bundle and its selected dependencies, and produce
`./jsh-extras`, run:

```sh
make extras
```

The optional bundle currently covers 20 selectable groups, including built-in
coreutils, mux, encrypted embed/pass/vault storage, SSH, YubiKey, AWS,
wormhole, recording, sandboxing, resource limits, profiling, proxying,
WireGuard, process watching, hardening, AWK, and sed. See
[`docs/extras.md`](docs/extras.md) for the complete command reference,
selection rules, platform requirements, security boundaries, and known
limitations.

The top-level target uses `_vendor/jerboa-shell-extras/embed` as its embed
input. It does not automatically read or encrypt `~/.embed`; the extras guide
shows the explicit encrypted build command.

## Test

```sh
make test
make test-native
make test-security-regressions
make audit
make release-evidence
make test-binary
make compat-smoke
```

The Oils spec runner under `test/` measures shell compatibility. Benchmark
scripts live here so speed work stays close to the shell implementation.
`make release-evidence` records unit tests, native FFI audit output, SBOM
manifests, and reproducibility output under `dist/release-evidence/`.

Command substitution is drained concurrently and is limited to 8 MiB by
default. Set `JSH_COMMAND_SUB_MAX_BYTES` to a positive byte limit no greater
than 1 GiB when a workload needs a different bound. Exceeding the limit aborts
the expansion after the producer has been drained, rather than hanging it on a
full pipe.

Interpreted development runs load `libjsh-ffi` only when
`JSH_FFI_DEV_NATIVE=1` and `JSH_FFI_LIB` names an absolute, non-symlink
directory. Standalone builds register the shim statically; neither mode
searches the current directory or a bare library name. Development loading
also rejects ambient DYLD/LD search overrides and verifies the JSH1 ABI canary.

## History

Interactive `jsh` writes normal line-oriented shell history to `$HISTFILE`
(default: `~/.jsh_history`). Set `HISTSIZE` and `HISTFILESIZE` to control the
in-memory and saved entry limits.

History recording can be disabled from startup config with the bash-style
history option:

```sh
# ~/.jshrc
case "$PWD/" in
  "$HOME/mine/obersh/"*) set +o history ;;
esac
```

For memory-only session history without saving a file, unset `HISTFILE`, set
`HISTFILE=`, or set `HISTFILE=/dev/null`.

## Layout

```text
*.ss                  shell source modules
jerboa-src/src/       small compatibility modules used by the build
support/              build helpers
test/                 unit, binary, and Oils compatibility tests
bench*.ss             shell benchmark scripts
```

recent commits