@xingjisoft/neutrino 0.6.0 → 0.7.0

package/dist/terminal/renderer.d.ts

@@ -0,0 +1,43 @@
+import type { Buffer } from "./buffer.js";
+export declare class Renderer {
+    private prevSig;
+    private disposed;
+    private prevW;
+    private prevH;
+    private out;
+    /**
+     * The most recent frame, kept so `repaint()` can re-emit it without re-running the
+     * screen's (potentially expensive) render — to heal any drift the terminal
+     * introduced behind our back.
+     */
+    private lastBuf;
+    private blocked;
+    private pendingForce;
+    private drainHandler;
+    init(): void;
+    dispose(): void;
+    /**
+     * @param forceRows rows to repaint unconditionally, even when their contents
+     *   are unchanged. Screens use this for persistent chrome (input box, hints)
+     *   so that terminal-side drift can never leave it stale (see
+     *   `Screen.alwaysRepaintRows`).
+     */
+    render(buf: Buffer, forceRows?: readonly number[]): void;
+    /**
+     * Re-emit the last frame in full. Cheap (no screen re-render) and visually a
+     * no-op when nothing drifted, but it repairs rows the terminal moved on its
+     * own (resize reflow, stray scroll). Called periodically as a safety net.
+     */
+    repaint(): void;
+    /**
+     * Ring the terminal bell.
+     *
+     * Written straight to the stream rather than into a frame: BEL has no visual
+     * effect, so it cannot desync the diffed rows, and it must never end up in
+     * `lastBuf` where repaint() would replay it.
+     */
+    bell(times?: number): void;
+    private draw;
+    private renderRow;
+    private write;
+}

package/dist/terminal/restore.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Escape sequences that undo everything the TUI switches on.
+ *
+ * Mouse tracking is disabled before the alternate screen is left, and the
+ * cursor is restored before the screen swap, so the shell never inherits a
+ * half-configured terminal. Order matters: `?1049l` must come last or the
+ * remaining writes would land on the main screen.
+ */
+export declare const TUI_TEARDOWN: string;
+/** Called once the renderer has entered the alternate screen and raw mode. */
+export declare function markTuiActive(): void;
+/**
+ * Puts the terminal back into a usable state, synchronously and at most once.
+ *
+ * Everything here has to work while the process is dying: no promises, no
+ * asynchronous writes, and every step individually guarded so one failure
+ * cannot skip the rest (a broken `setRawMode` must not leave the cursor
+ * hidden, for example).
+ */
+export declare function restoreTerminalSync(): boolean;
+/** Appends a crash entry to `~/.neutrino/crash.log` and returns the path. */
+export declare function writeCrashLog(kind: string, err: unknown): string | null;
+/**
+ * Installs process-wide handlers that restore the terminal before the process
+ * dies.
+ *
+ * Without this, any throw that escapes a timer, a stream callback or a floating
+ * promise kills the process with raw mode still on and the alternate screen
+ * still active. The visible result is a terminal that works but spews
+ * `[<b>;<x>;<y>M` mouse reports at the shell prompt, because the shell now
+ * receives the mouse events the TUI asked the terminal to send.
+ */
+export interface CrashGuardOptions {
+    /**
+     * Keep SIGHUP for the caller. A detached background service must survive the
+     * terminal that started it closing (on POSIX that arrives as SIGHUP), while
+     * the terminal UI still wants a hangup to end the process.
+     */
+    surviveHangup?: boolean;
+}
+export declare function installCrashGuard(options?: CrashGuardOptions): void;

package/dist/terminal/screen.d.ts

@@ -0,0 +1,57 @@
+import type { Buffer } from "./buffer.js";
+import type { Key, MouseEvent } from "./input.js";
+import type { App } from "../app.js";
+/**
+ * A screen's scrollbar, as seen by the app. Supplying this lets the app turn a
+ * press/drag on the scrollbar column into scrolling, the same way a GUI does.
+ */
+export interface ScrollbarHandle {
+    /** Column the bar is drawn in. */
+    x: number;
+    /** Inclusive row range of the groove. */
+    top: number;
+    bottom: number;
+    /** Total scrollable lines and how many fit on screen. */
+    total: number;
+    viewport: number;
+    /** Current topmost visible line. */
+    offset: number;
+    /** Scroll to the given offset (clamped by the screen). */
+    scrollTo(offset: number): void;
+}
+export declare abstract class Screen {
+    app: App;
+    abstract onKey(key: Key): void;
+    onMouse(_ev: MouseEvent): void;
+    /**
+     * Describe the on-screen scrollbar so the app can drag it, or null when this
+     * screen has none / its content fits. Geometry is only valid right after a
+     * render, which is exactly when the app needs it.
+     */
+    scrollbar(): ScrollbarHandle | null;
+    /**
+     * Rows this screen draws as persistent "chrome" (an input box, key hints, …)
+     * that must be repainted on *every* frame, even when their contents are
+     * unchanged.
+     *
+     * The renderer normally emits only rows whose cells changed, which is what
+     * keeps redraws cheap. But the terminal can shift its own contents behind our
+     * back — ConPTY reflowing the buffer mid-resize, a size-race repaint, a stray
+     * scroll — and a diffed row would then stay stale forever (the classic
+     * "input box swallowed by the log" artefact). Redrawing this small strip by
+     * absolute position every frame makes it self-healing.
+     */
+    alwaysRepaintRows(): number[];
+    /**
+     * Handle a bracketed (or detected) paste. `text` already has its newlines
+     * flattened to spaces, so it can be inserted as a single line. Screens that
+     * have no text input can leave this as a no-op.
+     */
+    onPaste(_text: string): void;
+    abstract render(buf: Buffer): void;
+    /** Whether this screen currently shows a blinking text cursor. Used by the
+     *  app to run (or stop) the cursor blink timer. */
+    showsCursor(): boolean;
+    onActivate(): void;
+    onDeactivate(): void;
+}

package/dist/tray.d.ts

@@ -0,0 +1,14 @@
+export interface TrayOptions {
+    /** Console address opened by a click. */
+    url: string;
+    /** Management endpoint that stops the service. */
+    stopUrl: string;
+    /** Bearer token for `stopUrl`. */
+    token: string;
+    /** Process id the icon belongs to; the icon exits with it. */
+    pid: number;
+}
+/** The icon itself. Only Windows has a notification area, and only it can run this. */
+export declare function startBackgroundTray(options: TrayOptions): {
+    close(): void;
+} | null;

package/dist/ui.d.ts

@@ -0,0 +1,123 @@
+import type { Buffer } from "./terminal/buffer.js";
+import { type RGB } from "./colors.js";
+import type { ApprovalMode } from "./config.js";
+/** One terminal row; shared geometry keeps rendering and hit testing aligned. */
+export declare function approvalToggle(width: number, y: number, mode: ApprovalMode): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    text: string;
+};
+export declare function drawApprovalToggle(buf: Buffer, y: number, mode: ApprovalMode, focused?: boolean): void;
+export declare function wrapText(text: string, width: number): string[];
+export interface InputBoxOptions {
+    active?: boolean;
+    dimmed?: boolean;
+    placeholder?: string;
+    /** Blink phase of the text cursor. When false the cursor is hidden (the
+     *  character underneath is shown normally). */
+    cursorOn?: boolean;
+}
+export interface InputWindow {
+    /** Index (in UTF-16 code points) of the first visible character. */
+    startCp: number;
+    /** Display columns before the visible window. */
+    prefixW: number;
+    /** Number of visible characters. */
+    visibleCount: number;
+}
+/**
+ * Compute which part of the input value is visible inside the box, given the
+ * cursor position. Shared by `drawInputBox` and mouse click handling so the
+ * rendered text and click-to-position-cursor always agree.
+ */
+export declare function computeInputWindow(value: string, cursorPos: number, innerW: number): InputWindow;
+/**
+ * Map a column inside the input box (0-based, relative to the inner area) to a
+ * cursor index in the full value.
+ */
+export declare function cursorFromColumn(value: string, col: number, win: InputWindow): number;
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export declare function inRect(px: number, py: number, r: Rect): boolean;
+export declare function drawHint(buf: Buffer, y: number, text: string): void;
+export interface ScrollbarOptions {
+    /** Colour of the groove. Defaults to `C.scrollTrack`. */
+    track?: RGB;
+    /** Colour of the thumb. Defaults to `C.scrollThumb`. */
+    thumb?: RGB;
+}
+/**
+ * Draw a vertical scrollbar in column `x`, spanning rows `top`..`bottom`
+ * (inclusive). It is a no-op when everything fits, so callers can render it
+ * unconditionally.
+ *
+ *   total    - total number of scrollable items/lines
+ *   viewport - how many of them are visible at once
+ *   offset   - index of the topmost visible item (i.e. the current scrollTop)
+ *
+ * The thumb length is proportional to `viewport / total` (at least one cell)
+ * and its position is proportional to `offset / (total - viewport)`, matching
+ * the usual GUI scrollbar behaviour.
+ */
+export interface ScrollbarGeometry {
+    /** Height of the groove in cells. */
+    trackH: number;
+    /** Height of the thumb in cells (at least 1). */
+    thumbH: number;
+    /** Largest allowed top row of the thumb, relative to the groove. */
+    maxThumbTop: number;
+    /** Largest valid scroll offset (total - viewport). */
+    maxOffset: number;
+    /** Current top row of the thumb, relative to the groove. */
+    thumbTop: number;
+}
+/**
+ * Geometry of a vertical scrollbar, shared by the drawing code and the app's
+ * hit-testing / dragging so the two can never disagree.
+ */
+export declare function scrollbarGeometry(top: number, bottom: number, total: number, viewport: number, offset: number): ScrollbarGeometry;
+/**
+ * Inverse of the thumb positioning above: the scroll offset that places the
+ * thumb's top at 'thumbTop'. Used while dragging the thumb; feeding the result
+ * back through scrollbarGeometry reproduces the same 'thumbTop'.
+ */
+export declare function offsetFromThumbTop(g: ScrollbarGeometry, thumbTop: number): number;
+export declare function drawScrollbar(buf: Buffer, x: number, top: number, bottom: number, total: number, viewport: number, offset: number, opts?: ScrollbarOptions): void;
+export declare function drawInputBox(buf: Buffer, x: number, y: number, w: number, value: string, cursorPos: number, opts?: InputBoxOptions): void;
+export declare function drawTabButton(buf: Buffer, x: number, y: number, w: number, label: string, selected: boolean, align?: "center" | "left"): void;
+/** Label of the CLI entry point that opens the browser console's Pro workspace. */
+export declare const PRO_MODE_LABEL = "\u542F\u7528Pro\u6A21\u5F0F";
+/** Label of the CLI entry point that opens the browser console itself. */
+export declare const WEB_MODE_LABEL = "\u6253\u5F00Web\u7AEF";
+/** One of the small entry-point boxes painted in the top-left corner. */
+export interface HeaderButton {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    label: string;
+}
+/**
+ * The Pro-mode button: flush to the left edge with a single blank column, as
+ * the start screen expects.
+ */
+export declare function proModeButton(width: number, height: number): HeaderButton | null;
+/**
+ * The Web-mode button: glued to the right border of the Pro-mode button so the
+ * two read as one row of entry points. It starts where the Pro box ends, which
+ * also means it is hidden together with it on terminals too small for the row.
+ */
+export declare function webModeButton(width: number, height: number): HeaderButton | null;
+/**
+ * Draw one top-left button. It is painted as opaque chrome so content behind it
+ * can never bleed through; the label row turns into the highlight background
+ * while the pointer is over it.
+ */
+export declare function drawHeaderButton(buf: Buffer, button: HeaderButton | null, hovered?: boolean): void;
+export declare function centerVertically(totalHeight: number, contentHeight: number): number;

package/dist/update.d.ts

@@ -0,0 +1,71 @@
+/** The published package whose registry version decides whether an update exists. */
+export declare const UPDATE_PACKAGE = "@xingjisoft/neutrino";
+/** What a user can run by hand when the automatic update fails. */
+export declare const MANUAL_UPDATE_COMMAND = "npm install -g @xingjisoft/neutrino";
+export interface UpdateStatus {
+    /** The version this process runs, read from its own package.json. */
+    currentVersion: string;
+    /** The published version; empty until a registry lookup has succeeded. */
+    latestVersion: string;
+    /** True only when the registry offers a strictly newer version. */
+    hasUpdate: boolean;
+}
+export interface UpdateCheck extends UpdateStatus {
+    /** Why the registry could not be read; the status then reports no update. */
+    error?: string;
+}
+export interface UpdateInstallResult {
+    /** Whether npm reported success. */
+    ok: boolean;
+    /** The version this run was updating to; empty when none was known. */
+    version: string;
+    /** Why the install failed; empty on success. */
+    error?: string;
+}
+export interface UpdateCheckOptions {
+    /**
+     * Ask the registry again even though an answer is already remembered. The
+     * settings page's manual check and the periodic background check need a
+     * fresh answer; waiting for the next start-up would tell them nothing new.
+     */
+    refresh?: boolean;
+}
+/**
+ * The last known answer, for the terminal screen and the Web console payload.
+ * Reading this never touches the network: the lookup runs once per process (see
+ * checkForUpdate) and costs nothing afterwards.
+ */
+export declare function updateStatus(): UpdateStatus;
+/**
+ * Ask npm which version is published and remember it. This never rejects: an
+ * offline machine, a missing npm or a registry hiccup only means "no update to
+ * announce", which is what the next start is for. Concurrent callers share the
+ * one lookup, and a successful answer is kept for the rest of the process so
+ * the terminal and the Web console cannot disagree.
+ *
+ * Start-up asks once and is served from that answer from then on. A caller that
+ * passes `refresh` — the settings button, the background timer — queries the
+ * registry again, so an answer from an hour ago cannot make a check look idle.
+ * A failed refresh changes nothing: the last good answer stays, and the caller
+ * learns what went wrong from `error`.
+ */
+export declare function checkForUpdate(options?: UpdateCheckOptions): Promise<UpdateCheck>;
+/**
+ * Install the latest published release with npm.
+ *
+ * The terminal and both Web workspaces can ask for this, so requests share one
+ * install instead of running npm twice over the same files. It never rejects:
+ * whoever asked gets a result and, on failure, the command to run by hand.
+ *
+ * The version this process runs is not replaced — the running code stays on
+ * disk until the user restarts — so callers must tell the user to restart.
+ */
+export declare function installUpdate(): Promise<UpdateInstallResult>;
+/**
+ * Semantic-version order: returns 1 when `left` is newer, -1 when older and 0
+ * when they are the same release. A version that cannot be parsed compares as
+ * equal, so a malformed registry answer can never claim an update is due.
+ */
+export declare function compareVersions(left: string, right: string): number;
+/** Whether `candidate` is a strictly newer release than `current`. */
+export declare function isNewerVersion(candidate: string, current: string): boolean;

package/dist/updateWatch.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The periodic update check.
+ *
+ * A Web console can stay open for days, so the start-up lookup alone would
+ * never tell its windows about a release published afterwards. This module asks
+ * the registry again on a timer, in the process that serves those windows, and
+ * hands a release it has not seen before to whoever is listening: the console
+ * forwards it to every open browser (GET /api/update/events) and the first-open
+ * dialog reads the same answer.
+ */
+import { type UpdateCheck } from "./update.js";
+/** How often the background service asks the registry again. */
+export declare const UPDATE_CHECK_INTERVAL_MS: number;
+export interface UpdateWatchOptions {
+    /** Overridable so a test can watch a timer; the console never changes it. */
+    intervalMs?: number;
+    /**
+     * Called after every check, including the ones that found nothing or failed,
+     * so the background log can record a change. Never allowed to stop the timer.
+     */
+    onCheck?: (check: UpdateCheck) => void;
+}
+type Listener = (check: UpdateCheck) => void;
+/**
+ * Listen for a release the periodic check finds. Returns the unsubscribe
+ * function.
+ *
+ * Only news is announced: a version this process already knows — from the
+ * start-up lookup, the settings button or an earlier tick — is not sent again,
+ * so the dialogs cannot reopen every half hour for a release the user has
+ * already declined.
+ */
+export declare function subscribeUpdateAnnouncements(listener: Listener): () => void;
+/**
+ * Start asking the registry every `intervalMs` (30 minutes by default).
+ *
+ * Idempotent, and the returned function stops the timer and leaves the module
+ * ready to start again. Checks run off the timer rather than at start-up: both
+ * the console and the terminal UI already look once when they start, and a
+ * second immediate lookup would only spend npm calls on the same answer.
+ */
+export declare function startUpdateWatch(options?: UpdateWatchOptions): () => void;
+export {};

package/dist/web/approvalQueue.d.ts

@@ -0,0 +1,8 @@
+/** Serialize human prompts without overwriting an unresolved decision. */
+export declare class ApprovalQueue {
+    private active;
+    private waiting;
+    run(start: () => Promise<boolean | null>, signal?: AbortSignal): Promise<boolean | null>;
+    cancelWaiting(): void;
+    private next;
+}

package/dist/web/approvalQueue.js

@@ -0,0 +1,59 @@
+/** Serialize human prompts without overwriting an unresolved decision. */
+export class ApprovalQueue {
+    active = false;
+    waiting = [];
+    run(start, signal) {
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                resolve(false);
+                return;
+            }
+            const item = {
+                cancel: () => {
+                    const index = this.waiting.indexOf(item);
+                    if (index >= 0) {
+                        this.waiting.splice(index, 1);
+                        signal?.removeEventListener("abort", item.cancel);
+                        resolve(false);
+                    }
+                },
+                run: () => {
+                    signal?.removeEventListener("abort", item.cancel);
+                    if (signal?.aborted) {
+                        this.next();
+                        resolve(false);
+                        return;
+                    }
+                    this.active = true;
+                    let result;
+                    try {
+                        result = start();
+                    }
+                    catch (error) {
+                        this.next();
+                        reject(error);
+                        return;
+                    }
+                    result.then(value => { this.next(); resolve(value); }, error => { this.next(); reject(error); });
+                },
+            };
+            if (this.active) {
+                this.waiting.push(item);
+                signal?.addEventListener("abort", item.cancel, { once: true });
+            }
+            else
+                item.run();
+        });
+    }
+    cancelWaiting() {
+        for (const item of [...this.waiting])
+            item.cancel();
+    }
+    next() {
+        const next = this.waiting.shift();
+        if (next)
+            next.run();
+        else
+            this.active = false;
+    }
+}

package/dist/web/auth.d.ts

@@ -0,0 +1,14 @@
+import type http from "node:http";
+export declare const DEFAULT_WEB_PASSWORD = "114514";
+export declare function validateWebPassword(password: unknown): asserts password is string;
+/** Only a salted password hash is persisted; settings never return it. */
+export declare function hashWebPassword(password: unknown): string;
+/** Signed cookies survive restarts, but a password change invalidates all of them. */
+export declare class WebAuth {
+    readonly enabled: boolean;
+    constructor(enabled: boolean);
+    authenticated(req: http.IncomingMessage): boolean;
+    login(password: unknown): Promise<boolean>;
+    remember(res: http.ServerResponse): void;
+    forget(res: http.ServerResponse): void;
+}

package/dist/web/clientState.d.ts

@@ -0,0 +1,16 @@
+import { type Mode } from "../config.js";
+export declare const WEB_STATE_FILE: string;
+/** How many finished conversations one workspace remembers, newest last. */
+export declare const SEEN_LIMIT = 300;
+/** Whether a value from a request is an identity this file can hold. */
+export declare function isSeenIdentity(value: unknown): value is string;
+/** The conversations this workspace has already shown the reader, oldest first. */
+export declare function loadSeen(mode?: Mode): string[];
+/**
+ * Record (`seen: true`) or forget (`seen: false`) the given conversations and
+ * write the file back. Returns the workspace's new record.
+ *
+ * Identities that are not valid are ignored rather than rejected: the route
+ * already validated them, so this is only a guard on what reaches the disk.
+ */
+export declare function updateSeen(mode: Mode, identities: string[], seen: boolean): string[];

package/dist/web/folderPicker.d.ts

@@ -0,0 +1,34 @@
+/** What the folder window reported. Closing the window is a normal outcome. */
+export type FolderPick = {
+    picked: string;
+} | {
+    cancelled: true;
+} | {
+    unavailable: string;
+};
+/** One finished dialog process. */
+export interface DialogRun {
+    /** Exit code, or null when the process never ran to completion. */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    /** The executable itself does not exist here. */
+    missing: boolean;
+}
+/**
+ * Runs one dialog command. Injectable so the Windows, macOS and Linux paths can
+ * be tested on any machine, without a desktop session to draw a window in.
+ */
+export type DialogRunner = (command: string, args: string[], env: NodeJS.ProcessEnv, timeoutMs: number) => Promise<DialogRun>;
+export interface FolderPickRequest {
+    /** Folder the window opens in. Ignored when it is not an existing folder. */
+    start?: string;
+    /** Window title, already translated by the console. */
+    title?: string;
+    platform?: NodeJS.Platform;
+    timeoutMs?: number;
+    runner?: DialogRunner;
+    env?: NodeJS.ProcessEnv;
+}
+/** Open the operating system's folder window and report what the user chose. */
+export declare function pickFolder(request?: FolderPickRequest): Promise<FolderPick>;