askmri 0.0.1

package/README.md

@@ -0,0 +1,10 @@
+# AskMRI
+
+The open AI workbench for MRI research.
+
+```bash
+npx askmri doctor
+npx askmri setup
+```
+
+[askmri.com](https://askmri.com) · [GitHub](https://github.com/askmri)

package/dist/bootstrap/uv.d.ts

@@ -0,0 +1,45 @@
+type EnvGroup = "base" | "ants" | "totalseg" | "brats";
+/**
+ * Bootstrap pipeline:
+ *   1. ensure `uv` is on PATH (install if missing)
+ *   2. ensure ASKMRI_HOME directories exist
+ *   3. ensure a venv with `askmri[full-light]` installed
+ *
+ * Per-tool-group venvs are created lazily via `ensureGroupVenv()` when
+ * installing models that require isolated environments (ants, totalseg, brats).
+ *
+ * The heavy ML extras stay opt-in via `askmri setup --with ants,total`.
+ */
+interface CommandCheck {
+    ok: boolean;
+    version?: string;
+}
+export declare function commandExists(name: string): Promise<CommandCheck>;
+export declare function ensureUv(): Promise<void>;
+export declare function ensureDirs(): void;
+export interface InstallOptions {
+    extras?: string[];
+    force?: boolean;
+}
+export declare function ensureVenv(opts?: InstallOptions): Promise<void>;
+export interface GroupVenvOptions {
+    /** Force reinstall even if marker exists */
+    force?: boolean;
+}
+/**
+ * Ensure a per-tool-group venv exists and has its dependencies installed.
+ * Used for isolated environments (ants, totalseg, brats) that have conflicting
+ * numpy requirements.
+ *
+ * - "base" is a no-op (always uses the main venv)
+ * - Other groups create ~/.askmri/venvs/{group}/ with Python 3.11
+ *
+ * Returns the venv path.
+ */
+export declare function ensureGroupVenv(group: EnvGroup, opts?: GroupVenvOptions): Promise<string>;
+/**
+ * Check if a group's venv is installed (marker file exists).
+ */
+export declare function isGroupVenvInstalled(group: EnvGroup): boolean;
+export {};
+//# sourceMappingURL=uv.d.ts.map

package/dist/bootstrap/uv.js

@@ -0,0 +1,138 @@
+import { mkdirSync, existsSync, writeFileSync } from "node:fs";
+import { x } from "tinyexec";
+import { log } from "../log.js";
+import { paths, venvFor, venvMarkerFor } from "../paths.js";
+const ENV_GROUP_LABELS = {
+    base: "Base (builtin)",
+    ants: "ANTsPy / ANTsPyNet",
+    totalseg: "TotalSegmentator",
+    brats: "BraTS Toolkit",
+};
+const ENV_GROUP_INSTALL_CMDS = {
+    base: null,
+    ants: "pip install antspynet",
+    totalseg: "pip install TotalSegmentator",
+    brats: "pip install brats-toolkit",
+};
+export async function commandExists(name) {
+    try {
+        const result = await x(name, ["--version"], { throwOnError: false });
+        if (result.exitCode === 0) {
+            const firstLine = result.stdout.trim().split("\n")[0];
+            return { ok: true, version: firstLine ?? result.stdout.trim() };
+        }
+        return { ok: false };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+export async function ensureUv() {
+    const uv = await commandExists("uv");
+    if (uv.ok) {
+        log.ok(`uv detected (${uv.version})`);
+        return;
+    }
+    log.warn("uv not found — installing it locally");
+    // Use the official installer; it places `uv` at ~/.local/bin/uv (Unix) or %USERPROFILE%\.local\bin (Win).
+    if (process.platform === "win32") {
+        await x("powershell", [
+            "-ExecutionPolicy",
+            "ByPass",
+            "-c",
+            "irm https://astral.sh/uv/install.ps1 | iex",
+        ]);
+    }
+    else {
+        await x("sh", ["-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"]);
+    }
+    const recheck = await commandExists("uv");
+    if (!recheck.ok) {
+        throw new Error("uv installation finished but `uv` is still not on PATH. Add ~/.local/bin to PATH and re-run.");
+    }
+    log.ok(`uv installed (${recheck.version})`);
+}
+export function ensureDirs() {
+    for (const dir of [paths.home, paths.bin, paths.venvs, paths.cache, paths.data, paths.logs]) {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+    }
+}
+export async function ensureVenv(opts = {}) {
+    ensureDirs();
+    const venvExists = existsSync(paths.venv);
+    if (venvExists && existsSync(paths.marker) && !opts.force) {
+        log.ok("Python environment already installed");
+        return;
+    }
+    if (!venvExists) {
+        log.step(`Creating Python venv at ${paths.venv}`);
+        await x("uv", ["venv", "--python", "3.11", paths.venv]);
+    }
+    const pkg = opts.extras?.length ? `askmri[${opts.extras.join(",")}]` : "askmri";
+    log.step(`Installing ${pkg} into the venv (this may take a minute)`);
+    await x("uv", ["pip", "install", "--python", paths.venv, pkg], {
+        nodeOptions: { stdio: "inherit" },
+    });
+    // Drop a marker file so subsequent invocations skip the install step.
+    writeFileSync(paths.marker, new Date().toISOString());
+    log.ok("Python environment ready");
+}
+/**
+ * Ensure a per-tool-group venv exists and has its dependencies installed.
+ * Used for isolated environments (ants, totalseg, brats) that have conflicting
+ * numpy requirements.
+ *
+ * - "base" is a no-op (always uses the main venv)
+ * - Other groups create ~/.askmri/venvs/{group}/ with Python 3.11
+ *
+ * Returns the venv path.
+ */
+export async function ensureGroupVenv(group, opts = {}) {
+    // "base" group uses the main venv — nothing to do
+    if (group === "base") {
+        return paths.venv;
+    }
+    ensureDirs();
+    const venvPath = venvFor(group);
+    const markerPath = venvMarkerFor(group);
+    const venvExists = existsSync(venvPath);
+    const markerExists = existsSync(markerPath);
+    // If already installed and not forcing, skip
+    if (venvExists && markerExists && !opts.force) {
+        log.ok(`${ENV_GROUP_LABELS[group]} environment already installed`);
+        return venvPath;
+    }
+    // Create the venv if it doesn't exist
+    if (!venvExists) {
+        log.step(`Creating isolated venv for ${ENV_GROUP_LABELS[group]} at ${venvPath}`);
+        await x("uv", ["venv", "--python", "3.11", venvPath]);
+    }
+    // Install group dependencies
+    const installCmd = ENV_GROUP_INSTALL_CMDS[group];
+    if (installCmd) {
+        // Extract package spec from "pip install <package>"
+        const packageSpec = installCmd.replace(/^pip install\s+/, "").replace(/^['"]|['"]$/g, "");
+        log.step(`Installing ${packageSpec} into ${group} venv`);
+        const result = await x("uv", ["pip", "install", "--python", venvPath, packageSpec], {
+            nodeOptions: { stdio: "inherit" },
+            throwOnError: false,
+        });
+        if (result.exitCode !== 0) {
+            throw new Error(`Failed to install ${packageSpec} (exit code ${result.exitCode})`);
+        }
+    }
+    // Drop marker only after successful install
+    writeFileSync(markerPath, new Date().toISOString());
+    log.ok(`${ENV_GROUP_LABELS[group]} environment ready`);
+    return venvPath;
+}
+/**
+ * Check if a group's venv is installed (marker file exists).
+ */
+export function isGroupVenvInstalled(group) {
+    if (group === "base") {
+        return existsSync(paths.marker);
+    }
+    return existsSync(venvMarkerFor(group));
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,2 @@
+export declare function doctor(): Promise<number>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.js

@@ -0,0 +1,213 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { totalmem } from "node:os";
+import { join } from "node:path";
+import { x } from "tinyexec";
+import { commandExists } from "../bootstrap/uv.js";
+import { log } from "../log.js";
+import { monaiBundlesDir, paths, pythonBin, pythonCliBin } from "../paths.js";
+/**
+ * Probe a Python import inside the managed venv. Returns the version
+ * string emitted by `<pkg>.__version__` when available, otherwise "ok".
+ */
+async function probePythonImport(pkg, attr = "__version__") {
+    if (!existsSync(pythonBin())) {
+        return { ok: false, detail: "venv missing" };
+    }
+    const script = `import ${pkg}; v=getattr(${pkg}, '${attr}', 'ok'); print(v)`;
+    try {
+        const r = await x(pythonBin(), ["-c", script], { throwOnError: false });
+        if (r.exitCode === 0) {
+            return { ok: true, detail: (r.stdout ?? "").trim() || "ok" };
+        }
+        return { ok: false, detail: "not installed" };
+    }
+    catch {
+        return { ok: false, detail: "probe failed" };
+    }
+}
+async function probeGpu() {
+    if (!existsSync(pythonBin())) {
+        return { ok: false, detail: "venv missing" };
+    }
+    const script = "import torch; "
+        + "cuda=torch.cuda.is_available(); "
+        + "mps=getattr(torch.backends,'mps',None) and torch.backends.mps.is_available(); "
+        + "print('cuda' if cuda else ('mps' if mps else 'cpu'))";
+    try {
+        const r = await x(pythonBin(), ["-c", script], { throwOnError: false });
+        if (r.exitCode !== 0)
+            return { ok: false, detail: "torch not installed" };
+        const dev = (r.stdout ?? "").trim();
+        return { ok: dev !== "cpu", detail: dev || "cpu" };
+    }
+    catch {
+        return { ok: false, detail: "probe failed" };
+    }
+}
+function bundleCacheSummary() {
+    if (!existsSync(monaiBundlesDir))
+        return "empty";
+    try {
+        const entries = readdirSync(monaiBundlesDir).filter((e) => statSync(join(monaiBundlesDir, e)).isDirectory());
+        return entries.length === 0
+            ? "empty"
+            : `${entries.length} bundle(s): ${entries.slice(0, 3).join(", ")}${entries.length > 3 ? "…" : ""}`;
+    }
+    catch {
+        return "unreadable";
+    }
+}
+async function checks() {
+    const results = [];
+    // ---------- Core ----------
+    const node = process.versions.node;
+    const nodeMajor = node.split(".")[0];
+    results.push({
+        name: "Node.js",
+        required: true,
+        ok: nodeMajor !== undefined && parseInt(nodeMajor, 10) >= 18,
+        detail: `v${node}`,
+        fix: "Upgrade to Node 18.18+ from https://nodejs.org",
+    });
+    const uv = await commandExists("uv");
+    results.push({
+        name: "uv (Python installer)",
+        required: true,
+        ok: uv.ok,
+        detail: uv.version ?? "not found",
+        fix: "Run `askmri setup` to install uv automatically.",
+    });
+    const venvOk = existsSync(pythonCliBin());
+    results.push({
+        name: "Python venv + askmri-server",
+        required: true,
+        ok: venvOk,
+        detail: venvOk ? paths.venv : "not installed",
+        fix: "Run `askmri setup`",
+    });
+    // ---------- Optional binaries on PATH ----------
+    const dcm2niix = await commandExists("dcm2niix");
+    results.push({
+        name: "dcm2niix (DICOM → NIfTI)",
+        required: false,
+        ok: dcm2niix.ok,
+        detail: dcm2niix.version ?? "not found",
+        fix: "macOS: `brew install dcm2niix` · Ubuntu: `apt install dcm2niix`",
+    });
+    const synthstrip = await commandExists("mri_synthstrip");
+    results.push({
+        name: "mri_synthstrip (alt skull-strip)",
+        required: false,
+        ok: synthstrip.ok,
+        detail: synthstrip.version ?? "not found",
+        fix: "FreeSurfer 7.3+ or https://surfer.nmr.mgh.harvard.edu/docs/synthstrip",
+    });
+    const npx = await commandExists("npx");
+    results.push({
+        name: "npx (for bids-validator)",
+        required: false,
+        ok: npx.ok,
+        detail: npx.version ?? "not found",
+        fix: "Bundled with Node.js 18+",
+    });
+    // ---------- Optional Python packages ----------
+    if (venvOk) {
+        const optional = [
+            ["pyradiomics", "radiomics", "pip install 'askmri-core[radiomics]'"],
+            ["highdicom", "highdicom", "pip install 'askmri-core[interop]'"],
+            ["nilearn", "nilearn", "pip install 'askmri-core[reports]'"],
+            ["monai", "monai", "pip install 'askmri-core[monai]'"],
+            ["dicomanonymizer", "dicomanonymizer", "pip install 'askmri-core[anonymize]'"],
+            ["torch", "torch", "pip install 'askmri-core[torch]'"],
+            ["antspynet", "antspynet", "pip install 'askmri-core[ants]'"],
+            ["HD-BET", "HD_BET", "pip install 'askmri-core[hdbet]'"],
+            ["TotalSegmentator", "totalsegmentator", "pip install TotalSegmentator"],
+        ];
+        for (const [label, importName, fix] of optional) {
+            const r = await probePythonImport(importName);
+            results.push({
+                name: label,
+                required: false,
+                ok: r.ok,
+                detail: r.detail,
+                fix,
+            });
+        }
+    }
+    // ---------- GPU ----------
+    if (venvOk) {
+        const gpu = await probeGpu();
+        results.push({
+            name: "Accelerator",
+            required: false,
+            ok: gpu.ok,
+            detail: gpu.detail,
+            fix: "Install torch with CUDA / MPS support for GPU acceleration.",
+        });
+    }
+    // ---------- MONAI bundle cache ----------
+    results.push({
+        name: "MONAI bundle cache",
+        required: false,
+        ok: existsSync(monaiBundlesDir),
+        detail: bundleCacheSummary(),
+        fix: "First `askmri-server monai-bundle download <name>` will create it.",
+    });
+    // ---------- Host resources ----------
+    const ram = totalmem() / 1024 / 1024 / 1024;
+    results.push({
+        name: "System RAM",
+        required: false,
+        ok: ram >= 8,
+        detail: `${ram.toFixed(1)} GiB`,
+        fix: "8 GiB minimum recommended; 16 GiB comfortable for TotalSegmentator.",
+    });
+    const dataDirExists = existsSync(paths.data);
+    results.push({
+        name: "Data directory",
+        required: false,
+        ok: dataDirExists,
+        detail: dataDirExists ? `${paths.data} (${dirSize(paths.data)})` : "missing",
+        fix: "`askmri setup` will create it.",
+    });
+    return results;
+}
+function dirSize(_dir) {
+    try {
+        const s = statSync(_dir);
+        return s.isDirectory() ? "ready" : "not a directory";
+    }
+    catch {
+        return "unknown";
+    }
+}
+export async function doctor() {
+    log.header("AskMRI compatibility check");
+    const all = await checks();
+    let hasFailure = false;
+    for (const c of all) {
+        const label = `${c.name.padEnd(34)} ${c.detail}`;
+        if (c.ok) {
+            log.ok(label);
+        }
+        else if (c.required) {
+            log.error(label);
+            if (c.fix)
+                log.step(`fix: ${c.fix}`);
+            hasFailure = true;
+        }
+        else {
+            log.warn(label);
+            if (c.fix)
+                log.step(`fix: ${c.fix}`);
+        }
+    }
+    console.error();
+    if (hasFailure) {
+        log.error("Some required dependencies are missing. Run `askmri setup`.");
+        return 1;
+    }
+    log.ok("Ready for MRI research.");
+    log.step("Install optional extras: `askmri setup --with radiomics,reports,interop,monai,anonymize,full`");
+    return 0;
+}

package/dist/commands/passthrough.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Forward every argument unchanged to the bundled `askmri-server` Python
+ * binary. If the venv is missing, install it first.
+ *
+ * Examples:
+ *   askmri info ./dicom              → askmri-server info ./dicom
+ *   askmri run ./dicom -m totalseg   → askmri-server run ./dicom -m totalseg
+ */
+export declare function passthrough(args: string[]): Promise<number>;
+//# sourceMappingURL=passthrough.d.ts.map

package/dist/commands/passthrough.js

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs";
+import { x } from "tinyexec";
+import { ensureUv, ensureVenv } from "../bootstrap/uv.js";
+import { log } from "../log.js";
+import { pythonCliBin } from "../paths.js";
+/**
+ * Forward every argument unchanged to the bundled `askmri-server` Python
+ * binary. If the venv is missing, install it first.
+ *
+ * Examples:
+ *   askmri info ./dicom              → askmri-server info ./dicom
+ *   askmri run ./dicom -m totalseg   → askmri-server run ./dicom -m totalseg
+ */
+export async function passthrough(args) {
+    if (!existsSync(pythonCliBin())) {
+        log.info("First run — installing the Python pipeline…");
+        await ensureUv();
+        await ensureVenv();
+    }
+    const result = await x(pythonCliBin(), args, {
+        nodeOptions: { stdio: "inherit" },
+        throwOnError: false,
+    });
+    return result.exitCode ?? 1;
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1,6 @@
+import { type InstallOptions } from "../bootstrap/uv.js";
+export interface SetupOptions extends InstallOptions {
+}
+export declare function setup(opts?: SetupOptions): Promise<number>;
+export declare function parseSetupArgs(argv: string[]): SetupOptions;
+//# sourceMappingURL=setup.d.ts.map

package/dist/commands/setup.js

@@ -0,0 +1,40 @@
+import { ensureUv, ensureVenv } from "../bootstrap/uv.js";
+import { log } from "../log.js";
+import { paths } from "../paths.js";
+export async function setup(opts = {}) {
+    log.header("Setup");
+    log.info(`Home: ${paths.home}`);
+    if (opts.extras?.length)
+        log.info(`Extras: ${opts.extras.join(", ")}`);
+    if (opts.force)
+        log.info("Force reinstall: yes");
+    try {
+        await ensureUv();
+        await ensureVenv(opts);
+    }
+    catch (err) {
+        log.error(err instanceof Error ? err.message : String(err));
+        log.step("If this is a network issue, retry. Otherwise report at https://github.com/iplanwebsites/askmri/issues");
+        return 1;
+    }
+    console.error();
+    log.ok("Setup complete.");
+    log.step("Next: `askmri doctor` to verify, or `askmri serve` to launch the viewer.");
+    return 0;
+}
+export function parseSetupArgs(argv) {
+    const opts = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--with" || a === "-w") {
+            const next = argv[++i];
+            if (!next)
+                continue;
+            opts.extras = next.split(",").map((s) => s.trim()).filter(Boolean);
+        }
+        else if (a === "--force" || a === "-f") {
+            opts.force = true;
+        }
+    }
+    return opts;
+}

package/dist/commands/version.d.ts

@@ -0,0 +1,2 @@
+export declare function versionCommand(args: string[]): Promise<number>;
+//# sourceMappingURL=version.d.ts.map

package/dist/commands/version.js

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+import { x } from "tinyexec";
+import kleur from "kleur";
+import { VERSION } from "../version.js";
+import { pythonCliBin } from "../paths.js";
+import { log } from "../log.js";
+async function readPythonVersions() {
+    if (!existsSync(pythonCliBin()))
+        return null;
+    const res = await x(pythonCliBin(), ["version-json"], { throwOnError: false });
+    if (res.exitCode !== 0)
+        return null;
+    try {
+        return JSON.parse(res.stdout);
+    }
+    catch {
+        return null;
+    }
+}
+export async function versionCommand(args) {
+    const check = args.includes("--check");
+    const json = args.includes("--json");
+    const py = await readPythonVersions();
+    if (json) {
+        console.log(JSON.stringify({
+            launcher: VERSION,
+            python: py,
+        }, null, 2));
+        return 0;
+    }
+    if (!check) {
+        console.log(VERSION);
+        return 0;
+    }
+    // --check mode: print a comparison table and fail on drift.
+    console.error(kleur.bold("Version alignment\n"));
+    const row = (label, value, expected) => {
+        const v = value ?? kleur.dim("(not installed)");
+        const ok = !expected || value === expected;
+        const mark = ok ? kleur.green("✓") : kleur.red("✗");
+        console.error(`  ${mark} ${label.padEnd(20)} ${v}`);
+        return ok;
+    };
+    let allAligned = row("launcher (npm)", VERSION);
+    if (!py) {
+        console.error(kleur.yellow("\n  Python pipeline is not installed yet."));
+        console.error(kleur.dim("  Run `askmri setup` to install it."));
+        return check ? 1 : 0;
+    }
+    allAligned = row("askmri-cli", py["askmri-cli"], VERSION) && allAligned;
+    allAligned = row("askmri-core", py["askmri-core"], VERSION) && allAligned;
+    allAligned = row("askmri-api", py["askmri-api"], VERSION) && allAligned;
+    allAligned = row("askmri (meta)", py.askmri, VERSION) && allAligned;
+    console.error();
+    if (!allAligned) {
+        log.error("Version drift between the npm launcher and the installed Python pipeline.");
+        log.step("Run `askmri setup --force` to reinstall and align.");
+        return 1;
+    }
+    log.ok("All versions aligned.");
+    return 0;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+import kleur from "kleur";
+import { doctor } from "./commands/doctor.js";
+import { setup, parseSetupArgs } from "./commands/setup.js";
+import { passthrough } from "./commands/passthrough.js";
+import { versionCommand } from "./commands/version.js";
+import { paths } from "./paths.js";
+import { VERSION } from "./version.js";
+import { log, initFileLogging } from "./log.js";
+// ============================================================================
+// MINIMAL_MODE: Toggle full CLI features for npm publish.
+// To enable full mode: set MINIMAL_MODE = false and uncomment the loaders.
+// ============================================================================
+const MINIMAL_MODE = true;
+// const MINIMAL_MODE = false
+// const loadServe = () => import("./commands/serve.js")
+// const loadOpen = () => import("./commands/open.js")
+// const loadConfig = () => import("./commands/config.js")
+// const loadDatasets = () => import("./commands/datasets.js")
+const HELP_MINIMAL = `${kleur.bold("askmri")} v${VERSION} — MRI research toolkit
+
+${kleur.dim("Usage:")} askmri <command> [options]
+
+${kleur.bold("Commands:")}
+  ${kleur.cyan("doctor")}              Check Python, uv, environment
+  ${kleur.cyan("setup")} [--with X]    Install the Python pipeline
+  ${kleur.cyan("version")} [--check]   Print version
+  ${kleur.cyan("home")}                Print the AskMRI home directory
+  ${kleur.cyan("help")}                Show this message
+
+${kleur.bold("Examples:")}
+  ${kleur.dim("$")} npx askmri doctor
+  ${kleur.dim("$")} npx askmri setup
+
+${kleur.bold("Environment:")}
+  ASKMRI_HOME       Override the install directory (default: ~/.askmri)
+
+More at https://askmri.com
+`;
+const HELP_FULL = `${kleur.bold("askmri")} v${VERSION} — MRI research toolkit (research preview, not for clinical use)
+
+${kleur.dim("Usage:")} askmri <command> [options]
+
+${kleur.bold("Launcher commands:")}
+  ${kleur.cyan("open")}                Open the viewer in a desktop app window (chromeless)
+  ${kleur.cyan("serve")} [--port P]    Start the web viewer + API (headless, for dev/scripting)
+  ${kleur.cyan("datasets")} <cmd>      Browse, download, and process public datasets
+  ${kleur.cyan("doctor")}              Check uv, venv, optional Python deps, GPU, MONAI cache
+  ${kleur.cyan("setup")} [--with X]    Install the Python pipeline (extras: radiomics,reports,interop,monai,anonymize,torch,ants,hdbet,full)
+  ${kleur.cyan("config")} <cmd>        Manage API keys (set/get/list/delete/sync)
+  ${kleur.cyan("version")} [--check]   Print launcher version; --check compares against the Python pipeline
+  ${kleur.cyan("home")}                Print the AskMRI home directory
+  ${kleur.cyan("help")}                Show this message
+
+${kleur.bold("Passthrough to the Python pipeline (askmri-server):")}
+  ${kleur.cyan("info")} <folder>                          DICOM metadata
+  ${kleur.cyan("run")} <folder> -m <method>               Full pipeline
+  ${kleur.cyan("preprocess")} <folder>                    DICOM → NIfTI (auto-detects body region)
+  ${kleur.cyan("analyze")} <file> -m <method>             Run a single method
+  ${kleur.cyan("stats")} <file>                           Volume statistics
+  ${kleur.cyan("analyze-all")} <file>                     Run multiple methods on one input
+  ${kleur.cyan("radiomics")} <image> <mask>               PyRadiomics features per label
+  ${kleur.cyan("export-dicom-seg")} <mask> <reference>    Mask → DICOM-SEG via highdicom
+  ${kleur.cyan("anonymize")} <path>                       PHI scrubbing on DICOM file/dir
+  ${kleur.cyan("html-report")} <scan_dir>                 Printable HTML report (nilearn)
+  ${kleur.cyan("monai-bundle")} {list|info|download|run}  MONAI model-zoo loader
+  ${kleur.cyan("validate-bids")} <path>                   Validate a BIDS dataset (npx)
+
+${kleur.bold("Examples:")}
+  ${kleur.dim("$")} npx askmri open                    # Launch viewer in app window
+  ${kleur.dim("$")} npx askmri serve --port 5173       # Headless server for dev
+  ${kleur.dim("$")} npx askmri doctor
+  ${kleur.dim("$")} npx askmri setup
+  ${kleur.dim("$")} npx askmri run ./dicom -m totalseg
+
+${kleur.bold("Environment:")}
+  ASKMRI_HOME       Override the install directory (default: ~/.askmri)
+  ASKMRI_QUIET      Set to "1" to suppress non-error console output
+  ASKMRI_NO_LOG     Set to "1" to disable file logging
+`;
+const HELP = MINIMAL_MODE ? HELP_MINIMAL : HELP_FULL;
+// Commands that should NOT auto-print the launcher banner (they need clean
+// stdout for piping, or print their own banner).
+const QUIET_COMMANDS = new Set([
+    "version",
+    "home",
+    "help",
+    "-h",
+    "--help",
+    "-v",
+    "--version",
+]);
+async function main(argv) {
+    const [cmd, ...rest] = argv;
+    if (cmd && !QUIET_COMMANDS.has(cmd)) {
+        initFileLogging();
+        log.banner(VERSION, paths.home);
+    }
+    switch (cmd) {
+        case undefined:
+        case "-h":
+        case "--help":
+        case "help":
+            console.error(HELP);
+            return 0;
+        case "-v":
+        case "--version":
+        case "version":
+            return versionCommand(rest);
+        case "home":
+            console.log(paths.home);
+            return 0;
+        case "doctor":
+            return doctor();
+        case "setup":
+            if (rest.length === 0 || rest.every((a) => a.startsWith("-"))) {
+                return setup(parseSetupArgs(rest));
+            }
+            if (MINIMAL_MODE) {
+                console.error(`Unknown command: ${cmd}`);
+                return 1;
+            }
+            return passthrough([cmd, ...rest]);
+        // [FULL] case "serve": {
+        // [FULL]   const { serve, parseServeArgs } = await loadServe()
+        // [FULL]   return serve(parseServeArgs(rest))
+        // [FULL] }
+        // [FULL] case "open": {
+        // [FULL]   const { open, parseOpenArgs } = await loadOpen()
+        // [FULL]   return open(parseOpenArgs(rest))
+        // [FULL] }
+        // [FULL] case "config": {
+        // [FULL]   const { config } = await loadConfig()
+        // [FULL]   return config(rest)
+        // [FULL] }
+        // [FULL] case "datasets": {
+        // [FULL]   const { datasets } = await loadDatasets()
+        // [FULL]   return datasets(rest)
+        // [FULL] }
+        // [FULL] default:
+        // [FULL]   return passthrough([cmd, ...rest])
+        default:
+            console.error(`Unknown command: ${cmd}`);
+            return 1;
+    }
+}
+main(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    log.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/log.d.ts

@@ -0,0 +1,16 @@
+export declare function initFileLogging(): string | null;
+export declare const log: {
+    info(msg: string): void;
+    ok(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    step(msg: string): void;
+    header(msg: string): void;
+    /** Print the launcher's identity banner on every non-quiet invocation. */
+    banner(version: string, home: string): void;
+    /** Used by the Python subprocess proxy in serve.ts. */
+    python(line: string): void;
+    /** Filesystem path of the current log file, if file logging is active. */
+    readonly file: string | null;
+};
+//# sourceMappingURL=log.d.ts.map

package/dist/log.js

@@ -0,0 +1,85 @@
+import kleur from "kleur";
+import { existsSync, mkdirSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { platform, arch, totalmem, release } from "node:os";
+import { paths } from "./paths.js";
+const isQuiet = process.env.ASKMRI_QUIET === "1";
+const fileLoggingDisabled = process.env.ASKMRI_NO_LOG === "1";
+let logFile = null;
+export function initFileLogging() {
+    if (fileLoggingDisabled)
+        return null;
+    try {
+        if (!existsSync(paths.logs))
+            mkdirSync(paths.logs, { recursive: true });
+        const today = new Date().toISOString().slice(0, 10);
+        logFile = join(paths.logs, `launcher-${today}.log`);
+        appendFileSync(logFile, `\n${new Date().toISOString()} ──── new invocation ${process.argv.slice(2).join(" ")}\n`);
+        return logFile;
+    }
+    catch {
+        // Disk full / permission denied — fall back to console-only.
+        return null;
+    }
+}
+function writeToFile(level, msg) {
+    if (!logFile)
+        return;
+    try {
+        appendFileSync(logFile, `${new Date().toISOString()} ${level.padEnd(5)} ${msg}\n`);
+    }
+    catch {
+        // ignore — best effort
+    }
+}
+export const log = {
+    info(msg) {
+        if (!isQuiet)
+            console.error(kleur.cyan("·"), msg);
+        writeToFile("info", msg);
+    },
+    ok(msg) {
+        if (!isQuiet)
+            console.error(kleur.green("✓"), msg);
+        writeToFile("ok", msg);
+    },
+    warn(msg) {
+        console.error(kleur.yellow("!"), msg);
+        writeToFile("warn", msg);
+    },
+    error(msg) {
+        console.error(kleur.red("✗"), msg);
+        writeToFile("error", msg);
+    },
+    step(msg) {
+        if (!isQuiet)
+            console.error(kleur.dim("→"), kleur.dim(msg));
+        writeToFile("step", msg);
+    },
+    header(msg) {
+        if (!isQuiet)
+            console.error("\n" + kleur.bold(msg));
+        writeToFile("info", msg);
+    },
+    /** Print the launcher's identity banner on every non-quiet invocation. */
+    banner(version, home) {
+        const platformInfo = `${platform()} ${arch()} · node ${process.versions.node} · ${(totalmem() / 1024 / 1024 / 1024).toFixed(1)} GiB`;
+        const banner = `askmri v${version}  ${kleur.dim(`(${platformInfo})`)}`;
+        if (!isQuiet) {
+            console.error(kleur.bold().magenta(banner));
+            console.error(kleur.dim(`home: ${home}` + (logFile ? `  ·  log: ${logFile}` : "")));
+        }
+        writeToFile("info", `banner: askmri v${version} ${platformInfo}`);
+        writeToFile("info", `home: ${home}, kernel: ${release()}`);
+    },
+    /** Used by the Python subprocess proxy in serve.ts. */
+    python(line) {
+        if (!isQuiet)
+            process.stderr.write(kleur.dim("[py] ") + line);
+        writeToFile("py", line.trimEnd());
+    },
+    /** Filesystem path of the current log file, if file logging is active. */
+    get file() {
+        return logFile;
+    },
+};

package/dist/paths.d.ts

@@ -0,0 +1,48 @@
+import type { EnvGroup } from "@askmri/content";
+/**
+ * Resolve the AskMRI home directory. Honours $ASKMRI_HOME, then falls back
+ * to ~/.askmri. The directory holds:
+ *
+ *   bin/        — installed askmri-server binary (uv-managed)
+ *   venv/       — Python virtual environment (base/server)
+ *   venvs/      — per-tool-group isolated venvs (ants, totalseg, brats)
+ *   cache/      — preprocessing + model weight cache
+ *   data/       — default scan and output storage
+ *   logs/       — launcher + server logs
+ */
+export declare function askmriHome(): string;
+export declare const paths: {
+    home: string;
+    bin: string;
+    venv: string;
+    venvs: string;
+    cache: string;
+    data: string;
+    logs: string;
+    marker: string;
+};
+/**
+ * Get the venv path for a specific environment group.
+ * - "base" uses the main venv at ~/.askmri/venv/ (where the server runs)
+ * - Other groups use isolated venvs at ~/.askmri/venvs/{group}/
+ */
+export declare function venvFor(group: EnvGroup): string;
+/**
+ * Get the Python binary path for a specific environment group's venv.
+ */
+export declare function pythonBinFor(group: EnvGroup): string;
+/**
+ * Get the pip binary path for a specific environment group's venv.
+ */
+export declare function pipBinFor(group: EnvGroup): string;
+/**
+ * Marker file path indicating a group's venv is installed.
+ */
+export declare function venvMarkerFor(group: EnvGroup): string;
+/** Path to the `askmri-server` binary inside the managed venv. */
+export declare function pythonCliBin(): string;
+/** Path to the `python` binary inside the managed venv (base). */
+export declare function pythonBin(): string;
+/** Cache directory for MONAI bundles (shared with the Python side). */
+export declare const monaiBundlesDir: string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.js

@@ -0,0 +1,78 @@
+import { homedir, platform } from "node:os";
+import { join, resolve } from "node:path";
+import { env } from "node:process";
+/**
+ * Resolve the AskMRI home directory. Honours $ASKMRI_HOME, then falls back
+ * to ~/.askmri. The directory holds:
+ *
+ *   bin/        — installed askmri-server binary (uv-managed)
+ *   venv/       — Python virtual environment (base/server)
+ *   venvs/      — per-tool-group isolated venvs (ants, totalseg, brats)
+ *   cache/      — preprocessing + model weight cache
+ *   data/       — default scan and output storage
+ *   logs/       — launcher + server logs
+ */
+export function askmriHome() {
+    if (env.ASKMRI_HOME)
+        return resolve(env.ASKMRI_HOME);
+    return join(homedir(), ".askmri");
+}
+export const paths = {
+    home: askmriHome(),
+    bin: join(askmriHome(), "bin"),
+    venv: join(askmriHome(), "venv"),
+    venvs: join(askmriHome(), "venvs"),
+    cache: join(askmriHome(), "cache"),
+    data: join(askmriHome(), "data"),
+    logs: join(askmriHome(), "logs"),
+    marker: join(askmriHome(), "INSTALLED"),
+};
+/**
+ * Get the venv path for a specific environment group.
+ * - "base" uses the main venv at ~/.askmri/venv/ (where the server runs)
+ * - Other groups use isolated venvs at ~/.askmri/venvs/{group}/
+ */
+export function venvFor(group) {
+    if (group === "base")
+        return paths.venv;
+    return join(paths.venvs, group);
+}
+/**
+ * Get the Python binary path for a specific environment group's venv.
+ */
+export function pythonBinFor(group) {
+    const venv = venvFor(group);
+    const ext = platform() === "win32" ? ".exe" : "";
+    const dir = platform() === "win32" ? "Scripts" : "bin";
+    return join(venv, dir, `python${ext}`);
+}
+/**
+ * Get the pip binary path for a specific environment group's venv.
+ */
+export function pipBinFor(group) {
+    const venv = venvFor(group);
+    const ext = platform() === "win32" ? ".exe" : "";
+    const dir = platform() === "win32" ? "Scripts" : "bin";
+    // uv creates pip3, not pip
+    return join(venv, dir, `pip3${ext}`);
+}
+/**
+ * Marker file path indicating a group's venv is installed.
+ */
+export function venvMarkerFor(group) {
+    if (group === "base")
+        return paths.marker;
+    return join(paths.venvs, group, "INSTALLED");
+}
+/** Path to the `askmri-server` binary inside the managed venv. */
+export function pythonCliBin() {
+    const ext = platform() === "win32" ? ".exe" : "";
+    const dir = platform() === "win32" ? "Scripts" : "bin";
+    return join(paths.venv, dir, `askmri-server${ext}`);
+}
+/** Path to the `python` binary inside the managed venv (base). */
+export function pythonBin() {
+    return pythonBinFor("base");
+}
+/** Cache directory for MONAI bundles (shared with the Python side). */
+export const monaiBundlesDir = join(askmriHome(), "monai-bundles");

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -0,0 +1,3 @@
+// Auto-generated by scripts/sync-versions.mjs from /VERSION.
+// Do not edit by hand.
+export const VERSION = "0.1.0";

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "askmri",
+  "version": "0.0.1",
+  "description": "The open AI workbench for MRI research.",
+  "keywords": [
+    "mri",
+    "nifti",
+    "research",
+    "viewer"
+  ],
+  "homepage": "https://askmri.com",
+  "bugs": "https://github.com/askmri/askmri/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/askmri/askmri.git"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "askmri": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/__tests__",
+    "!dist/**/*.test.*",
+    "!dist/**/*.e2e.test.*",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.minimal.json && node scripts/post-build.mjs",
+    "build:full": "tsc -p tsconfig.json && node scripts/post-build.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "dev": "tsx src/index.ts",
+    "clean": "rm -rf dist",
+    "test:chat": "tsx src/trpc/procedures/chat.e2e.test.ts"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^1",
+    "@ai-sdk/openai": "^1",
+    "@askmri/agent": "workspace:*",
+    "@askmri/api": "workspace:*",
+    "@askmri/content": "workspace:*",
+    "@askmri/db": "workspace:*",
+    "@askmri/shared": "workspace:*",
+    "@trpc/server": "^11.7.1",
+    "ai": "^4",
+    "kleur": "^4.1.5",
+    "nanoid": "^5",
+    "tinyexec": "^1.0.1",
+    "zod": "^3.25.34"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.3",
+    "tsx": "^4.20.0",
+    "typescript": "~6.0.2"
+  }
+}