@leemour/max-cli 0.1.0

package/dist/program.js

@@ -0,0 +1,130 @@
+import { CliError, exitCodeFor, GENERIC_FAILURE, processStreams } from "@leemour/cli-core";
+import { Command, CommanderError } from "commander";
+import { accountCommand } from "./commands/account.js";
+import { cacheCommand } from "./commands/cache.js";
+import { chatsCommand } from "./commands/chats.js";
+import { contactsCommand } from "./commands/contacts.js";
+import { messagesCommand } from "./commands/messages.js";
+import { runsCommand } from "./commands/runs.js";
+import { sessionCommand } from "./commands/session.js";
+import { commandWords, liftProfile } from "./profile.js";
+import { VERSION } from "./version.js";
+/**
+ * The command tree, built fresh on each call.
+ *
+ * Commander is global state by default — `exitOverride` and the write hooks below turn it into a
+ * value a test can drive. A command that calls `process.exit` cannot be tested, and a CLI whose
+ * argument parsing is untested is a CLI that breaks on the day someone adds an option.
+ */
+export const createProgram = ({ out, err } = {}) => {
+    const program = new Command();
+    program
+        .name("max")
+        .usage("[profile] [options] <command>")
+        .description("A local command line interface for a personal MAX Messenger account\n\n" +
+        "The first word is the profile whenever it is not a command — `max personal chats list`.\n" +
+        "`MAX_PROFILE` says the same thing for a whole shell session; without either it is `default`.")
+        .version(VERSION, "-v, --version")
+        .option("--json", "machine-readable output: one JSON value on stdout, nothing else")
+        .option("--quiet", "diagnostics off")
+        .option("--verbose", "diagnostics on: ids and timings on stderr, never message content")
+        .option("--offline", "answer from what was recorded and never connect; fails if nothing was")
+        .option("--record", "keep this run under `max runs` — ids and timings, never message content")
+        .option("--no-record", "do not keep it, whatever the configuration says")
+        .showHelpAfterError();
+    // One resource per command, one action per subcommand — `max chats list`, `max messages send`.
+    // The shape `braze-cli` uses, and the reason there is no `max send`: an action is never a
+    // top-level command, so there is one rule instead of a list of exceptions.
+    program.addCommand(sessionCommand());
+    program.addCommand(accountCommand());
+    program.addCommand(chatsCommand());
+    program.addCommand(contactsCommand());
+    program.addCommand(messagesCommand());
+    program.addCommand(cacheCommand());
+    program.addCommand(runsCommand());
+    // Depth-first: Commander does not pass `configureOutput` down to a command added with
+    // `addCommand`, so `max messages --help` would write to the real terminal while the top level
+    // wrote to the injected streams — and a test reading stdout would see nothing at all.
+    if (out || err) {
+        forEachCommand(program, (command) => command.configureOutput({
+            writeOut: (text) => out?.(text),
+            writeErr: (text) => err?.(text),
+        }));
+    }
+    return program;
+};
+const forEachCommand = (command, apply) => {
+    apply(command);
+    for (const child of command.commands)
+        forEachCommand(child, apply);
+};
+/**
+ * Runs the program and **returns an exit code instead of throwing**.
+ *
+ * A stack trace is not an error message: it puts Node internals on stderr, tells a script nothing
+ * it can branch on, and exits 1 for every kind of failure alike. Here a failure becomes a code an
+ * agent can switch on, and a sentence a person can act on.
+ */
+export const run = async (argv, options = {}) => {
+    const streams = options.streams ?? processStreams;
+    const program = createProgram({
+        out: (text) => streams.data(text.replace(/\n$/, "")),
+        err: (text) => streams.diagnostic(text.replace(/\n$/, "")),
+    });
+    // Commander calls process.exit for --help and --version. A library that kills the process cannot
+    // be tested and cannot be embedded, so it throws instead and `run` decides the exit code.
+    //
+    // Depth-first, not one level: `max chats list --nonsense` is handled by the subcommand, and a
+    // subcommand left with the default behaviour kills the process from inside a test.
+    forEachCommand(program, (command) => command.exitOverride());
+    // Before commander, not inside it: a custom argument parser would still have to be told that
+    // the first word is sometimes a command, and commander has no hook that runs before it decides
+    // which subcommand it is looking at.
+    const { profile, rest } = liftProfile(argv, commandWords(program));
+    if (profile !== undefined)
+        program.setOptionValue("profile", profile);
+    // `max me` — a command that was renamed away — is now a profile with nothing after it, and
+    // commander answers a missing command by printing help **on stdout**. That breaks the one
+    // contract this program has, and it tells the person nothing about why their command vanished.
+    if (profile !== undefined && rest.length === 0) {
+        report(streams, options, {
+            code: "validation_error",
+            message: `"${profile}" is not a command, so it was read as a profile name — and no command followed it. ` +
+                `Run \`max --help\` for the commands, or \`max ${profile} account show\` if "${profile}" is your profile.`,
+        });
+        return exitCodeFor("validation_error");
+    }
+    try {
+        await program.parseAsync(rest, { from: "user" });
+        return process.exitCode === undefined ? 0 : Number(process.exitCode);
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            // `max chat list` — one letter short of `chats` — now reports an unknown command `list`,
+            // which is baffling on its own. This is the everyday cost of the first word being a profile.
+            if (profile !== undefined && error.code === "commander.unknownCommand") {
+                streams.diagnostic(`"${profile}" is not a command, so it was read as a profile name — which left "${rest[0]}" to be one.`);
+            }
+            return error.exitCode;
+        }
+        if (error instanceof CliError) {
+            report(streams, options, { code: error.code, message: error.message, ...error.details });
+            return exitCodeFor(error.code);
+        }
+        report(streams, options, {
+            code: "generic_failure",
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return GENERIC_FAILURE;
+    }
+};
+/**
+ * **A failure never reaches stdout.** An agent reading stdout must not be able to mistake a refusal
+ * for a result, so the error goes to stderr — as JSON when nobody is watching, because an exit code
+ * says which kind of thing went wrong and nothing about which chat or how long to wait.
+ */
+const report = (streams, options, error) => {
+    const interactive = options.tty ?? process.stdout.isTTY === true;
+    streams.diagnostic(interactive ? `\u2717 ${error.message}` : JSON.stringify({ error }));
+};
+//# sourceMappingURL=program.js.map

package/dist/program.js.map

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

package/dist/protocol/connection.d.ts

@@ -0,0 +1,60 @@
+import { WebSocket } from "ws";
+import { type InboundFrame, type Payload } from "./frame.js";
+export declare const MAX_WEBSOCKET_URL = "wss://ws-api.oneme.ru/websocket";
+/** MAX's web client sends this; we send what it sends rather than announcing ourselves (§34). */
+export declare const WEB_ORIGIN = "https://web.max.ru";
+/**
+ * What one frame cost, reported as it happens.
+ *
+ * The transport is the only layer that knows the `seq` it allocated and how many bytes actually
+ * went over the socket, and it is the only one that can time the wait. It reports those and
+ * nothing else — **who is asking, and why, stays above it** (`ARCHITECTURE.md` §2).
+ */
+export interface WireEvent {
+    phase: "sent" | "received";
+    seq: number;
+    opcode: number;
+    bytes: number;
+}
+export interface ConnectionOptions {
+    url?: string;
+    origin?: string;
+    /** Per request, not per connection. */
+    timeoutMs?: number;
+    /** Events MAX pushes on its own — messages arriving, presence. Ignored unless a caller cares. */
+    onEvent?: (frame: InboundFrame) => void;
+    /** Injected in tests; defaults to the real `ws` client. */
+    createSocket?: (url: string, origin: string) => WebSocket;
+}
+export declare class ProtocolError extends Error {
+    readonly opcode: number;
+    readonly payload: Payload | null;
+    constructor(message: string, opcode: number, payload: Payload | null);
+}
+/**
+ * One WebSocket, one command's worth of work, then closed.
+ *
+ * **Everything that could keep the process alive is owned here**: the socket, the per-request
+ * timers and the listeners. `close()` clears all three, and a command that opens a connection
+ * closes it in a `finally` — a CLI that prints its result and then hangs is a defect, not a rough
+ * edge (REQUIREMENTS §18).
+ */
+export declare class Connection {
+    #private;
+    constructor(options?: ConnectionOptions);
+    open(): Promise<void>;
+    /**
+     * Sends one request and waits for the response carrying the same `seq`.
+     *
+     * MAX interleaves pushed events with responses on one socket, so the `seq` is the only thing
+     * tying an answer to its question — a reader that takes the next frame as its answer will
+     * eventually read somebody's incoming message instead.
+     *
+     * `watch` is told what left and what came back, for the caller that is keeping a diagnostic. It
+     * is called synchronously on the way out, so a request that never gets an answer is still on
+     * record — which is the run somebody actually wants to read.
+     */
+    invoke(opcode: number, payload?: Payload, watch?: (event: WireEvent) => void): Promise<Payload>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/protocol/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/protocol/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAA;AAC9B,OAAO,EAAqC,KAAK,YAAY,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAA;AAE/F,eAAO,MAAM,iBAAiB,oCAAoC,CAAA;AAClE,iGAAiG;AACjG,eAAO,MAAM,UAAU,uBAAuB,CAAA;AAE9C;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,GAAG,UAAU,CAAA;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iGAAiG;IACjG,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IACvC,2DAA2D;IAC3D,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,SAAS,CAAA;CAC1D;AAED,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;gBAEpB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;CAMrE;AAED;;;;;;;GAOG;AACH,qBAAa,UAAU;;gBAmBT,OAAO,GAAE,iBAAsB;IAQrC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB3B;;;;;;;;;;OAUG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,OAAY,EAAE,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC;IAoCnG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAuC7B"}

package/dist/protocol/connection.js

@@ -0,0 +1,142 @@
+import { WebSocket } from "ws";
+import { Command, decodeFrame, encodeFrame } from "./frame.js";
+export const MAX_WEBSOCKET_URL = "wss://ws-api.oneme.ru/websocket";
+/** MAX's web client sends this; we send what it sends rather than announcing ourselves (§34). */
+export const WEB_ORIGIN = "https://web.max.ru";
+export class ProtocolError extends Error {
+    opcode;
+    payload;
+    constructor(message, opcode, payload) {
+        super(message);
+        this.name = "ProtocolError";
+        this.opcode = opcode;
+        this.payload = payload;
+    }
+}
+/**
+ * One WebSocket, one command's worth of work, then closed.
+ *
+ * **Everything that could keep the process alive is owned here**: the socket, the per-request
+ * timers and the listeners. `close()` clears all three, and a command that opens a connection
+ * closes it in a `finally` — a CLI that prints its result and then hangs is a defect, not a rough
+ * edge (REQUIREMENTS §18).
+ */
+export class Connection {
+    #url;
+    #origin;
+    #timeoutMs;
+    #onEvent;
+    #createSocket;
+    #pending = new Map();
+    #socket;
+    #seq = 0;
+    #closed = false;
+    constructor(options = {}) {
+        this.#url = options.url ?? MAX_WEBSOCKET_URL;
+        this.#origin = options.origin ?? WEB_ORIGIN;
+        this.#timeoutMs = options.timeoutMs ?? 30_000;
+        this.#onEvent = options.onEvent;
+        this.#createSocket = options.createSocket ?? ((url, origin) => new WebSocket(url, { headers: { Origin: origin } }));
+    }
+    async open() {
+        if (this.#socket)
+            return;
+        const socket = this.#createSocket(this.#url, this.#origin);
+        this.#socket = socket;
+        await new Promise((resolve, reject) => {
+            const onOpen = () => {
+                socket.off("error", onError);
+                resolve();
+            };
+            const onError = (error) => {
+                socket.off("open", onOpen);
+                reject(error);
+            };
+            socket.once("open", onOpen);
+            socket.once("error", onError);
+        });
+        socket.on("message", (data) => this.#receive(String(data)));
+        socket.on("close", () => this.#failAll(new Error("MAX closed the connection")));
+        socket.on("error", (error) => this.#failAll(error));
+    }
+    /**
+     * Sends one request and waits for the response carrying the same `seq`.
+     *
+     * MAX interleaves pushed events with responses on one socket, so the `seq` is the only thing
+     * tying an answer to its question — a reader that takes the next frame as its answer will
+     * eventually read somebody's incoming message instead.
+     *
+     * `watch` is told what left and what came back, for the caller that is keeping a diagnostic. It
+     * is called synchronously on the way out, so a request that never gets an answer is still on
+     * record — which is the run somebody actually wants to read.
+     */
+    async invoke(opcode, payload = {}, watch) {
+        if (!Number.isInteger(opcode)) {
+            // A typo in an opcode constant is otherwise a round trip to MAX that comes back
+            // "неизвестный opcode", which reads as the protocol's fault rather than ours.
+            throw new Error(`refusing to send a frame with a non-integer opcode: ${String(opcode)}`);
+        }
+        if (!this.#socket)
+            throw new Error("the connection is not open");
+        if (this.#closed)
+            throw new Error("the connection is closed");
+        this.#seq += 1;
+        const seq = this.#seq;
+        const socket = this.#socket;
+        const answer = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(seq);
+                reject(new Error(`MAX did not answer opcode ${opcode} within ${this.#timeoutMs}ms`));
+            }, this.#timeoutMs);
+            this.#pending.set(seq, { resolve, reject, timer });
+            const sent = encodeFrame({ seq, opcode, payload });
+            socket.send(sent);
+            watch?.({ phase: "sent", seq, opcode, bytes: Buffer.byteLength(sent) });
+        });
+        const frame = answer.frame;
+        watch?.({ phase: "received", seq, opcode, bytes: answer.bytes });
+        if (frame.cmd === Command.ERROR) {
+            const reason = typeof frame.payload?.error === "string" ? frame.payload.error : "an error with no reason given";
+            throw new ProtocolError(`MAX refused opcode ${opcode}: ${reason}`, opcode, frame.payload);
+        }
+        return frame.payload ?? {};
+    }
+    async close() {
+        this.#closed = true;
+        const socket = this.#socket;
+        this.#socket = undefined;
+        for (const { timer } of this.#pending.values())
+            clearTimeout(timer);
+        this.#pending.clear();
+        if (!socket)
+            return;
+        socket.removeAllListeners();
+        if (socket.readyState === socket.OPEN || socket.readyState === socket.CONNECTING)
+            socket.close();
+    }
+    #receive(raw) {
+        let frame;
+        try {
+            frame = decodeFrame(raw);
+        }
+        catch {
+            return; // A frame we cannot read is not a reason to fail a request we can.
+        }
+        const waiting = frame.seq === null ? undefined : this.#pending.get(frame.seq);
+        if (!waiting) {
+            this.#onEvent?.(frame);
+            return;
+        }
+        clearTimeout(waiting.timer);
+        this.#pending.delete(frame.seq);
+        waiting.resolve({ frame, bytes: Buffer.byteLength(raw) });
+    }
+    #failAll(error) {
+        for (const { reject, timer } of this.#pending.values()) {
+            clearTimeout(timer);
+            reject(error);
+        }
+        this.#pending.clear();
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/protocol/connection.js.map

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

package/dist/protocol/frame.d.ts

@@ -0,0 +1,44 @@
+/** The protocol version the web client pins. Confirmed in tsmax, maxrs and max-api-docs. */
+export declare const PROTOCOL_VERSION = 11;
+export declare const Command: {
+    readonly REQUEST: 0;
+    readonly RESPONSE: 1;
+    readonly EVENT: 2;
+    readonly ERROR: 3;
+};
+export type Command = (typeof Command)[keyof typeof Command];
+export type Payload = Record<string, unknown>;
+export interface OutboundFrame {
+    seq: number;
+    opcode: number;
+    payload: Payload;
+    cmd?: Command;
+}
+export interface InboundFrame {
+    ver: number;
+    cmd: number;
+    seq: number | null;
+    opcode: number;
+    payload: Payload | null;
+}
+export declare const encodeFrame: (frame: OutboundFrame) => string;
+/**
+ * **Never `JSON.parse`.** Message ids are 64-bit and past `Number.MAX_SAFE_INTEGER` — 18 digits,
+ * measured — so the built-in parser rounds them and two different messages arrive as one id.
+ * `lossless-json` hands back a bigint for any integer that would not survive, and every id leaves
+ * this layer as a string.
+ *
+ * ⚠ Measured 2026-09-19: **chat ids on the owner's account reach 14 digits, not 19**, and contact
+ * ids reach 9 — all comfortably inside a number. The hazard is real and it is the message ids that
+ * carry it; a 19-digit chat id is an illustration, not something seen.
+ */
+export declare const decodeFrame: (raw: string) => InboundFrame;
+export declare class FrameError extends Error {
+    constructor(what: string);
+}
+/**
+ * Ids arrive as `number` when small and `bigint` when not, and both have to render identically.
+ * A domain id is a string from here on — it is an identifier, never arithmetic.
+ */
+export declare const asId: (value: unknown) => string | undefined;
+//# sourceMappingURL=frame.d.ts.map

package/dist/protocol/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../src/protocol/frame.ts"],"names":[],"mappings":"AAEA,4FAA4F;AAC5F,eAAO,MAAM,gBAAgB,KAAK,CAAA;AAElC,eAAO,MAAM,OAAO;;;;;CAKV,CAAA;AACV,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,OAAO,OAAO,CAAC,CAAA;AAE5D,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE7C,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,OAAO,CAAA;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;CACxB;AAED,eAAO,MAAM,WAAW,GAAI,OAAO,aAAa,KAAG,MAOrC,CAAA;AAEd;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,YAczC,CAAA;AAED,qBAAa,UAAW,SAAQ,KAAK;gBACvB,IAAI,EAAE,MAAM;CAIzB;AAED;;;GAGG;AACH,eAAO,MAAM,IAAI,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SAK9C,CAAA"}

package/dist/protocol/frame.js

@@ -0,0 +1,68 @@
+import { isInteger, isSafeNumber, parse, stringify } from "lossless-json";
+/** The protocol version the web client pins. Confirmed in tsmax, maxrs and max-api-docs. */
+export const PROTOCOL_VERSION = 11;
+export const Command = {
+    REQUEST: 0,
+    RESPONSE: 1,
+    EVENT: 2,
+    ERROR: 3,
+};
+export const encodeFrame = (frame) => stringify({
+    ver: PROTOCOL_VERSION,
+    cmd: frame.cmd ?? Command.REQUEST,
+    seq: frame.seq,
+    opcode: frame.opcode,
+    payload: frame.payload,
+});
+/**
+ * **Never `JSON.parse`.** Message ids are 64-bit and past `Number.MAX_SAFE_INTEGER` — 18 digits,
+ * measured — so the built-in parser rounds them and two different messages arrive as one id.
+ * `lossless-json` hands back a bigint for any integer that would not survive, and every id leaves
+ * this layer as a string.
+ *
+ * ⚠ Measured 2026-09-19: **chat ids on the owner's account reach 14 digits, not 19**, and contact
+ * ids reach 9 — all comfortably inside a number. The hazard is real and it is the message ids that
+ * carry it; a 19-digit chat id is an illustration, not something seen.
+ */
+export const decodeFrame = (raw) => {
+    const value = parse(raw, undefined, {
+        parseNumber: (text) => (isInteger(text) && !isSafeNumber(text) ? BigInt(text) : Number(text)),
+    });
+    if (!isRecord(value))
+        throw new FrameError("a frame that is not an object");
+    return {
+        ver: header(value.ver, "ver"),
+        cmd: header(value.cmd ?? Command.RESPONSE, "cmd"),
+        seq: value.seq === null || value.seq === undefined ? null : header(value.seq, "seq"),
+        opcode: header(value.opcode, "opcode"),
+        payload: isRecord(value.payload) ? value.payload : null,
+    };
+};
+export class FrameError extends Error {
+    constructor(what) {
+        super(`MAX sent ${what}`);
+        this.name = "FrameError";
+    }
+}
+/**
+ * Ids arrive as `number` when small and `bigint` when not, and both have to render identically.
+ * A domain id is a string from here on — it is an identifier, never arithmetic.
+ */
+export const asId = (value) => {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    if (typeof value === "string" && value !== "")
+        return value;
+    return undefined;
+};
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const header = (value, field) => {
+    const asNumber = typeof value === "bigint" ? Number(value) : value;
+    if (typeof asNumber !== "number" || !Number.isSafeInteger(asNumber)) {
+        throw new FrameError(`a frame whose \`${field}\` is not a whole number`);
+    }
+    return asNumber;
+};
+//# sourceMappingURL=frame.js.map

package/dist/protocol/frame.js.map

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

package/dist/runs/events.d.ts

@@ -0,0 +1,92 @@
+import type { Payload } from "../protocol/frame.js";
+/**
+ * One request, as both sinks see it: `--verbose` renders it, the run log writes it as a line of
+ * JSON. **One object, two sinks** — a second shape for one of them is how the two start disagreeing
+ * about what happened.
+ *
+ * ⚠ **Nothing here may carry content.** The operation, the opcode, the `seq`, the ids a request
+ * named, byte counts and durations are safe: an id is opaque and can only be correlated by whoever
+ * already has the session. A chat title, a person's name, a message body, a phone number or a token
+ * are not — not truncated and not hashed (`REQUIREMENTS.md` §14, §24). The fields below are the
+ * whole vocabulary, and `idsOf` builds them from named fields rather than filtering a copy of the
+ * payload, so there is no path by which an unforeseen field arrives here.
+ */
+export interface RequestEvent {
+    event: "request" | "response";
+    /** Ours, not MAX's: `chats.history`, not `CHAT_HISTORY`. */
+    operation: string;
+    opcode: number;
+    seq: number;
+    /** The frame that went out, or the one that came back. Absent when nothing came back. */
+    bytes?: number;
+    /** Which things the request named — `{ chat: "0" }`. Never how they are called. */
+    ids?: Record<string, string>;
+    /** How many things, per field: `{ messages: 3 }`. A field name and a length carry no content. */
+    counts?: Record<string, number>;
+    durationMs?: number;
+    outcome?: "ok" | "error";
+    /** `cli-core`'s code — `timeout`, `provider_error`. Never the message: MAX quotes our payload. */
+    errorCode?: string;
+}
+/**
+ * A read that never reached MAX.
+ *
+ * It is not a request and must not be shaped like one — there is no opcode, no `seq` and no frame,
+ * and calling a local answer "request 0 bytes" would put a fiction in the record. The call sites
+ * belong to the cache (`MAX-7`); what lives here is the vocabulary, so that the two of them cannot
+ * drift into two shapes for one diagnostic.
+ */
+export interface CacheEvent {
+    event: "cache";
+    /** Ours: `chats.list`, `messages.list`. */
+    operation: string;
+    reason: CacheReason;
+    ids?: Record<string, string>;
+    counts?: Record<string, number>;
+    /** How old the local answer was. The number a person wants when a list looks wrong. */
+    ageMs?: number;
+}
+/**
+ * Why MAX was not asked. **"We did not ask" and "there was nothing to ask" are different events**,
+ * and only the second is the record doing its job rather than standing in for a connection.
+ *
+ * Written out as two words rather than a free string so that the vocabulary has one home and a
+ * third case has to be added here, deliberately, instead of appearing in a log nobody can group.
+ */
+export type CacheReason = 
+/** The caller said never connect, so the record is all there is. */
+"offline"
+/** The window asked for is older than a fetch would return, so the record is authoritative. */
+ | "history";
+/** What either sink is handed. One object, two sinks — see `RequestEvent`. */
+export type DiagnosticEvent = RequestEvent | CacheEvent;
+/**
+ * The ids a request named, by name, from a list of fields that is written out here.
+ *
+ * **An allowlist, never a filter.** Copying the request and removing what looks dangerous means a
+ * field nobody has seen yet arrives in the log by default; this way it cannot. `token` is the case
+ * that matters: it is a field of `session.login` and there is no branch here that could reach it.
+ */
+export declare const idsOf: (request: unknown) => {
+    ids?: Record<string, string>;
+    counts?: Record<string, number>;
+};
+/**
+ * How many of each list MAX sent back — `{ chats: 25, contacts: 6 }`.
+ *
+ * Every array at the top of the answer, counted. Generic on purpose: a per-operation table of
+ * "which field is the interesting one" is a second registry to keep in step with `src/spec/`, and
+ * a field name with a length beside it is content-free whatever MAX adds next.
+ */
+export declare const countsIn: (payload: Payload) => Record<string, number> | undefined;
+/**
+ * The line a person reads. `→` is what we asked, `←` what came back, `•` what never left.
+ *
+ * ```text
+ * → chats.history    op 49  seq 3  chat 0
+ * ← chats.history    op 49  seq 3  118ms  4.2 kB  3 messages
+ * • chats.list       offline  cached 42s  25 chats
+ * ```
+ */
+export declare const renderEvent: (event: DiagnosticEvent) => string;
+//# sourceMappingURL=events.d.ts.map

package/dist/runs/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/runs/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAEnD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,SAAS,GAAG,UAAU,CAAA;IAC7B,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mFAAmF;IACnF,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,IAAI,GAAG,OAAO,CAAA;IACxB,kGAAkG;IAClG,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAA;IACd,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,WAAW,CAAA;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;GAMG;AACH,MAAM,MAAM,WAAW;AACrB,oEAAoE;AAClE,SAAS;AACX,+FAA+F;GAC7F,SAAS,CAAA;AAEb,8EAA8E;AAC9E,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,UAAU,CAAA;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,GAAI,SAAS,OAAO,KAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAqBvG,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,SAAS,OAAO,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAIpE,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,eAAe,KAAG,MAqBpD,CAAA"}