@moldesk/runtime 0.0.1 → 0.0.2

package/dist/docker/index.d.ts

@@ -1,6 +1,43 @@
-export interface DockerInfo {
-    installed: boolean;
+import type { CaptureFn } from "../process/index.js";
+import type { ToolCapability } from "../python/index.js";
+export interface DockerCapability extends ToolCapability {
     running: boolean;
-    version?: string;
+    gpuAccess: "available" | "unavailable" | "unknown";
 }
-export declare function detectDocker(): Promise<DockerInfo>;
+export type DockerInfo = DockerCapability;
+/**
+ * Detect Docker install + daemon state. Tier-1 GPU signal (a registered
+ * `nvidia` runtime) is derived for free from `docker info` — no pulls, safe
+ * for `doctor`/`list`. Pass `options.gpuAccess` to inject a Tier-2 verified
+ * probe result (`install.ts` only).
+ */
+export declare function detectDocker(capture?: CaptureFn, options?: {
+    timeoutMs?: number;
+    gpuAccess?: DockerCapability["gpuAccess"];
+}): Promise<DockerCapability>;
+/** Tier-2: is the (small, digest-pinned) GPU-probe image already cached locally? */
+export declare function isImageCachedLocally(image: string, capture?: CaptureFn): Promise<boolean>;
+/**
+ * Tier-2: explicitly pull the GPU-probe image. Kept separate from
+ * `probeDockerGpuAccess` so a slow download uses its own (longer) timeout
+ * and can never be mistaken for a GPU-probe failure.
+ */
+export declare function pullDockerImage(image: string, capture?: CaptureFn, options?: {
+    timeoutMs?: number;
+}): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+/**
+ * Tier-2: authoritative GPU-access probe. Runs a real container with
+ * `--gpus all`; `--pull=never` guarantees this call can never itself trigger
+ * an implicit (slow) pull, so its short timeout can't produce a false
+ * failure. The image must already be present locally — call
+ * `isImageCachedLocally`/`pullDockerImage` first.
+ */
+export declare function probeDockerGpuAccess(image: string, capture?: CaptureFn, options?: {
+    timeoutMs?: number;
+}): Promise<{
+    access: "available" | "unavailable";
+    error?: string;
+}>;

package/dist/docker/index.js

@@ -1,19 +1,145 @@
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-const execFileAsync = promisify(execFile);
-export async function detectDocker() {
+const PROBE_TIMEOUT_MS = 10_000;
+function parseDockerVersion(stdout) {
+    const trimmed = stdout.trim();
+    // "Docker version 24.0.7, build abc" -> "24.0.7, build abc"
+    const withoutPrefix = trimmed.replace(/^Docker version\s+/i, "").trim();
+    return withoutPrefix.length > 0 ? withoutPrefix : undefined;
+}
+/**
+ * Tier-1 GPU signal: does the target daemon (local or remote, via `docker
+ * info`'s `Runtimes` map) have an `nvidia` container runtime registered?
+ * This does NOT prove a container can actually reach the GPU — registration
+ * alone can't confirm that — so a registered runtime only ever resolves to
+ * `"unknown"`, never `"available"`. Only an explicit Tier-2 probe (a real
+ * `docker run --gpus all ... nvidia-smi`, run by `install.ts`, never by
+ * `doctor`/`list`) can confirm `"available"`.
+ */
+function dockerHasNvidiaRuntime(infoJson) {
+    if (typeof infoJson !== "object" || infoJson === null)
+        return undefined;
+    const runtimes = infoJson["Runtimes"];
+    if (typeof runtimes !== "object" || runtimes === null)
+        return undefined;
+    return Object.keys(runtimes).some((k) => k.toLowerCase().includes("nvidia"));
+}
+function resolveGpuAccess(nvidiaRuntimeRegistered, override) {
+    if (override)
+        return override;
+    if (nvidiaRuntimeRegistered === undefined)
+        return "unknown";
+    return nvidiaRuntimeRegistered ? "unknown" : "unavailable";
+}
+/**
+ * Detect Docker install + daemon state. Tier-1 GPU signal (a registered
+ * `nvidia` runtime) is derived for free from `docker info` — no pulls, safe
+ * for `doctor`/`list`. Pass `options.gpuAccess` to inject a Tier-2 verified
+ * probe result (`install.ts` only).
+ */
+export async function detectDocker(capture, options = {}) {
+    const timeoutMs = options.timeoutMs ?? PROBE_TIMEOUT_MS;
+    let run;
+    if (capture) {
+        run = capture;
+    }
+    else {
+        const { defaultCapture } = await import("../process/index.js");
+        run = defaultCapture;
+    }
+    const versionResult = await run("docker", ["--version"], { timeoutMs });
+    if (versionResult.timedOut) {
+        return {
+            available: false,
+            running: false,
+            gpuAccess: "unknown",
+            error: `docker --version timed out after ${timeoutMs}ms`,
+        };
+    }
+    if (versionResult.code !== 0) {
+        const detail = `${versionResult.stdout}\n${versionResult.stderr}`.trim();
+        return {
+            available: false,
+            running: false,
+            gpuAccess: "unknown",
+            error: detail.length > 0
+                ? `docker not detected: ${detail.split("\n")[0]}`
+                : "docker not detected on PATH",
+        };
+    }
+    const version = parseDockerVersion(versionResult.stdout);
+    const infoJsonResult = await run("docker", ["info", "--format", "{{json .}}"], { timeoutMs });
+    if (infoJsonResult.timedOut) {
+        return {
+            available: true,
+            running: false,
+            version,
+            gpuAccess: options.gpuAccess ?? "unknown",
+            error: `docker info timed out after ${timeoutMs}ms; daemon state unknown`,
+        };
+    }
+    if (infoJsonResult.code !== 0) {
+        return {
+            available: true,
+            running: false,
+            version,
+            gpuAccess: options.gpuAccess ?? "unknown",
+            error: "docker installed but daemon not running (docker info failed)",
+        };
+    }
+    let nvidiaRuntimeRegistered;
     try {
-        const { stdout } = await execFileAsync("docker", ["--version"]);
-        const version = stdout.trim().replace(/^Docker version\s+/, "");
-        try {
-            await execFileAsync("docker", ["info"]);
-            return { installed: true, running: true, version };
-        }
-        catch {
-            return { installed: true, running: false, version };
-        }
+        nvidiaRuntimeRegistered = dockerHasNvidiaRuntime(JSON.parse(infoJsonResult.stdout));
     }
     catch {
-        return { installed: false, running: false };
+        nvidiaRuntimeRegistered = undefined;
+    }
+    return {
+        available: true,
+        running: true,
+        version,
+        gpuAccess: resolveGpuAccess(nvidiaRuntimeRegistered, options.gpuAccess),
+    };
+}
+const DEFAULT_PULL_TIMEOUT_MS = 120_000;
+const DEFAULT_PROBE_TIMEOUT_MS = 10_000;
+/** Tier-2: is the (small, digest-pinned) GPU-probe image already cached locally? */
+export async function isImageCachedLocally(image, capture) {
+    const run = capture ?? (await import("../process/index.js")).defaultCapture;
+    const result = await run("docker", ["image", "inspect", image], { timeoutMs: DEFAULT_PROBE_TIMEOUT_MS });
+    return !result.timedOut && result.code === 0;
+}
+/**
+ * Tier-2: explicitly pull the GPU-probe image. Kept separate from
+ * `probeDockerGpuAccess` so a slow download uses its own (longer) timeout
+ * and can never be mistaken for a GPU-probe failure.
+ */
+export async function pullDockerImage(image, capture, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_PULL_TIMEOUT_MS;
+    const run = capture ?? (await import("../process/index.js")).defaultCapture;
+    const result = await run("docker", ["pull", image], { timeoutMs });
+    if (result.timedOut)
+        return { ok: false, error: `docker pull timed out after ${timeoutMs}ms` };
+    if (result.code !== 0) {
+        const detail = `${result.stdout}\n${result.stderr}`.trim();
+        return { ok: false, error: detail.length > 0 ? detail.split("\n").at(-1) : "docker pull failed" };
+    }
+    return { ok: true };
+}
+/**
+ * Tier-2: authoritative GPU-access probe. Runs a real container with
+ * `--gpus all`; `--pull=never` guarantees this call can never itself trigger
+ * an implicit (slow) pull, so its short timeout can't produce a false
+ * failure. The image must already be present locally — call
+ * `isImageCachedLocally`/`pullDockerImage` first.
+ */
+export async function probeDockerGpuAccess(image, capture, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    const run = capture ?? (await import("../process/index.js")).defaultCapture;
+    const result = await run("docker", ["run", "--rm", "--gpus", "all", "--pull=never", image, "nvidia-smi", "-L"], { timeoutMs });
+    if (result.timedOut)
+        return { access: "unavailable", error: `GPU probe timed out after ${timeoutMs}ms` };
+    if (result.code !== 0) {
+        const detail = `${result.stdout}\n${result.stderr}`.trim();
+        return { access: "unavailable", error: detail.length > 0 ? detail.split("\n")[0] : "docker GPU probe failed" };
     }
+    return { access: "available" };
 }

package/dist/docker/index.test.d.ts

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

package/dist/docker/index.test.js

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import { detectDocker, isImageCachedLocally, probeDockerGpuAccess, pullDockerImage, } from "./index.js";
+function stubCapture(handler) {
+    return async (command, args) => {
+        const r = handler(command, args);
+        return { code: r.code, stdout: r.stdout ?? "", stderr: r.stderr ?? "", timedOut: r.timedOut };
+    };
+}
+const VERSION_OK = { code: 0, stdout: "Docker version 24.0.7, build abc\n" };
+describe("detectDocker — Tier 1 (docker info runtimes)", () => {
+    it("resolves 'unknown' (not 'available') when the nvidia runtime is registered", async () => {
+        const capture = stubCapture((cmd, args) => {
+            if (args[0] === "--version")
+                return VERSION_OK;
+            if (args[0] === "info")
+                return { code: 0, stdout: JSON.stringify({ Runtimes: { runc: {}, nvidia: {} } }) };
+            return { code: 1 };
+        });
+        const result = await detectDocker(capture);
+        expect(result).toMatchObject({ available: true, running: true, gpuAccess: "unknown" });
+    });
+    it("resolves 'unavailable' when no nvidia runtime is registered", async () => {
+        const capture = stubCapture((cmd, args) => {
+            if (args[0] === "--version")
+                return VERSION_OK;
+            if (args[0] === "info")
+                return { code: 0, stdout: JSON.stringify({ Runtimes: { runc: {} } }) };
+            return { code: 1 };
+        });
+        const result = await detectDocker(capture);
+        expect(result).toMatchObject({ available: true, running: true, gpuAccess: "unavailable" });
+    });
+    it("resolves 'unknown' when the daemon is unreachable", async () => {
+        const capture = stubCapture((cmd, args) => {
+            if (args[0] === "--version")
+                return VERSION_OK;
+            return { code: 1, stderr: "Cannot connect to the Docker daemon" };
+        });
+        const result = await detectDocker(capture);
+        expect(result).toMatchObject({ available: true, running: false, gpuAccess: "unknown" });
+    });
+    it("falls back to 'unknown' on malformed JSON from docker info", async () => {
+        const capture = stubCapture((cmd, args) => {
+            if (args[0] === "--version")
+                return VERSION_OK;
+            if (args[0] === "info")
+                return { code: 0, stdout: "not json" };
+            return { code: 1 };
+        });
+        const result = await detectDocker(capture);
+        expect(result).toMatchObject({ available: true, running: true, gpuAccess: "unknown" });
+    });
+    it("an explicit options.gpuAccess override always wins over the Tier-1 signal", async () => {
+        const capture = stubCapture((cmd, args) => {
+            if (args[0] === "--version")
+                return VERSION_OK;
+            if (args[0] === "info")
+                return { code: 0, stdout: JSON.stringify({ Runtimes: { runc: {} } }) };
+            return { code: 1 };
+        });
+        const result = await detectDocker(capture, { gpuAccess: "available" });
+        expect(result.gpuAccess).toBe("available");
+    });
+});
+describe("Tier 2 — isImageCachedLocally / pullDockerImage / probeDockerGpuAccess", () => {
+    it("isImageCachedLocally reports a cache hit", async () => {
+        const capture = stubCapture(() => ({ code: 0, stdout: "[{}]" }));
+        expect(await isImageCachedLocally("img@sha256:abc", capture)).toBe(true);
+    });
+    it("isImageCachedLocally reports a cache miss", async () => {
+        const capture = stubCapture(() => ({ code: 1, stderr: "No such image" }));
+        expect(await isImageCachedLocally("img@sha256:abc", capture)).toBe(false);
+    });
+    it("pullDockerImage succeeds", async () => {
+        const capture = stubCapture(() => ({ code: 0, stdout: "Status: Downloaded" }));
+        const result = await pullDockerImage("img@sha256:abc", capture);
+        expect(result.ok).toBe(true);
+    });
+    it("pullDockerImage reports a failure", async () => {
+        const capture = stubCapture(() => ({ code: 1, stderr: "manifest unknown" }));
+        const result = await pullDockerImage("img@sha256:abc", capture);
+        expect(result.ok).toBe(false);
+        expect(result.error).toBeTruthy();
+    });
+    it("pullDockerImage reports a timeout distinctly", async () => {
+        const capture = stubCapture(() => ({ code: 0, timedOut: true }));
+        const result = await pullDockerImage("img@sha256:abc", capture);
+        expect(result.ok).toBe(false);
+        expect(result.error).toMatch(/timed out/);
+    });
+    it("probeDockerGpuAccess reports available on success", async () => {
+        const capture = stubCapture(() => ({ code: 0, stdout: "GPU 0: NVIDIA A100" }));
+        const result = await probeDockerGpuAccess("img@sha256:abc", capture);
+        expect(result.access).toBe("available");
+    });
+    it("probeDockerGpuAccess reports unavailable on failure", async () => {
+        const capture = stubCapture(() => ({ code: 1, stderr: "could not select device driver" }));
+        const result = await probeDockerGpuAccess("img@sha256:abc", capture);
+        expect(result.access).toBe("unavailable");
+        expect(result.error).toBeTruthy();
+    });
+    it("probeDockerGpuAccess reports unavailable on timeout", async () => {
+        const capture = stubCapture(() => ({ code: 0, timedOut: true }));
+        const result = await probeDockerGpuAccess("img@sha256:abc", capture);
+        expect(result.access).toBe("unavailable");
+        expect(result.error).toMatch(/timed out/);
+    });
+});

package/dist/filesystem/companion-inputs.d.ts

@@ -0,0 +1,34 @@
+/** A single companion-file reference an adapter extracted from a job file (e.g.
+ * DiffDock-L's `proteinPath`/`ligand.path`). `id` namespaces the staged copy on
+ * disk and must be a safe, unique-per-call directory-segment identifier — it is
+ * adapter-controlled (a fixed string like `"protein"`), never derived from user
+ * input, but is still validated defensively since it becomes a path segment. */
+export interface CompanionInputRef {
+    id: string;
+    sourcePath: string;
+}
+export interface StagedCompanionInputPath {
+    id: string;
+    originalPath: string;
+    storedPath: string;
+}
+export interface StageCompanionInputsParams {
+    /** Absolute (or resolvable) path of the submitted job file; relative `sourcePath`
+     * references are resolved against its directory. */
+    jobFilePath: string;
+    refs: CompanionInputRef[];
+    /** The run's `input/` directory. Must already exist. */
+    inputDir: string;
+    /** Confinement boundary for every resolved reference. Defaults to
+     * `path.dirname(jobFilePath)` — the job file's own directory — so a job cannot
+     * reference arbitrary filesystem locations outside where it itself lives. */
+    allowedRoot?: string;
+}
+/**
+ * Safely copies one or more adapter-declared companion files (e.g. DiffDock-L's
+ * protein PDB and ligand file) into a run's `input/` directory, confined to
+ * `allowedRoot`. Generic across models — job-format-specific reference
+ * extraction stays in the adapter (`ModelAdapterDefinition.resolveCompanionInputs`);
+ * this module only validates and copies.
+ */
+export declare function stageCompanionInputs(params: StageCompanionInputsParams): StagedCompanionInputPath[];

package/dist/filesystem/companion-inputs.js

@@ -0,0 +1,123 @@
+import fs from "node:fs";
+import path from "node:path";
+import { MoldeskError } from "@moldesk/registry";
+const SAFE_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+function companionError(code, message, remediation, details) {
+    return new MoldeskError({ code, message, remediation, details });
+}
+/**
+ * True when `target` (already `path.resolve`d) is `root` itself or strictly
+ * inside it. Uses `path.relative`, not `string.startsWith(root)` — a prefix
+ * check would incorrectly accept a sibling directory like `/allowed-root-evil`
+ * when `root` is `/allowed-root`, since the string literally starts with that
+ * prefix. `path.relative` returns a `..`-leading (or absolute, on Windows
+ * across drives) path whenever `target` escapes `root`, regardless of any
+ * shared string prefix.
+ */
+function isWithinRoot(root, target) {
+    if (target === root)
+        return true;
+    const rel = path.relative(root, target);
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+/**
+ * Resolves and validates one companion-file reference against `allowedRoot`,
+ * re-checking existence/type/symlink-target on every call rather than trusting
+ * any earlier inspection — this is what makes the check effective immediately
+ * before staging, not just at an earlier "discovery" step, narrowing (though
+ * not eliminating) the TOCTOU window between an adapter resolving a reference
+ * and this module copying it.
+ *
+ * `allowedRootReal` must already be `fs.realpathSync`-canonicalized by the
+ * caller (once, not per-ref). The boundary check runs against the fully
+ * canonicalized path, not just the lexical one — a symlink escape is not only
+ * possible at the final path component. If an ANCESTOR directory in the
+ * reference is itself a symlink pointing outside `allowedRoot` (e.g.
+ * `sub/file.pdb` where `allowedRoot/sub` is a symlink to `/etc`), the OS
+ * silently resolves that ancestor symlink during ordinary path traversal —
+ * `lstat` on the leaf alone would report the real target file directly and
+ * never show a symlink at all, so checking only "is the final component a
+ * symlink" misses this entirely. `fs.realpathSync` on the *complete* resolved
+ * path canonicalizes every symlink in the chain (leaf and every ancestor
+ * alike), which is why it always runs here rather than being gated behind an
+ * `lstat().isSymbolicLink()` check on just the leaf.
+ */
+function resolveCompanionSource(ref, allowedRoot, allowedRootReal) {
+    const resolved = path.isAbsolute(ref.sourcePath)
+        ? path.resolve(ref.sourcePath)
+        : path.resolve(allowedRoot, ref.sourcePath);
+    // Cheap lexical pre-check — catches obvious ../ traversal before touching
+    // the filesystem at all. Not sufficient on its own (see doc comment above),
+    // hence the canonical re-check below.
+    if (!isWithinRoot(allowedRoot, resolved)) {
+        throw companionError("UNSAFE_COMPANION_INPUT_PATH", `Companion input "${ref.id}" resolves outside the allowed source tree: ${resolved}.`, "Reference only files within the job file's own directory tree.", { id: ref.id, sourcePath: ref.sourcePath, resolved, allowedRoot });
+    }
+    let real;
+    try {
+        real = fs.realpathSync(resolved);
+    }
+    catch {
+        throw companionError("INVALID_RUN_INPUT", `Companion input "${ref.id}" not found: ${resolved}.`, "Check the referenced path exists and retry.", { id: ref.id, sourcePath: ref.sourcePath, resolved });
+    }
+    if (!isWithinRoot(allowedRootReal, real)) {
+        throw companionError("UNSAFE_COMPANION_INPUT_PATH", `Companion input "${ref.id}" escapes the allowed source tree via a symlink (in the file itself or an ancestor directory): ${resolved} -> ${real}.`, "Reference only real files within the job file's own directory tree; do not use symlinks (directly or via a symlinked parent directory) that point outside it.", { id: ref.id, resolved, real, allowedRootReal });
+    }
+    let stat;
+    try {
+        stat = fs.statSync(real);
+    }
+    catch {
+        throw companionError("INVALID_RUN_INPUT", `Companion input "${ref.id}" not found: ${real}.`, "Check the referenced path exists and retry.", { id: ref.id, resolved: real });
+    }
+    if (!stat.isFile()) {
+        throw companionError("UNSAFE_COMPANION_INPUT_TYPE", `Companion input "${ref.id}" is not a regular file: ${real}.`, "Reference a regular file, not a directory, socket, or device.", { id: ref.id, resolved: real });
+    }
+    return real;
+}
+/**
+ * Safely copies one or more adapter-declared companion files (e.g. DiffDock-L's
+ * protein PDB and ligand file) into a run's `input/` directory, confined to
+ * `allowedRoot`. Generic across models — job-format-specific reference
+ * extraction stays in the adapter (`ModelAdapterDefinition.resolveCompanionInputs`);
+ * this module only validates and copies.
+ */
+export function stageCompanionInputs(params) {
+    const { jobFilePath, refs, inputDir } = params;
+    const allowedRoot = path.resolve(params.allowedRoot ?? path.dirname(jobFilePath));
+    let allowedRootReal;
+    try {
+        allowedRootReal = fs.realpathSync(allowedRoot);
+    }
+    catch {
+        throw companionError("UNSAFE_COMPANION_INPUT_PATH", `Allowed source root does not exist: ${allowedRoot}.`, "This is a MoleculeDesk bug — report it; the job file's own directory should always exist.", { allowedRoot });
+    }
+    const seenIds = new Set();
+    for (const ref of refs) {
+        if (!SAFE_ID_PATTERN.test(ref.id)) {
+            throw companionError("UNSAFE_COMPANION_INPUT_ID", `Unsafe companion input id: ${JSON.stringify(ref.id)}.`, "This is a MoleculeDesk adapter bug — report it; ids must match [A-Za-z0-9_-]+.", { id: ref.id });
+        }
+        if (seenIds.has(ref.id)) {
+            throw companionError("DUPLICATE_STAGED_INPUT", `Duplicate companion input id: "${ref.id}".`, "This is a MoleculeDesk adapter bug — report it; each companion input id must be unique.", { id: ref.id });
+        }
+        seenIds.add(ref.id);
+    }
+    const staged = [];
+    for (const ref of refs) {
+        // Resolve/validate immediately before copying — see resolveCompanionSource's doc.
+        const sourceFile = resolveCompanionSource(ref, allowedRoot, allowedRootReal);
+        const destDir = path.join(inputDir, ref.id);
+        fs.mkdirSync(destDir, { recursive: true });
+        const destFile = path.join(destDir, path.basename(sourceFile));
+        try {
+            fs.copyFileSync(sourceFile, destFile, fs.constants.COPYFILE_EXCL);
+        }
+        catch (error) {
+            if (error.code === "EEXIST") {
+                throw companionError("STAGED_INPUT_DESTINATION_EXISTS", `Refusing to overwrite an existing staged destination for companion input "${ref.id}": ${destFile}.`, "This is a MoleculeDesk bug — report it; each run directory should be freshly allocated.", { id: ref.id, destFile });
+            }
+            throw error;
+        }
+        staged.push({ id: ref.id, originalPath: sourceFile, storedPath: destFile });
+    }
+    return staged;
+}

package/dist/filesystem/companion-inputs.test.d.ts

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