@wirecat/max-cli 0.0.0-stage → 0.42.0

package/dist/server/server-connection.js

@@ -0,0 +1,245 @@
+import { createHash } from "node:crypto";
+import { connect } from "node:net";
+import { CliError, errorCodes } from "@wirecat/cli-core";
+import { currentOperation } from "@wirecat/cli-messaging/sends";
+import { Opcode } from "../generated/opcodes.generated.js";
+import { OPERATIONS } from "../generated/operations.generated.js";
+import { permissionApprovals } from "../permissions.js";
+import { Connection, ProtocolError } from "../protocol/connection.js";
+import { asId } from "../protocol/frame.js";
+import { fromLine, lineReader, toLine } from "./lines.js";
+/**
+ * **A command's connection: `max serve`'s, shared** (`MAX-35`, `NEED-229`).
+ *
+ * One connection to MAX per profile, whoever asks — CLI commands, `max mcp`, `max watch`. INIT
+ * and LOGIN are answered by the server's own login; **every other request goes over its
+ * connection, sends included**. The server runs the send guards on every write and journals it;
+ * the command's client checks too, so a refusal comes before an upload, and journals only that.
+ *
+ * Before the first request, `ensure` replaces a server a command started under another build; with
+ * none answering, it starts one and waits for it. A connection of the command's own
+ * is opened only when there is no `ensure` (the owner said `serve: false`) and no server, or for
+ * a token being tried out (`max session start`), which is by definition not the server's.
+ */
+export class ServerConnection {
+    #path;
+    #store;
+    #timeoutMs;
+    #direct;
+    #ensure;
+    #pending = new Map();
+    #socket;
+    #id = 0;
+    #login;
+    /** What the client sent as INIT; a fallback at LOGIN has to send it first, or MAX refuses. */
+    #init;
+    #own;
+    #ensured = false;
+    constructor({ path, store, timeoutMs = 30_000, direct, ensure, }) {
+        this.#ensure = ensure;
+        this.#path = path;
+        this.#store = store;
+        this.#timeoutMs = timeoutMs;
+        this.#direct = direct ?? (() => new Connection({ timeoutMs }));
+    }
+    async open() { }
+    /** Whether the server is the one answering — and so the one writing the send journal. */
+    get journals() {
+        return this.#login !== undefined && this.#own === undefined;
+    }
+    async invoke(opcode, payload = {}, watch) {
+        if (this.#own)
+            return this.#own.invoke(opcode, payload, watch);
+        if (opcode === Opcode.SESSION_INIT) {
+            this.#init = payload;
+            this.#login = await this.#askServer({ login: true });
+            return this.#login ? {} : this.#fallBack(opcode, payload, watch);
+        }
+        if (opcode === Opcode.LOGIN) {
+            // A token being tried out (`max session start`) is not the one the server logged in with, and
+            // a server still logged in as the account this profile had before is not this profile's.
+            if (!this.#login || payload.token !== this.#store.readToken() || !this.#sameAccount(this.#login)) {
+                return this.#fallBack(opcode, payload, watch);
+            }
+            return this.#login;
+        }
+        watch?.({ phase: "sent", seq: this.#id + 1, opcode, bytes: 0 });
+        // The write this frame belongs to, so the server's journal line carries the id the command answers with.
+        const operationId = currentOperation();
+        const answer = await this.#ask({
+            opcode,
+            payload,
+            approvals: permissionApprovals(),
+            ...(operationId === undefined ? {} : { operationId }),
+        });
+        watch?.({ phase: "received", seq: this.#id, opcode, bytes: 0 });
+        return answer;
+    }
+    /** The server's answer, starting one if `ensure` may; `undefined` when there is none to be had. */
+    async #askServer(request) {
+        // Once, even when a server answers: it may be another build's, and only `ensure` replaces one a
+        // command started (`BUG-66` — an old server refused opcodes this build sends).
+        if (this.#ensure && !this.#ensured) {
+            this.#ensured = true;
+            await this.#ensure();
+        }
+        try {
+            return await this.#ask(request);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "ECONNREFUSED" && code !== "ENOENT")
+                throw error;
+            if (!this.#ensure || !(await this.#ensure())) {
+                if (this.#ensure) {
+                    throw new CliError("network_error", "`max serve` did not start, and this profile shares one connection (`serve: true`) — " +
+                        "its log is beside the profile's state; `--no-serve` runs this command on its own");
+                }
+                return undefined;
+            }
+            return this.#ask(request);
+        }
+    }
+    #sameAccount(login) {
+        const profile = login.profile;
+        const viewerId = this.#store.readState().viewerId;
+        return viewerId === undefined || asId(profile?.contact?.id) === viewerId;
+    }
+    async close() {
+        for (const { reject, timer } of this.#pending.values()) {
+            clearTimeout(timer);
+            reject(new Error("the connection was closed before max serve answered"));
+        }
+        this.#pending.clear();
+        this.#socket?.destroy();
+        this.#socket = undefined;
+        await this.#own?.close();
+    }
+    /** Before anything was sent: the command runs on its own connection, as with no server at all. */
+    async #fallBack(opcode, payload, watch) {
+        this.#socket?.destroy();
+        this.#socket = undefined;
+        this.#own = this.#direct();
+        await this.#own.open();
+        if (opcode === Opcode.LOGIN && this.#init)
+            await this.#own.invoke(Opcode.SESSION_INIT, this.#init);
+        return this.#own.invoke(opcode, payload, watch);
+    }
+    async #ask(request) {
+        const socket = await this.#connected();
+        this.#id += 1;
+        const id = this.#id;
+        const answer = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                reject(new Error(`max serve did not answer within ${this.#timeoutMs}ms`));
+            }, this.#timeoutMs);
+            this.#pending.set(id, { resolve, reject, timer });
+            socket.write(toLine({ id, ...request }));
+        });
+        const error = answer.error;
+        // The server's send guard: the same refusal, and so the same exit code, as the command's own.
+        if (error?.guard === true) {
+            const code = errorCodes.find((known) => known === error.code) ?? "permission_error";
+            throw new CliError(code, error.message ?? "the server's send guard refused it", error.details);
+        }
+        if (error?.code === "refused") {
+            throw new ProtocolError(error.message ?? "MAX refused it", Number(request.opcode), error.payload ?? null);
+        }
+        if (error?.code === "not_allowed") {
+            throw new CliError("configuration_error", `${error.message ?? "the server does not pass this on"} — the running max serve is older than this max; ` +
+                "stop it with `max server stop` and run the command again");
+        }
+        if (error)
+            throw new Error(error.message ?? "max serve could not do it");
+        return (answer.payload ?? {});
+    }
+    async #connected() {
+        if (this.#socket)
+            return this.#socket;
+        const socket = connect(this.#path);
+        await new Promise((resolve, reject) => {
+            socket.once("connect", () => resolve());
+            socket.once("error", reject);
+        });
+        socket.on("data", lineReader((line) => {
+            const answer = fromLine(line);
+            const waiting = this.#pending.get(Number(answer.id));
+            if (!waiting)
+                return;
+            clearTimeout(waiting.timer);
+            this.#pending.delete(Number(answer.id));
+            waiting.resolve(answer);
+        }));
+        socket.on("error", () => { });
+        socket.on("close", () => {
+            for (const { reject, timer } of this.#pending.values()) {
+                clearTimeout(timer);
+                reject(new Error("max serve went away"));
+            }
+            this.#pending.clear();
+            this.#socket = undefined;
+        });
+        this.#socket = socket;
+        return socket;
+    }
+}
+/**
+ * The operation the server passes on for this opcode, or `undefined` for one it does not: logging
+ * in is the server's own business, a login by QR or SMS is `max session start` on a connection of
+ * its own, and a reserved number is never sent at all.
+ */
+export const forwardedOperation = (opcode) => Object.values(OPERATIONS).find((operation) => operation.opcode === opcode && !operation.name.startsWith("session.") && !operation.name.startsWith("login."));
+/**
+ * Which operations this build passes on. Two builds can carry the same version number — a checkout
+ * of main against the published package — so the version alone does not tell a server that
+ * refuses a newer operation from one that does not.
+ */
+export const OPERATIONS_FINGERPRINT = createHash("sha256")
+    .update(Object.values(OPERATIONS)
+    .filter((operation) => forwardedOperation(operation.opcode) === operation)
+    .map((operation) => `${operation.name}:${operation.opcode}`)
+    .sort()
+    .join(","))
+    .digest("hex")
+    .slice(0, 16);
+/**
+ * Asks a running server to stop. `"refused"` is a server started by hand, which only Ctrl-C
+ * stops; `"none"` is nobody listening.
+ */
+export const stopServer = (path, { force = false } = {}) => new Promise((resolve) => {
+    const socket = connect(path);
+    let answer = "none";
+    const timer = setTimeout(() => {
+        socket.destroy();
+        resolve(answer);
+    }, 2000);
+    // `force` is a person's own `max serve --stop`, which a server started by hand obeys too.
+    socket.once("connect", () => socket.write(toLine({ id: 1, stop: true, ...(force ? { force } : {}) })));
+    socket.on("data", lineReader((line) => {
+        answer = fromLine(line).stopped === true ? "stopped" : "refused";
+    }));
+    socket.once("error", () => {
+        clearTimeout(timer);
+        resolve("none");
+    });
+    // After the answer, the server closes its end: stopped, it is gone once this fires.
+    socket.once("close", () => {
+        clearTimeout(timer);
+        resolve(answer);
+    });
+});
+/** What a running server says about itself, or `undefined` when nobody answers. */
+export const serverStatus = (path) => new Promise((resolve) => {
+    const socket = connect(path);
+    const done = (status) => {
+        clearTimeout(timer);
+        socket.destroy();
+        resolve(status);
+    };
+    const timer = setTimeout(() => done(undefined), 2000);
+    socket.once("connect", () => socket.write(toLine({ status: true })));
+    socket.on("data", lineReader((line) => done(fromLine(line))));
+    socket.once("error", () => done(undefined));
+});
+//# sourceMappingURL=server-connection.js.map

package/dist/server/server-connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-connection.js","sourceRoot":"","sources":["../../src/server/server-connection.ts"],"names":[],"mappings":"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"}

package/dist/server/server.d.ts

@@ -0,0 +1,88 @@
+import type { SendGuard } from "@wirecat/cli-messaging/sends";
+import { MaxClient, type MaxClientOptions } from "../client.js";
+import type { MessageChange, MessageHit } from "../domain/models.js";
+import { Connection, type ConnectionOptions } from "../protocol/connection.js";
+import type { SessionStore } from "../session/store.js";
+export type ServerEvent = {
+    event: "message";
+    message: MessageHit;
+} | {
+    event: "change";
+    change: MessageChange;
+} | {
+    event: "status";
+    connected: boolean;
+    at: string;
+    byHand?: boolean;
+    pid?: number;
+};
+export interface MaxServerOptions {
+    members?: (client: () => MaxClient | undefined) => {
+        start(): void;
+        stop(): Promise<void>;
+    };
+    store: SessionStore;
+    timeoutMs?: number;
+    /** One line for a person, on stderr. */
+    note: (line: string) => void;
+    /** Tests hand in a scripted MAX; the hooks must reach it. */
+    connection?: (hooks: Pick<ConnectionOptions, "onEvent" | "onClose" | "onError">) => Connection;
+    pingEveryMs?: number;
+    telemetryAfterMs?: number;
+    /** The least time between two background logins after the snapshot went stale. */
+    refreshEveryMs?: number;
+    retryAfterMs?: (attempt: number) => number;
+    /**
+     * **A command started it**, not a person. Only such a server stops when asked over its socket;
+     * one started by hand runs until Ctrl-C, whoever asks (the owner's rule, 2026-09-24).
+     */
+    startedByCommand?: boolean;
+    /**
+     * Stop after this long with nobody using it — no request, no `max watch`. Absent, it runs until
+     * stopped; a server started by a command gets one, or it would outlive every reason it had.
+     */
+    idleMs?: number;
+    /** One event per request, for `--trace` and the run log — pings included. */
+    events?: MaxClientOptions["events"];
+    /** Tests hand in their own; otherwise built from the profile's configuration for every write. */
+    guard?: () => SendGuard;
+}
+/**
+ * **One logged-in connection per profile, kept open** (`MAX-16`), and a Unix socket beside the
+ * profile's state for local readers.
+ *
+ * It reopens REQUIREMENTS §3 and §18 on purpose and only here: every other command stays one-shot.
+ * What it does on the wire copies web.max.ru — a ping every 30 s, MAX's pings answered, each new
+ * message acknowledged (`Connection` with `live`). It never marks anything read. It sends on its own
+ * only what the owner's reply rules answer, to the people and chats their audience allows (`NEED-645`).
+ *
+ * The socket answers `{"subscribe": true}` with a stream of `ServerEvent` lines and
+ * `{"status": true}` with one. For a command reusing the connection (`ServerConnection`) it answers
+ * `{"id", "login": true}` with the login it holds, and `{"id", "opcode", "payload"}` by passing the
+ * request to MAX — sends included (`NEED-229`). **Every write goes through the send guard here**,
+ * and is journaled here (`NEED-269`): anything of the owner's can write to this socket, not only a
+ * command that checked first. An operation the specification does not declare is not passed on.
+ */
+export declare class MaxServer {
+    #private;
+    /** Settles when the server stops — cleanly, or with the error that stopped it. */
+    readonly done: Promise<void>;
+    constructor(options: MaxServerOptions);
+    get connected(): boolean;
+    /** Logs in first: a token that does not work should fail here, before anything listens. */
+    start(): Promise<void>;
+    stop(error?: Error): Promise<void>;
+}
+/**
+ * **MAX answered the login and said no** — as opposed to a network that dropped or a MAX that did
+ * not answer. Only those two are retried. A refusal is not: a token MAX no longer takes will not
+ * start working, and a login repeated after the limit error kept a PyMax account locked (PyMax
+ * #106). Any refusal counts, not only the recognised limit, because what that error says is a claim
+ * (`NEED-266`).
+ */
+export declare const refusedLogin: (error: unknown) => boolean;
+/** Present while a server is being started in the background, so two commands do not start two. */
+export declare const startingPath: (store: SessionStore) => string;
+/** Whether something is listening on the socket — a live server, not a leftover file. */
+export declare const answers: (path: string) => Promise<boolean>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AAE7D,OAAO,EAGL,SAAS,EACT,KAAK,gBAAgB,EAGtB,MAAM,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAGpE,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAiB,MAAM,2BAA2B,CAAA;AAI7F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAQvD,MAAM,MAAM,WAAW,GACnB;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,GACzC;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GAC1C;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,SAAS,GAAG,SAAS,KAAK;QAAE,KAAK,IAAI,IAAI,CAAC;QAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAA;IAC3F,KAAK,EAAE,YAAY,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,wCAAwC;IACxC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,iBAAiB,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC,KAAK,UAAU,CAAA;IAC9F,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,kFAAkF;IAClF,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IAC1C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,6EAA6E;IAC7E,MAAM,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAA;IACnC,iGAAiG;IACjG,KAAK,CAAC,EAAE,MAAM,SAAS,CAAA;CACxB;AAyBD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAS;;IAgCpB,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAE5B,YAAY,OAAO,EAAE,gBAAgB,EAuBpC;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,2FAA2F;IACrF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CA2B3B;IAEK,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BvC;CAyaF;AAsBD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,UAAW,OAAO,KAAG,OAE+D,CAAA;AAK7G,mGAAmG;AACnG,eAAO,MAAM,YAAY,UAAW,YAAY,KAAG,MAA4C,CAAA;AAE/F,yFAAyF;AACzF,eAAO,MAAM,OAAO,SAAU,MAAM,KAAG,OAAO,CAAC,OAAO,CAQlD,CAAA"}