@moldesk/cli 0.0.1 → 0.0.3

package/dist/commands/doctor.d.ts

@@ -1,2 +1,4 @@
 import type { Command } from "commander";
+import type { SystemReport } from "@moldesk/core";
+export declare function printHuman(report: SystemReport): void;
 export declare function registerDoctorCommand(program: Command): void;

package/dist/commands/doctor.js

@@ -1,22 +1,71 @@
 import { getSystemReport, VERSION } from "@moldesk/core";
 import { checkmark, section } from "../utils/format.js";
+function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return "unknown";
+    const gb = bytes / 1024 ** 3;
+    if (gb >= 1)
+        return `${gb.toFixed(1)} GB`;
+    return `${Math.round(bytes / 1024 ** 2)} MB`;
+}
+export function printHuman(report) {
+    console.log(`MoleculeDesk ${VERSION}`);
+    console.log(section("System"));
+    console.log(`  OS           ${report.platform} (${report.arch})`);
+    console.log(`  CPU          ${report.cpu.model} (${report.cpu.logicalCores} cores)`);
+    console.log(`  Memory       ${formatBytes(report.memory.totalBytes)}`);
+    console.log(`  Disk         ${report.disk.probeFailed ? `unknown (${report.disk.probeError ?? "probe failed"})` : `${formatBytes(report.disk.availableBytes)} free at ${report.disk.path}`}`);
+    console.log(`  ${checkmark(report.appleSilicon)} Apple Silicon${report.appleSilicon ? "" : " not detected"}`);
+    console.log(section("Compute"));
+    const py = report.hostPython;
+    console.log(`  ${checkmark(py.available)} Python       ${py.available ? `${py.version ?? "unknown"}${py.path ? ` (${py.path})` : ""}` : (py.error ?? "not found")} (diagnostic only)`);
+    const gpuCount = report.nvidia.gpus.length;
+    const gpuDetail = report.nvidia.available && gpuCount > 0
+        ? report.nvidia.gpus
+            .map((g) => `${g.name}${typeof g.totalVramBytes === "number" ? ` (${formatBytes(g.totalVramBytes)} VRAM)` : ""}`)
+            .join(", ")
+        : null;
+    console.log(`  ${checkmark(report.nvidia.available)} NVIDIA GPU   ${report.nvidia.available
+        ? `${gpuCount} GPU${gpuCount === 1 ? "" : "s"}: ${gpuDetail ?? "detected"}` +
+            `${report.nvidia.driverCudaVersion ? ` | CUDA (driver max) ${report.nvidia.driverCudaVersion}` : ""}` +
+            `${report.nvidia.cudaToolkitVersion ? ` | CUDA toolkit ${report.nvidia.cudaToolkitVersion}` : ""}` +
+            `${report.nvidia.driverVersion ? ` | driver ${report.nvidia.driverVersion}` : ""}`
+        : (report.nvidia.error ?? "not detected")}`);
+    console.log(section("Docker"));
+    const docker = report.docker;
+    console.log(`  ${checkmark(docker.available)} Installed    ${docker.available ? (docker.version ?? "yes") : (docker.error ?? "not installed")}`);
+    console.log(`  ${checkmark(docker.running)} Running      ${docker.available ? (docker.running ? "running" : "not running") : "n/a"}`);
+    console.log(`  GPU access   ${docker.gpuAccess}`);
+    console.log(section("Notes"));
+    if (!report.nvidia.available) {
+        console.log("  No NVIDIA GPU detected: CUDA/GPU models will run on CPU only.");
+        console.log("  Docker GPU runtimes need the same host NVIDIA driver — Docker does not provide GPU access independently.");
+    }
+    if (report.docker.available && !report.docker.running) {
+        console.log("  Start the Docker daemon to enable docker runtimes.");
+    }
+    if (report.docker.gpuAccess === "unknown") {
+        console.log("  Docker GPU access not yet verified (run `moldesk install` to verify; doctor never pulls images).");
+    }
+    console.log("  Host Python is diagnostic only; installs use managed uv Python.");
+}
 export function registerDoctorCommand(program) {
     program
         .command("doctor")
         .description("Check system compatibility for running models")
-        .action(async () => {
-        const report = await getSystemReport();
-        const { hardware, python, docker } = report;
-        console.log(`MoleculeDesk ${VERSION}`);
-        console.log(section("System"));
-        console.log(`  OS           ${hardware.platform} (${hardware.arch})`);
-        console.log(`  CPU          ${hardware.cpuModel} (${hardware.cpuCores} cores)`);
-        console.log(`  Memory       ${hardware.totalMemoryGb} GB`);
-        console.log(`  ${checkmark(hardware.isAppleSilicon)} Apple Silicon${hardware.isAppleSilicon ? "" : " not detected"}`);
-        console.log(section("Compute"));
-        console.log(`  ${checkmark(python.found)} Python       ${python.found ? python.version : "not found"}`);
-        console.log(`  ${checkmark(docker.installed)} Docker       ${docker.installed ? (docker.running ? `${docker.version} (running)` : `${docker.version} (not running)`) : "not installed"}`);
-        console.log(section("Models"));
-        console.log("  No models installed yet. Run `moldesk list` to see what's available.");
+        .option("--json", "print the raw system report as JSON")
+        .action(async (options) => {
+        try {
+            const report = await getSystemReport();
+            if (options.json) {
+                console.log(JSON.stringify(report, null, 2));
+                return;
+            }
+            printHuman(report);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exitCode = 1;
+        }
     });
 }

package/dist/commands/doctor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/doctor.test.js

@@ -0,0 +1,108 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+import { Command } from "commander";
+import { createFakeSpawn } from "../testSupport/spawnMock.js";
+import { registerDoctorCommand, printHuman } from "./doctor.js";
+const state = vi.hoisted(() => ({
+    handler: ((_cmd, _args) => ({ code: 127, spawnError: true })),
+}));
+vi.mock("node:child_process", () => ({
+    spawn: (command, args) => createFakeSpawn((c, a) => state.handler(c, a))(command, args),
+}));
+let moldeskHome;
+let logs;
+beforeEach(() => {
+    moldeskHome = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk-home-"));
+    process.env["MOLDESK_HOME"] = moldeskHome;
+    logs = [];
+    vi.spyOn(console, "log").mockImplementation((msg) => {
+        logs.push(String(msg));
+    });
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    state.handler = () => ({ code: 127, spawnError: true });
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+    delete process.env["MOLDESK_HOME"];
+    fs.rmSync(moldeskHome, { recursive: true, force: true });
+});
+function buildProgram() {
+    const program = new Command();
+    program.exitOverride();
+    registerDoctorCommand(program);
+    return program;
+}
+describe("doctor (real command, faked process boundary only)", () => {
+    it("never triggers a docker pull or gpu-run probe (doctor stays fast, no pulls)", async () => {
+        state.handler = (cmd, args) => {
+            expect(args).not.toContain("pull");
+            if (cmd === "docker" && args[0] === "run")
+                throw new Error("doctor must never run a docker container");
+            return { code: 127, spawnError: true };
+        };
+        const program = buildProgram();
+        await program.parseAsync(["doctor"], { from: "user" });
+    });
+    it("prints GPU count and per-GPU VRAM when GPUs are present", async () => {
+        state.handler = (cmd, args) => {
+            if (cmd === "nvidia-smi" && args.join(" ").includes("memory.total"))
+                return { code: 0, stdout: "0, NVIDIA A100, 81920\n1, NVIDIA A100, 81920\n" };
+            if (cmd === "nvidia-smi" && args.includes("-x"))
+                return { code: 0, stdout: "<nvidia_smi_log><cuda_version>12.4</cuda_version></nvidia_smi_log>" };
+            if (cmd === "nvidia-smi")
+                return { code: 0, stdout: "550.54.15\n" };
+            return { code: 127, spawnError: true };
+        };
+        const program = buildProgram();
+        await program.parseAsync(["doctor"], { from: "user" });
+        const output = logs.join("\n");
+        expect(output).toContain("2 GPUs:");
+        expect(output).toContain("80.0 GB VRAM");
+        expect(output).toContain("CUDA (driver max) 12.4");
+    });
+    it("renders the corrected no-NVIDIA guidance instead of the misleading Docker-fallback note", async () => {
+        const program = buildProgram();
+        await program.parseAsync(["doctor"], { from: "user" });
+        const output = logs.join("\n");
+        expect(output).toContain("No NVIDIA GPU detected: CUDA/GPU models will run on CPU only.");
+        expect(output).toContain("Docker GPU runtimes need the same host NVIDIA driver");
+        expect(output).not.toMatch(/CPU or Docker fallbacks/);
+    });
+    it("renders 'unknown (<error>)' instead of '0 MB' when the disk probe failed", () => {
+        const report = {
+            capturedAt: "2026-01-01T00:00:00.000Z",
+            platform: "linux",
+            arch: "x64",
+            cpu: { model: "Test CPU", logicalCores: 8 },
+            memory: { totalBytes: 32 * 1024 ** 3 },
+            disk: { availableBytes: 0, path: "/tmp/moldesk", probeFailed: true, probeError: "EACCES: permission denied" },
+            appleSilicon: false,
+            hostPython: { available: false, error: "no python" },
+            docker: { available: false, running: false, gpuAccess: "unknown" },
+            nvidia: { available: false, gpus: [], error: "no gpu" },
+        };
+        printHuman(report);
+        const output = logs.join("\n");
+        expect(output).toContain("unknown (EACCES: permission denied)");
+        expect(output).not.toContain("0 MB");
+    });
+    it("renders the free-space reading normally when the disk probe succeeds (including a genuine zero)", () => {
+        const report = {
+            capturedAt: "2026-01-01T00:00:00.000Z",
+            platform: "linux",
+            arch: "x64",
+            cpu: { model: "Test CPU", logicalCores: 8 },
+            memory: { totalBytes: 32 * 1024 ** 3 },
+            disk: { availableBytes: 0, path: "/tmp/moldesk" },
+            appleSilicon: false,
+            hostPython: { available: false, error: "no python" },
+            docker: { available: false, running: false, gpuAccess: "unknown" },
+            nvidia: { available: false, gpus: [], error: "no gpu" },
+        };
+        printHuman(report);
+        const output = logs.join("\n");
+        expect(output).toContain("0 MB free at /tmp/moldesk");
+    });
+});

package/dist/commands/install.js

@@ -1,17 +1,245 @@
-import { listAvailableModels } from "@moldesk/core";
+import { createInterface } from "node:readline/promises";
+import { createInstallationPlan, evaluateCompatibility, getSystemReport, installModel, isImageCachedLocally, listAvailableModels, probeDockerGpuAccess, pullDockerImage, requiresInstallConfirmation, shortReason, } from "@moldesk/core";
+// TODO: pin by digest (`docker manifest inspect nvidia/cuda:12.4.1-base-ubuntu22.04`)
+// before release — kept as a tag here since resolving a real digest needs a
+// reachable Docker daemon/registry, and fabricating one would be worse than
+// a tag (a wrong digest fails every pull; a tag just isn't reproducible yet).
+const DOCKER_GPU_PROBE_IMAGE = "nvidia/cuda:12.4.1-base-ubuntu22.04";
+const PULL_TIMEOUT_MS = 120_000;
+const PROBE_TIMEOUT_MS = 10_000;
+function parseRuntime(value) {
+    if (value === "python" || value === "docker")
+        return value;
+    console.error(`Invalid --runtime "${value}". Expected python|docker.`);
+    process.exit(1);
+    throw new Error("unreachable");
+}
+function formatBytes(bytes) {
+    if (bytes <= 0)
+        return "unknown";
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1000 && unit < units.length - 1) {
+        value /= 1000;
+        unit += 1;
+    }
+    return `${value >= 10 || unit === 0 ? value.toFixed(0) : value.toFixed(1)} ${units[unit]}`;
+}
+async function confirmDownload(image) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(`Verifying Docker GPU access requires downloading ${image}. Continue? [y/N] `);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+async function confirmInstallation(model) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(`Install ${model}? [y/N] `);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Cost-aware confirmation gate: proceeds without asking for small, known-size,
+ * non-destructive installs; otherwise prompts interactively, or — with no TTY,
+ * `--json`, or `--yes` already declining — fails before any mutation happens.
+ */
+async function decideInstallConfirmation(displayName, needsConfirmation, options) {
+    if (!needsConfirmation || options.yes)
+        return { proceed: true };
+    if (options.json || !process.stdin.isTTY || !process.stdout.isTTY) {
+        return { proceed: false, reason: "confirmation-required" };
+    }
+    return (await confirmInstallation(displayName))
+        ? { proceed: true }
+        : { proceed: false, reason: "cancelled" };
+}
+/**
+ * Tier 2: deterministically probe Docker GPU access, but only for the one
+ * runtime candidate it could actually rescue — a docker runtime with
+ * `gpu: "required"` that is otherwise fully compatible except for an
+ * unverified GPU signal. Never runs for `gpu: "optional"`, never runs more
+ * than once, and never runs at all from `doctor`/`list`.
+ */
+async function verifyDockerGpuAccess(options) {
+    const cached = await isImageCachedLocally(DOCKER_GPU_PROBE_IMAGE);
+    if (!cached) {
+        if (!options.yes) {
+            // Can't prompt interactively in --json mode without a stdin TTY; require --yes there.
+            if (options.json)
+                return "skipped";
+            const confirmed = await confirmDownload(DOCKER_GPU_PROBE_IMAGE);
+            if (!confirmed)
+                return "skipped";
+        }
+        const pullResult = await pullDockerImage(DOCKER_GPU_PROBE_IMAGE, undefined, { timeoutMs: PULL_TIMEOUT_MS });
+        if (!pullResult.ok) {
+            console.error(`Could not download ${DOCKER_GPU_PROBE_IMAGE} to verify GPU access: ${pullResult.error ?? "unknown error"}`);
+            return "skipped";
+        }
+    }
+    const probeResult = await probeDockerGpuAccess(DOCKER_GPU_PROBE_IMAGE, undefined, { timeoutMs: PROBE_TIMEOUT_MS });
+    return probeResult.access;
+}
 export function registerInstallCommand(program) {
     program
         .command("install <model>")
-        .description("Install a model (coming soon)")
-        .action((model) => {
+        .description("Install a model into an isolated, reproducible environment")
+        .option("--runtime <kind>", "select runtime python|docker (no silent fallback)")
+        .option("--yes", "accept downloads and installation without prompting")
+        .option("--reinstall", "stage and atomically replace an existing installation")
+        .option("--json", "print compatibility/plan result as JSON")
+        .action(async (model, options) => {
         const available = listAvailableModels();
         const manifest = available.find((m) => m.name === model);
         if (!manifest) {
-            console.error(`Unknown model "${model}". Run \`moldesk list\` to see available models.`);
+            const message = `Unknown model "${model}". Run \`moldesk list\` to see available models.`;
+            if (options.json) {
+                console.log(JSON.stringify({ model, status: "unknown-model", message }, null, 2));
+            }
+            else {
+                console.error(message);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const requestedRuntime = options.runtime ? parseRuntime(options.runtime) : undefined;
+        let report = await getSystemReport();
+        let compatibility = evaluateCompatibility(manifest, report, { requestedRuntime });
+        // Deterministic Tier 2: only for the single docker+gpu:required candidate
+        // that would otherwise be selected if GPU access were verified.
+        if (!requestedRuntime || requestedRuntime === "docker") {
+            const rescuable = compatibility.runtimes.find((rt) => rt.kind === "docker" &&
+                rt.status === "unsupported" &&
+                rt.reasons.length > 0 &&
+                rt.reasons.every((r) => r.code === "DOCKER_GPU_UNVERIFIED"));
+            if (rescuable) {
+                const verified = await verifyDockerGpuAccess(options);
+                if (verified !== "skipped") {
+                    report = await getSystemReport({ dockerGpuAccess: verified });
+                    compatibility = evaluateCompatibility(manifest, report, { requestedRuntime });
+                }
+            }
+        }
+        if (compatibility.status === "unsupported") {
+            const reason = shortReason(compatibility);
+            if (options.json) {
+                console.log(JSON.stringify({ model, status: "unsupported", compatibility }, null, 2));
+            }
+            else {
+                console.error(`Cannot install "${model}": ${reason || "unsupported on this machine"}.`);
+                for (const rt of compatibility.runtimes) {
+                    console.error(`  [${rt.kind}] ${rt.status}`);
+                    for (const r of rt.reasons) {
+                        console.error(`    ${r.code}: ${r.message}${r.remediation ? ` — ${r.remediation}` : ""}`);
+                    }
+                }
+                console.error("No files were written.");
+            }
             process.exitCode = 1;
             return;
         }
-        console.log(`Installing "${model}" is not yet supported.`);
-        console.log("Track progress at https://github.com/pooriyapfn/moldesk");
+        const runtime = manifest.runtimes.find((candidate) => candidate.kind === compatibility.selectedRuntime);
+        if (!runtime) {
+            console.error(`Cannot resolve selected runtime for "${model}".`);
+            process.exitCode = 1;
+            return;
+        }
+        let planned;
+        try {
+            planned = await createInstallationPlan(manifest, runtime);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (options.json) {
+                console.log(JSON.stringify({ model, status: compatibility.status, selectedRuntime: runtime.kind, compatibility, installable: false, message }, null, 2));
+            }
+            else {
+                console.error(message);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const payload = {
+            model,
+            status: compatibility.status,
+            selectedRuntime: runtime.kind,
+            compatibility,
+            alreadyInstalled: planned.alreadyInstalled,
+            reinstall: options.reinstall ?? false,
+            targetDir: planned.targetDir,
+            estimatedDownloadBytes: planned.estimatedDownloadBytes,
+            estimatedDiskBytes: planned.estimatedDiskBytes,
+            steps: planned.plan.steps,
+        };
+        // An identical fingerprint that's already installed and not being replaced is a
+        // successful no-op below — nothing will be mutated, so there is nothing to confirm.
+        const isNoop = planned.alreadyInstalled && !options.reinstall;
+        const destructive = Boolean(options.reinstall) && planned.alreadyInstalled;
+        const needsConfirmation = !isNoop && requiresInstallConfirmation({
+            downloadBytes: planned.estimatedDownloadBytes,
+            downloadSizeUnknown: planned.downloadSizeUnknown,
+            diskBytes: planned.estimatedDiskBytes,
+            diskSizeUnknown: planned.diskSizeUnknown,
+        }, { destructive });
+        if (!options.json) {
+            console.log(`Installation plan for ${manifest.displayName} (${runtime.kind}):`);
+            for (const [index, step] of planned.plan.steps.entries())
+                console.log(`  ${index + 1}. ${step.description}`);
+            console.log(`  Download: ${formatBytes(planned.estimatedDownloadBytes)}${planned.downloadSizeUnknown ? " (partly unknown)" : ""}`);
+            console.log(`  Additional disk: ${formatBytes(planned.estimatedDiskBytes)}${planned.diskSizeUnknown ? " (unknown)" : ""}`);
+            console.log(`  Target: ${planned.targetDir}`);
+        }
+        const decision = await decideInstallConfirmation(manifest.displayName, needsConfirmation, options);
+        if (!decision.proceed) {
+            if (decision.reason === "confirmation-required") {
+                const message = `Installing ${manifest.displayName} requires confirmation (large or unknown-size download/disk use, or a destructive reinstall). Re-run with --yes.`;
+                if (options.json)
+                    console.log(JSON.stringify({ ...payload, status: "confirmation-required", message }, null, 2));
+                else
+                    console.error(message);
+                process.exitCode = 1;
+            }
+            else {
+                if (options.json)
+                    console.log(JSON.stringify({ ...payload, status: "cancelled" }, null, 2));
+                else
+                    console.log("Installation cancelled. Re-run with --yes for non-interactive use.");
+            }
+            return;
+        }
+        try {
+            const result = await installModel(planned, {
+                reinstall: options.reinstall,
+                onProgress: options.json ? undefined : (progress) => {
+                    if (progress.receivedBytes !== undefined && progress.totalBytes) {
+                        const percent = Math.floor((progress.receivedBytes / progress.totalBytes) * 100);
+                        console.log(`  [${progress.step}] ${progress.message} (${percent}%)`);
+                    }
+                    else {
+                        console.log(`  [${progress.step}] ${progress.message}`);
+                    }
+                },
+            });
+            if (options.json)
+                console.log(JSON.stringify({ ...payload, status: result.status, installation: result.installation }, null, 2));
+            else
+                console.log(`${manifest.displayName}: ${result.status}.`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (options.json)
+                console.log(JSON.stringify({ ...payload, status: "failed", message }, null, 2));
+            else
+                console.error(`Installation failed: ${message}`);
+            process.exitCode = 1;
+        }
     });
 }

package/dist/commands/install.test.d.ts

@@ -0,0 +1 @@
+export {};