modelmux-cli 0.0.0-stage → 0.3.0

package/dist/prompt.js

@@ -0,0 +1,69 @@
+/**
+ * Questions on the terminal: a yes/no answer (Python's `input`) and a hidden
+ * secret (Python's `getpass`). Neither answer is stored or logged.
+ */
+import { createInterface } from "node:readline";
+import { Interrupted } from "./errors.js";
+/** Read one line from stdin (no echo control). Rejects at end of input. */
+function readLine(prompt, output) {
+    return new Promise((resolve, reject) => {
+        const rl = createInterface({ input: process.stdin, output, terminal: false });
+        let answered = false;
+        output.write(prompt);
+        rl.once("line", (line) => {
+            answered = true;
+            rl.close();
+            resolve(line);
+        });
+        rl.once("close", () => {
+            if (!answered)
+                reject(new Error("EOF when reading a line"));
+        });
+    });
+}
+/** Python's `input(question)`: the prompt goes to stdout. */
+export function ask(question) {
+    return readLine(question, process.stdout);
+}
+/** Python's `getpass.getpass(prompt)`: read a line without echoing it. */
+export function readSecret(prompt) {
+    const stdin = process.stdin;
+    if (!stdin.isTTY) {
+        process.stderr.write("Warning: Password input may be echoed.\n");
+        return readLine(prompt, process.stderr);
+    }
+    return new Promise((resolve, reject) => {
+        let value = "";
+        process.stderr.write(prompt);
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding("utf8");
+        const finish = (error) => {
+            stdin.removeListener("data", onData);
+            stdin.setRawMode(false);
+            stdin.pause();
+            process.stderr.write("\n");
+            if (error)
+                reject(error);
+            else
+                resolve(value);
+        };
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === "\r" || ch === "\n")
+                    return finish(null);
+                if (ch === "\x03")
+                    return finish(new Interrupted()); // Ctrl+C
+                if (ch === "\x04" && value === "")
+                    return finish(new Error("EOF when reading a line"));
+                if (ch === "\x7f" || ch === "\b")
+                    value = value.slice(0, -1);
+                else if (ch === "\x15")
+                    value = ""; // Ctrl+U
+                else if (ch >= " ")
+                    value += ch;
+            }
+        };
+        stdin.on("data", onData);
+    });
+}

package/dist/providers.js

@@ -0,0 +1,178 @@
+/**
+ * Provider definitions, loaded from the shared JSON files.
+ *
+ * The files are validated strictly here (no dependency needed); the test suite
+ * additionally validates them against `shared/schema/provider.schema.json`.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError, UsageError } from "./errors.js";
+import { repr, sortedStrings } from "./text.js";
+const IDENTIFIER = /^[a-z][a-z0-9-]{0,31}$/;
+const VOLUME = /^[a-z0-9][a-z0-9_.-]{0,62}$/;
+const ARG = /^[A-Za-z0-9._=/-]+$/;
+/** The bundled shared data, or the repository's /shared when run from source. */
+export function sharedDir() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const bundled = path.join(here, "_shared");
+    if (existsSync(bundled) && statSync(bundled).isDirectory())
+        return bundled;
+    return path.resolve(here, "..", "..", "..", "shared"); // cli/node/{src,dist} -> repo root
+}
+export class ProviderFileError extends CliError {
+    constructor(file, problem) {
+        super(`Provider definition ${path.basename(file)} is invalid: ${problem}`, {
+            hint: "This is a packaging bug; please report it.",
+        });
+    }
+}
+function isDict(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireValue(data, key, kind, file) {
+    const value = data[key];
+    const ok = kind === "str"
+        ? typeof value === "string"
+        : kind === "int"
+            ? Number.isInteger(value)
+            : isDict(value);
+    if (!ok)
+        throw new ProviderFileError(file, `'${key}' must be a ${kind}`);
+    return value;
+}
+function command(value, file, where) {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        !value.every((a) => typeof a === "string" && ARG.test(a))) {
+        throw new ProviderFileError(file, `'${where}' must be a non-empty list of plain arguments`);
+    }
+    return Object.freeze([...value]);
+}
+function errorName(error) {
+    if (error instanceof SyntaxError)
+        return "JSONDecodeError";
+    const code = error?.code;
+    if (code === "ENOENT")
+        return "FileNotFoundError";
+    if (code === "EACCES" || code === "EPERM")
+        return "PermissionError";
+    if (code === "EISDIR")
+        return "IsADirectoryError";
+    return "OSError";
+}
+function parse(file) {
+    let data;
+    try {
+        data = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new ProviderFileError(file, `cannot be read (${errorName(error)})`);
+    }
+    if (!isDict(data) || data.schema_version !== 1) {
+        throw new ProviderFileError(file, "unsupported schema_version");
+    }
+    const name = requireValue(data, "name", "str", file);
+    if (!IDENTIFIER.test(name) || path.basename(file, ".json") !== name) {
+        throw new ProviderFileError(file, "'name' must be an identifier matching the file name");
+    }
+    const volume = requireValue(data, "volume", "str", file);
+    if (!VOLUME.test(volume))
+        throw new ProviderFileError(file, "'volume' is not a valid volume name");
+    const home = requireValue(data, "home", "str", file);
+    if (!home.startsWith("/")) {
+        throw new ProviderFileError(file, "'home' must be an absolute container path");
+    }
+    const port = requireValue(data, "default_port", "int", file);
+    if (port < 1024 || port > 65535) {
+        throw new ProviderFileError(file, "'default_port' must be between 1024 and 65535");
+    }
+    const login = requireValue(data, "login", "dict", file);
+    const methods = new Map();
+    for (const [methodName, method] of Object.entries(requireValue(login, "methods", "dict", file))) {
+        if (!IDENTIFIER.test(methodName) || !isDict(method)) {
+            throw new ProviderFileError(file, `invalid login method ${repr(methodName)}`);
+        }
+        const secret = method.secret_stdin;
+        methods.set(methodName, {
+            name: methodName,
+            description: requireValue(method, "description", "str", file),
+            command: command(method.command, file, `login.methods.${methodName}`),
+            secretStdin: typeof secret === "string" ? secret : null,
+        });
+    }
+    const defaultMethod = requireValue(login, "default_method", "str", file);
+    if (!methods.has(defaultMethod)) {
+        throw new ProviderFileError(file, "'login.default_method' is not one of the methods");
+    }
+    let linkPattern;
+    try {
+        linkPattern = new RegExp(requireValue(login, "link_pattern", "str", file), "g");
+    }
+    catch (error) {
+        if (error instanceof ProviderFileError)
+            throw error;
+        throw new ProviderFileError(file, "'login.link_pattern' is not a valid regex");
+    }
+    const status = requireValue(data, "status", "dict", file);
+    const logout = requireValue(data, "logout", "dict", file);
+    const docsUrl = data.docs_url;
+    return Object.freeze({
+        name,
+        displayName: requireValue(data, "display_name", "str", file),
+        driver: requireValue(data, "driver", "str", file),
+        defaultPort: port,
+        volume,
+        home,
+        exampleModel: requireValue(data, "example_model", "str", file),
+        loginMethods: methods,
+        defaultLoginMethod: defaultMethod,
+        linkPattern,
+        loginTimeout: requireValue(login, "timeout_seconds", "int", file),
+        statusCommand: command(status.command, file, "status.command"),
+        loggedInExitCode: requireValue(status, "logged_in_exit_code", "int", file),
+        logoutCommand: command(logout.command, file, "logout.command"),
+        docsUrl: typeof docsUrl === "string" ? docsUrl : null,
+    });
+}
+const cache = new Map();
+/** All providers by name, sorted by name. Cached per directory. */
+export function loadProviders(directory) {
+    const dir = directory ?? path.join(sharedDir(), "providers");
+    const cached = cache.get(dir);
+    if (cached)
+        return cached;
+    let names = [];
+    try {
+        names = sortedStrings(readdirSync(dir).filter((f) => f.endsWith(".json")));
+    }
+    catch {
+        names = [];
+    }
+    const providers = new Map();
+    for (const provider of names.map((f) => parse(path.join(dir, f)))) {
+        providers.set(provider.name, provider);
+    }
+    if (providers.size === 0) {
+        throw new CliError("No provider definitions found.", {
+            hint: "This is a packaging bug; please report it.",
+        });
+    }
+    const volumes = [...providers.values()].map((p) => p.volume);
+    if (new Set(volumes).size !== volumes.length) {
+        throw new CliError("Two providers share a login volume.", { hint: "Please report this bug." });
+    }
+    const sorted = new Map(sortedStrings(providers.keys()).map((n) => [n, providers.get(n)]));
+    cache.set(dir, sorted);
+    return sorted;
+}
+export function getProvider(name) {
+    const providers = loadProviders();
+    const provider = providers.get(name);
+    if (provider === undefined) {
+        throw new UsageError(`Unknown provider ${repr(name)}.`, {
+            hint: `Choose one of: ${[...providers.keys()].join(", ")}.`,
+        });
+    }
+    return provider;
+}

package/dist/redact.js

@@ -0,0 +1,33 @@
+/** Mask secrets in anything the CLI prints (including --verbose output). */
+export const MASK = "[REDACTED]";
+const PATTERNS = [
+    [/\b(bearer)\s+[A-Za-z0-9._~+/=-]+/gi, `$1 ${MASK}`],
+    [/\bsk-[A-Za-z0-9_-]{8,}/g, MASK],
+    [/\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]*/g, MASK],
+    // The server's key list: only values that look like keys, not "$(...)" hints.
+    [/\b(MODELMUX_API_KEYS=)[A-Za-z0-9_,-]{16,}/g, `$1${MASK}`],
+];
+const secrets = new Set();
+/** Mask these exact values everywhere from now on (e.g. the server API key). */
+export function registerSecret(...values) {
+    for (const value of values) {
+        if (value.length >= 8)
+            secrets.add(value);
+    }
+}
+export function registered() {
+    return new Set(secrets);
+}
+/** Forget every registered secret (tests). */
+export function clearSecrets() {
+    secrets.clear();
+}
+export function redact(text) {
+    for (const secret of [...secrets].sort((a, b) => b.length - a.length)) {
+        text = text.split(secret).join(MASK);
+    }
+    for (const [pattern, replacement] of PATTERNS) {
+        text = text.replace(pattern, replacement);
+    }
+    return text;
+}

package/dist/release.js

@@ -0,0 +1,52 @@
+/**
+ * The release this CLI belongs to, from `shared/release.json`.
+ *
+ * The release workflow writes the server image pinned by digest
+ * (`ghcr.io/smit153/modelmux@sha256:...`) into that file before building, so
+ * every CLI implementation (Python and Node) runs the same image. In a
+ * development checkout `image` is null: pass `--image` instead.
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { CliError } from "./errors.js";
+import { sharedDir } from "./providers.js";
+let cached = null;
+export function releaseData() {
+    if (cached !== null)
+        return cached;
+    let data;
+    try {
+        data = JSON.parse(readFileSync(path.join(sharedDir(), "release.json"), "utf8"));
+    }
+    catch {
+        throw new CliError("The release data is missing or damaged.", {
+            hint: "Please report this bug.",
+        });
+    }
+    if (typeof data !== "object" ||
+        data === null ||
+        Array.isArray(data) ||
+        typeof data.version !== "string") {
+        throw new CliError("The release data is invalid.", { hint: "Please report this bug." });
+    }
+    const record = data;
+    const image = record.image ?? null;
+    if (image !== null && !(typeof image === "string" && image.includes("@sha256:"))) {
+        throw new CliError("The pinned server image is not pinned by digest.", {
+            hint: "Please report this bug.",
+        });
+    }
+    cached = { version: record.version, image: typeof image === "string" ? image : null };
+    return cached;
+}
+/** Forget the cached release data (tests). */
+export function resetReleaseCache() {
+    cached = null;
+}
+function readPinnedImage() {
+    return releaseData().image;
+}
+/** Replaceable in tests. */
+export const release = {
+    pinnedImage: readPinnedImage,
+};

package/dist/secretsStore.js

@@ -0,0 +1,61 @@
+/**
+ * The API key clients use to call ModelMux (not a provider credential).
+ *
+ * Generated once with `crypto`, stored in `secrets.env` with mode 0600 in the
+ * format compose reads as an env file. The value is registered for redaction
+ * as soon as it is loaded, so it never appears in output unless the user
+ * explicitly asks for it (`modelmux key show`).
+ */
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { CliError } from "./errors.js";
+import { tighten, writePrivate } from "./files.js";
+import { ensurePrivateDir } from "./paths.js";
+import { registerSecret } from "./redact.js";
+export const SECRETS_FILE = "secrets.env";
+export const VARIABLE = "MODELMUX_API_KEYS";
+export const KEY_BYTES = 32; // base64url(32 bytes) -> 43 characters; the server requires >= 32
+const LINE = new RegExp(`^${VARIABLE}=([A-Za-z0-9_-]{32,})$`);
+export class SecretsFileError extends CliError {
+    constructor(file) {
+        super("The saved ModelMux API key is unreadable or damaged.", {
+            hint: `Delete ${file} and run 'modelmux up' to create a new key ` +
+                "(clients using the old key will need the new one).",
+        });
+    }
+}
+export function readApiKey(directory) {
+    const file = path.join(directory, SECRETS_FILE);
+    if (!existsSync(file))
+        return null;
+    const fixed = tighten(file);
+    let lines;
+    try {
+        lines = readFileSync(file, "utf8")
+            .split(/\r\n|\r|\n/)
+            .map((ln) => ln.trim())
+            .filter((ln) => ln !== "");
+    }
+    catch {
+        throw new SecretsFileError(file);
+    }
+    const match = lines.length === 1 ? LINE.exec(lines[0]) : null;
+    if (match === null)
+        throw new SecretsFileError(file);
+    const value = match[1];
+    registerSecret(value);
+    return { value, path: file, created: false, permissionsFixed: fixed };
+}
+/** Return the saved key, creating one on first use. */
+export function ensureApiKey(directory) {
+    const existing = readApiKey(directory);
+    if (existing !== null)
+        return existing;
+    ensurePrivateDir(directory);
+    const value = randomBytes(KEY_BYTES).toString("base64url");
+    registerSecret(value);
+    const file = path.join(directory, SECRETS_FILE);
+    writePrivate(file, `${VARIABLE}=${value}\n`);
+    return { value, path: file, created: true, permissionsFixed: false };
+}

package/dist/stack.js

@@ -0,0 +1,220 @@
+/**
+ * The ModelMux containers on this machine: image, compose file, login volumes.
+ *
+ * All containers belong to the compose project `modelmux`. Each provider has
+ * one service (`modelmux-<provider>`) and one *external* login volume
+ * (`modelmux_<provider>-home`) that only `modelmux logout` deletes.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { pyJson } from "./config.js";
+import { PULL_TIMEOUT } from "./docker.js";
+import { CliError, DockerError, UsageError } from "./errors.js";
+import { writePrivate } from "./files.js";
+import { sharedDir } from "./providers.js";
+import { release } from "./release.js";
+import { repr, sortedStrings } from "./text.js";
+export const PROJECT = "modelmux";
+export const COMPOSE_FILE = "compose.yaml"; // JSON content; YAML is a superset of JSON
+export const CONTAINER_PORT = 8000;
+// tmpfs mount spec inside helper containers (not a host path)
+export const CONTAINER_TMP = "/tmp:rw,noexec,nosuid,nodev,size=64m";
+const IMAGE_REF = /^[A-Za-z0-9][A-Za-z0-9._/:@-]{0,254}$/;
+export function volumeName(provider) {
+    return `${PROJECT}_${provider.volume}`;
+}
+export function serviceName(provider) {
+    return `${PROJECT}-${provider.name}`;
+}
+/** The image to run: --image, then the saved override, then the pinned release image. */
+export function resolveImage(config, override = null) {
+    const image = override || config.image || release.pinnedImage();
+    if (!image) {
+        throw new UsageError("This development build of modelmux has no pinned server image.", {
+            hint: "Pass one explicitly, e.g. --image modelmux:dev (it is remembered).",
+        });
+    }
+    if (!IMAGE_REF.test(image))
+        throw new UsageError(`${repr(image)} is not a valid image reference.`);
+    return image;
+}
+export function serviceTemplate() {
+    const file = path.join(sharedDir(), "templates", "compose-service.json");
+    const data = JSON.parse(readFileSync(file, "utf8"));
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        throw new CliError("The compose template is invalid.", { hint: "Please report this bug." });
+    }
+    return data;
+}
+export function buildCompose(providers, config, image, secretsFile) {
+    const template = serviceTemplate();
+    const labels = (template.labels ?? {});
+    const services = {};
+    const volumes = {};
+    for (const name of sortedStrings(providers.keys())) {
+        const provider = providers.get(name);
+        services[serviceName(provider)] = {
+            ...template,
+            image,
+            environment: { MODELMUX_DRIVER: provider.driver },
+            env_file: [secretsFile],
+            volumes: [`${provider.volume}:${provider.home}`],
+            ports: [`127.0.0.1:${config.port(name)}:${CONTAINER_PORT}`],
+            networks: [PROJECT],
+            labels: { ...labels, "io.modelmux.provider": name },
+        };
+        volumes[provider.volume] = { external: true, name: volumeName(provider) };
+    }
+    return {
+        name: PROJECT,
+        services,
+        volumes,
+        networks: { [PROJECT]: { driver: "bridge" } },
+    };
+}
+/** Write the compose file. Returns true if its content changed. */
+export function writeCompose(directory, compose) {
+    const file = path.join(directory, COMPOSE_FILE);
+    const header = "# Generated by modelmux. Do not edit: changes are overwritten by 'modelmux up'.\n";
+    const content = header + pyJson(compose) + "\n";
+    try {
+        if (readFileSync(file, "utf8") === content)
+            return false;
+    }
+    catch {
+        // missing or unreadable: write it
+    }
+    writePrivate(file, content);
+    return true;
+}
+export class Stack {
+    docker;
+    home;
+    constructor(docker, home) {
+        this.docker = docker;
+        this.home = home;
+    }
+    get composeFile() {
+        return path.join(this.home, COMPOSE_FILE);
+    }
+    // ------------------------------------------------------------ image
+    async imagePresent(image) {
+        return (await this.docker.run(["image", "inspect", image], { check: false })).ok;
+    }
+    /** Pull `image` if it is not present. Returns true if it was pulled. */
+    async ensureImage(image) {
+        if (await this.imagePresent(image))
+            return false;
+        try {
+            await this.docker.run(["pull", image], { timeout: PULL_TIMEOUT });
+        }
+        catch (error) {
+            if (!(error instanceof DockerError) || image.split("@", 1)[0].includes("/"))
+                throw error;
+            // A local-only name such as modelmux:dev.
+            throw new DockerError(`The image ${image} is not on this machine and could not be downloaded.`, { hint: `Build it first: docker build -f docker/Dockerfile -t ${image} .` });
+        }
+        return true;
+    }
+    // ------------------------------------------------------------ volumes
+    async volumeExists(provider) {
+        return (await this.docker.run(["volume", "inspect", volumeName(provider)], { check: false })).ok;
+    }
+    async ensureVolume(provider) {
+        if (!(await this.volumeExists(provider))) {
+            await this.docker.run([
+                "volume", "create",
+                "--label", "io.modelmux.managed=true",
+                "--label", `io.modelmux.provider=${provider.name}`,
+                volumeName(provider),
+            ]);
+        }
+    }
+    // ------------------------------------------------------------ helper containers
+    /**
+     * `docker run` arguments for a short-lived, hardened helper container.
+     *
+     * `extra` adds run options such as `-it` or `--name`.
+     */
+    helperArgs(provider, image, command, extra = []) {
+        return [
+            "run", "--rm", ...extra,
+            "--read-only", "--tmpfs", CONTAINER_TMP,
+            "--cap-drop", "ALL", "--security-opt", "no-new-privileges:true",
+            "--user", "10001:10001",
+            "--label", "io.modelmux.managed=true",
+            "-v", `${volumeName(provider)}:${provider.home}`,
+            "-e", `HOME=${provider.home}`,
+            "--entrypoint", command[0],
+            image, ...command.slice(1),
+        ];
+    }
+    async loggedIn(provider, image) {
+        if (!(await this.volumeExists(provider)))
+            return false;
+        const result = await this.docker.run(this.helperArgs(provider, image, provider.statusCommand), {
+            check: false,
+            timeout: 90,
+        });
+        return result.returncode === provider.loggedInExitCode;
+    }
+    // ------------------------------------------------------------ compose
+    compose(args, options = {}) {
+        return this.docker.compose(PROJECT, this.composeFile, args, options);
+    }
+    /** Current containers of the project, by service name. Empty if none. */
+    async states() {
+        if (!existsSync(this.composeFile))
+            return new Map();
+        const result = await this.compose(["ps", "--all", "--format", "json"], { check: false });
+        if (!result.ok)
+            return new Map();
+        return parsePs(result.stdout);
+    }
+}
+/** `docker compose ps --format json` output: one object per line, or one array. */
+export function parsePs(output) {
+    const text = output.trim();
+    const states = new Map();
+    if (!text)
+        return states;
+    let items;
+    try {
+        items = text.startsWith("[")
+            ? JSON.parse(text)
+            : text
+                .split(/\r\n|\r|\n/)
+                .filter((line) => line.trim())
+                .map((line) => JSON.parse(line));
+    }
+    catch {
+        return states;
+    }
+    if (!Array.isArray(items))
+        return states;
+    for (const item of items) {
+        if (typeof item !== "object" || item === null || Array.isArray(item))
+            continue;
+        const record = item;
+        if (typeof record.Service !== "string")
+            continue;
+        const code = record.ExitCode;
+        states.set(record.Service, {
+            service: record.Service,
+            state: pyStr(record.State ?? ""),
+            health: pyStr(record.Health ?? ""),
+            exitCode: Number.isInteger(code) ? code : null,
+        });
+    }
+    return states;
+}
+/** Python's `str()` for the JSON scalars Docker reports. */
+function pyStr(value) {
+    if (value === null)
+        return "None";
+    if (value === true)
+        return "True";
+    if (value === false)
+        return "False";
+    return typeof value === "string" ? value : JSON.stringify(value);
+}

package/dist/terminal.js

@@ -0,0 +1,46 @@
+/**
+ * Find the login link in a provider CLI's terminal output.
+ *
+ * Output arrives in arbitrary chunks and contains escape sequences: colours
+ * (CSI) and OSC 8 hyperlinks, which carry the URL a second time. Escapes are
+ * removed from a rolling buffer, and a link is only reported once it is
+ * complete, i.e. followed by whitespace, so a URL split across reads is never
+ * opened half-finished.
+ */
+const OSC = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+const CSI = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+const OTHER_ESC = /\x1b[@-Z\\-_]/g;
+const BUFFER_LIMIT = 64 * 1024;
+// Python's str.isspace() for the characters a terminal can produce.
+const SPACE = /^[\s\x1c-\x1f\x85]$/u;
+/** Remove escape sequences (bytes are handled as latin1 so offsets stay byte offsets). */
+export function stripEscapes(data) {
+    let text = data.toString("latin1");
+    text = text.replace(OSC, "").replace(CSI, "").replace(OTHER_ESC, "");
+    return new TextDecoder("utf-8").decode(Buffer.from(text, "latin1"));
+}
+export class LinkScanner {
+    pattern;
+    raw = Buffer.alloc(0);
+    link = null;
+    constructor(pattern) {
+        this.pattern = new RegExp(pattern.source, pattern.flags.includes("g") ? pattern.flags : pattern.flags + "g");
+    }
+    /** Add output. Returns the link the first time a complete one is seen. */
+    feed(data) {
+        if (this.link !== null)
+            return null;
+        const joined = Buffer.concat([this.raw, data]);
+        this.raw = joined.subarray(Math.max(0, joined.length - BUFFER_LIMIT));
+        const text = stripEscapes(this.raw);
+        this.pattern.lastIndex = 0;
+        for (const match of text.matchAll(this.pattern)) {
+            const end = match.index + match[0].length;
+            if (end < text.length && SPACE.test(text[end])) {
+                this.link = match[0];
+                return this.link;
+            }
+        }
+        return null;
+    }
+}