@x-tech-laboratories/x-libs 0.14.0 → 0.14.1

package/dist/web/react/menus.js

@@ -2,8 +2,8 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 // Menus and popovers on the native popover: closed by Escape or a click elsewhere, and here also by scrolling or leaving the window.
 import { Fragment, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
 import { item_after_key, item_starting_with, on_screen_position } from "../menus.js";
-// Shows the element as a popover while it is rendered, calling the latest on_close once it closes for any reason.
-function use_popover(on_close, opener) {
+// Shows the element as a popover while it is rendered, calling the latest on_close once it closes for any reason; a manual one closes itself on a press outside it.
+function use_popover(on_close, opener, manual = false) {
     const element = useRef(null);
     const close = useRef(on_close);
     close.current = on_close;
@@ -14,15 +14,18 @@ function use_popover(on_close, opener) {
             popover.hidePopover(); };
         const toggled = (event) => { if (event.newState === "closed")
             close.current(); };
-        const outside_scroll = (event) => { if (!popover.contains(event.target))
+        const outside = (event) => { if (!popover.contains(event.target))
             hide(); };
         popover.addEventListener("toggle", toggled);
         window.addEventListener("blur", hide);
-        window.addEventListener("scroll", outside_scroll, true);
+        window.addEventListener("scroll", outside, true);
+        if (manual)
+            window.addEventListener("pointerdown", outside, true);
         return () => {
             popover.removeEventListener("toggle", toggled);
             window.removeEventListener("blur", hide);
-            window.removeEventListener("scroll", outside_scroll, true);
+            window.removeEventListener("scroll", outside, true);
+            window.removeEventListener("pointerdown", outside, true);
         };
     }, []);
     const return_focus = () => {
@@ -126,14 +129,15 @@ export function MenuList({ items, on_close }) {
                         item.run();
                     }, children: [_jsx("span", { className: "menu-label", children: item.label }), item.hint && _jsx("span", { className: "menu-hint", children: item.hint })] })] }, item.label))) }));
 }
+// Manual, since on Linux the menu opens on the button's press and an auto popover would close on its release.
 export function ContextMenu({ x, y, items, on_close, label }) {
-    const { element: menu, dismiss, return_focus } = use_popover(on_close);
+    const { element: menu, dismiss, return_focus } = use_popover(on_close, undefined, true);
     const keys = use_menu_keys(menu, dismiss, true);
     useLayoutEffect(() => {
         show_at(menu.current, x, y);
         menu.current.querySelector(item_selector)?.focus();
     }, [x, y]);
-    return (_jsx("div", { ref: menu, popover: "auto", className: "menu", role: "menu", "aria-label": label, tabIndex: -1, onKeyDown: keys, children: _jsx(MenuList, { items: items, on_close: () => { return_focus(); on_close(); } }) }));
+    return (_jsx("div", { ref: menu, popover: "manual", className: "menu", role: "menu", "aria-label": label, tabIndex: -1, onKeyDown: keys, children: _jsx(MenuList, { items: items, on_close: () => { return_focus(); on_close(); } }) }));
 }
 let open_menu = null;
 let next_menu_id = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-tech-laboratories/x-libs",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Code the X-apps share: agents and their long runs, passwords and sign-in, the Fastify server pieces, durations, and the web page's helpers and widgets",
   "license": "GPL-3.0-or-later",
   "repository": {

package/dist/agent/client.d.ts

@@ -1,32 +0,0 @@
-import type { KeyObject } from "node:crypto";
-import { LongRuns, type LongRunOptions } from "./long_runs.ts";
-import { type AgentApp } from "./protocol.ts";
-import { AgentSession, type SessionHooks } from "./session.ts";
-import type { TaskRunner } from "./tasks.ts";
-export interface AgentConfig<Task> extends SessionHooks<Task> {
-    app: AgentApp<Task>;
-    runner: TaskRunner<Task>;
-    url: string;
-    key_file?: string;
-    token_file?: string;
-    state_directory: string;
-    host: string;
-    agent_version: string;
-    heartbeat_in_milliseconds?: number;
-    backoff_initial_in_milliseconds?: number;
-    backoff_longest_in_milliseconds?: number;
-    long_runs?: LongRunOptions;
-    log?: (line: string) => void;
-}
-export declare class AgentConfigError extends Error {
-    constructor(message: string);
-}
-export declare function check_url(text: string): URL;
-export declare function read_key_file(file: string): KeyObject;
-export interface RunningAgent<Task> {
-    readonly runs: LongRuns<Task>;
-    connected(): boolean;
-    session(): AgentSession<Task> | null;
-    stop(): Promise<void>;
-}
-export declare function start_agent<Task>(config: AgentConfig<Task>): RunningAgent<Task>;

package/dist/agent/client.js

@@ -1,148 +0,0 @@
-// The agent's connection to the server: dials out over a WebSocket with its host's key or token, hands the connection
-// to a session, and dials again with a growing, jittered wait whenever it drops.
-import { readFileSync } from "node:fs";
-import { AgentKeyError, parse_private_key } from "./keys.js";
-import { LongRuns } from "./long_runs.js";
-import { key_host_header } from "./protocol.js";
-import { AgentSession } from "./session.js";
-export class AgentConfigError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "AgentConfigError";
-    }
-}
-const local_names = new Set(["localhost", "[::1]", "::1"]);
-// ── Checks ───────────────────────────────────────────────────────────────────
-// The server's URL, which must be wss:// so secrets and output travel encrypted, unless it is this machine.
-export function check_url(text) {
-    let url;
-    try {
-        url = new URL(text);
-    }
-    catch {
-        throw new AgentConfigError(`'${text}' is not a URL.`);
-    }
-    if (url.protocol === "wss:")
-        return url;
-    if (url.protocol !== "ws:")
-        throw new AgentConfigError(`The server URL must start with wss://, not ${url.protocol}//.`);
-    const local = local_names.has(url.hostname) || /^127\.\d+\.\d+\.\d+$/.test(url.hostname);
-    if (!local)
-        throw new AgentConfigError(`ws:// is unencrypted, so it is only allowed to this machine; use wss://${url.host}${url.pathname}.`);
-    return url;
-}
-function login_of(config) {
-    const has_key = Boolean(config.key_file);
-    const has_token = Boolean(config.token_file);
-    if (has_key === has_token)
-        throw new AgentConfigError("Give exactly one of a key file and a token file.");
-    return has_key ? { kind: "key", file: config.key_file } : { kind: "token", file: config.token_file };
-}
-// The key in the file, or an AgentConfigError naming the file for one that is not a usable key.
-export function read_key_file(file) {
-    const text = readFileSync(file, "utf8");
-    try {
-        return parse_private_key(text);
-    }
-    catch (error) {
-        if (error instanceof AgentKeyError)
-            throw new AgentConfigError(`The key file ${file} ${error.message}`);
-        throw error;
-    }
-}
-export function start_agent(config) {
-    const url = check_url(config.url);
-    const login = login_of(config);
-    // A key that is there but unusable stops the agent at once; one not there yet, as before secrets are in place, is retried.
-    if (login.kind === "key") {
-        try {
-            read_key_file(login.file);
-        }
-        catch (error) {
-            if (error instanceof AgentConfigError)
-                throw error;
-        }
-    }
-    const runs = new LongRuns(config.state_directory, config.runner, config.long_runs);
-    const log = config.log ?? ((line) => console.log(line));
-    const heartbeat = config.heartbeat_in_milliseconds ?? 15_000;
-    const initial = config.backoff_initial_in_milliseconds ?? 1000;
-    const longest = config.backoff_longest_in_milliseconds ?? 60_000;
-    let socket = null;
-    let session = null;
-    let failures = 0;
-    let stopping = false;
-    let retry_timer;
-    let closed_resolve = null;
-    const dial_later = () => {
-        if (stopping)
-            return;
-        // Half the wait is fixed and half random, so hosts that lost the server together do not all return at once.
-        const wait = Math.min(longest, initial * 2 ** failures);
-        failures++;
-        retry_timer = setTimeout(dial, wait / 2 + Math.random() * (wait / 2));
-    };
-    const dial = () => {
-        if (stopping)
-            return;
-        let headers;
-        let key = null;
-        try {
-            if (login.kind === "key") {
-                key = read_key_file(login.file);
-                headers = { [key_host_header(config.app.name)]: config.host };
-            }
-            else {
-                headers = { authorization: `Bearer ${readFileSync(login.file, "utf8").trim()}` };
-            }
-        }
-        catch (error) {
-            log(`Could not read the ${login.kind} file: ${error.message}`);
-            dial_later();
-            return;
-        }
-        // Node's WebSocket takes headers, which the browser's type has no room for.
-        const current = new WebSocket(url, { headers });
-        current.binaryType = "arraybuffer";
-        socket = current;
-        current.addEventListener("open", () => {
-            failures = 0;
-            log(`Connected to ${url.origin}`);
-            session = new AgentSession(current, runs, {
-                app: config.app, runner: config.runner, host: config.host, agent_version: config.agent_version, heartbeat_in_milliseconds: heartbeat, key,
-                requests: config.requests, on_message: config.on_message, on_hello: config.on_hello,
-            });
-        });
-        current.addEventListener("message", (event) => {
-            if (typeof event.data === "string")
-                session?.receive(event.data);
-        });
-        current.addEventListener("error", () => { });
-        current.addEventListener("close", (event) => {
-            if (session !== null)
-                log(`Disconnected from ${url.origin} (${event.code}${event.reason ? `: ${event.reason}` : ""})`);
-            session?.close();
-            session = null;
-            socket = null;
-            if (closed_resolve !== null)
-                closed_resolve();
-            else
-                dial_later();
-        });
-    };
-    dial();
-    return {
-        runs,
-        connected: () => session !== null,
-        session: () => session,
-        stop: () => {
-            stopping = true;
-            clearTimeout(retry_timer);
-            if (socket === null)
-                return Promise.resolve();
-            const closing = new Promise((resolve) => (closed_resolve = resolve));
-            socket.close(1000, "The agent is stopping.");
-            return closing;
-        },
-    };
-}

package/dist/agent/commands.d.ts

@@ -1,23 +0,0 @@
-import type { Readable } from "node:stream";
-import type { RunResult } from "./protocol.ts";
-export interface RunOptions {
-    timeout_in_seconds: number;
-    stdin?: string | null;
-}
-export interface StreamOptions {
-    stdin?: string | null;
-}
-export interface CommandStream {
-    stdout: Readable;
-    done: Promise<{
-        exit_code: number;
-        stderr: string;
-    }>;
-    stop: () => void;
-}
-export declare const kill_grace_in_milliseconds = 5000;
-export declare const run_stdout_limit_in_bytes: number;
-export declare const stderr_limit_in_bytes: number;
-export declare function signal_group(pid: number | undefined, signal: NodeJS.Signals): void;
-export declare function run_command(command: string, options: RunOptions): Promise<RunResult>;
-export declare function stream_command(command: string, options?: StreamOptions): CommandStream;

package/dist/agent/commands.js

@@ -1,118 +0,0 @@
-// Runs one shell command on this machine, either to its end with its output kept or with its stdout handed back as it
-// comes. Both the agent and the server's built-in agent run commands through here.
-// ── Imports ──────────────────────────────────────────────────────────────────
-import { spawn } from "node:child_process";
-// Give a stopped command this long to exit before it is killed outright.
-export const kill_grace_in_milliseconds = 5000;
-// A run keeps at most this much stdout, since it travels whole in one message.
-export const run_stdout_limit_in_bytes = 32 * 1024 * 1024;
-// Stderr is only ever an error message, so this much is plenty.
-export const stderr_limit_in_bytes = 64 * 1024;
-// ── Helpers ──────────────────────────────────────────────────────────────────
-// Sends the signal to a process group, which may have ended already.
-export function signal_group(pid, signal) {
-    if (pid === undefined)
-        return;
-    try {
-        process.kill(-pid, signal);
-    }
-    catch {
-        // The process group is already gone.
-    }
-}
-// Collects chunks up to a size, noting whether any were dropped.
-class BoundedBuffer {
-    chunks = [];
-    size = 0;
-    truncated = false;
-    limit;
-    constructor(limit) {
-        this.limit = limit;
-    }
-    add(chunk) {
-        const room = this.limit - this.size;
-        if (room <= 0) {
-            this.truncated = true;
-            return;
-        }
-        const kept = chunk.length > room ? chunk.subarray(0, room) : chunk;
-        if (kept !== chunk)
-            this.truncated = true;
-        this.chunks.push(kept);
-        this.size += kept.length;
-    }
-    text() {
-        return Buffer.concat(this.chunks).toString("utf8").trim();
-    }
-}
-// Its own process group, so stopping it stops the command's children too.
-function spawn_shell(command, stdin) {
-    const child = spawn("sh", ["-c", command], { detached: true, stdio: [stdin == null ? "ignore" : "pipe", "pipe", "pipe"] });
-    if (stdin != null) {
-        child.stdin.on("error", () => { });
-        child.stdin.end(stdin);
-    }
-    return child;
-}
-// ── Running ──────────────────────────────────────────────────────────────────
-export function run_command(command, options) {
-    return new Promise((resolve) => {
-        const child = spawn_shell(command, options.stdin);
-        const stdout = new BoundedBuffer(run_stdout_limit_in_bytes);
-        const stderr = new BoundedBuffer(stderr_limit_in_bytes);
-        let timed_out = false;
-        let kill_timer;
-        const timeout_timer = setTimeout(() => {
-            timed_out = true;
-            signal_group(child.pid, "SIGTERM");
-            kill_timer = setTimeout(() => signal_group(child.pid, "SIGKILL"), kill_grace_in_milliseconds);
-        }, options.timeout_in_seconds * 1000);
-        child.stdout.on("data", (chunk) => stdout.add(chunk));
-        child.stderr.on("data", (chunk) => stderr.add(chunk));
-        child.on("error", (error) => {
-            clearTimeout(timeout_timer);
-            clearTimeout(kill_timer);
-            resolve({ exit_code: -1, stdout: "", stderr: `Could not start sh: ${error.message}` });
-        });
-        child.on("close", (exit_code) => {
-            clearTimeout(timeout_timer);
-            clearTimeout(kill_timer);
-            if (timed_out) {
-                resolve({ exit_code: -1, stdout: stdout.text(), stderr: `Timed out after ${options.timeout_in_seconds}s` });
-                return;
-            }
-            const note = stdout.truncated ? `Output cut at ${run_stdout_limit_in_bytes} bytes` : "";
-            resolve({ exit_code: exit_code ?? -1, stdout: stdout.text(), stderr: [stderr.text(), note].filter(Boolean).join("\n") });
-        });
-    });
-}
-// ── Streaming ────────────────────────────────────────────────────────────────
-// Runs the command with no timeout and hands back its stdout as it comes, for output too big to hold.
-export function stream_command(command, options = {}) {
-    const child = spawn_shell(command, options.stdin);
-    const stderr = new BoundedBuffer(stderr_limit_in_bytes);
-    let ended = false;
-    let kill_timer;
-    child.stderr.on("data", (chunk) => stderr.add(chunk));
-    const done = new Promise((resolve) => {
-        child.on("error", (error) => {
-            ended = true;
-            resolve({ exit_code: -1, stderr: `Could not start sh: ${error.message}` });
-        });
-        child.on("close", (exit_code) => {
-            ended = true;
-            clearTimeout(kill_timer);
-            resolve({ exit_code: exit_code ?? -1, stderr: stderr.text() });
-        });
-    });
-    const stop = () => {
-        if (ended)
-            return;
-        signal_group(child.pid, "SIGTERM");
-        // Output nobody reads any more is thrown away, so a full pipe cannot keep the command from ending.
-        child.stdout.unpipe();
-        child.stdout.destroy();
-        kill_timer ??= setTimeout(() => signal_group(child.pid, "SIGKILL"), kill_grace_in_milliseconds);
-    };
-    return { stdout: child.stdout, done, stop };
-}

package/dist/agent/keys.d.ts

@@ -1,14 +0,0 @@
-import { type KeyObject } from "node:crypto";
-export declare class AgentKeyError extends Error {
-    constructor(message: string);
-}
-export declare function challenge_text(app: string, host: string, nonce: string): Buffer;
-export declare function sign_challenge(private_key: KeyObject, app: string, host: string, nonce: string): string;
-export declare function verify_challenge(public_key: KeyObject, app: string, host: string, nonce: string, signature: string): boolean;
-export declare function parse_public_key(line: string): KeyObject;
-export declare function key_fingerprint(line: string): string;
-export declare function parse_private_key(text: string): KeyObject;
-export declare function generate_agent_key(comment: string): {
-    private_text: string;
-    public_line: string;
-};

package/dist/agent/keys.js

@@ -1,81 +0,0 @@
-// A host's agent key: an ed25519 key made by `ssh-keygen -t ed25519 -N ""`, whose private half the agent holds and
-// whose public line the server's config declares. The agent proves it holds the key by signing the server's nonce.
-// sshpk reads and writes the OpenSSH formats, which Node's crypto does not, and Node's crypto signs.
-// ── Imports ──────────────────────────────────────────────────────────────────
-import { createPrivateKey, createPublicKey, sign, verify } from "node:crypto";
-import sshpk from "sshpk";
-// ── Settings ─────────────────────────────────────────────────────────────────
-export class AgentKeyError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "AgentKeyError";
-    }
-}
-// ── Challenge ────────────────────────────────────────────────────────────────
-// What the agent signs: the app, the protocol, the host it logs in as and the server's nonce, so a signature fits one
-// login to one app only; `app` is the app's name, such as "x-nix".
-export function challenge_text(app, host, nonce) {
-    return Buffer.from(`${app}-agent-v1|${host}|${nonce}`, "utf8");
-}
-export function sign_challenge(private_key, app, host, nonce) {
-    return sign(null, challenge_text(app, host, nonce), private_key).toString("base64");
-}
-export function verify_challenge(public_key, app, host, nonce, signature) {
-    try {
-        return verify(null, challenge_text(app, host, nonce), public_key, Buffer.from(signature, "base64"));
-    }
-    catch {
-        return false;
-    }
-}
-// ── Public key ───────────────────────────────────────────────────────────────
-// Reads an OpenSSH public key line; the messages never quote the key itself.
-export function parse_public_key(line) {
-    const parts = line.trim().split(/\s+/);
-    if (parts.length < 2 || parts[0] === "")
-        throw new AgentKeyError('must be an OpenSSH public key line such as "ssh-ed25519 AAAA... comment".');
-    if (parts[0] !== "ssh-ed25519")
-        throw new AgentKeyError(`must be an ssh-ed25519 key, not ${parts[0]}; make one with ssh-keygen -t ed25519.`);
-    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(parts[1]))
-        throw new AgentKeyError("holds a key that is not base64.");
-    let key;
-    try {
-        key = sshpk.parseKey(line.trim(), "ssh");
-    }
-    catch {
-        throw new AgentKeyError("is cut short or damaged.");
-    }
-    if (key.type !== "ed25519")
-        throw new AgentKeyError(`says ssh-ed25519 but holds a ${key.type} key.`);
-    return createPublicKey(key.toString("pkcs8"));
-}
-// The key's SHA256 fingerprint as ssh-keygen -l prints it.
-export function key_fingerprint(line) {
-    return sshpk.parseKey(line.trim(), "ssh").fingerprint("sha256").toString();
-}
-// ── Private key ──────────────────────────────────────────────────────────────
-// Reads an unencrypted OpenSSH ed25519 private key; the messages never quote the key itself.
-export function parse_private_key(text) {
-    if (!/-{5}BEGIN OPENSSH PRIVATE KEY-{5}/.test(text))
-        throw new AgentKeyError('is not an OpenSSH private key; make one with ssh-keygen -t ed25519 -N "".');
-    let key;
-    try {
-        key = sshpk.parsePrivateKey(text, "ssh");
-    }
-    catch (error) {
-        if (error.name === "KeyEncryptedError") {
-            throw new AgentKeyError('is encrypted with a passphrase, which the agent cannot type; make it with -N "" and keep it in a secret store instead.');
-        }
-        throw new AgentKeyError("is cut short or damaged.");
-    }
-    if (key.type !== "ed25519")
-        throw new AgentKeyError(`must be an ssh-ed25519 key, not ${key.type}; make one with ssh-keygen -t ed25519.`);
-    return createPrivateKey(key.toString("pkcs8"));
-}
-// ── New keys ─────────────────────────────────────────────────────────────────
-// A new ed25519 key in the files ssh-keygen would write: the unencrypted OpenSSH private key and its public line.
-export function generate_agent_key(comment) {
-    const key = sshpk.generatePrivateKey("ed25519");
-    key.comment = comment;
-    return { private_text: key.toString("ssh"), public_line: key.toPublic().toString("ssh") };
-}

package/dist/agent/long_runs.d.ts

@@ -1,32 +0,0 @@
-import { type CommandStream } from "./commands.ts";
-import { type LongRun, type LongRunPoll } from "./protocol.ts";
-import type { TaskRunner } from "./tasks.ts";
-export declare const poll_limit_in_bytes: number;
-export interface LongRunOptions {
-    kill_grace_in_milliseconds?: number;
-    tail_interval_in_milliseconds?: number;
-}
-export declare class LongRunError extends Error {
-    constructor(message: string);
-}
-export declare class LongRuns<Task> {
-    private readonly directory;
-    private readonly grace;
-    private readonly tail_interval;
-    private readonly runner;
-    private readonly children;
-    constructor(state_directory: string, runner: TaskRunner<Task>, options?: LongRunOptions);
-    start(run_id: string, task: Task, stdin: string | null): LongRun;
-    list(): LongRun[];
-    get(run_id: string): LongRun;
-    poll(run_id: string, offset: number, limit?: number): Promise<LongRunPoll>;
-    tail(run_id: string, offset: number): CommandStream;
-    stop(run_id: string): Promise<LongRun>;
-    forget(run_id: string): void;
-    prune(max_age_in_seconds: number): void;
-    private folder;
-    private record;
-    private require;
-    private is_alive;
-    private describe;
-}