@amritk/nish-x86_64-linux 0.20.0 → 0.22.1

package/runtime/core/strings.mjs

@@ -0,0 +1,169 @@
+/**
+ * The strings of the core: an Nish string is its UTF-8 bytes, so every length
+ * and offset here counts bytes. Only the web's `TextEncoder` and `TextDecoder`
+ * are used, and the decoder keeps a leading byte-order mark, as a cut through
+ * the bytes must. Decoding is lossy where native is not: bytes that are not
+ * UTF-8, or a cut through a character, decode to U+FFFD, whose three bytes
+ * then change the string's length.
+ */
+import { panicIndex, panicSlice, toIndex } from "./checks.mjs";
+
+const ENCODER = new TextEncoder();
+const DECODER = new TextDecoder("utf-8", { ignoreBOM: true });
+
+/** The string `bytesOf` encoded last, and its bytes. */
+let lastString = "";
+let lastBytes = new Uint8Array(0);
+
+/**
+ * The UTF-8 bytes of `s`, which is what an Nish string holds. The last string
+ * encoded is kept with its bytes, so a loop of `s.charCodeAt(i)` over one
+ * string encodes it once rather than once per byte. Nothing here writes to
+ * the bytes it is handed.
+ */
+function bytesOf(s) {
+  if (s !== lastString) {
+    lastBytes = ENCODER.encode(s);
+    lastString = s;
+  }
+  return lastBytes;
+}
+
+/**
+ * `s.length`: UTF-8 byte length for strings (arrays keep their own `.length`).
+ * The engine's encoder outruns a count in JavaScript, and the loop condition
+ * `i < s.length` then leaves the bytes for the `s.charCodeAt(i)` it guards.
+ */
+export function strLen(x) {
+  return typeof x === "string" ? bytesOf(x).length : x.length;
+}
+
+/**
+ * `s?.length` in a `?.` chain: `undefined` when the chain has stopped at a
+ * `null` or `undefined` link, as `?.` answers, and the byte length otherwise.
+ * The chain is its argument, so it is evaluated once and its short circuit
+ * kept.
+ */
+export function strLenOpt(x) {
+  return x === null || x === undefined ? undefined : strLen(x);
+}
+
+/** `s.charCodeAt(i)`: the byte at `i`, bounds-checked as `a[i]` is (JavaScript answers NaN). */
+export function charCodeAt(s, i) {
+  const bytes = bytesOf(s);
+  const k = toIndex(i);
+  if (!(k >= 0 && k < bytes.length)) panicIndex(k, bytes.length);
+  return bytes[k];
+}
+
+/** `s.substring(a, b)`: JavaScript's clamp and swap, over byte offsets. */
+export function substring(s, a, b) {
+  const bytes = bytesOf(s);
+  const clamp = (v) => Math.max(0, Math.min(toIndex(v), bytes.length));
+  const from = clamp(a);
+  const to = b === undefined ? bytes.length : clamp(b);
+  return DECODER.decode(bytes.subarray(Math.min(from, to), Math.max(from, to)));
+}
+
+/**
+ * `s.slice(a, b)`: the bytes of `[a, b)` with no clamp, `b` defaulting to the
+ * byte length (WP15 §4). Out of range panics rather than clamping, so the two
+ * compares the native code emits are reproduced here rather than JavaScript's
+ * negative-from-the-end rule.
+ */
+export function slice(s, a, b) {
+  const bytes = bytesOf(s);
+  const from = toIndex(a);
+  const to = b === undefined ? bytes.length : toIndex(b);
+  if (!(from >= 0 && from <= to && to <= bytes.length)) panicSlice(from, to, bytes.length);
+  return DECODER.decode(bytes.subarray(from, to));
+}
+
+/** Whether `needle` sits in `bytes` at byte offset `at`. */
+function bytesAt(bytes, at, needle) {
+  if (!(at >= 0 && at + needle.length <= bytes.length)) return false;
+  for (let j = 0; j < needle.length; j++) {
+    if (bytes[at + j] !== needle[j]) return false;
+  }
+  return true;
+}
+
+/**
+ * `s.indexOf(sub, from)`: the first *byte* offset at or after `from`, or -1.
+ * `from` is converted as JavaScript's `ToIntegerOrInfinity` converts it (NaN
+ * is 0) and clamped into `[0, len]`, so an empty `sub` is found at `from`.
+ * The engine's `indexOf` over the bytes finds each candidate for `sub`'s
+ * first byte, and only those are compared in full.
+ */
+export function indexOf(s, sub, from) {
+  const haystack = bytesOf(s);
+  const at = from === undefined ? 0 : toIndex(from);
+  const start = Number.isNaN(at) ? 0 : Math.max(0, Math.min(at, haystack.length));
+  if (sub.length === 0) return start;
+  const needle = ENCODER.encode(sub);
+  const last = haystack.length - needle.length;
+  for (let i = haystack.indexOf(needle[0], start); i >= 0 && i <= last; i = haystack.indexOf(needle[0], i + 1)) {
+    if (bytesAt(haystack, i, needle)) return i;
+  }
+  return -1;
+}
+
+/** `nish_str_at`: whether `sub`'s bytes sit at byte offset `at`. */
+function occursAt(s, at, sub) {
+  return bytesAt(bytesOf(s), at, ENCODER.encode(sub));
+}
+
+export function startsWith(s, sub) {
+  return occursAt(s, 0, sub);
+}
+
+export function endsWith(s, sub) {
+  const bytes = bytesOf(s);
+  const needle = ENCODER.encode(sub);
+  return bytesAt(bytes, bytes.length - needle.length, needle);
+}
+
+/**
+ * `String.fromCharCode(c)`: the one-unit string of `c & 0xFF`. Under 128 that
+ * is the one byte native builds; from 128 it is the Latin-1 character, two
+ * UTF-8 bytes where native holds one (LANGUAGE.md's C row).
+ */
+export function fromCharCode(code) {
+  return String.fromCharCode(toIndex(code) & 0xff);
+}
+
+/**
+ * `String.fromBytes(bytes, start, end)`: the bytes of `[start, end)`, one
+ * code unit each as `fromCharCode` builds them, checked as `s.slice`'s range
+ * is and failing with its panic. The copy into a `Uint8Array` reduces each
+ * element to a byte as a `Buffer` store does, and the string is built a chunk
+ * at a time so that no call passes more arguments than the engine takes.
+ */
+export function fromBytes(bytes, start, end) {
+  const from = toIndex(start);
+  const to = toIndex(end);
+  if (!(from >= 0 && from <= to && to <= bytes.length)) panicSlice(from, to, bytes.length);
+  const out = new Uint8Array(to - from);
+  for (let i = from; i < to; i++) out[i - from] = bytes[i];
+  let text = "";
+  for (let i = 0; i < out.length; i += 8192) {
+    text += String.fromCharCode.apply(null, out.subarray(i, i + 8192));
+  }
+  return text;
+}
+
+/**
+ * `String.fromBytes(bytes, start, end)` as `--emit-ts` writes it: the bytes of
+ * `[start, end)` decoded as UTF-8, which is the string a native program holds,
+ * checked as `fromBytes`'s range is. A sequence that is not UTF-8 decodes to
+ * U+FFFD where native keeps the bytes. `fromBytes` above stays the
+ * one-unit-per-byte reading the prelude's programs are pinned to.
+ */
+export function utf8FromBytes(bytes, start, end) {
+  const from = toIndex(start);
+  const to = toIndex(end);
+  if (!(from >= 0 && from <= to && to <= bytes.length)) panicSlice(from, to, bytes.length);
+  const out = new Uint8Array(to - from);
+  for (let i = from; i < to; i++) out[i - from] = bytes[i];
+  return DECODER.decode(out);
+}

package/runtime/core.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `nish/runtime`: the host-agnostic core (runtime/core.mjs). Pair it with
+ * `nish/runtime/node` or `nish/runtime/browser`, which install a host.
+ */
+export * from "./core/arrays.js";
+export * from "./core/host.js";
+export * from "./core/numbers.js";
+export * from "./core/result.js";
+export * from "./core/strings.js";

package/runtime/core.mjs

@@ -0,0 +1,55 @@
+/**
+ * Nish builtins, host-agnostic (WP13 differential testing, WP33 R3).
+ *
+ * The differential runner (tests/differential/run.js) rewrites an Nish
+ * program into plain JavaScript and runs it under Node with this module as
+ * `__nish` (`runtime/shim.mjs`, which is this core with `runtime/node.mjs`
+ * installed as its host). Every helper here reproduces the *runtime* semantics the compiled
+ * binary has (runtime/runtime.c and runtime/runtime-os.c, the system-call half,
+ * plus the intrinsics in docs/wp7-runtime.md) where JavaScript's own semantics
+ * differ:
+ *
+ *   - `number` is a 32-bit integer in the default mode (`--number-mode i32`),
+ *     `i64` is a 64-bit integer, both wrapping; JS has doubles and BigInt.
+ *   - `u8`/`u16`/`u32`/`u64` are unsigned and wrapping, and JavaScript has no
+ *     unsigned integers at all: the narrow three live in a `number` masked
+ *     back into range (`& 0xFF`, `& 0xFFFF`, `>>> 0`) and `u64` is a BigInt
+ *     kept in range with `BigInt.asUintN(64, x)`.
+ *   - `f32` is a 32-bit float and JavaScript has only doubles, so every `f32`
+ *     result is rounded with `Math.fround`.
+ *   - `s.length` is the UTF-8 byte length, and so is every index the string
+ *     methods take or return: `charCodeAt` yields a byte (and bounds-checks
+ *     instead of returning `NaN`), `substring` cuts on byte offsets, and
+ *     `indexOf` answers with one. `slice` cuts on byte offsets too and panics
+ *     on a range the string does not contain, where JavaScript would clamp and
+ *     read a negative offset from the end. `String.fromCharCode` builds a
+ *     one-byte string from the low 8 bits, and `String.fromBytes` one such
+ *     string per byte of its range.
+ *   - `a[i]` is bounds-checked: out of range prints
+ *     `index out of range: <i> >= <len>` to stderr and exits 1, and so is
+ *     `a.pop()` on an empty array, which has no `undefined` to return.
+ *   - `toI32/toI64` from f64 saturate (NaN -> 0), integer conversions wrap.
+ *   - `console.log(x)` never prints the `n` suffix of an i64 and writes
+ *     synchronously so `process.exit` cannot lose output.
+ *   - file I/O errors print `nish: cannot read <path>` and exit 1.
+ *   - a directory listing is sorted by UTF-8 bytes, which is `strcmp`'s order
+ *     and not `Array#sort`'s UTF-16 one; `monotonicNanos` reads a clock whose
+ *     origin is arbitrary, so two readings can agree with a native run and a
+ *     single reading never can.
+ *   - `process.argv[0]` is the program (the script here, the executable
+ *     natively); `parseInt` is base 10 only and saturates into i32 (0 for no
+ *     digits); `parseFloat`/`Number` accept ASCII whitespace, decimal forms,
+ *     `Infinity`, and a `0x` hex prefix (parseFloat too, unlike JS).
+ *
+ * The core names no `node:` module and neither `process` nor `Buffer`: what it
+ * needs of the world goes through the host `runtime/core/host.mjs` holds, so
+ * another adapter can stand where `runtime/node.mjs` stands. A check in
+ * `tests/run.js` (`runtime-hosts`) holds it to that.
+ *
+ * The rewrite rules that call these helpers are listed in docs/wp13-differential.md.
+ */
+export * from "./core/arrays.mjs";
+export * from "./core/host.mjs";
+export * from "./core/numbers.mjs";
+export * from "./core/result.mjs";
+export * from "./core/strings.mjs";

package/runtime/host.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `nish/runtime/node` exports nothing: importing it installs that host on the
+ * core in `nish/runtime` (docs/RUN_UNDER_NODE.md). `nish/runtime/browser`
+ * installs its host too, and exports `NishExit` (`browser.d.ts`).
+ */
+export {};

package/runtime/nish.d.ts

@@ -171,6 +171,8 @@ declare function toF64(x: number | boolean): f64;
 /** Reinterpret the 64 bits of an `f64`, never convert the value. */
 declare function f64ToBits(x: f64): i64;
 declare function bitsToF64(bits: i64): f64;
+/** Reinterpret the 32 bits of an `f32`, never convert the value. */
+declare function f32ToBits(x: f32): i32;
 
 // ---- Constant time (WP34 N6) ------------------------------------------------
 
@@ -351,7 +353,7 @@ declare function netWrite(fd: i32, buf: readonly u8[], off: i32, len: i32): i32;
 declare function netShutdown(fd: i32, how: i32): i32;
 /** Close the descriptor. */
 declare function netClose(fd: i32): i32;
-/** A TCP socket connecting to `addr`, answered while it connects: writable once it has, or has failed. */
+/** A TCP socket connecting to `addr`, answered while it connects: writable once it has, or has failed. It holds `TCP_NODELAY`, so a small write is sent at once. */
 declare function tcpConnect(addr: readonly u8[]): i32;
 /** Once `fd` is writable: 0 when the connection is made, else its failure (-111 refused). */
 declare function connectResult(fd: i32): i32;
@@ -380,6 +382,33 @@ declare function pollRemove(loop: i32, fd: i32): i32;
 /** Wait up to `timeoutMs` (negative: forever); pairs `ready[2k]` token, `ready[2k + 1]` events (4: hang-up or error). */
 declare function pollWait(loop: i32, ready: i32[], timeoutMs: i32): i32;
 
+// ---- `nish:term` ------------------------------------------------------------------
+//
+// stdin without blocking and the terminal it may be: the frame clock and the
+// keys of a terminal UI, with no `net` capability. -11 is "nothing is
+// waiting" and -25 "not a terminal" on every platform; any other failure is
+// the host's `-errno`. Under WASI the reading works, `readStdin` waiting for
+// its bytes (ask `waitStdin` first), and the terminal answers -25. Under Node `isTerminal` and `terminalSize` answer and the other four
+// throw.
+
+/** Up to `len` bytes of stdin into `buf` from `off`, never blocking: the count, 0 at end of stream, or -11 when nothing is waiting. */
+declare function readStdin(buf: u8[], off: i32, len: i32): i32;
+/** Wait up to `timeoutMs` (negative: forever) for stdin to be readable (its end and an error count): `true` when it is, `false` when the time passed. */
+declare function waitStdin(timeoutMs: i32): boolean;
+/** Whether descriptor `fd` is a terminal (`isatty`). */
+declare function isTerminal(fd: i32): boolean;
+/** `[columns, rows]` of the terminal on stdout, else stderr; `[-25, 0]` when neither is one, `[0, 0]` when it has no size set. */
+declare function terminalSize(): i32[];
+/**
+ * Raw mode on stdin's terminal, or the mode it had back: 0, -25 when stdin is
+ * not a terminal. No echo, no line editing; Ctrl-C stays SIGINT and "\n"
+ * still starts a line. The terminal is put back at exit, on a panic and on
+ * every signal that ends the program, SIGKILL aside.
+ */
+declare function setRawMode(on: boolean): i32;
+/** Bytes the runtime writes to the terminal on stdout at exit, on a panic and on every signal that ends the program (SIGKILL aside), before termios is restored. Replaces the previous string; "" clears it. 0, -25 when stdout is not a terminal, -7 (E2BIG) past NISH_TERM_RESTORE_MAX bytes. The cap is 4096 bytes. */
+declare function setTerminalRestore(bytes: string): i32;
+
 // ---- `Date` and `crypto` (WP34 N3) -----------------------------------------------
 //
 // `lib.es2022` already declares `Date`, whose `now()` is Nish's one member of it,
@@ -481,7 +510,7 @@ declare module "nish:net" {
   /** Shut the read side (0), the write side (1) or both (2). */
   export function netShutdown(fd: i32, how: i32): i32;
   export function netClose(fd: i32): i32;
-  /** A TCP socket connecting to `addr`, answered while it connects: writable once it has, or has failed. */
+  /** A TCP socket connecting to `addr`, answered while it connects: writable once it has, or has failed. It holds `TCP_NODELAY`, so a small write is sent at once. */
   export function tcpConnect(addr: readonly u8[]): i32;
   /** Once `fd` is writable: 0 when the connection is made, else its failure (-111 refused). */
   export function connectResult(fd: i32): i32;
@@ -535,6 +564,21 @@ declare module "nish:io" {
   export function panic(message: string): never;
 }
 
+declare module "nish:term" {
+  /** Up to `len` bytes of stdin into `buf` from `off`, never blocking: the count, 0 at end of stream, or -11 when nothing is waiting. */
+  export function readStdin(buf: u8[], off: i32, len: i32): i32;
+  /** Wait up to `timeoutMs` (negative: forever) for stdin to be readable (its end and an error count): `true` when it is, `false` when the time passed. */
+  export function waitStdin(timeoutMs: i32): boolean;
+  /** Whether descriptor `fd` is a terminal (`isatty`). */
+  export function isTerminal(fd: i32): boolean;
+  /** `[columns, rows]` of the terminal on stdout, else stderr; `[-25, 0]` when neither is one, `[0, 0]` when it has no size set. */
+  export function terminalSize(): i32[];
+  /** Raw mode on stdin's terminal (0), or the mode it had back; -25 when stdin is not a terminal. Restored at exit, on a panic and on every signal that ends the program, SIGKILL aside. */
+  export function setRawMode(on: boolean): i32;
+  /** Bytes the runtime writes to the terminal on stdout at exit, on a panic and on every signal that ends the program (SIGKILL aside), before termios is restored. Replaces the previous string; "" clears it. 0, -25 when stdout is not a terminal, -7 (E2BIG) past NISH_TERM_RESTORE_MAX bytes. */
+  export function setTerminalRestore(bytes: string): i32;
+}
+
 // `nish:secret` has source behind it, `std/secret.ts`, but a program imports it
 // by this name, so `tsc` reads these declarations rather than that file. The
 // class is declared with a private constructor and a private field: `tsc` then

package/runtime/nish.h

@@ -9,7 +9,8 @@
  * functions, the directory and subprocess calls, `nish_getenv`, the monotonic
  * clock, `nish_platform` / `nish_arch` — and runtime-parallel.c, runtime-host.c,
  * runtime-net.c, runtime-simd.c (the byte searches that read a vector at a
- * time) and runtime-aes.c (AES-GCM on the CPU's AES instructions) split off
+ * time), runtime-aes.c (AES-GCM on the CPU's AES instructions) and
+ * runtime-term.c (stdin and the terminal, `nish:term`) split off
  * the same way since. They are separate so that each carries its own measured
  * code-size ceiling (docs/wp7-runtime.md, "Runtime additions and budget"); a
  * host links all of them, which `scripts/build.sh` does for you when handed
@@ -154,6 +155,22 @@ int64_t nish_str_index_of_from(const nish_str *s, const nish_str *sub, int64_t f
    set outside 1..16 bytes is answered by the scalar path rather than refused,
    but only 1..16 is the contract. Variable-time: never call it on a secret. */
 int64_t nish_str_index_of_any(const nish_str *s, const nish_str *set, int64_t from);
+/* WP38 S6a, the byte-class runs of `nish/bytes`: the first index i in
+   [from, to) whose byte p[i] is outside the class, or `to`. `p` is an array's
+   data and the caller has clamped 0 <= from <= to <= its length, so no byte at
+   or past `to` is read. `skip_blank` steps over JSON's four blanks (space, tab,
+   newline, carriage return) and `skip_digits` over 0-9. `skip_json_text` steps
+   over printable ASCII other than `"` and `\`, and over every well-formed
+   UTF-8 sequence (RFC 3629) that ends at or before `to`; a malformed or cut-off
+   sequence stops the run at its lead byte. `skip_json_plain` steps over every
+   byte from 0x20 up other than `"` and `\` -- what a JSON writer copies without
+   an escape -- with no UTF-8 check. They live in runtime/runtime-bytes.c and
+   choose their path as `nish_str_index_of_any` does. Variable-time: never call
+   them on a secret. */
+int64_t nish_bytes_skip_blank(const uint8_t *p, int64_t from, int64_t to);
+int64_t nish_bytes_skip_digits(const uint8_t *p, int64_t from, int64_t to);
+int64_t nish_bytes_skip_json_text(const uint8_t *p, int64_t from, int64_t to);
+int64_t nish_bytes_skip_json_plain(const uint8_t *p, int64_t from, int64_t to);
 /* `console.log(s)`: one write(2) of the bytes plus a newline to stdout. */
 void nish_print(const nish_str *s);
 /* `console.error` and the newline-free `write` / `writeError`: fd 1 or 2. */
@@ -170,6 +187,13 @@ void nish_panic_claim(void);
 #else
 #define nish_panic_claim() ((void)0)
 #endif
+/* How a panic that skips atexit ends: `_exit(1)`, after `nish_fatal_hook`
+   when it is set (runtime.c). The hook is the terminal's restore while
+   `setRawMode(true)` holds or `setTerminalRestore` bytes wait
+   (runtime-term.c), and null otherwise. Under `-DNISH_FUZZ_ABORT`
+   (scripts/fuzz.sh) it and `nish_panic` call `abort()`. */
+__attribute__((noreturn)) void nish_fatal_exit(void);
+extern void (*nish_fatal_hook)(void);
 /* Number to string, as `${n}` does: decimal for integers, shortest round-trip (JS Number#toString) for f64. */
 nish_str *nish_str_from_i32(int32_t v);
 nish_str *nish_str_from_f64(double v);
@@ -244,11 +268,28 @@ typedef struct nish_array { uint64_t len; uint64_t cap; char *data; } nish_array
  * `elem_size` is `sizeof` one element, so for a record element type it is
  * `sizeof(struct Point)` and the block is a C array of them. */
 nish_array *nish_alloc_array(uint64_t elem_size, uint64_t len);
+/* `nish/regex`'s match-start search: the first i >= from with i + depth <=
+   len where every s[i + j], j < depth, is in position j's byte set, or -1.
+   Position j's set is written twice: as the 32 bytes of masks from 32 * j,
+   where byte b is in it when bit (b >> 4) & 7 of byte (b & 15) | (b >> 7) << 4
+   is set, and as the 256 bytes from 32 * depth + 256 * j, where it is in it
+   when byte b of them is not 0; the two must agree. The vector paths look for
+   the width positions from off first, in the first form, and test the others
+   in the second; the answer does not depend on them. from is already in
+   [0, len], depth is 1..8, width is 1..4, off + width <= depth and masks
+   holds at least 288 * depth bytes. It lives
+   in runtime/runtime-simd.c and picks its path as nish_str_index_of_any does.
+   Variable-time: never call it on a secret. */
+int64_t nish_regex_scan(const nish_str *s, const nish_array *masks, int64_t depth, int64_t off, int64_t width,
+                        int64_t from);
 /* No array grows past 2^31 - 1 elements and no string past 2^31 - 1 bytes:
  * `nish_array_grow`, `nish_alloc_array` and `nish_str_concat` fail as an
  * allocation does (`nish: out of memory`, exit 1; a trap on wasm) rather than
  * make one, because under --number-mode i32 its `length` would read back
- * negative (docs/security/codegen.md K1-6, docs/security/runtime.md RT-2). */
+ * negative (docs/security/codegen.md K1-6, docs/security/runtime.md RT-2).
+ * A host that hands an array in keeps the same bound: the N-API shim refuses a
+ * longer typed array, and a C host must not pass a `len` past it
+ * (docs/security/bytes.md, BYTES-1). */
 /* The cold paths compiled code calls: `push` when len == cap, a failed bounds
  * check. `nish_array_grow` moves `cap * elem_size` bytes into a fresh arena
  * block and writes `data`/`cap`, so for a record element type it relocates the
@@ -315,6 +356,13 @@ void nish_panic_slice(int64_t start, int64_t end, int64_t len);
 extern nish_array *nish_argv;
 void nish_argv_init(int32_t argc, char **argv);
 
+/* The 128-bit SipHash-1-3 key of every `Map` and `Set` string hash
+ * (docs/security/json.md, JSON-13). A constructor the compiled module
+ * registers fills it from `getentropy` before `main`, once per process, and
+ * sets bit 0 of word 0 so a filled key is never all zero; nothing writes it
+ * afterwards. A host must not change it while any table exists. */
+extern uint64_t nish_hash_key[2];
+
 /* ---- Directories and subprocesses (WP14 D4) -----------------------------
  * The calls a self-hosted driver needs to find its inputs and link its own
  * output. Every one of them answers a value instead of exiting, exactly as
@@ -541,6 +589,31 @@ int32_t nish_poll_modify(int32_t loop, int32_t fd, int32_t events, int32_t token
 int32_t nish_poll_remove(int32_t loop, int32_t fd);
 int32_t nish_poll_wait(int32_t loop, nish_array *ready, int32_t timeout_ms);
 
+/* ---- The terminal, runtime/runtime-term.c, `nish:term` -------------------
+ *
+ * `nish_read_stdin(buf, off, len)`: at most `len` bytes of stdin into `buf`
+ * from `off`, without blocking: the count, 0 at the end of the stream, -11
+ * when nothing is waiting, or another `-errno`. `nish_wait_stdin(timeout_ms)`:
+ * whether stdin became readable before `timeout_ms` passed (negative waits
+ * for ever). `nish_is_terminal(fd)`: `isatty`. `nish_terminal_size()`: a fresh
+ * `i32[]` of `[columns, rows]`, or `[-errno, 0]`, -25 for "not a terminal".
+ * `nish_set_raw_mode(on)`: 0, -25 when stdin is not a terminal, or `-errno`;
+ * the saved termios comes back on `false`, at exit, on a panic and on every
+ * signal left at its default that ends the program, SIGKILL aside (the list is
+ * runtime-term.c's). -11 and -25 are those
+ * numbers on WASI too, where the three TTY calls answer "not a terminal".
+ * `nish_set_terminal_restore(bytes)`: keeps up to `NISH_TERM_RESTORE_MAX`
+ * bytes to write to stdout, once, at exit, on a panic and on each of those
+ * signals, before the termios comes back; "" keeps none. 0, -7 past the cap,
+ * -25 when stdout is not a terminal (always, for bytes, on WASI). */
+#define NISH_TERM_RESTORE_MAX 4096
+int32_t nish_read_stdin(nish_array *buf, int64_t off, int64_t len);
+bool nish_wait_stdin(int32_t timeout_ms);
+bool nish_is_terminal(int32_t fd);
+nish_array *nish_terminal_size(void);
+int32_t nish_set_raw_mode(bool on);
+int32_t nish_set_terminal_restore(const nish_str *bytes);
+
 /* String to number (WP7), ASCII whitespace only. mode 0 is `parseFloat`
  * (longest JS decimal literal or `Infinity`, else NaN), mode 1 is `Number`
  * (the whole string, trimmed; blank is 0; `0x` hex accepted, as in JS),

package/runtime/nish.mjs

@@ -52,7 +52,10 @@
  *
  * Everything here delegates to `runtime/shim.mjs`, the module the differential
  * harness already uses, so the two cannot drift apart: a semantic fixed there
- * is fixed here in the same commit.
+ * is fixed here in the same commit. The shim is itself two layers: the
+ * host-agnostic core (`runtime/core.mjs`) and the Node host
+ * (`runtime/node.mjs`) it installs, so this module adds only what is Node's to
+ * add — the globals, the module hooks and `process.argv`.
  */
 import { registerHooks } from "node:module";
 import * as shim from "./shim.mjs";
@@ -131,6 +134,17 @@ for (const name of [
   provide(name, () => shim.noNetReading(name));
 }
 
+// `nish:term`. Whether a descriptor is a terminal and how big stdout's is have
+// Node's answers; reading stdin, waiting for it and raw mode throw, each naming
+// itself, for the net functions' reason, and restore bytes throw for their own
+// (core/host.mjs).
+provide("isTerminal", shim.isTerminal);
+provide("terminalSize", shim.terminalSize);
+for (const name of ["readStdin", "waitStdin", "setRawMode"]) {
+  provide(name, () => shim.noTermReading(name));
+}
+provide("setTerminalRestore", shim.setTerminalRestore);
+
 // `crypto.getRandomValues(bytes)` (WP34 N3). Node has the global, but it
 // takes only a typed array and a `u8[]` is a plain `Array` here, so the one
 // method is replaced on Node's own `crypto` object by one that fills a plain
@@ -179,6 +193,7 @@ provide("toU32", (x) => shim.convert(x, "f64", "u32"));
 provide("toU64", (x) => shim.convert(x, "f64", "u64"));
 provide("f64ToBits", shim.f64ToBits);
 provide("bitsToF64", shim.bitsToF64);
+provide("f32ToBits", shim.f32ToBits);
 
 // Constant time (WP34 N6). Pure functions of their operands, so the answers
 // agree with a native run; the timing does not, and is not claimed here.
@@ -274,11 +289,13 @@ provide("arena", shim.arena);
 // `nish:secret` is answered here as well, because the standard library imports
 // it (`std/crypto/p256.ts` and its neighbours): its names are
 // `runtime/shim.mjs`'s, where a `Secret` is a plain wrapper and `wipe`
-// zero-fills it. `nish:unsafe` is answered by a module that hands back the
-// globals installed above: its functions are globals of this module either
+// zero-fills it. `nish:unsafe` and `nish:term` are each answered by a module
+// that hands back the globals installed above: its functions are globals of this module either
 // way, and the import is what the compiler requires a program to write.
 const UNSAFE_EXPORTS = ["uncheckedGet", "uncheckedSet", "wrappingAdd", "wrappingSub", "wrappingMul"];
 const unsafeSource = UNSAFE_EXPORTS.map((name) => `export const ${name} = globalThis.${name};`).join("\n");
+const TERM_EXPORTS = ["readStdin", "waitStdin", "isTerminal", "terminalSize", "setRawMode", "setTerminalRestore"];
+const termSource = TERM_EXPORTS.map((name) => `export const ${name} = globalThis.${name};`).join("\n");
 registerHooks({
   resolve: (specifier, context, next) => {
     if (specifier === "nish:secret") {
@@ -287,6 +304,9 @@ registerHooks({
     if (specifier === "nish:unsafe") {
       return { url: `data:text/javascript,${encodeURIComponent(unsafeSource)}`, shortCircuit: true };
     }
+    if (specifier === "nish:term") {
+      return { url: `data:text/javascript,${encodeURIComponent(termSource)}`, shortCircuit: true };
+    }
     return specifier.startsWith("nish/")
       ? next(new URL(`../std/${specifier.slice("nish/".length)}.ts`, import.meta.url).href, context)
       : next(specifier, context);