@b3labs/b3iq-cli 0.0.0-stage → 0.1.0

package/dist/lib/ssh-session.js

@@ -0,0 +1,280 @@
+import { spawn } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { connect } from "node:net";
+import { constants, tmpdir } from "node:os";
+import { join } from "node:path";
+import { explainSshMissing } from "./diagnosis.js";
+export const SSH_USER = "b3iq";
+const SIGINT = 2;
+const HOST_KEY_POLICY = "StrictHostKeyChecking=accept-new";
+const DIRECT_HOST_KEY_POLICY = "StrictHostKeyChecking=yes";
+const KEEPALIVE = ["-o", "ServerAliveInterval=15", "-o", "ServerAliveCountMax=3"];
+const DIRECT_CONNECT_TIMEOUT_SECONDS = 8;
+export const DIRECT_PROBE_TIMEOUT_MS = 2_500;
+export function directRoute(address, port, hostKeyAlias, user, passthrough) {
+    return {
+        transport: "direct",
+        host: address,
+        user,
+        args: [
+            "-o", `HostKeyAlias=${hostKeyAlias}`,
+            "-o", DIRECT_HOST_KEY_POLICY,
+            "-o", `ConnectTimeout=${DIRECT_CONNECT_TIMEOUT_SECONDS}`,
+            ...KEEPALIVE,
+            "-p", String(port),
+            `${user}@${address}`,
+            ...passthrough,
+        ],
+    };
+}
+export function bastionRoute(bastion, host, passthrough, keepalive = false) {
+    return {
+        transport: "bastion",
+        host,
+        user: bastion.user,
+        via: bastion.host,
+        args: ["-J", `${bastion.user}@${bastion.host}`, "-o", HOST_KEY_POLICY, ...(keepalive ? KEEPALIVE : []), `${bastion.user}@${host}`, ...passthrough],
+    };
+}
+export function cloudflaredRoute(host, passthrough, user = SSH_USER, keepalive = false) {
+    return {
+        transport: "cloudflared",
+        host,
+        user,
+        args: ["-o", "ProxyCommand=cloudflared access ssh --hostname %h", "-o", HOST_KEY_POLICY, ...(keepalive ? KEEPALIVE : []), `${user}@${host}`, ...passthrough],
+    };
+}
+const SSH_OPTIONS_WITH_ARGUMENT = new Set("BbcDEeFIiJLlmOoPpQRSWw");
+export function hasRemoteCommand(passthrough) {
+    for (let i = 0; i < passthrough.length; i++) {
+        const token = passthrough[i];
+        if (token === "--")
+            return i + 1 < passthrough.length;
+        if (!token.startsWith("-") || token === "-")
+            return true;
+        for (let c = 1; c < token.length; c++) {
+            if (!SSH_OPTIONS_WITH_ARGUMENT.has(token[c]))
+                continue;
+            if (c === token.length - 1)
+                i++;
+            break;
+        }
+    }
+    return false;
+}
+export function wantsOwnSshLogging(passthrough) {
+    for (let i = 0; i < passthrough.length; i++) {
+        const token = passthrough[i];
+        if (token === "--" || !token.startsWith("-") || token === "-")
+            return false;
+        for (let c = 1; c < token.length; c++) {
+            const flag = token[c];
+            if (flag === "v" || flag === "E" || flag === "q" || flag === "y" || flag === "S")
+                return true;
+            if (!SSH_OPTIONS_WITH_ARGUMENT.has(flag))
+                continue;
+            if (c === token.length - 1)
+                i++;
+            break;
+        }
+    }
+    return false;
+}
+export function classifySshRun(code, log) {
+    if (code !== 255)
+        return { kind: "exited", code };
+    const killed = /^Killed by signal (\d+)\./m.exec(log);
+    if (killed)
+        return { kind: "interrupted", signal: Number(killed[1]) };
+    const authenticated = /^Authenticated to /m.test(log);
+    if (!authenticated)
+        return { kind: "connect_failed", reason: lastProblem(log) ?? "ssh could not connect" };
+    const exitStatus = /^debug1: Exit status (-?\d+)/m.exec(log);
+    if (exitStatus && exitStatus[1] !== "-1")
+        return { kind: "exited", code };
+    return { kind: "dropped", reason: lastProblem(log) ?? "the connection was lost" };
+}
+export function lastProblem(log) {
+    const lines = userVisibleLines(log).filter((line) => !/^(Transferred|Bytes per second|Authenticated to|Warning: Permanently added)/.test(line));
+    return lines.at(-1);
+}
+export function userVisibleLines(log) {
+    return log.split("\n").map((line) => line.trimEnd()).filter((line) => line && !line.startsWith("debug"));
+}
+export function probeSsh(address, port, timeoutMs = DIRECT_PROBE_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        const socket = connect({ host: address, port });
+        let banner = "";
+        const done = (ok) => {
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(ok);
+        };
+        const timer = setTimeout(() => done(false), timeoutMs);
+        socket.setEncoding("latin1");
+        socket.on("data", (chunk) => {
+            banner += chunk;
+            if (banner.length >= 4)
+                done(banner.startsWith("SSH-"));
+        });
+        socket.on("error", () => done(false));
+        socket.on("close", () => done(false));
+    });
+}
+export async function firstReachable(endpoint, probe = probeSsh) {
+    const results = endpoint.addresses.map((address) => probe(address, endpoint.port));
+    for (let i = 0; i < results.length; i++) {
+        if (await results[i])
+            return endpoint.addresses[i];
+    }
+    return null;
+}
+export function runSsh(args, logged) {
+    const dir = logged ? mkdtempSync(join(tmpdir(), "b3iq-ssh-")) : null;
+    const logFile = dir ? join(dir, "ssh.log") : null;
+    const fullArgs = logFile ? ["-E", logFile, "-o", "LogLevel=DEBUG1", "-o", "ControlPath=none", ...args] : args;
+    const ignore = () => { };
+    if (logged)
+        process.on("SIGINT", ignore);
+    return new Promise((resolve, reject) => {
+        const child = spawn("ssh", fullArgs, { stdio: "inherit" });
+        child.on("error", (error) => reject(error.code === "ENOENT" ? explainSshMissing() : error));
+        child.on("exit", (code, signal) => {
+            let log = "";
+            if (logFile) {
+                try {
+                    log = readFileSync(logFile, "utf8");
+                }
+                catch {
+                    log = "";
+                }
+            }
+            const signo = signal ? constants.signals[signal] : null;
+            resolve({ code: code ?? (signo !== null ? 128 + signo : 1), log, signal: signo });
+        });
+    }).finally(() => {
+        if (logged)
+            process.off("SIGINT", ignore);
+        if (dir)
+            rmSync(dir, { recursive: true, force: true });
+    });
+}
+export const RECONNECT_DELAYS_MS = [1_000, 2_000, 5_000];
+export const RECONNECT_MAX_DELAY_MS = 10_000;
+export const RECONNECT_WINDOW_MS = 180_000;
+export const RECONNECT_BUDGET_RESET_MS = 60_000;
+export const reconnectDelay = (attempt) => RECONNECT_DELAYS_MS[attempt] ?? RECONNECT_MAX_DELAY_MS;
+export function formatDuration(ms) {
+    const total = Math.max(0, Math.round(ms / 1000));
+    const minutes = Math.floor(total / 60);
+    const seconds = total % 60;
+    return minutes === 0 ? `${seconds} s` : seconds === 0 ? `${minutes} min` : `${minutes} min ${seconds} s`;
+}
+export function isPermanentRefusal(log) {
+    return /Permission denied \(|Host key verification failed|REMOTE HOST IDENTIFICATION HAS CHANGED|Too many authentication failures|no matching host key type/.test(log);
+}
+const describe = (route) => route.transport === "direct" ? `directly at ${route.host}`
+    : route.transport === "bastion" ? `via the bastion ${route.via ?? route.host}`
+        : "over the Cloudflare Tunnel";
+export async function runSession(plan, io, logged = true) {
+    let attempts = 0;
+    let droppedAt = null;
+    let reconnecting = false;
+    for (;;) {
+        const routes = await routesInOrder(plan, io);
+        let outcome = null;
+        let startedAt = io.now();
+        let last = null;
+        if (routes.length === 0) {
+            if (!reconnecting) {
+                io.warn("No direct address answered, and there is no tunnel to fall back to.");
+                return 255;
+            }
+            outcome = { kind: "connect_failed", reason: "no direct address answered" };
+        }
+        for (let i = 0; i < routes.length; i++) {
+            const route = routes[i];
+            io.log(`connecting ${plan.target ? `to ${plan.target} ` : ""}${describe(route)} as ${route.user}…`);
+            startedAt = io.now();
+            last = await io.run(route.args, logged);
+            if (!logged)
+                return last.code;
+            outcome = last.signal !== null ? { kind: "interrupted", signal: last.signal } : classifySshRun(last.code, last.log);
+            if (outcome.kind !== "connect_failed")
+                break;
+            const next = routes[i + 1];
+            if (next)
+                io.warn(`SSH ${describe(route)} failed (${outcome.reason}). Trying ${describe(next)}.`);
+        }
+        if (!outcome)
+            return 255;
+        if (outcome.kind === "exited")
+            return outcome.code;
+        if (outcome.kind === "interrupted") {
+            io.die(outcome.signal);
+            return 128 + outcome.signal;
+        }
+        if (outcome.kind === "connect_failed" && !reconnecting) {
+            for (const line of userVisibleLines(last?.log ?? ""))
+                io.warn(line);
+            return 255;
+        }
+        const what = outcome.kind === "dropped" ? `The connection dropped (${outcome.reason})` : `Could not reconnect (${outcome.reason})`;
+        if (!plan.reconnect) {
+            io.warn(`${what}.`);
+            return 255;
+        }
+        if (outcome.kind === "connect_failed" && isPermanentRefusal(last?.log ?? "")) {
+            for (const line of userVisibleLines(last?.log ?? ""))
+                io.warn(line);
+            io.warn(`${what}. Not retrying: waiting will not fix a refused key or a host key mismatch.`);
+            return 255;
+        }
+        const now = io.now();
+        if (outcome.kind === "dropped" && (droppedAt === null || now - startedAt >= RECONNECT_BUDGET_RESET_MS)) {
+            attempts = 0;
+            droppedAt = now;
+        }
+        droppedAt ??= now;
+        const elapsed = now - droppedAt;
+        const delay = reconnectDelay(attempts);
+        if (elapsed + delay > RECONNECT_WINDOW_MS) {
+            io.warn(`${what}, and it has not come back in ${formatDuration(elapsed)}. Giving up.`);
+            return 255;
+        }
+        attempts++;
+        reconnecting = true;
+        io.warn(`${what}. Reconnecting in ${formatDuration(delay)} (attempt ${attempts}, ${formatDuration(elapsed)} since the drop, ${formatDuration(RECONNECT_WINDOW_MS - elapsed)} left). Ctrl-C to stop.`);
+        const interrupted = await sleepUnlessInterrupted(io, delay);
+        if (interrupted) {
+            io.die(SIGINT);
+            return 128 + SIGINT;
+        }
+    }
+}
+async function routesInOrder(plan, io) {
+    const routes = [];
+    if (plan.direct) {
+        const address = await firstReachable(plan.direct.endpoint, io.probe);
+        if (address)
+            routes.push(plan.direct.route(address));
+        else if (plan.fallback)
+            io.log(`No direct address answered on port ${plan.direct.endpoint.port}; using ${describe(plan.fallback).replace(/^over /, "")}.`);
+    }
+    if (plan.fallback)
+        routes.push(plan.fallback);
+    return routes;
+}
+function sleepUnlessInterrupted(io, ms) {
+    return new Promise((resolve) => {
+        const onInterrupt = () => {
+            process.off("SIGINT", onInterrupt);
+            resolve(true);
+        };
+        process.on("SIGINT", onInterrupt);
+        void io.sleep(ms).then(() => {
+            process.off("SIGINT", onInterrupt);
+            resolve(false);
+        });
+    });
+}

package/dist/lib/ssh-target.js

@@ -0,0 +1,28 @@
+import { isIPv6 } from "node:net";
+import { CliError } from "./output.js";
+const HOSTNAME = /^[A-Za-z0-9](?:[A-Za-z0-9.-]{0,252})$/;
+const USERNAME = /^[A-Za-z_][A-Za-z0-9_.-]{0,31}$/;
+function refuse(what, value) {
+    return new CliError(`The control plane returned an SSH ${what} the CLI will not pass to ssh: ${JSON.stringify(value)}.`, "api", 2, undefined, {
+        diagnostic: "ssh_target_invalid",
+        cause: `The ${what} is not a plain hostname, address, user name or port. ssh hands these to a shell, so the CLI refuses rather than passes it on.`,
+        observed: { field: what, length: typeof value === "string" ? value.length : null },
+        recovery: ["b3iq machines get <machine> --json", "b3iq doctor"],
+        limitation: "Nothing was started. Report the request_id to B3IQ support if the machine's own page shows a normal hostname.",
+    });
+}
+export function assertSshHost(value, what = "hostname") {
+    if (HOSTNAME.test(value) || isIPv6(value))
+        return value;
+    throw refuse(what, value);
+}
+export function assertSshUser(value, what = "user") {
+    if (USERNAME.test(value))
+        return value;
+    throw refuse(what, value);
+}
+export function assertSshPort(value, what = "port") {
+    if (typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65535)
+        return value;
+    throw refuse(what, value);
+}

package/dist/lib/stdin.js

@@ -0,0 +1,16 @@
+import { CliError } from "./output.js";
+const MAX_SECRET_BYTES = 4096;
+export async function readSecretFromStdin(what, stream = process.stdin) {
+    if (stream.isTTY)
+        throw new CliError(`Supply the ${what} over stdin, from a pipe or a file; never as a command-line argument.`, "usage");
+    let input = "";
+    for await (const chunk of stream) {
+        input += String(chunk);
+        if (input.length > MAX_SECRET_BYTES)
+            throw new CliError(`The ${what} is too long.`, "usage");
+    }
+    const key = input.trim();
+    if (!key || /[\r\n]/.test(key))
+        throw new CliError(`Supply one ${what} on stdin.`, "usage");
+    return key;
+}

package/dist/lib/version.js

@@ -0,0 +1 @@
+export const VERSION = "0.1.0";

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@b3labs/b3iq-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Manage your b3iq machines from the terminal or an AI agent.",
+  "keywords": [
+    "b3iq",
+    "gpu",
+    "inference",
+    "cli",
+    "openai-compatible",
+    "neocloud"
+  ],
+  "homepage": "https://b3iq.org",
+  "license": "Apache-2.0",
+  "author": "B3-IQ",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/b3-fun/b3iq.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "email": "hello@b3iq.org"
+  },
+  "bin": {
+    "b3iq": "dist/index.js"
+  },
+  "engines": {
+    "node": "^22.23.4 || ^24.22.1"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "AGENTS.md",
+    "ERROR_PATHS.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "node src/index.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepack": "pnpm --silent run build",
+    "prepublishOnly": "pnpm run typecheck && pnpm run test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "jsonc-parser": "3.3.1",
+    "zod": "4.6.7"
+  }
+}