λgitsite

~ober/jerboa-coreutils

Imported from ~/mine/jerboa-coreutils

download snapshot

about

# jerboa-coreutils

GNU coreutils implemented in [Jerboa](https://git.jerboa.sh/ober/jerboa) on stock Chez Scheme.

## Architecture

```
┌─────────────────────────────────────────┐
│  113 coreutils (true, cat, ls, ...)     │
│  src/jerboa-coreutils/*.ss  (Jerboa)    │
└─────────────────────────────────────────┘
   ↓ jerbuild transpile  (src/ .ss → lib/ .sls)
┌─────────────────────────────────────────┐
│  Jerboa: (jerboa core), (std/cli/getopt)│
│  Jerboa syntax: def, let-hash, match... │
│  Stdlib: format, sugar, sort, crypto... │
└─────────────────────────────────────────┘
   ↓ jerbuild build  (whole-program compile + link)
┌─────────────────────────────────────────┐
│  Stock Chez Scheme 10.x (unmodified)    │
│  one self-contained multi-call binary   │
└─────────────────────────────────────────┘
```

Code is written in **Jerboa** (`.ss`, using `(jerboa prelude)`, `def`,
reader extras, `(std …)` modules). The jerboa toolchain (`jerbuild`)
transpiles `src/` to R6RS `lib/` and whole-program-compiles the multi-call
entry (`main-binary.ss`) into one binary that dispatches on `argv[0]`.

## Quick Start

```bash
# Prerequisites: jerbuild + a C compiler + cargo (crypto crate). On FreeBSD
# use gmake. The vendored crate is auto-fetched by `make vendor-deps`.
make binary

# Run utilities (binary dispatches on argv[0] via bin/ symlinks)
bin/true
bin/echo "hello world"
echo "foo bar" | bin/cat -n
bin/seq 1 10
bin/ls -la

# Cross-compile (toolchains required; see Makefile)
make linux-amd64   # static musl x86-64
make linux-arm64   # static musl aarch64
make freebsd-amd64 # FreeBSD 14 amd64
```

## Project Structure

```
jerboa-coreutils/
├── src/jerboa-coreutils/       # 113 utilities — Jerboa SOURCE (.ss)
│   ├── common.ss               # Shared error handling, exit codes
│   ├── common/io.ss            # File/line processing utilities
│   ├── common/security.ss      # Checked sinks, audit, taint, FFI helpers
│   ├── grep/pcre2.ss           # PCRE2 FFI bindings (lazy dlopen)
│   └── true.ss ... grep.ss     # Individual utilities
├── lib/jerboa-coreutils/       # GENERATED R6RS libraries (jerbuild transpile)
├── main-binary.ss              # Multi-call dispatch entry (argv[0] basename)
├── .jerbuild                   # jerbuild build config (entry, ffi, crate)
├── support/
│   ├── libcoreutils.c          # C shim for FFI (stat, ls, cp, terminal…)
│   ├── coreutils-jerbuild-main.c   # custom main() (sets _CU_CMD = argv[0])
│   └── coreutils-ffi-symbols.list  # registered FFI symbols (shim + crypto)
├── vendor/jerboa-native-rs/    # vendored crypto crate (checksum applets)
├── Makefile
└── README.md
```

## Utilities (110)

**Phase 1 - Basic:** true, false, yes, echo, printenv, sleep, whoami, logname, pwd, basename, dirname, link, unlink, hostname, nproc, tty, sync

**Phase 2 - Text:** cat, head, tail, wc, tee, tac, nl, fold, expand, unexpand

**Phase 3 - Advanced Text:** cut, paste, join, comm, sort, uniq, tr, numfmt

**Phase 4 - File Ops:** mkdir, rmdir, mktemp, touch, ln, readlink, realpath

**Phase 5-6 - Info:** truncate, uname, arch, id, groups

**Phase 7 - Transforms:** seq, factor

**Phase 8 - Process:** env, timeout, kill, nice, nohup

**Phase 9 - Encoding:** shuf, base64, base32

**Phase 10-13 - Misc:** tsort, hostid, users, uptime, chroot, mkfifo, mknod, pathchk, fmt, printf

**Phase 14 - Checksums:** cksum, md5sum, sha1sum, sha256sum, sha512sum, sha224sum, sha384sum

**Phase 15-18 - System:** chmod, chown, chgrp, stat, du, df, date, expr, test

**Phase 19-24 - Advanced:** who, split, dircolors, install, shred, pinky, basenc, b2sum, sum, od, csplit, pr, chcon, runcon, ptx, cp, mv, rm, ls, dd, stty, stdbuf, dir, vdir

## Release Gates

```bash
make security
make verify
make sbom
make reproducibility-report
make target-evidence
make release-evidence
```

`make verify` runs static security checks, dependency/native audit metadata,
module import checks, focused symlink/process-argument security smokes, and the
multicall smoke test suite. `make release-evidence` writes
`dist/release-evidence`, including SBOM/toolchain data and repeated-build
reproducibility evidence.

Production support is still blocked until `make target-evidence` records a
marker-complete proof through `JCOREUTILS_TARGET_PROOF_FILE`; production
release hosts should set `JCOREUTILS_REQUIRE_TARGET_PROOF=1` so missing or
incomplete proof fails closed. The proof is a summary of release-host SBOM and
reproducibility review, history secret review, native RustSec review, external
FFI review, filesystem/process review, PCRE2 target linkage, and cross-platform
smoke status. It must not contain raw command output, file contents, private
paths, hostnames, customer data, tokens, or keys.

The current source scanner posture is clean at medium-or-higher severity.
Kernel sandboxing is not claimed; deployments that need seccomp or Landlock
must wrap the binary externally or add verified native enforcement.
Rust advisory status is a fail-closed release gate: `make audit` runs
`cargo audit --file <Cargo.lock> -D warnings` for the native crate, and missing
`cargo-audit` or any advisory finding fails release evidence.

This repository intentionally has filesystem, process, terminal, and FFI
surfaces because it implements coreutils applets. The current production policy
is documented in `docs/threat-model.md`, `docs/ffi-boundary.md`, and
`docs/process-and-filesystem-policy.md`.

## License

Apache-2.0. See `LICENSE`.

recent commits