Beagle SCM

JaB - JavaScript bindings for Beagle

JaB is a WebKit JSC based runtime with a set of js bindings for libabc and libdog. It is a way to extend Beagle with arbitrary scripts to automate routines and workflows. The runtime binary is jab (formerly jabc), divorced from be: be links no JSC and runs no JS, while jab resolves and runs scripts kept in the be/ submodule (see Extensions, Verbs).

• very basic runtime, still able to do low-level stuff
• revision control specific bindings
• no use of NPM infrastructure because of security issues
• the git repo is the only code distribution channel
• no async() APIs, no node APIs: minimalistic, lightweight

Invocation — jab [path] args

The jab binary is a standalone runner; the first argument picks one of two modes, and everything after it reaches the script as args (and Node-ish process.argv).

• Explicit path (/abs, ./rel, ../up) runs that file directly by global eval — no be/ scan; the CMake js/test/*.js cases use this absolute-path form.
• A bare name (no leading slash or dot) runs the require machinery below to find a script under a be/ dir, then evals it.
• jab links no be logic and be links no JSC — fully divorced; a script reaches the repo by spawning be/dogs via io.spawn.
• process.argv[1] is patched to the resolved abspath, so a script locates its siblings and lib/ through the here idiom.

require() machinery

A bare name — a CLI argument or a require("name") — resolves by scanning UP for a be/ dir; an explicit path resolves node-style, so a script set versions independently of where it runs.

• Bare name: from cwd walk up ./be ../be ../../be …; in each try <be>/<name> then <be>/<name>.js.
• The scan ceiling is $HOME/be for paths under $HOME, else /be; absent be/ dirs are skipped.
• Explicit path (./rel, ../up, /abs) resolves relative to the requiring module's own dir, node-style (.js / /index.js).
• require() is synchronous CommonJS (mmap → eval → cache), cycle-safe; canonical scripts live in the be/ submodule (beagle-ext): the verb scripts plus lib/.

Bindings

JaB exposes libabc and libdog as a flat set of global modules — thin syscall/format leaves holding no memory across the boundary (only JS-owned buffers and fds cross). Install order is fixed in main.cpp.

• io — fds, read/write, mmap, readdir, spawn/reap, cwd/getenv/stat/mkdir/rename: the syscall leaves.
• Buf — a Uint8Array plus PAST|DATA|IDLE boundaries; the one cursor abstraction over heap, mmap, or file backings.
• abc — containers over abc logs (ram/mmap/over/book), abc.index (the mmap LSM), merge/intersect.
• git — git.pack (offset-pure PACK), git.delta.apply, git.tree, git.parseCommit.
• tok — generic source tokenizer (tok.parse, TokStream) sharing dog/tok's lexer core.
• codec — hex, sha1/sha256, and ron (the ron60 time codec, 2000–2099).
• zip — raw zlib deflate/inflate, the git-wire primitive.
• uri — abc/URI parse/make/escape and the URI class.
• pol — the poll(2) event loop (watch/every/after/run).
• net — Node-style TCP/UDP plus setTimeout/setInterval over pol.
• ansi / tty — SGR colour wrappers and terminal raw-mode/winsize for the bro pager.
• utf8, process, require — UTF-8 ↔ string, Node-ish process.argv / global args, and CommonJS require.