modelmux-cli 0.0.0-stage → 0.3.0

package/dist/commands/up.js

@@ -0,0 +1,204 @@
+/** `modelmux up`: prepare everything and start the logged-in providers. */
+import { saveConfig } from "../config.js";
+import { makeContext } from "../context.js";
+import { CliError, UsageError } from "../errors.js";
+import * as health from "../health.js";
+import { ensurePrivateDir } from "../paths.js";
+import { ports } from "../ports.js";
+import { ensureApiKey } from "../secretsStore.js";
+import { buildCompose, resolveImage, serviceName, writeCompose } from "../stack.js";
+import { repr } from "../text.js";
+export const COMPOSE_UP_TIMEOUT = 300.0;
+/** How long to wait for /health/ready, and how often to ask. Replaceable in tests. */
+export const timing = {
+    readyTimeout: 240.0,
+    pollInterval: 0.5,
+};
+export function parsePortOverrides(values, known) {
+    const ports = new Map();
+    for (const value of values) {
+        const at = value.indexOf("=");
+        const name = at < 0 ? value : value.slice(0, at);
+        const raw = at < 0 ? "" : value.slice(at + 1);
+        if (at < 0 || !known.has(name) || !/^\d+$/.test(raw) || Number(raw) < 1024 || Number(raw) > 65535) {
+            throw new UsageError(`Invalid --port ${repr(value)}.`, {
+                hint: "Use --port <provider>=<1024-65535>, e.g. claude=9101.",
+            });
+        }
+        ports.set(name, Number(raw));
+    }
+    return ports;
+}
+/** Validate and remember --image / --port; return the image to run. */
+export function applySettings(ctx, args) {
+    const config = ctx.config;
+    const image = resolveImage(config, args.image);
+    const ports = parsePortOverrides(args.port ?? [], new Set(ctx.providers.keys()));
+    const changed = ports.size > 0 || (args.image !== null && args.image !== config.image);
+    for (const [name, port] of ports)
+        config.ports.set(name, port);
+    if (args.image !== null)
+        config.image = args.image;
+    const used = [...ctx.providers.keys()].map((name) => config.port(name));
+    if (new Set(used).size !== used.length) {
+        throw new UsageError("Two providers are set to the same port.", {
+            hint: "Choose different --port values.",
+        });
+    }
+    if (changed)
+        saveConfig(ctx.home, config);
+    return image;
+}
+export async function startAndWait(ctx, provider) {
+    const { console, stack } = ctx;
+    const service = serviceName(provider);
+    const port = ctx.config.port(provider.name);
+    const stopped = async () => {
+        const state = (await stack.states()).get(service);
+        return state !== undefined && ["exited", "dead"].includes(state.state);
+    };
+    console.step(`Starting ${provider.displayName} (it checks its login, about 10-30 s)...`);
+    const ok = await health.waitUntil(() => health.server.ready(port), {
+        timeout: timing.readyTimeout,
+        interval: timing.pollInterval,
+        shouldStop: stopped,
+    });
+    if (!ok) {
+        if (await stopped()) {
+            throw new CliError(`${provider.displayName} stopped while starting.`, {
+                hint: `Its login may have expired: modelmux login ${provider.name}. ` +
+                    `Details: modelmux logs ${provider.name}`,
+            });
+        }
+        throw new CliError(`${provider.displayName} did not become ready in time.`, {
+            hint: `See what it is doing: modelmux logs ${provider.name}`,
+        });
+    }
+    console.success(`${provider.displayName} is running at ${health.baseUrl(port)}/v1`);
+}
+/**
+ * Docker, API key, compose file, image and login volumes: all idempotent.
+ *
+ * Returns true if the compose file changed (so running containers must be
+ * recreated to pick it up).
+ */
+export async function prepare(ctx, image) {
+    const { console, stack } = ctx;
+    console.step("Checking Docker...");
+    await ctx.docker.checkAvailable();
+    ensurePrivateDir(ctx.home);
+    const key = ensureApiKey(ctx.home);
+    if (key.created) {
+        console.success("Created an API key for your clients (see it with: modelmux key show).");
+    }
+    const changed = writeCompose(ctx.home, buildCompose(ctx.providers, ctx.config, image, key.path));
+    if (!(await stack.imagePresent(image))) {
+        console.step(`Downloading the ModelMux server image ${image} (first time only, ~1.4 GB)...`);
+        await stack.ensureImage(image);
+    }
+    for (const provider of ctx.providers.values())
+        await stack.ensureVolume(provider);
+    return changed || key.created;
+}
+/**
+ * Providers whose container runs and answers /health/ready. Their login is
+ * proven (the server's startup check made a real request), so no helper
+ * container is needed to check it again.
+ */
+export async function runningAndReady(ctx, providers) {
+    const states = await ctx.stack.states();
+    const ready = new Set();
+    for (const p of providers) {
+        const s = states.get(serviceName(p));
+        if (s !== undefined && s.state === "running" && (await health.server.ready(ctx.config.port(p.name)))) {
+            ready.add(p.name);
+        }
+    }
+    return ready;
+}
+/**
+ * Logged in or not, per provider: running ones count as logged in, the rest
+ * are checked in parallel helper containers.
+ */
+export async function checkLogins(ctx, providers, image) {
+    const ready = await runningAndReady(ctx, providers);
+    const unknown = providers.filter((p) => !ready.has(p.name));
+    const answers = await settleAll(unknown.map((p) => ctx.stack.loggedIn(p, image)));
+    const result = new Map();
+    for (const p of providers)
+        if (ready.has(p.name))
+            result.set(p.name, true);
+    unknown.forEach((p, i) => result.set(p.name, answers[i]));
+    return result;
+}
+/** Wait for all promises, then return their values or throw the first failure (in order). */
+async function settleAll(promises) {
+    const settled = await Promise.allSettled(promises);
+    for (const outcome of settled)
+        if (outcome.status === "rejected")
+            throw outcome.reason;
+    return settled.map((outcome) => outcome.value);
+}
+/** Wait for every provider at once; report the first failure afterwards. */
+export async function waitAll(ctx, providers) {
+    await settleAll(providers.map((p) => startAndWait(ctx, p)));
+}
+export async function checkPorts(ctx, providers) {
+    const states = await ctx.stack.states();
+    for (const provider of providers) {
+        const running = states.get(serviceName(provider));
+        const port = ctx.config.port(provider.name);
+        if ((running === undefined || running.state !== "running") && !(await ports.portFree(port))) {
+            throw new CliError(`Port ${port} for ${provider.displayName} is already in use by another program.`, {
+                hint: `Pick another port: modelmux up --port ${provider.name}=<port>, ` +
+                    "or run 'modelmux doctor'.",
+            });
+        }
+    }
+}
+export async function run(args, console) {
+    const ctx = makeContext(console);
+    const providers = ctx.providers;
+    const unknown = args.providers.filter((name) => !providers.has(name));
+    if (unknown.length) {
+        throw new UsageError(`Unknown provider ${repr(unknown[0])}.`, {
+            hint: `Choose from: ${[...providers.keys()].join(", ")}.`,
+        });
+    }
+    const image = applySettings(ctx, args);
+    const composeChanged = await prepare(ctx, image);
+    const names = args.providers.length ? args.providers : [...providers.keys()];
+    const targets = names.map((name) => providers.get(name));
+    console.step("Checking logins...");
+    const loggedIn = await checkLogins(ctx, targets, image);
+    const missing = targets.filter((p) => !loggedIn.get(p.name));
+    if (args.providers.length && missing.length) {
+        throw new CliError(`${missing[0].displayName} is not logged in yet.`, {
+            hint: `Log in first: modelmux login ${missing[0].name}`,
+        });
+    }
+    const toStart = targets.filter((p) => loggedIn.get(p.name));
+    if (!toStart.length) {
+        console.success("ModelMux is set up. No provider is logged in yet.");
+        console.step(`Next: modelmux login ${targets[0].name}`);
+        return 0;
+    }
+    const ready = composeChanged ? new Set() : await runningAndReady(ctx, toStart);
+    const waiting = toStart.filter((p) => !ready.has(p.name));
+    if (waiting.length) {
+        await checkPorts(ctx, waiting);
+        await ctx.stack.compose(["up", "-d", ...toStart.map(serviceName)], { timeout: COMPOSE_UP_TIMEOUT });
+    }
+    for (const provider of toStart) {
+        if (ready.has(provider.name)) {
+            const port = ctx.config.port(provider.name);
+            console.success(`${provider.displayName} is already running at ${health.baseUrl(port)}/v1`);
+        }
+    }
+    await waitAll(ctx, waiting);
+    for (const provider of missing) {
+        console.step(`${provider.displayName} is not logged in: modelmux login ${provider.name}`);
+    }
+    console.step("Configure your tools: modelmux config litellm (or openai-python, langchain)");
+    return 0;
+}

package/dist/commands/upgrade.js

@@ -0,0 +1,46 @@
+/**
+ * `modelmux upgrade`: run the server image that matches this CLI, keeping logins.
+ *
+ * The image version follows the CLI version: a newer server comes with a newer
+ * modelmux-cli. This command makes sure the image pinned for the installed CLI
+ * (or an explicit `--image`) is present, recreates the providers that were
+ * running, and says when a newer CLI is available.
+ */
+import { existsSync } from "node:fs";
+import { saveConfig } from "../config.js";
+import { makeContext } from "../context.js";
+import { resolveImage, serviceName } from "../stack.js";
+import * as updates from "../updates.js";
+import { VERSION } from "../version.js";
+import * as upModule from "./up.js";
+export async function run(args, console) {
+    const ctx = makeContext(console);
+    const image = resolveImage(ctx.config, args.image);
+    if (args.image !== null && args.image !== ctx.config.image) {
+        ctx.config.image = args.image;
+        saveConfig(ctx.home, ctx.config);
+    }
+    const states = existsSync(ctx.stack.composeFile)
+        ? await ctx.stack.states()
+        : new Map();
+    await upModule.prepare(ctx, image); // downloads the image if needed, rewrites compose.yaml
+    console.success(`Server image: ${image}`);
+    const running = [...ctx.providers.values()].filter((p) => states.get(serviceName(p))?.state === "running");
+    if (running.length) {
+        await ctx.stack.compose(["up", "-d", ...running.map(serviceName)], {
+            timeout: upModule.COMPOSE_UP_TIMEOUT,
+        });
+        for (const provider of running)
+            await upModule.startAndWait(ctx, provider);
+        console.success("Upgraded. Logins were kept.");
+    }
+    else {
+        console.success("Nothing was running; the next 'modelmux up' uses this image.");
+    }
+    const latest = await updates.registry.latestVersion();
+    if (updates.newerAvailable(VERSION, latest)) {
+        console.step(`modelmux-cli ${latest} is available (you have ${VERSION}). ` +
+            `It comes with a newer server: ${updates.UPGRADE_HINT}`);
+    }
+    return 0;
+}

package/dist/config.js

@@ -0,0 +1,97 @@
+/**
+ * The CLI's settings (`config.json`): ports, and an optional image override.
+ *
+ * Everything has a default, so the file only exists once something is changed
+ * or `modelmux up` runs. A damaged file is reported, never silently replaced.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { CliError } from "./errors.js";
+import { writePrivate } from "./files.js";
+import { ensurePrivateDir } from "./paths.js";
+import { loadProviders } from "./providers.js";
+import { repr, sortedStrings } from "./text.js";
+export const CONFIG_FILE = "config.json";
+export const CONFIG_VERSION = 1;
+export class Config {
+    ports;
+    /** Explicit override; null means "the image pinned for this CLI". */
+    image;
+    constructor(ports = new Map(), image = null) {
+        this.ports = ports;
+        this.image = image;
+    }
+    port(provider) {
+        const port = this.ports.get(provider);
+        if (port !== undefined)
+            return port;
+        const known = loadProviders().get(provider);
+        if (known === undefined)
+            throw new CliError(`Unknown provider ${repr(provider)}.`);
+        return known.defaultPort;
+    }
+}
+export class ConfigFileError extends CliError {
+    constructor(file, problem) {
+        super(`Your ModelMux settings file is damaged (${problem}).`, {
+            hint: `Fix or delete ${file} and run the command again.`,
+        });
+    }
+}
+function parse(file, data) {
+    if (typeof data !== "object" ||
+        data === null ||
+        Array.isArray(data) ||
+        data.version !== CONFIG_VERSION) {
+        throw new ConfigFileError(file, "unknown format version");
+    }
+    const record = data;
+    const ports = record.ports ?? {};
+    if (typeof ports !== "object" || ports === null || Array.isArray(ports)) {
+        throw new ConfigFileError(file, "'ports' must be an object");
+    }
+    const known = loadProviders();
+    const parsed = new Map();
+    for (const [name, port] of Object.entries(ports)) {
+        if (!known.has(name))
+            throw new ConfigFileError(file, `unknown provider ${repr(name)} in 'ports'`);
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new ConfigFileError(file, `invalid port for ${repr(name)}`);
+        }
+        parsed.set(name, port);
+    }
+    const image = record.image ?? null;
+    if (image !== null && typeof image !== "string") {
+        throw new ConfigFileError(file, "'image' must be a string");
+    }
+    return new Config(parsed, image);
+}
+export function loadConfig(directory) {
+    const file = path.join(directory, CONFIG_FILE);
+    if (!existsSync(file))
+        return new Config();
+    let data;
+    try {
+        data = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        throw new ConfigFileError(file, "not valid JSON");
+    }
+    return parse(file, data);
+}
+/** Python's `json.dumps(data, indent=2)`: same spacing, non-ASCII escaped. */
+export function pyJson(data) {
+    return JSON.stringify(data, null, 2).replace(/[\u0080-￿]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+export function saveConfig(directory, config) {
+    ensurePrivateDir(directory);
+    const file = path.join(directory, CONFIG_FILE);
+    const ports = {};
+    for (const name of sortedStrings(config.ports.keys()))
+        ports[name] = config.ports.get(name);
+    const data = { version: CONFIG_VERSION, ports };
+    if (config.image !== null)
+        data.image = config.image;
+    writePrivate(file, pyJson(data) + "\n");
+    return file;
+}

package/dist/console.js

@@ -0,0 +1,93 @@
+/**
+ * Terminal output: short, friendly lines with ✓ / ✗ markers.
+ *
+ * Colour is used only on a real terminal, never when `NO_COLOR` is set or
+ * `TERM=dumb`. Symbols fall back to ASCII when the terminal cannot show them
+ * (older Windows consoles).
+ */
+import { redact } from "./redact.js";
+const RESET = "\x1b[0m";
+const STYLES = {
+    ok: "\x1b[32m",
+    error: "\x1b[31m",
+    warn: "\x1b[33m",
+    dim: "\x1b[2m",
+    bold: "\x1b[1m",
+};
+const SYMBOLS = {
+    ok: ["✓", "OK"],
+    error: ["✗", "X"],
+    warn: ["!", "!"],
+    step: ["→", ">"],
+};
+/**
+ * Can this terminal show ✓✗→? Node always writes UTF-8; only legacy Windows
+ * consoles (not Windows Terminal or VS Code) show it as garbage.
+ */
+function supportsUnicode(env = process.env) {
+    if (process.platform !== "win32")
+        return true;
+    return Boolean(env.WT_SESSION || env.TERM_PROGRAM === "vscode" || env.TERM === "xterm-256color" || env.CI);
+}
+export class Console {
+    out;
+    err;
+    verbose;
+    color;
+    unicode;
+    constructor(options = {}) {
+        this.out = options.out ?? process.stdout;
+        this.err = options.err ?? process.stderr;
+        this.verbose = options.verbose ?? false;
+        let color = options.color ?? null;
+        if (color === null) {
+            // Node enables ANSI escape handling in the Windows console by itself.
+            color =
+                this.out.isTTY === true && !("NO_COLOR" in process.env) && process.env.TERM !== "dumb";
+        }
+        this.color = color;
+        this.unicode = options.unicode ?? supportsUnicode();
+    }
+    style(kind, text) {
+        return this.color ? `${STYLES[kind]}${text}${RESET}` : text;
+    }
+    symbol(kind) {
+        const [fancy, plain] = SYMBOLS[kind];
+        return this.unicode ? fancy : plain;
+    }
+    line(stream, text) {
+        stream.write(redact(text) + "\n");
+    }
+    // ------------------------------------------------------------ public API
+    /** Plain output (command results, config snippets). */
+    print(text = "") {
+        this.line(this.out, text);
+    }
+    success(text) {
+        this.line(this.out, `${this.style("ok", this.symbol("ok"))} ${text}`);
+    }
+    step(text) {
+        this.line(this.out, `${this.style("dim", this.symbol("step"))} ${text}`);
+    }
+    warn(text) {
+        this.line(this.err, `${this.style("warn", this.symbol("warn"))} ${text}`);
+    }
+    error(text, hint = null) {
+        this.line(this.err, `${this.style("error", this.symbol("error"))} ${text}`);
+        if (hint)
+            this.line(this.err, `  ${this.style("dim", hint)}`);
+    }
+    /** A hint on stderr, so stdout stays clean for piping (`config > file`). */
+    note(text) {
+        this.line(this.err, `${this.style("dim", this.symbol("step"))} ${text}`);
+    }
+    /** Print WITHOUT redaction. Only for an explicit user request to see a secret. */
+    reveal(text) {
+        this.out.write(text + "\n");
+    }
+    /** Only shown with --verbose. */
+    detail(text) {
+        if (this.verbose)
+            this.line(this.err, this.style("dim", `  ${text}`));
+    }
+}

package/dist/context.js

@@ -0,0 +1,36 @@
+/** Everything a command needs, built in one place (and replaceable in tests). */
+import { loadConfig } from "./config.js";
+import { Docker } from "./docker.js";
+import { configDir } from "./paths.js";
+import { loadProviders } from "./providers.js";
+import { Stack } from "./stack.js";
+/** Replaceable in tests: how commands get their Docker. */
+export const factory = {
+    makeDocker: (console) => new Docker(console),
+};
+export class Context {
+    console;
+    docker;
+    home;
+    cachedConfig = null;
+    cachedStack = null;
+    constructor(console, docker, home = configDir()) {
+        this.console = console;
+        this.docker = docker;
+        this.home = home;
+    }
+    get config() {
+        this.cachedConfig ??= loadConfig(this.home);
+        return this.cachedConfig;
+    }
+    get providers() {
+        return loadProviders();
+    }
+    get stack() {
+        this.cachedStack ??= new Stack(this.docker, this.home);
+        return this.cachedStack;
+    }
+}
+export function makeContext(console) {
+    return new Context(console, factory.makeDocker(console));
+}