@mason-data/cli 0.8.0 → 0.10.0

package/dist/src/lib/cidr.js

@@ -0,0 +1,177 @@
+/**
+ * ADDRESSES AND ADDRESS RANGES, READ BY ONE GRAMMAR: `MASON_PG_PROXY_FROM` (src/api/postgres/proxy.ts) and a `mason
+ * user`'s address ranges (src/duck/users.ts `from`) both read an entry here. An entry is an IPv4 or IPv6 address, alone
+ * (one address: /32 or /128) or with its prefix length, held to its family (`10.0.0.0/33` and `999.999.999.999/99` are
+ * refused), with no bits set past the prefix (`10.0.1.5/24` is refused with its network as the guess), and no host name
+ * (never looked up) nor zone index. An address is first held to `node:net`'s own reading (`isIPv4`, `isIPv6`), then
+ * read into its bytes here, so nothing either reading refuses is ever taken.
+ *
+ * EVERY ADDRESS IN ONE SPACE, as Mason means one: IPv6's 128 bits, an IPv4 address at its v4-mapped place
+ * (::ffff:a.b.c.d), since a v4-mapped peer or header source IS that IPv4 client (`shownAddress`). What an entry names and
+ * what a list covers are both read here, never from how an entry is spelt: `0.0.0.0/1,128.0.0.0/1` is every IPv4
+ * address, as `0.0.0.0/0` is, and `::/64` holds every v4-mapped address, so every IPv4 one too.
+ */
+import * as net from "node:net";
+/** An address as Mason shows it: IPv4 dotted, IPv6 in RFC 5952's form, a v4-mapped IPv6 one as IPv4; null when it is no
+ *  address (undefined, a zone index, a name). */
+export function shownAddress(text) {
+    if (text === undefined)
+        return null;
+    const v4 = ipv4Bytes(text);
+    if (v4 !== null)
+        return Array.from(v4).join(".");
+    const v6 = ipv6Bytes(text);
+    return v6 === null ? null : ipv6Text(v6);
+}
+/** An IPv4 address's 4 bytes, from dotted decimal with no leading zero; null for anything else. */
+function ipv4Bytes(text) {
+    if (!net.isIPv4(text))
+        return null;
+    const parts = text.split(".");
+    if (parts.length !== 4 || !parts.every((p) => /^(?:0|[1-9]\d{0,2})$/.test(p) && Number(p) <= 255))
+        return null;
+    return Uint8Array.from(parts.map(Number));
+}
+/** An IPv6 address's 16 bytes (`::` once at most, an IPv4 tail); null for anything else, a zone index included. */
+export function ipv6Bytes(text) {
+    // node:net takes a zone index (fe80::1%eth0): an address with one names no place here
+    if (!/^[0-9A-Fa-f:.]+$/.test(text) || !net.isIPv6(text))
+        return null;
+    const halves = text.split("::");
+    if (halves.length > 2 || (halves.length === 2 && halves[0].includes(".")))
+        return null;
+    const groups = (s) => {
+        if (s === "")
+            return [];
+        const out = [];
+        const parts = s.split(":");
+        for (const [i, p] of parts.entries()) {
+            if (i === parts.length - 1 && p.includes(".")) {
+                const v4 = ipv4Bytes(p);
+                if (v4 === null)
+                    return null;
+                out.push((v4[0] << 8) | v4[1], (v4[2] << 8) | v4[3]);
+            }
+            else if (/^[0-9A-Fa-f]{1,4}$/.test(p))
+                out.push(parseInt(p, 16));
+            else
+                return null;
+        }
+        return out;
+    };
+    const head = groups(halves[0]), tail = halves.length === 2 ? groups(halves[1]) : [];
+    if (head === null || tail === null)
+        return null;
+    const n = head.length + tail.length;
+    if (halves.length === 1 ? n !== 8 : n > 7)
+        return null;
+    const all = [...head, ...new Array(8 - n).fill(0), ...tail];
+    return Uint8Array.from(all.flatMap((g) => [g >> 8, g & 0xff]));
+}
+/** whether 16 bytes are an IPv4 address mapped into IPv6 (::ffff:a.b.c.d) */
+const v4Mapped = (b) => b.subarray(0, 10).every((x) => x === 0) && b[10] === 0xff && b[11] === 0xff;
+/** 16 bytes as Mason shows an IPv6 address: RFC 5952 (lower case, the longest run of two or more zero groups as `::`,
+ *  the first of equal runs), and a v4-mapped one as its IPv4 address. */
+export function ipv6Text(b) {
+    if (v4Mapped(b))
+        return Array.from(b.subarray(12, 16)).join(".");
+    const g = Array.from({ length: 8 }, (_, i) => (b[2 * i] << 8) | b[2 * i + 1]);
+    let at = -1, run = 0;
+    for (let i = 0; i < 8;) {
+        if (g[i] !== 0) {
+            i++;
+            continue;
+        }
+        let j = i;
+        while (j < 8 && g[j] === 0)
+            j++;
+        if (j - i > run) {
+            at = i;
+            run = j - i;
+        }
+        i = j;
+    }
+    const hex = g.map((x) => x.toString(16));
+    return run < 2 ? hex.join(":") : `${hex.slice(0, at).join(":")}::${hex.slice(at + run).join(":")}`;
+}
+export const V4_START = 0xffffn << 32n;
+export const V4_END = V4_START + (1n << 32n) - 1n;
+export const ALL_END = (1n << 128n) - 1n;
+const bigOf = (b) => b.reduce((n, x) => (n << 8n) | BigInt(x), 0n);
+/** an address's place (`V4_START`), or null when it is no address */
+function placeOf(address) {
+    const v4 = ipv4Bytes(address);
+    if (v4 !== null)
+        return V4_START | bigOf(v4);
+    const v6 = ipv6Bytes(address);
+    return v6 === null ? null : bigOf(v6);
+}
+/** the places an entry names */
+export function rangeOf(c) {
+    const start = c.family === 4 ? V4_START | bigOf(c.bytes) : bigOf(c.bytes);
+    return { start, end: start + (1n << BigInt((c.family === 4 ? 32 : 128) - c.prefix)) - 1n };
+}
+/** Whether `address` (as `shownAddress` shows one, or in any spelling of the same address) is in one of `ranges`; never
+ *  for what is no address. */
+export function inRanges(ranges, address) {
+    const at = placeOf(address);
+    return at !== null && ranges.some((r) => r.start <= at && at <= r.end);
+}
+/** whether `ranges` together hold every place from `lo` to `hi` */
+export function covers(ranges, lo, hi) {
+    let next = lo;
+    for (const r of [...ranges].sort((a, b) => (a.start < b.start ? -1 : a.start > b.start ? 1 : 0))) {
+        if (r.start > next)
+            return false;
+        if (r.end >= next)
+            next = r.end + 1n;
+        if (next > hi)
+            return true;
+    }
+    return next > hi;
+}
+function prefixEqual(a, b, bits) {
+    for (let i = 0; i * 8 < bits; i++) {
+        const mask = bits - i * 8 >= 8 ? 0xff : (0xff << (8 - (bits - i * 8))) & 0xff;
+        if ((a[i] & mask) !== (b[i] & mask))
+            return false;
+    }
+    return true;
+}
+/** the network `bytes` / `prefix` names, its host bits cleared */
+function network(bytes, prefix) {
+    return bytes.map((x, i) => i * 8 >= prefix ? 0 : prefix - i * 8 >= 8 ? x : x & ((0xff << (8 - (prefix - i * 8))) & 0xff));
+}
+const text = (family, bytes) => family === 4 ? Array.from(bytes).join(".") : ipv6Text(bytes);
+/** An entry as Mason writes it back: the network in `shownAddress`'s form, its prefix only when it is not one address. */
+export const cidrText = (c) => `${text(c.family, c.bytes)}${c.prefix === (c.family === 4 ? 32 : 128) ? "" : `/${c.prefix}`}`;
+/**
+ * One entry read, or what is wrong with it, with a did-you-mean where one is a fair guess: a guess is offered only
+ * once it is read as an entry itself, so it is never one that would be refused in turn. `everyRefused`: a prefix of 0
+ * (every address of a family) is refused with these words (a PROXY header believed from anyone); else it is taken.
+ */
+export function cidrOf(entry, everyRefused = null) {
+    const quoted = JSON.stringify(entry);
+    const m = /^([^/]*)(?:\/(\d{1,3}))?$/.exec(entry);
+    const v4 = m === null ? null : ipv4Bytes(m[1]), v6 = m === null || v4 !== null ? null : ipv6Bytes(m[1]);
+    if (m === null || (v4 === null && v6 === null)) {
+        return { problem: `${quoted} is not an address or a CIDR (10.0.0.0/16, 2001:db8::/32, or one address such as 10.0.4.7; a host name is not looked up)` };
+    }
+    const family = v4 !== null ? 4 : 6, bytes = (v4 ?? v6), max = family === 4 ? 32 : 128;
+    const prefix = m[2] === undefined ? max : Number(m[2]);
+    if (prefix > max)
+        return { problem: `${quoted}: an IPv${family} prefix is at most /${max}` };
+    if (family === 6 && v4Mapped(bytes) && prefix >= 96) {
+        const p4 = prefix - 96, net4 = network(bytes.subarray(12, 16), p4);
+        const meant = `${text(4, net4)}${p4 === 32 ? "" : `/${p4}`}`, read = cidrOf(meant, everyRefused);
+        return { problem: "problem" in read
+                ? `${quoted} is IPv4 written as IPv6, which Mason reads as ${meant}, and ${read.problem}`
+                : `${quoted} is IPv4 written as IPv6, which Mason reads as IPv4: did you mean ${meant}?` };
+    }
+    if (prefix === 0 && everyRefused !== null)
+        return { problem: `${quoted} names every address, ${everyRefused}` };
+    const net = network(bytes, prefix);
+    if (!prefixEqual(net, bytes, max))
+        return { problem: `${quoted} has bits set past its prefix: did you mean ${text(family, net)}/${prefix}?` };
+    return { family, bytes: net, prefix };
+}

package/dist/src/lib/database-url.js

@@ -11,9 +11,57 @@
  *
  * Pure; dependency-free.
  */
-const SSLMODES = new Set(["disable", "allow", "prefer", "require", "verify-ca", "verify-full"]);
-const KNOWN_PARAMS = new Set(["sslmode", "application_name"]);
-/** Parse a `postgres://` / `postgresql://` URL. Throws on anything it cannot represent faithfully. */
+export const SSLMODES = new Set(["disable", "allow", "prefer", "require", "verify-ca", "verify-full"]);
+/** The query parameters a URL may carry: the only ones read, and so the only ones a URL is shown with (src/cli/preflight.ts shownUrl). */
+export const KNOWN_PARAMS = new Set(["sslmode", "application_name"]);
+/** application_name's value as a URL may give it: what is shown of it, so it can hold nothing else (a `password=…`). */
+const APPLICATION_NAME = /^[A-Za-z0-9._-]{1,64}$/;
+/**
+ * The parameters a refusal may NAME: libpq's documented connection keywords and a few drivers' own (Prisma's, node-postgres's),
+ * a fixed list, so a key said is Mason's word, never an arbitrary part of the value (issue 541).
+ */
+const NAMED_PARAMS = new Set([
+    "host", "hostaddr", "port", "dbname", "user", "password", "passfile", "require_auth", "channel_binding", "connect_timeout",
+    "client_encoding", "options", "fallback_application_name", "keepalives", "keepalives_idle", "keepalives_interval",
+    "keepalives_count", "tcp_user_timeout", "replication", "gssencmode", "requiressl", "sslnegotiation", "sslcompression",
+    "sslcert", "sslkey", "sslpassword", "sslcertmode", "sslrootcert", "sslcrl", "sslcrldir", "sslsni", "requirepeer",
+    "ssl_min_protocol_version", "ssl_max_protocol_version", "min_protocol_version", "max_protocol_version", "krbsrvname",
+    "gsslib", "gssdelegation", "service", "target_session_attrs", "load_balance_hosts", "scram_client_key",
+    "scram_server_key", "oauth_issuer", "oauth_client_id", "oauth_client_secret", "oauth_scope",
+    "pgbouncer", "schema", "connection_limit", "pool_timeout", "socket_timeout", "statement_cache_size", "ssl", "sslaccept",
+]);
+/** The parameters that carry a password: where the URL puts it instead is said. */
+const PASSWORD_PARAMS = new Set(["password", "sslpassword"]);
+/**
+ * THE ONE READING OF A URL'S QUERY (issue 541): null when every parameter is one the URL is read with, given once, its
+ * value one the reading accepts — `sslmode` one of SSLMODES, `application_name` letters, digits, `.`, `_` and `-` (at
+ * most 64) — else what is wrong, in words that NAME a parameter only from Mason's own lists and never repeat a value.
+ * `parseDatabaseUrl` refuses by it, and `shownUrl` shows a URL only when it is null, so no part shown is one not read.
+ */
+export function queryProblem(params) {
+    const keys = [...params.keys()];
+    const unread = keys.filter((k) => !KNOWN_PARAMS.has(k));
+    if (unread.length) {
+        const named = [...new Set(unread.map((k) => k.toLowerCase()).filter((k) => NAMED_PARAMS.has(k)))];
+        const others = unread.some((k) => !NAMED_PARAMS.has(k.toLowerCase()));
+        const what = named.length === 0 ? "a parameter Mason does not read"
+            : `${named.length === 1 ? "the parameter" : "the parameters"} ${named.join(", ")}${others ? ", and another," : ","} which Mason does not read`;
+        const way = named.some((k) => PASSWORD_PARAMS.has(k)) ? "a password goes before the host, postgres://user:password@host:5432/your_app"
+            : "leave it out of the URL";
+        return `it has ${what} (it reads ${[...KNOWN_PARAMS].join(" and ")} alone): ${way}`;
+    }
+    for (const k of KNOWN_PARAMS)
+        if (params.getAll(k).length > 1)
+            return `it gives ${k} more than once: give it once`;
+    const sslmode = params.get("sslmode");
+    if (sslmode !== null && !SSLMODES.has(sslmode))
+        return `its sslmode is not one of ${[...SSLMODES].join(", ")}`;
+    const name = params.get("application_name");
+    if (name !== null && !APPLICATION_NAME.test(name))
+        return "its application_name is not letters, digits, . _ and - (at most 64): give it in those, or leave it out";
+    return null;
+}
+/** Parse a `postgres://` / `postgresql://` URL. Throws on anything it cannot represent faithfully, never repeating a part of it. */
 export function parseDatabaseUrl(url) {
     let u;
     try {
@@ -23,15 +71,12 @@ export function parseDatabaseUrl(url) {
         throw new Error("DATABASE_URL is not a URL (expected postgres://user:password@host:port/database)");
     }
     if (u.protocol !== "postgres:" && u.protocol !== "postgresql:") {
-        throw new Error(`DATABASE_URL: scheme ${u.protocol.replace(/:$/, "")} is not postgres or postgresql`);
-    }
-    for (const key of u.searchParams.keys()) {
-        if (!KNOWN_PARAMS.has(key))
-            throw new Error(`DATABASE_URL: parameter ${key} is not supported (only ${[...KNOWN_PARAMS].join(", ")})`);
+        throw new Error("DATABASE_URL: its scheme is not postgres or postgresql");
     }
+    const query = queryProblem(u.searchParams);
+    if (query !== null)
+        throw new Error(`DATABASE_URL: ${query}`);
     const sslmode = u.searchParams.get("sslmode") ?? "prefer";
-    if (!SSLMODES.has(sslmode))
-        throw new Error(`DATABASE_URL: sslmode=${sslmode} is not one of ${[...SSLMODES].join(", ")}`);
     const database = decodeURIComponent(u.pathname.replace(/^\//, ""));
     if (!u.hostname)
         throw new Error("DATABASE_URL has no host");

package/dist/src/lib/instant.js

@@ -0,0 +1,50 @@
+/**
+ * THE SESSION'S INSTANT IS MICROSECONDS (GitHub issues 372, 363): Postgres's transaction start is gettimeofday's
+ * microseconds, so `now()`, the clock keywords and a relative word (`'now'`) carry six fraction digits, and a prepared
+ * statement's `'now'` and its run's `now()` differ whenever their transactions do, even inside one millisecond. A
+ * JavaScript millisecond made them equal there (the flaky oracle of issue 372). So the instant is an integer count of
+ * microseconds since the Unix epoch (exact below 2^53, until the year 2255), read from ONE clock (`nowMicros`), written
+ * for DuckDB by ONE formatter (`instantText`), and handed to the catalog's PGlite as the wall clock that reads back as
+ * exactly that microsecond (`instantWallMs`).
+ */
+/** where the monotonic clock stood at the last re-anchoring, and the microsecond it was read as */
+let anchor = null;
+/**
+ * The wall clock in microseconds since the epoch. `wall` (Date.now) decides the millisecond, so the reading never
+ * drifts from the clock an operator sets; the monotonic clock (`performance.now()`) only fills the microseconds inside
+ * it. The reading is clamped into that millisecond and re-anchored there when the monotonic clock has parted from it
+ * (`performance.timeOrigin + performance.now()` alone drifts from the wall clock over a long uptime), so it is
+ * non-decreasing while the wall clock is. `wall`: the worker that replaces `Date.now` passes the real one.
+ */
+export function nowMicros(wall = Date.now) {
+    const ms = wall();
+    const mono = performance.now();
+    const lo = ms * 1000, hi = lo + 999;
+    anchor ??= { us: Math.floor((performance.timeOrigin + mono) * 1000), mono };
+    let us = anchor.us + Math.floor((mono - anchor.mono) * 1000);
+    if (us < lo || us > hi) {
+        us = us < lo ? lo : hi;
+        anchor = { us, mono };
+    }
+    return us;
+}
+const integral = (us) => {
+    if (!Number.isSafeInteger(us))
+        throw new Error(`an instant is a whole number of microseconds, not ${us}`);
+    return us;
+};
+/** An instant as the text DuckDB binds as a TIMESTAMPTZ: ISO 8601 in UTC with six fraction digits,
+ *  `2026-01-02T20:00:00.123456Z` (Date's own text stops at the millisecond). */
+export function instantText(us) {
+    const ms = Math.floor(integral(us) / 1000);
+    return `${new Date(ms).toISOString().slice(0, -1)}${String(us - ms * 1000).padStart(3, "0")}Z`;
+}
+/**
+ * The `Date.now()` value PGlite reads back as exactly the microsecond `us`. Emscripten's `clock_time_get` takes
+ * `Math.round(Date.now() * 1e3 * 1e3)` nanoseconds, a product past 2^53 and so off by up to ~256 ns, and musl's
+ * gettimeofday truncates that to microseconds: `us / 1000` lands one microsecond low about half the time. The
+ * half-microsecond point lands inside `us` whatever that rounding does (tests/postgres-api/catalog.test.ts).
+ */
+export function instantWallMs(us) {
+    return (integral(us) + 0.5) / 1000;
+}

package/dist/src/lib/log-buffer.js

@@ -9,8 +9,10 @@
  *
  * `LogBuffer` is fed by the one place the run writes its log (src/cli/dev.ts `logLine`: mason.log under `mason start`,
  * stdout under `mason serve`), so both modes have it; the command server serves it (`GET /api/logs`). `mason logs` reads
- * the FILE with `logEntries`, the same parser, so a line is the same `{ at, text }` from either.
+ * the FILE with `logEntries`, the same parser, so a line is the same `{ at, text }` from either. Both are masked by one
+ * mask (`PasswordLineMask`): the file as it is read (src/lib/log-read.ts), the buffer as an entry is kept.
  */
+import { PasswordLineMask } from "./secret-mask.js";
 /**
  * How many entries the run keeps: a startup and a copy of a hundred tables log a few thousand lines, and an agent asking
  * "what just happened" wants the last minutes, not the file (which `mason logs` reads whole). 2000 entries at a few hundred
@@ -25,10 +27,15 @@ const HEAD = /^(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?Z) /;
  * be an empty entry counted by `-n`.
  */
 export function logEntries(text, o = {}) {
-    const out = [];
     const lines = text.split("\n");
     if (lines[lines.length - 1] === "")
         lines.pop(); // the file's last newline ends its last line, it does not start another
+    return entriesOfLines(lines, o);
+}
+/** Lines (no newline), as `logEntries` reads a text's: what `mason logs` hands it from the reader (src/lib/log-read.ts
+ *  `readLines`), so a long line is never joined to the next and split again. */
+export function entriesOfLines(lines, o = {}) {
+    const out = [];
     for (const line of lines) {
         if (line.trim() === "") {
             if (o.perLine)
@@ -52,9 +59,11 @@ export class LogBuffer {
     capacity;
     kept = [];
     constructor(capacity = LOG_KEPT) { this.capacity = capacity; }
-    /** An entry as `textEntry` wrote it (one head line, the rest indented): kept as ONE entry. */
+    /** An entry as `textEntry` wrote it (one head line, the rest indented): kept as ONE entry, each of its lines masked
+     *  as a log file's are read (src/lib/log-read.ts, issue 621), so `/api/logs` shows a line as `mason logs` does. */
     push(entry) {
-        for (const l of logEntries(entry)) {
+        const mask = new PasswordLineMask();
+        for (const l of logEntries(entry.split("\n").map((line) => mask.line(line)).join("\n"))) {
             this.kept.push(l);
             if (this.kept.length > this.capacity)
                 this.kept.shift();

package/dist/src/lib/log-read.js

@@ -0,0 +1,196 @@
+/**
+ * THE RUN'S LOG FILES, AND THEIR ONE READER (issue 621: `mason logs` showed lines an older Mason wrote with the source's
+ * password in a `password=` value, because it read the file as it was).
+ *
+ * `.mason/mason.log` (the run's log) and `.mason/dev.log` (the run's terminal, `mason start`'s) are named here alone, and
+ * every reader of either reads it through `LogReader`, which masks each line as it is read (`PasswordLineMask`,
+ * src/lib/secret-mask.ts): `mason logs` (whole, `--start`, `-f`), `mason start`'s own watch of the run's terminal and the
+ * supervisor's scan of it after a run exits (src/cli/background.ts, src/cli/supervise.ts). The run's memory of its log
+ * (src/lib/log-buffer.ts, `GET /api/logs`) is the same mask, applied as an entry is kept. So a line an older Mason wrote
+ * is shown masked wherever it is shown, and the file itself is never rewritten: a log a person or a collector already
+ * read cannot be unread (the release notes of 599 say to rotate the password and delete the old files).
+ *
+ * WHAT IS MASKED is #620's decision, kept: a libpq `password=` value, the one form the old string leaked, and never a
+ * substring of the password now, which a table's, a user's or a slot's name may hold (docs/DESIGN.md "How wide the mask
+ * is, and why").
+ *
+ * A LINE IS RELEASED ONLY WHOLE, AND READ ONCE MORE AT MOST. The reader reads the file in chunks (a log with every
+ * statement traced runs to hundreds of MB), and a chunk ends anywhere — inside a `password='…'`, inside a character's
+ * bytes. So it decodes and masks only the bytes up to a chunk's last newline, a line at a time, and keeps NOTHING of the
+ * line after it but where it starts in the file: when a later chunk ends that line, its bytes are read again from there,
+ * once, and decoded whole (the review of PR 641: a line held as text and joined to every chunk cost a line of L bytes
+ * L²/chunk, and twice the base's memory). A newline byte is never inside a UTF-8 character, so a line's bytes decode as
+ * the whole file's would. A value that runs on past its line is the mask's to carry (`PasswordLineMask`). What is read is
+ * the same however the file is cut; tests/log-read.test.ts holds it, and the reader's work to a count of the bytes it
+ * reads; tests/conventions.test.ts refuses a log file read in src/ any other way.
+ *
+ * A FOLLOW SHOWS THE LINE NOT ENDED YET (`follow`, `mason logs -f`): a run killed mid-write leaves its last words with
+ * no newline, so at the file's end the follow shows that line as it stands, masked, and then only what more of it adds.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { PasswordLineMask } from "./secret-mask.js";
+/** The run's log, in the project's `.mason/`: `mason logs`. */
+export const RUN_LOG = "mason.log";
+/** The run's terminal, in the project's `.mason/`: `mason logs --start`. */
+export const START_LOG = "dev.log";
+/** A log file's path in a project's `.mason/` folder: the run's log, or its terminal (`start`). */
+export function logPath(home, which) {
+    return path.join(home, which === "run" ? RUN_LOG : START_LOG);
+}
+/** How much of the file one read takes, at most. */
+const CHUNK = 1 << 20;
+/** A log file read from an offset on, its lines masked as they are read. */
+export class LogReader {
+    file;
+    /** the next byte a read takes */
+    at;
+    /** where the line not ended yet starts: the bytes from here to `at` are read, and not yet released */
+    lineStart;
+    chunk;
+    mask = new PasswordLineMask();
+    /** what `follow` has shown of the line not ended yet, masked */
+    shown = "";
+    /** the file was begun again under a line `follow` had shown part of: the next it shows starts a line */
+    broken = false;
+    /** the offset `follow` last showed the unended line at: unchanged, it is not read again */
+    peeked = -1;
+    readBytes = 0;
+    searchedBytes = 0;
+    /** `from`: the byte to start at (default the file's start); `chunk`: the most one read takes (a test's to set). */
+    constructor(file, o = {}) {
+        this.file = file;
+        this.at = o.from ?? 0;
+        this.lineStart = this.at;
+        this.chunk = o.chunk ?? CHUNK;
+    }
+    /** The bytes read so far: the file's offset the next read starts at. */
+    get offset() { return this.at; }
+    /** The reader's own work, for a test to hold linear: the bytes it read from the file (a line's again once it ends) and
+     *  those it searched for a newline, whatever the lines' lengths and the chunks. */
+    get work() { return { read: this.readBytes, searched: this.searchedBytes }; }
+    /**
+     * The lines the next chunk completes, each masked and ending in its newline ("" when the chunk completed none); null
+     * once the file has no byte more now. A file shorter than what was read was begun again (a new run's log): it is
+     * read from its start, nothing kept of the old.
+     */
+    read() {
+        const lines = this.next();
+        if (lines === null)
+            return null;
+        let out = "";
+        for (const l of lines)
+            out += `${l}\n`;
+        return out;
+    }
+    /** Every line completed from where the reader is to the file's end now, masked, each without its newline: `mason
+     *  logs`' (src/lib/log-buffer.ts `entriesOfLines`), so a line of hundreds of MB is never copied again to be split. */
+    readLines() {
+        const out = [];
+        for (let lines = this.next(); lines !== null; lines = this.next())
+            for (const l of lines)
+                out.push(l);
+        return out;
+    }
+    /** Every line completed from where the reader is to the file's end now, masked. */
+    readAll() {
+        let out = "";
+        for (let t = this.read(); t !== null; t = this.read())
+            out += t;
+        return out;
+    }
+    /** The last line, which no newline ended yet, masked: read once the reader is done with the file ("" when none). */
+    rest() {
+        const last = this.bytes(this.lineStart, this.at).toString("utf8");
+        this.lineStart = this.at;
+        return last === "" ? "" : this.mask.line(last);
+    }
+    /**
+     * WHAT A FOLLOW PRINTS NEXT (`mason logs -f`): every line written since, and then, the file's end reached, the line not
+     * ended yet as it stands, masked (the review of PR 641: a run killed mid-write leaves its last words unended, and a
+     * follow that waited for their newline never showed them). Printed one after another, the answers are the masked
+     * lines with the unended one's masked text so far; once more of it comes, only what its mask adds is printed, and
+     * should its mask read differently with more of it (never seen: a mask of a prefix is the whole mask's prefix), the
+     * line is shown again whole on a line of its own, never a byte unmasked. A character whose bytes are not all written
+     * yet waits for them.
+     */
+    follow() {
+        let out = "";
+        const ended = this.readAll();
+        if (this.broken) {
+            out += "\n";
+            this.broken = false;
+        }
+        if (ended !== "") {
+            out += this.after(ended);
+            this.shown = "";
+        }
+        if (this.at !== this.peeked) {
+            this.peeked = this.at;
+            const unended = new StringDecoder("utf8").write(this.bytes(this.lineStart, this.at));
+            const now = unended === "" ? "" : this.mask.peek(unended);
+            if (now !== this.shown) {
+                out += this.after(now);
+                this.shown = now;
+            }
+        }
+        return out;
+    }
+    /** `text` as it continues what `follow` has shown of the line: what it adds, or itself on a line of its own. */
+    after(text) {
+        if (this.shown === "")
+            return text;
+        return text.startsWith(this.shown) ? text.slice(this.shown.length) : `\n${text}`;
+    }
+    /** The lines the next chunk completes, masked, without their newlines; null once the file has no byte more now. */
+    next() {
+        const size = fs.statSync(this.file).size;
+        if (size < this.at) {
+            this.at = 0;
+            this.lineStart = 0;
+            this.mask = new PasswordLineMask();
+            if (this.shown !== "")
+                this.broken = true;
+            this.shown = "";
+            this.peeked = -1;
+        }
+        if (size === this.at)
+            return null;
+        const buf = this.bytes(this.at, Math.min(this.at + this.chunk, size));
+        if (buf.length === 0)
+            return null;
+        const from = this.at;
+        this.at += buf.length;
+        // the chunk alone is searched: of a line it does not end, nothing is kept but where it starts
+        this.searchedBytes += buf.length;
+        const last = buf.lastIndexOf(10);
+        if (last === -1)
+            return [];
+        const end = from + last + 1;
+        // the lines it ends, from the first one's start: read again from the file once when that start is in an earlier
+        // chunk, so a line is had whole without being held
+        const whole = this.lineStart === from ? buf.subarray(0, last + 1) : this.bytes(this.lineStart, end);
+        this.lineStart = end;
+        const lines = whole.toString("utf8").split("\n");
+        lines.pop(); // the last newline ends its line, it does not start another
+        return lines.map((l) => this.mask.line(l));
+    }
+    /** The file's bytes from `start` to `end` (fewer when it is shorter now), counted as read. */
+    bytes(start, end) {
+        if (end <= start)
+            return Buffer.alloc(0);
+        const buf = Buffer.alloc(end - start);
+        const fd = fs.openSync(this.file, "r");
+        let n = 0;
+        try {
+            for (let got = -1; n < buf.length && got !== 0; n += got)
+                got = fs.readSync(fd, buf, n, buf.length - n, start + n);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        this.readBytes += n;
+        return n === buf.length ? buf : buf.subarray(0, n);
+    }
+}