@wirecat/max-cli 0.0.0-stage → 0.42.0

package/dist/profile.d.ts

@@ -0,0 +1,33 @@
+import type { Command } from "commander";
+export declare const DEFAULT_PROFILE = "default";
+/** How the command line names this profile: the first word, or nothing at all for the default. */
+export declare const asFirstWord: (profile: string) => string;
+export declare const usableProfileName: (profile: string) => string;
+/**
+ * Every word that means a command at the top level.
+ *
+ * Taken off the built program rather than written out, because a list written out goes stale the
+ * day a command is added — and `help` is in it without being in `program.commands`: commander
+ * answers `max help chats` from an implicit command that is not in that array.
+ */
+export declare const commandWords: (program: Command) => Set<string>;
+/**
+ * **The first word is the profile unless it names a command.** `max personal chats list`, and
+ * `max chats list` on the default profile, with no flag in either.
+ *
+ * An option is never a profile, so `max --json chats list` still works.
+ */
+export declare const liftProfile: (argv: string[], words: Set<string>) => {
+    profile?: string;
+    rest: string[];
+};
+/**
+ * Refused at creation, which is the only moment it can still be explained.
+ *
+ * A profile named after a command breaks silently and in the other direction: `max chats` would
+ * have to mean the command, so the profile called `chats` could never be selected at all.
+ */
+export declare const refuseCommandName: (profile: string, words: Set<string>) => void;
+/** The root of the command tree, from anywhere inside it. */
+export declare const rootOf: (command: Command) => Command;
+//# sourceMappingURL=profile.d.ts.map

package/dist/profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../src/profile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAExC,eAAO,MAAM,eAAe,YAAY,CAAA;AAExC,kGAAkG;AAClG,eAAO,MAAM,WAAW,YAAa,MAAM,KAAG,MAA4D,CAAA;AAW1G,eAAO,MAAM,iBAAiB,YAAa,MAAM,KAAG,MASnD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,YAAa,OAAO,KAAG,GAAG,CAAC,MAAM,CAC2C,CAAA;AAErG;;;;;GAKG;AACH,eAAO,MAAM,WAAW,SAAU,MAAM,EAAE,SAAS,GAAG,CAAC,MAAM,CAAC,KAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAIlG,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,YAAa,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,KAAG,IASvE,CAAA;AAED,6DAA6D;AAC7D,eAAO,MAAM,MAAM,YAAa,OAAO,KAAG,OAIzC,CAAA"}

package/dist/profile.js

@@ -0,0 +1,60 @@
+import { CliError } from "@wirecat/cli-core";
+export const DEFAULT_PROFILE = "default";
+/** How the command line names this profile: the first word, or nothing at all for the default. */
+export const asFirstWord = (profile) => (profile === DEFAULT_PROFILE ? "" : `${profile} `);
+/**
+ * A profile name becomes a file name — `<state>/profiles/<name>.json` (`session/store.ts:103`) —
+ * and the keyring account is the same string.
+ *
+ * The first word on the command line is now the profile, so a mistyped path arrives here as a
+ * name, and `a/../b` would write that file somewhere nobody would think to look.
+ */
+const PLAIN_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export const usableProfileName = (profile) => {
+    if (!PLAIN_NAME.test(profile)) {
+        throw new CliError("validation_error", `"${profile}" cannot be a profile name — letters, digits, dot, dash and underscore only, ` +
+            "starting with a letter or a digit");
+    }
+    return profile;
+};
+/**
+ * Every word that means a command at the top level.
+ *
+ * Taken off the built program rather than written out, because a list written out goes stale the
+ * day a command is added — and `help` is in it without being in `program.commands`: commander
+ * answers `max help chats` from an implicit command that is not in that array.
+ */
+export const commandWords = (program) => new Set(["help", ...program.commands.flatMap((command) => [command.name(), ...command.aliases()])]);
+/**
+ * **The first word is the profile unless it names a command.** `max personal chats list`, and
+ * `max chats list` on the default profile, with no flag in either.
+ *
+ * An option is never a profile, so `max --json chats list` still works.
+ */
+export const liftProfile = (argv, words) => {
+    const [first, ...rest] = argv;
+    if (first === undefined || first.startsWith("-") || words.has(first))
+        return { rest: argv };
+    return { profile: first, rest };
+};
+/**
+ * Refused at creation, which is the only moment it can still be explained.
+ *
+ * A profile named after a command breaks silently and in the other direction: `max chats` would
+ * have to mean the command, so the profile called `chats` could never be selected at all.
+ */
+export const refuseCommandName = (profile, words) => {
+    if (words.has(profile)) {
+        throw new CliError("validation_error", `"${profile}" is a command, so \`max ${profile} …\` would always mean the command and never ` +
+            "this profile. Pick a name that is not one of: " +
+            [...words].sort().join(", "));
+    }
+};
+/** The root of the command tree, from anywhere inside it. */
+export const rootOf = (command) => {
+    let root = command;
+    while (root.parent)
+        root = root.parent;
+    return root;
+};
+//# sourceMappingURL=profile.js.map

package/dist/profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.js","sourceRoot":"","sources":["../src/profile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAG5C,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAA;AAExC,kGAAkG;AAClG,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAe,EAAU,EAAE,CAAC,CAAC,OAAO,KAAK,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC,CAAA;AAE1G;;;;;;GAMG;AACH,MAAM,UAAU,GAAG,8BAA8B,CAAA;AAEjD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,OAAe,EAAU,EAAE;IAC3D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,QAAQ,CAChB,kBAAkB,EAClB,IAAI,OAAO,+EAA+E;YACxF,mCAAmC,CACtC,CAAA;IACH,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAgB,EAAe,EAAE,CAC5D,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;AAErG;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAc,EAAE,KAAkB,EAAwC,EAAE;IACtG,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAA;IAC7B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IAC3F,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;AACjC,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,OAAe,EAAE,KAAkB,EAAQ,EAAE;IAC7E,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,QAAQ,CAChB,kBAAkB,EAClB,IAAI,OAAO,4BAA4B,OAAO,+CAA+C;YAC3F,gDAAgD;YAChD,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAC/B,CAAA;IACH,CAAC;AACH,CAAC,CAAA;AAED,6DAA6D;AAC7D,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,OAAgB,EAAW,EAAE;IAClD,IAAI,IAAI,GAAG,OAAO,CAAA;IAClB,OAAO,IAAI,CAAC,MAAM;QAAE,IAAI,GAAG,IAAI,CAAC,MAAM,CAAA;IACtC,OAAO,IAAI,CAAA;AACb,CAAC,CAAA"}

package/dist/program.d.ts

@@ -0,0 +1,10 @@
+import { type ProgramOptions } from "@wirecat/cli-messaging/cli";
+import type { Command } from "commander";
+import { type Environment } from "./commands/context.js";
+export type { ProgramOptions };
+export interface RunOptions extends Environment {
+    answer?: (question: string) => string | null | Promise<string | null>;
+}
+export declare const createProgram: (options?: ProgramOptions) => Command;
+export declare const run: (argv: string[], options?: RunOptions) => Promise<number>;
+//# sourceMappingURL=program.d.ts.map

package/dist/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAGA,OAAO,EAQL,KAAK,cAAc,EAapB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAWxC,OAAO,EAAE,KAAK,WAAW,EAAW,MAAM,uBAAuB,CAAA;AAyBjE,YAAY,EAAE,cAAc,EAAE,CAAA;AAE9B,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CACtE;AAqGD,eAAO,MAAM,aAAa,aAAa,cAAc,KAAQ,OAAqD,CAAA;AAElH,eAAO,MAAM,GAAG,SAAgB,MAAM,EAAE,YAAW,UAAU,KAAQ,OAAO,CAAC,MAAM,CAgBlF,CAAA"}

package/dist/program.js

@@ -0,0 +1,172 @@
+import { appendFileSync } from "node:fs";
+import { CliError, processStreams } from "@wirecat/cli-core";
+import { metaOf } from "@wirecat/cli-core/commands";
+import { attachmentsCommand, conversationsCommand, createProgram as createSharedProgram, floodCommand, inboxCommand, metadataCommand, pollsCommand, provide as provideShared, reactionsCommand, repliesCommand, reviewCommand, run as runShared, searchCommand, searchesCommand, storeCommand as sharedStoreCommand, statsCommand, tagsCommand, tasksCommand, } from "@wirecat/cli-messaging/cli";
+import { levelFor } from "@wirecat/cli-messaging/sends";
+import { MAX_APP } from "./app.js";
+import { accountCommand } from "./commands/account.js";
+import { botCommand } from "./commands/bot.js";
+import { botRecordingOf } from "./commands/bot-context.js";
+import { callsCommand } from "./commands/calls.js";
+import { chatsCommand } from "./commands/chats.js";
+import { commandsCommand } from "./commands/commands.js";
+import { completeCommand } from "./commands/complete.js";
+import { configCommand } from "./commands/config.js";
+import { contactsCommand } from "./commands/contacts.js";
+import { provide } from "./commands/context.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { mcpCommand } from "./commands/mcp.js";
+import { messagesCommand } from "./commands/messages.js";
+import { modelsCommand } from "./commands/models.js";
+import { recipientsCommand } from "./commands/recipients.js";
+import { runsCommand } from "./commands/runs.js";
+import { sendsCommand } from "./commands/sends.js";
+import { serveCommand } from "./commands/serve.js";
+import { serverCommand } from "./commands/server.js";
+import { sessionCommand } from "./commands/session.js";
+import { setupCommand } from "./commands/setup.js";
+import { skillCommand } from "./commands/skill.js";
+import { stickersCommand } from "./commands/stickers.js";
+import { upgradeCommand } from "./commands/upgrade.js";
+import { watchCommand } from "./commands/watch.js";
+import { resolveSettings } from "./config.js";
+import { migrateInboxPoint } from "./inbox-point.js";
+import { maxMessenger } from "./messenger.js";
+import { assertReadable, commandPermission, permissionScope } from "./permissions.js";
+import { rootOf } from "./profile.js";
+import { modelsDirectory } from "./transcribe/install.js";
+import { updateNotice } from "./update.js";
+const definition = (options = {}) => ({
+    app: {
+        ...MAX_APP,
+        description: "MAX Messenger from the terminal: bots through the official Bot API (`max bot …`), and your personal account",
+    },
+    configuration: { resolveSettings },
+    commands: () => [
+        sessionCommand(),
+        setupCommand(),
+        accountCommand(),
+        callsCommand(),
+        stickersCommand(),
+        chatsCommand(),
+        contactsCommand(),
+        messagesCommand(),
+        sharedStoreCommand(maxMessenger),
+        statsCommand(maxMessenger),
+        tasksCommand(maxMessenger),
+        conversationsCommand(maxMessenger),
+        attachmentsCommand(maxMessenger),
+        tagsCommand(maxMessenger),
+        metadataCommand(maxMessenger),
+        searchCommand(maxMessenger),
+        searchesCommand(maxMessenger),
+        floodCommand(maxMessenger),
+        modelsCommand(),
+        pollsCommand(maxMessenger),
+        reactionsCommand(maxMessenger),
+        recipientsCommand(),
+        sendsCommand(),
+        inboxCommand(maxMessenger).hook("preAction", (command) => migrateInboxPoint(command)),
+        reviewCommand(maxMessenger),
+        repliesCommand(maxMessenger),
+        serveCommand(),
+        serverCommand(),
+        watchCommand(),
+        configCommand(),
+        doctorCommand(),
+        runsCommand(),
+        skillCommand(),
+        commandsCommand(),
+        upgradeCommand(),
+        completeCommand(),
+        mcpCommand(),
+        botCommand(),
+    ],
+    configure: (program) => {
+        program.addHelpText("after", "\nGetting started after installation:\n" +
+            "  max setup                    Guided personal-account login; allow about 5 minutes\n" +
+            "  max setup --agent codex      Connect the skill for your agent\n" +
+            "  max setup --help             Login methods, Windows advice and examples\n" +
+            "\nAgents: read `max skill show` before login; `max commands --json` lists commands.\n" +
+            "Choose a chat and how much history to fetch after setup.\n" +
+            "Bots: `max <profile> bot auth set` connects a bot separately.\n");
+        program
+            .option("--serve", "start `max serve` in the background if it is not running (the default)")
+            .option("--no-serve", "do not start it; log in on this command's own connection unless one is running");
+        const descriptions = {
+            "--trace": "one line per request on stderr: ids and timings, never message content",
+            "--record": "keep this run under `max runs` — ids and timings, never message content",
+            "--quiet": "diagnostics off",
+        };
+        for (const option of program.options) {
+            const description = descriptions[option.long ?? ""];
+            if (description)
+                option.description = description;
+        }
+        program.hook("preAction", (_root, action) => {
+            const key = commandPermission(action);
+            if (key) {
+                const settings = resolveSettings(rootOf(action).opts(), { kind: key.startsWith("bot.") ? "bot" : "personal" });
+                assertReadable(settings, key);
+                if (metaOf(action).mutates && metaOf(action).local && levelFor(settings.permissions, key).level === "readonly")
+                    throw new CliError("permission_error", `profile ${settings.profile} does not let ${key} write`, {
+                        permission: key,
+                    });
+            }
+        });
+        const argvLog = process.env.MAX_TEST_ARGV_LOG;
+        if (argvLog)
+            program.hook("preAction", (_root, action) => logParsed(argvLog, action));
+    },
+    prepare: (program, environment) => {
+        provide(program, {
+            ...options,
+            streams: environment.streams ?? processStreams,
+            signal: environment.signal,
+            commandSignal: environment.commandSignal,
+            trackCloseable: environment.trackCloseable,
+            answer: environment.answer,
+            env: environment.env,
+        });
+        provideShared(program, environment);
+    },
+    onFailure: (error, program) => botRecordingOf(program)?.fail(error),
+});
+export const createProgram = (options = {}) => createSharedProgram(definition(), options);
+export const run = async (argv, options = {}) => {
+    const { recognizer, ...environment } = options;
+    const notice = updateNotice(argv, { tty: options.tty, environment: options.update });
+    const code = await permissionScope(() => runShared(argv, definition(options), {
+        ...environment,
+        ...(recognizer ? { recognizer: (model) => recognizer(model, modelsDirectory()) } : {}),
+    }));
+    const argvLog = process.env.MAX_TEST_ARGV_LOG;
+    if (argvLog && code === 0 && argv.some((word) => word === "--version" || word === "-V")) {
+        appendFileSync(argvLog, `${JSON.stringify({ command: "", options: ["--version"] })}\n`);
+    }
+    const line = await notice;
+    if (line && code === 0)
+        (options.streams ?? processStreams).diagnostic(line);
+    return code;
+};
+/**
+ * Under vitest only (`src/testing/sandbox.ts`): which command ran and which options were typed, for
+ * `pnpm test:matrix`. Words and option names — never an argument's value.
+ */
+const logParsed = (file, action) => {
+    const words = [];
+    const options = [];
+    for (let at = action; at; at = at.parent) {
+        if (at.parent)
+            words.unshift(at.name());
+        for (const option of at.options) {
+            const key = option.attributeName();
+            if (at.getOptionValueSource(key) !== "cli" || !option.long)
+                continue;
+            if (option.negate === (at.getOptionValue(key) === false))
+                options.push(option.long);
+        }
+    }
+    appendFileSync(file, `${JSON.stringify({ command: words.join(" "), options })}\n`);
+};
+//# 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,83 @@
+import { WebSocket } from "ws";
+import { type InboundFrame, type Payload } from "./frame.js";
+/** Where web.max.ru connects, read off its live socket on 2026-09-25. */
+export declare const MAX_WEBSOCKET_URL = "wss://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;
+    /**
+     * **A connection that stays open**, as `max serve`'s does: it answers MAX's ping and acknowledges
+     * a new message the way web.max.ru does (bundle read 2026-09-24), and drops a push it has already
+     * seen. Off for a one-shot command, which is gone before either matters.
+     */
+    live?: boolean;
+    /** MAX closed the socket. Not called for our own `close()`. The connection is dead after it. */
+    onClose?: (error: Error) => void;
+    /** A push that could not be handled was dropped; the connection carries on. */
+    onError?: (error: Error) => 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);
+}
+/** What a client needs of a connection — so one that goes through `max serve` can stand in. */
+export type Wire = Pick<Connection, "open" | "invoke" | "close">;
+/**
+ * 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>;
+    /**
+     * Closes the socket and **settles anything still waiting**, rather than dropping it.
+     *
+     * ⚠ It used to clear the pending map without rejecting, which left the caller of an in-flight
+     * `invoke` awaiting a promise nothing could ever settle: the timers were cleared and the socket
+     * listeners removed in the same breath, so neither the timeout nor the close event was left to
+     * fire. Invisible in normal use, because `close()` runs in a `finally` once the body is done —
+     * and a hang the moment anything closes the connection while a request is out, which is exactly
+     * what a whole-command deadline does. Found by a test, not by a user.
+     */
+    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,EAML,KAAK,YAAY,EACjB,KAAK,OAAO,EAEb,MAAM,YAAY,CAAA;AAEnB,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,iCAAiC,CAAA;AAC/D,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;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,gGAAgG;IAChG,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAChC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAChC,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;IAEhC,YAAY,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,EAKnE;CACF;AAOD,+FAA+F;AAC/F,MAAM,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC,CAAA;AAEhE;;;;;;;GAOG;AACH,qBAAa,UAAU;;IAuBrB,YAAY,OAAO,GAAE,iBAAsB,EAiB1C;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAgC1B;IAaD;;;;;;;;;;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,CAiCxG;IAED;;;;;;;;;OASG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAoB3B;CAoGF"}