modelmux-cli 0.0.1 → 0.3.1

package/dist/args.js

@@ -0,0 +1,422 @@
+/**
+ * A small command-line parser that behaves like Python's argparse, so the
+ * Node CLI accepts exactly the same command lines as the Python one and
+ * answers with the same help, usage and error text (exit code 2).
+ *
+ * Supported: subcommands, store_true / store / append options, --version,
+ * -h/--help, choices, int values, positionals with nargs 1, "?" and "*",
+ * unique prefixes of long options (--verb -> --verbose), --opt=value,
+ * clusters of short flags (-fv), "--", and negative numbers as values.
+ */
+import { repr } from "./text.js";
+/** Raised for `-h` and `--version`: print `text` to stdout and exit 0. */
+export class ParserExit extends Error {
+    status;
+    text;
+    constructor(status, text) {
+        super(text);
+        this.status = status;
+        this.text = text;
+    }
+}
+/** A usage error: `text` (usage + "prog: error: ...") goes to stderr, exit 2. */
+export class ParserError extends Error {
+    status = 2;
+    text;
+    constructor(text) {
+        super(text);
+        this.text = text;
+    }
+}
+/** Python's `shutil.get_terminal_size().columns`. */
+function terminalColumns() {
+    const env = Number.parseInt(process.env.COLUMNS ?? "", 10);
+    if (env > 0)
+        return env;
+    return process.stdout.columns && process.stdout.columns > 0 ? process.stdout.columns : 80;
+}
+/** Python's `textwrap.wrap` after argparse collapses whitespace. */
+function wrap(text, width) {
+    const words = text.trim().split(/\s+/).filter(Boolean);
+    const lines = [];
+    let line = "";
+    for (const word of words) {
+        if (line && line.length + 1 + word.length > width) {
+            lines.push(line);
+            line = word;
+        }
+        else {
+            line = line ? `${line} ${word}` : word;
+        }
+    }
+    if (line)
+        lines.push(line);
+    return lines;
+}
+const INT = /^\s*[+-]?\d+(_\d+)*\s*$/;
+const NEGATIVE_NUMBER = /^-\d+$|^-\d*\.\d+$/;
+export class Parser {
+    prog;
+    description;
+    epilog;
+    options = [];
+    positionals = [];
+    sub = null;
+    defaults = {};
+    constructor(prog, options = {}) {
+        this.prog = prog;
+        this.description = options.description ?? null;
+        this.epilog = options.epilog ?? null;
+        this.addOption({ flags: ["-h", "--help"], action: "help", help: "show this help message and exit" });
+    }
+    addOption(spec) {
+        const long = spec.flags.find((f) => f.startsWith("--")) ?? spec.flags[0];
+        const dest = spec.dest ?? long.replace(/^-+/, "").replaceAll("-", "_");
+        const action = spec.action ?? "store";
+        this.options.push({ ...spec, dest, action });
+        if (action === "store_true")
+            this.defaults[dest] = spec.default ?? false;
+        else if (action === "store" || action === "append")
+            this.defaults[dest] = spec.default ?? null;
+        return this;
+    }
+    addPositional(spec) {
+        this.positionals.push(spec);
+        if (spec.nargs === "*")
+            this.defaults[spec.dest] = [];
+        else if (spec.nargs === "?")
+            this.defaults[spec.dest] = null;
+        return this;
+    }
+    addSubcommands(dest, metavar) {
+        this.sub = { dest, metavar, commands: [] };
+        return this;
+    }
+    addCommand(name, help, configure = () => undefined) {
+        if (this.sub === null)
+            throw new Error("no subcommands");
+        const parser = new Parser(`${this.prog} ${name}`);
+        configure(parser);
+        this.sub.commands.push({ name, help, parser });
+        return parser;
+    }
+    setDefaults(values) {
+        Object.assign(this.defaults, values);
+        return this;
+    }
+    // ---------------------------------------------------------------- parsing
+    /** Parse `argv`. Throws `ParserExit` (help/version) or `ParserError`. */
+    parse(argv) {
+        const namespace = {};
+        const extras = this.parseInto(argv, namespace);
+        if (extras.length)
+            this.error(`unrecognized arguments: ${extras.join(" ")}`);
+        return namespace;
+    }
+    looksLikeOption(arg) {
+        return arg.startsWith("-") && arg !== "-" && !NEGATIVE_NUMBER.test(arg);
+    }
+    /** Find the option an argument names: exact, `--opt=value`, or a unique long prefix. */
+    match(arg) {
+        const [name, inline] = arg.includes("=") && arg.startsWith("--")
+            ? [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)]
+            : [arg, null];
+        const exact = this.options.find((o) => o.flags.includes(name));
+        if (exact)
+            return { option: exact, inline };
+        if (name.startsWith("--")) {
+            const hits = [];
+            for (const option of this.options) {
+                for (const flag of option.flags) {
+                    if (flag.startsWith("--") && flag.startsWith(name))
+                        hits.push([option, flag]);
+                }
+            }
+            if (hits.length > 1) {
+                const names = hits.map(([, flag]) => flag).join(", ");
+                this.error(`ambiguous option: ${name} could match ${names}`);
+            }
+            if (hits.length === 1)
+                return { option: hits[0][0], inline };
+        }
+        return null;
+    }
+    convert(option, value) {
+        if (option.type === "int") {
+            if (!INT.test(value))
+                this.error(`argument ${option.flags.join("/")}: invalid int value: ${repr(value)}`);
+            return Number.parseInt(value.replaceAll("_", "").trim(), 10);
+        }
+        if (option.choices && !option.choices.includes(value)) {
+            this.error(`argument ${option.flags.join("/")}: invalid choice: ${repr(value)} ` +
+                `(choose from ${option.choices.map(repr).join(", ")})`);
+        }
+        return value;
+    }
+    apply(option, value, namespace) {
+        switch (option.action) {
+            case "help":
+                throw new ParserExit(0, this.formatHelp());
+            case "version":
+                throw new ParserExit(0, `${option.version ?? ""}\n`);
+            case "store_true":
+                namespace[option.dest] = true;
+                return;
+            case "store":
+                namespace[option.dest] = this.convert(option, value);
+                return;
+            case "append": {
+                const list = Array.isArray(namespace[option.dest]) ? namespace[option.dest] : [];
+                namespace[option.dest] = [...list, this.convert(option, value)];
+                return;
+            }
+        }
+    }
+    positionalName(spec) {
+        return spec.metavar ?? spec.dest;
+    }
+    checkChoice(spec, value) {
+        if (spec.choices && !spec.choices.includes(value)) {
+            this.error(`argument ${this.positionalName(spec)}: invalid choice: ${repr(value)} ` +
+                `(choose from ${spec.choices.map(repr).join(", ")})`);
+        }
+        return value;
+    }
+    /** Parse into `namespace`; returns arguments nobody recognised. */
+    parseInto(argv, namespace) {
+        for (const [key, value] of Object.entries(this.defaults)) {
+            if (!(key in namespace))
+                namespace[key] = Array.isArray(value) ? [...value] : value;
+        }
+        const extras = [];
+        const values = [];
+        let i = 0;
+        let onlyPositionals = false;
+        let subcommandAt = -1;
+        while (i < argv.length) {
+            const arg = argv[i];
+            if (!onlyPositionals && arg === "--") {
+                onlyPositionals = true;
+                i++;
+                continue;
+            }
+            if (onlyPositionals || !this.looksLikeOption(arg)) {
+                if (this.sub !== null && values.length === this.positionals.length) {
+                    subcommandAt = i;
+                    break;
+                }
+                values.push(arg);
+                i++;
+                continue;
+            }
+            const found = this.match(arg);
+            if (found !== null) {
+                const { option, inline } = found;
+                if (option.action === "store" || option.action === "append") {
+                    let value = inline;
+                    if (value === null) {
+                        const next = argv[i + 1];
+                        if (next === undefined || this.looksLikeOption(next)) {
+                            this.error(`argument ${option.flags.join("/")}: expected one argument`);
+                        }
+                        value = next;
+                        i++;
+                    }
+                    this.apply(option, value, namespace);
+                }
+                else {
+                    if (inline !== null) {
+                        this.error(`argument ${option.flags.join("/")}: ignored explicit argument ${repr(inline)}`);
+                    }
+                    this.apply(option, null, namespace);
+                }
+                i++;
+                continue;
+            }
+            // A cluster of short flags, e.g. -fv.
+            if (/^-[A-Za-z]{2,}$/.test(arg)) {
+                const flags = [...arg.slice(1)].map((ch) => this.options.find((o) => o.flags.includes(`-${ch}`)));
+                if (flags.every((o) => o !== undefined && o.action !== "store" && o.action !== "append")) {
+                    for (const option of flags)
+                        this.apply(option, null, namespace);
+                    i++;
+                    continue;
+                }
+            }
+            extras.push(arg);
+            i++;
+        }
+        this.assignPositionals(values, namespace, extras);
+        if (this.sub !== null) {
+            if (subcommandAt < 0) {
+                this.error(`the following arguments are required: ${this.sub.metavar}`);
+            }
+            const name = argv[subcommandAt];
+            const command = this.sub.commands.find((c) => c.name === name);
+            if (command === undefined) {
+                this.error(`argument ${this.sub.metavar}: invalid choice: ${repr(name)} ` +
+                    `(choose from ${this.sub.commands.map((c) => repr(c.name)).join(", ")})`);
+            }
+            namespace[this.sub.dest] = name;
+            extras.push(...command.parser.parseInto(argv.slice(subcommandAt + 1), namespace));
+        }
+        return extras;
+    }
+    assignPositionals(values, namespace, extras) {
+        const queue = [...values];
+        const missing = [];
+        for (const spec of this.positionals) {
+            if (spec.nargs === "*") {
+                namespace[spec.dest] = queue.splice(0).map((v) => this.checkChoice(spec, v));
+            }
+            else if (spec.nargs === "?") {
+                const value = queue.shift();
+                namespace[spec.dest] = value === undefined ? null : this.checkChoice(spec, value);
+            }
+            else {
+                const value = queue.shift();
+                if (value === undefined)
+                    missing.push(this.positionalName(spec));
+                else
+                    namespace[spec.dest] = this.checkChoice(spec, value);
+            }
+        }
+        if (missing.length)
+            this.error(`the following arguments are required: ${missing.join(", ")}`);
+        extras.push(...queue);
+    }
+    error(message) {
+        throw new ParserError(`${this.formatUsage()}${this.prog}: error: ${message}\n`);
+    }
+    // ---------------------------------------------------------------- help
+    width() {
+        return terminalColumns() - 2;
+    }
+    optionUsage(option) {
+        const flag = option.flags[0];
+        if (option.action === "store" || option.action === "append") {
+            return `[${flag} ${this.metavar(option)}]`;
+        }
+        return `[${flag}]`;
+    }
+    metavar(option) {
+        if (option.metavar)
+            return option.metavar;
+        if (option.choices)
+            return `{${option.choices.join(",")}}`;
+        return option.dest.toUpperCase();
+    }
+    positionalUsage(spec) {
+        const name = spec.metavar ?? (spec.choices ? `{${spec.choices.join(",")}}` : spec.dest);
+        if (spec.nargs === "?")
+            return `[${name}]`;
+        if (spec.nargs === "*")
+            return `[${name} ...]`;
+        return name;
+    }
+    positionalInvocation(spec) {
+        return spec.metavar ?? (spec.choices ? `{${spec.choices.join(",")}}` : spec.dest);
+    }
+    formatUsage() {
+        const prefix = "usage: ";
+        const optParts = this.options.map((o) => this.optionUsage(o));
+        const posParts = this.positionals.map((p) => this.positionalUsage(p));
+        if (this.sub !== null)
+            posParts.push(`${this.sub.metavar} ...`);
+        const textWidth = this.width();
+        const full = [this.prog, ...optParts, ...posParts].join(" ");
+        if (prefix.length + full.length <= textWidth)
+            return `${prefix}${full}\n`;
+        const getLines = (parts, indent, first = null) => {
+            const lines = [];
+            let line = [];
+            let length = first !== null ? first.length - 1 : indent.length - 1;
+            for (const part of parts) {
+                if (length + 1 + part.length > textWidth && line.length) {
+                    lines.push(indent + line.join(" "));
+                    line = [];
+                    length = indent.length - 1;
+                }
+                line.push(part);
+                length += part.length + 1;
+            }
+            if (line.length)
+                lines.push(indent + line.join(" "));
+            if (first !== null && lines.length)
+                lines[0] = lines[0].slice(indent.length);
+            return lines;
+        };
+        let lines;
+        if (prefix.length + this.prog.length <= 0.75 * textWidth) {
+            const indent = " ".repeat(prefix.length + this.prog.length + 1);
+            if (optParts.length) {
+                lines = getLines([this.prog, ...optParts], indent, prefix);
+                lines.push(...getLines(posParts, indent));
+            }
+            else if (posParts.length) {
+                lines = getLines([this.prog, ...posParts], indent, prefix);
+            }
+            else {
+                lines = [this.prog];
+            }
+        }
+        else {
+            const indent = " ".repeat(prefix.length);
+            lines = [this.prog, ...getLines([...optParts, ...posParts], indent)];
+        }
+        return `${prefix}${lines.join("\n")}\n`;
+    }
+    formatHelp() {
+        const width = this.width();
+        const maxHelpPosition = Math.min(24, Math.max(width - 20, 4));
+        const positionalRows = this.positionals.map((p) => ({
+            invocation: this.positionalInvocation(p),
+            help: p.help,
+            indent: 2,
+        }));
+        if (this.sub !== null) {
+            positionalRows.push({ invocation: this.sub.metavar, help: undefined, indent: 2 });
+            for (const command of this.sub.commands) {
+                positionalRows.push({ invocation: command.name, help: command.help, indent: 4 });
+            }
+        }
+        const optionRows = this.options.map((o) => ({
+            invocation: o.action === "store" || o.action === "append"
+                ? o.flags.map((f) => `${f} ${this.metavar(o)}`).join(", ")
+                : o.flags.join(", "),
+            help: o.help,
+            indent: 2,
+        }));
+        const all = [...positionalRows, ...optionRows];
+        const maxLength = Math.max(...all.map((r) => r.invocation.length + r.indent));
+        const helpPosition = Math.min(maxLength + 2, maxHelpPosition);
+        const helpWidth = Math.max(width - helpPosition, 11);
+        const formatRow = (row) => {
+            const actionWidth = helpPosition - row.indent - 2;
+            const head = " ".repeat(row.indent) + row.invocation;
+            if (!row.help)
+                return `${head}\n`;
+            const helpLines = wrap(row.help, helpWidth);
+            let out;
+            if (row.invocation.length <= actionWidth) {
+                out = head.padEnd(helpPosition) + helpLines[0] + "\n";
+            }
+            else {
+                out = `${head}\n${" ".repeat(helpPosition)}${helpLines[0]}\n`;
+            }
+            for (const line of helpLines.slice(1))
+                out += `${" ".repeat(helpPosition)}${line}\n`;
+            return out;
+        };
+        const sections = [this.formatUsage()];
+        if (this.description)
+            sections.push(wrap(this.description, width).join("\n") + "\n");
+        if (positionalRows.length) {
+            sections.push("positional arguments:\n" + positionalRows.map(formatRow).join(""));
+        }
+        sections.push("options:\n" + optionRows.map(formatRow).join(""));
+        if (this.epilog)
+            sections.push(wrap(this.epilog, width).join("\n") + "\n");
+        return sections.join("\n");
+    }
+}

package/dist/bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+/** The `modelmux` executable. */
+import { cli } from "./main.js";
+await cli();

package/dist/browser.js

@@ -0,0 +1,51 @@
+/**
+ * Open a link in the user's browser (Python's `webbrowser.open`).
+ *
+ * The second and last module that starts programs (besides docker.ts): the
+ * system's own opener, as an argument list without a shell, detached so it
+ * never holds the login up. Resolves false when there is no usable browser
+ * here (no desktop session, opener missing), so the caller can say so.
+ */
+import { spawn } from "node:child_process";
+import { which } from "./docker.js";
+/** The command to run for `url`, or null when no browser can be used here. */
+export function browserCommand(url, env = process.env, platform = process.platform) {
+    // $BROWSER: a list of commands; "%s" marks where the link goes.
+    for (const entry of (env.BROWSER ?? "").split(platform === "win32" ? ";" : ":")) {
+        const parts = entry.trim().split(/\s+/).filter(Boolean);
+        if (parts.length && which(parts[0], env, platform)) {
+            return parts.some((p) => p.includes("%s"))
+                ? parts.map((p) => p.replaceAll("%s", url))
+                : [...parts, url];
+        }
+    }
+    if (platform === "darwin")
+        return ["open", url];
+    if (platform === "win32")
+        return ["explorer.exe", url];
+    if (!env.DISPLAY && !env.WAYLAND_DISPLAY)
+        return null; // no desktop session
+    for (const opener of ["xdg-open", "gio", "sensible-browser", "x-www-browser"]) {
+        if (which(opener, env, platform))
+            return opener === "gio" ? [opener, "open", url] : [opener, url];
+    }
+    return null;
+}
+export function openBrowser(url) {
+    const command = browserCommand(url);
+    if (command === null)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(command[0], command.slice(1), { stdio: "ignore", detached: true });
+            child.once("error", () => resolve(false));
+            child.once("spawn", () => {
+                child.unref();
+                resolve(true);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}

package/dist/cli.js

@@ -0,0 +1,60 @@
+/** The command line: the same commands, options and help as the Python CLI. */
+import { Parser } from "./args.js";
+import { TARGETS } from "./clientconfig.js";
+import { loadProviders } from "./providers.js";
+import { VERSION } from "./version.js";
+export function buildParser() {
+    const providers = [...loadProviders().keys()];
+    const parser = new Parser("modelmux", {
+        description: "Run AI coding CLIs as a secure, OpenAI-compatible API.",
+        epilog: "Start with: modelmux up, then modelmux login <provider>.",
+    });
+    parser.addOption({ flags: ["--version"], action: "version", version: `modelmux ${VERSION}`,
+        help: "show program's version number and exit" });
+    parser.addOption({ flags: ["-v", "--verbose"], action: "store_true", help: "show details and commands" });
+    parser.addOption({ flags: ["--no-color"], action: "store_true", help: "disable coloured output" });
+    parser.addSubcommands("command", "<command>");
+    parser.addCommand("up", "start ModelMux (logged-in providers)", (up) => {
+        up.addPositional({ dest: "providers", nargs: "*", metavar: "provider",
+            help: `any of: ${providers.join(", ")}` });
+        up.addOption({ flags: ["--image"], metavar: "REF", help: "server image to run (remembered)" });
+        up.addOption({ flags: ["--port"], action: "append", metavar: "PROVIDER=PORT",
+            help: "local port (remembered)" });
+    });
+    parser.addCommand("down", "stop ModelMux (logins are kept)");
+    parser.addCommand("logs", "show server logs", (logs) => {
+        logs.addPositional({ dest: "provider", nargs: "?", choices: providers });
+        logs.addOption({ flags: ["-f", "--follow"], action: "store_true", help: "keep streaming new lines" });
+        logs.addOption({ flags: ["--tail"], type: "int", default: 100, metavar: "N",
+            help: "lines to show (100)" });
+    });
+    parser.addCommand("status", "what is running, logged in and healthy");
+    parser.addCommand("login", "log a provider in (guided)", (login) => {
+        login.addPositional({ dest: "provider", choices: providers });
+        login.addOption({ flags: ["--method"], help: "login method (see the provider's options)" });
+        login.addOption({ flags: ["--no-browser"], action: "store_true", help: "do not open a browser" });
+        login.addOption({ flags: ["--raw"], action: "store_true", help: "show the provider's raw output" });
+        login.addOption({ flags: ["--force"], action: "store_true", help: "log in again even if logged in" });
+    });
+    parser.addCommand("logout", "remove a provider's saved login", (logout) => {
+        logout.addPositional({ dest: "provider", choices: providers });
+        logout.addOption({ flags: ["-y", "--yes"], action: "store_true", help: "do not ask for confirmation" });
+    });
+    parser.addCommand("config", "print ready-to-paste client config", (config) => {
+        config.addPositional({ dest: "target", choices: TARGETS });
+        config.addOption({ flags: ["--provider"], choices: providers });
+        config.addOption({ flags: ["--reveal-key"], action: "store_true", help: "include the real API key" });
+    });
+    parser.addCommand("doctor", "diagnose common problems");
+    parser.addCommand("upgrade", "run the image matching this CLI version", (upgrade) => {
+        upgrade.addOption({ flags: ["--image"], metavar: "REF", help: "use a different image (advanced)" });
+    });
+    parser.addCommand("key", "the API key clients use to call ModelMux", (key) => {
+        key.addSubcommands("key_command", "<action>");
+        key.addCommand("show", "print the API key");
+    });
+    return parser;
+}
+export function asArgs(namespace) {
+    return namespace;
+}

package/dist/clientconfig.js

@@ -0,0 +1,89 @@
+/** Render client config snippets from `shared/templates/config/<target>.json`. */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { CliError } from "./errors.js";
+import { sharedDir } from "./providers.js";
+import { repr } from "./text.js";
+export const KEY_ENV = "MODELMUX_API_KEY";
+export const TARGETS = ["litellm", "openai-python", "langchain", "curl", "env"];
+/** Python's `json.dumps()` of a string (the key is URL-safe, so no escaping differs). */
+const jsonString = (key) => JSON.stringify(key);
+// How each target refers to the key: [by reference, when revealed].
+const KEY_STYLES = {
+    litellm: [`os.environ/${KEY_ENV}`, (key) => key],
+    python: [`os.environ["${KEY_ENV}"]`, jsonString],
+    shell: [`$${KEY_ENV}`, (key) => key],
+    env: ["", (key) => key],
+};
+const PLACEHOLDER = /\{\{(\w+)\}\}/g;
+export function loadTemplate(name) {
+    const file = path.join(sharedDir(), "templates", "config", `${name}.json`);
+    let template;
+    try {
+        const data = JSON.parse(readFileSync(file, "utf8"));
+        const field = (key) => {
+            if (!(key in data))
+                throw new TypeError(key);
+            return data[key];
+        };
+        template = {
+            name,
+            description: field("description"),
+            per: field("per"),
+            keyStyle: field("key_style"),
+            header: field("header"),
+            entry: field("entry"),
+            footer: field("footer"),
+        };
+    }
+    catch {
+        throw new CliError(`The ${repr(name)} config template is missing or invalid.`, {
+            hint: "Please report this bug.",
+        });
+    }
+    if (!["provider", "model"].includes(template.per) || !(template.keyStyle in KEY_STYLES)) {
+        throw new CliError(`The ${repr(name)} config template is invalid.`, {
+            hint: "Please report this bug.",
+        });
+    }
+    for (const key of ["header", "entry", "footer"]) {
+        if (typeof template[key] !== "string") {
+            throw new CliError(`The ${repr(name)} config template is missing or invalid.`, {
+                hint: "Please report this bug.",
+            });
+        }
+    }
+    return template;
+}
+function fill(text, values) {
+    return text.replace(PLACEHOLDER, (match, key) => {
+        if (!Object.hasOwn(values, key)) {
+            throw new CliError(`Unknown placeholder ${match} in a config template.`, {
+                hint: "Please report this bug.",
+            });
+        }
+        return values[key];
+    });
+}
+/** `apiKey` null means: refer to $MODELMUX_API_KEY instead of the value. */
+export function render(template, targets, apiKey) {
+    const [reference, literal] = KEY_STYLES[template.keyStyle];
+    const key = apiKey === null ? reference : literal(apiKey);
+    const parts = [fill(template.header, { key })];
+    for (const target of targets) {
+        const models = template.per === "model" ? target.models : target.models.slice(0, 1);
+        for (const model of models) {
+            parts.push(fill(template.entry, {
+                provider: target.provider,
+                PROVIDER: target.provider.toUpperCase().replaceAll("-", "_"),
+                provider_var: target.provider.replaceAll("-", "_"),
+                display_name: target.displayName,
+                model,
+                base_url: target.baseUrl,
+                key,
+            }));
+        }
+    }
+    parts.push(fill(template.footer, { key }));
+    return parts.join("").replace(/\n+$/, "") + "\n";
+}