@moldesk/runtime 0.0.1 → 0.0.2

package/dist/filesystem/companion-inputs.test.js

@@ -0,0 +1,256 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { MoldeskError } from "@moldesk/registry";
+import { stageCompanionInputs } from "./companion-inputs.js";
+const dirs = [];
+function tempDir(prefix) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    dirs.push(dir);
+    // Canonicalize immediately: on macOS, os.tmpdir() lives under a symlink
+    // (/var/folders -> /private/var/folders), and stageCompanionInputs now
+    // always returns realpathSync-canonicalized paths (that's the P1 fix this
+    // file tests) — comparing against the pre-canonicalized path would fail
+    // for reasons unrelated to what each test actually checks.
+    return fs.realpathSync(dir);
+}
+afterEach(() => {
+    for (const dir of dirs.splice(0))
+        fs.rmSync(dir, { recursive: true, force: true });
+});
+describe("stageCompanionInputs", () => {
+    it("stages a companion file into an id-namespaced subdirectory and records its original + stored paths", () => {
+        const jobDir = tempDir("moldesk-companion-job-");
+        const jobFilePath = path.join(jobDir, "job.json");
+        fs.writeFileSync(jobFilePath, "{}");
+        const proteinPath = path.join(jobDir, "protein.pdb");
+        fs.writeFileSync(proteinPath, "ATOM\n");
+        const runDir = tempDir("moldesk-companion-run-");
+        const inputDir = path.join(runDir, "input");
+        fs.mkdirSync(inputDir, { recursive: true });
+        const staged = stageCompanionInputs({
+            jobFilePath,
+            refs: [{ id: "protein", sourcePath: "protein.pdb" }],
+            inputDir,
+        });
+        expect(staged).toHaveLength(1);
+        expect(staged[0].id).toBe("protein");
+        expect(staged[0].originalPath).toBe(proteinPath);
+        expect(staged[0].storedPath).toBe(path.join(inputDir, "protein", "protein.pdb"));
+        expect(fs.readFileSync(staged[0].storedPath, "utf8")).toBe("ATOM\n");
+    });
+    it("resolves relative sourcePath against the job file's own directory, not the process cwd", () => {
+        const jobDir = tempDir("moldesk-companion-job-");
+        const nested = path.join(jobDir, "nested");
+        fs.mkdirSync(nested, { recursive: true });
+        const jobFilePath = path.join(nested, "job.json");
+        fs.writeFileSync(jobFilePath, "{}");
+        fs.writeFileSync(path.join(nested, "ligand.sdf"), "ligand-bytes");
+        const inputDir = path.join(tempDir("moldesk-companion-run-"), "input");
+        fs.mkdirSync(inputDir, { recursive: true });
+        const staged = stageCompanionInputs({
+            jobFilePath,
+            refs: [{ id: "ligand", sourcePath: "ligand.sdf" }],
+            inputDir,
+        });
+        expect(staged[0].originalPath).toBe(path.join(nested, "ligand.sdf"));
+    });
+    it("rejects a missing referenced file", () => {
+        const jobDir = tempDir("moldesk-companion-job-");
+        const jobFilePath = path.join(jobDir, "job.json");
+        fs.writeFileSync(jobFilePath, "{}");
+        const inputDir = path.join(tempDir("moldesk-companion-run-"), "input");
+        fs.mkdirSync(inputDir, { recursive: true });
+        expect(() => stageCompanionInputs({ jobFilePath, refs: [{ id: "protein", sourcePath: "missing.pdb" }], inputDir })).toThrowError(MoldeskError);
+        try {
+            stageCompanionInputs({ jobFilePath, refs: [{ id: "protein", sourcePath: "missing.pdb" }], inputDir });
+            expect.unreachable();
+        }
+        catch (error) {
+            expect(error.code).toBe("INVALID_RUN_INPUT");
+        }
+    });
+    it("rejects ../ traversal escaping the allowed root", () => {
+        const jobDir = tempDir("moldesk-companion-job-");
+        const jobFilePath = path.join(jobDir, "job.json");
+        fs.writeFileSync(jobFilePath, "{}");
+        const outsideDir = tempDir("moldesk-companion-outside-");
+        fs.writeFileSync(path.join(outsideDir, "secret.pdb"), "secret");
+        const inputDir = path.join(tempDir("moldesk-companion-run-"), "input");
+        fs.mkdirSync(inputDir, { recursive: true });
+        const traversal = path.relative(jobDir, path.join(outsideDir, "secret.pdb"));
+        try {
+            stageCompanionInputs({ jobFilePath, refs: [{ id: "protein", sourcePath: traversal }], inputDir });
+            expect.unreachable();
+        }
+        catch (error) {
+            expect(error.code).toBe("UNSAFE_COMPANION_INPUT_PATH");
+        }
+    });
+    it("rejects a sibling-prefix path a naive string.startsWith(allowedRoot) check would wrongly accept", () => {
+        const parent = tempDir("moldesk-companion-parent-");
+        const allowedRoot = path.join(parent, "allowed-root");
+        const evilSibling = path.join(parent, "allowed-root-evil");
+        fs.mkdirSync(allowedRoot, { recursive: true });
+        fs.mkdirSync(evilSibling, { recursive: true });
+        const jobFilePath = path.join(allowedRoot, "job.json");
+        fs.writeFileSync(jobFilePath, "{}");
+        fs.writeFileSync(path.join(evilSibling, "secret.pdb"), "secret");
+        const inputDir = path.join(tempDir("moldesk-companion-run-"), "input");
+        fs.mkdirSync(inputDir, { recursive: true });
+        // A plain `string.startsWith(allowedRoot)` check would incorrectly accept this,
+        // since "/…/allowed-root-evil/secret.pdb" starts with "/…/allowed-root". The
+        // correct `path.relative`-based confinement must reject it.
+        const absoluteEscape = path.join(evilSibling, "secret.pdb");
+        try {
+            stageCompanionInputs({ jobFilePath, refs: [{ id: "protein", sourcePath: absoluteEscape }], inputDir, allowedRoot });
+            expect.unreachable();
+        }
+        catch (error) {
+            expect(error.code).toBe("UNSAFE_COMPANION_INPUT_PATH");
+        }
+    });
+    it("rejects a symlink whose target escapes the allowed root", () => {
+        const jobDir = tempDir("moldesk-companion-job-");
+        const jobFilePath = path.join(jobDir, "job.json");
+        fs.writeFileSync(jobFilePath, "{}");
+        const outsideDir = tempDir("moldesk-companion-outside-");
+        const secretPath = path.join(outsideDir, "secret.pdb");
+        fs.writeFileSync(secretPath, "secret");
+        const linkPath = path.join(jobDir, "link.pdb");
+        fs.symlinkSync(secretPath, linkPath);
+        const inputDir = path.join(tempDir("moldesk-companion-run-"), "input");
+        fs.mkdirSync(inputDir, { recursive: true });
+        try {
+            stageCompanionInputs({ jobFilePath, refs: [{ id: "protein", sourcePath: "link.pdb" }], inputDir });
+            expect.unreachable();
+        }
+        catch (error) {
+            expect(error.code).toBe("UNSAFE_COMPANION_INPUT_PATH");
+        }
+    });
+    it("rejects a reference reached through a symlinked ANCESTOR directory, not just a symlinked leaf file", () => {
+        // allowedRoot/sub is a symlink to a directory outside allowedRoot. The leaf
+        // reference itself ("sub/secret.pdb") is a normal file, not a symlink — only
+        // an ancestor path component is. `lstat` on the leaf alone would report a
+        // regular file (the OS silently resolves the ancestor symlink during
+        // traversal), so this only fails if the full resolved path is canonicalized
+        // with `realpathSync` before the boundary check, not just the leaf.
+        const jobDir = tempDir("moldesk-companion-job-");
+        const jobFilePath = path.join(jobDir, "job.json");
+        fs.writeFileSync(jobFilePath, "{}");
+        const outsideDir = tempDir("moldesk-companion-outside-");
+        fs.writeFileSync(path.join(outsideDir, "secret.pdb"), "secret");
+        fs.symlinkSync(outsideDir, path.join(jobDir, "sub"));
+        const inputDir = path.join(tempDir("moldesk-companion-run-"), "input");
+        fs.mkdirSync(inputDir, { recursive: true });
+        try {
+            stageCompanionInputs({ jobFilePath, refs: [{ id: "protein", sourcePath: "sub/secret.pdb" }], inputDir });
+            expect.unreachable();
+        }
+        catch (error) {
+            expect(error.code).toBe("UNSAFE_COMPANION_INPUT_PATH");
+        }
+    });
+    it("rejects a directory reference", () => {
+        const jobDir = tempDir("moldesk-companion-job-");
+        const jobFilePath = path.join(jobDir, "job.json");
+        fs.writeFileSync(jobFilePath, "{}");
+        fs.mkdirSync(path.join(jobDir, "a-directory"));
+        const inputDir = path.join(tempDir("moldesk-companion-run-"), "input");
+        fs.mkdirSync(inputDir, { recursive: true });
+        try {
+            stageCompanionInputs({ jobFilePath, refs: [{ id: "protein", sourcePath: "a-directory" }], inputDir });
+            expect.unreachable();
+        }
+        catch (error) {
+            expect(error.code).toBe("UNSAFE_COMPANION_INPUT_TYPE");
+        }
+    });
+    it("rejects duplicate companion input ids before touching disk", () => {
+        const jobDir = tempDir("moldesk-companion-job-");
+        const jobFilePath = path.join(jobDir, "job.json");
+        fs.writeFileSync(jobFilePath, "{}");
+        fs.writeFileSync(path.join(jobDir, "a.pdb"), "a");
+        fs.writeFileSync(path.join(jobDir, "b.pdb"), "b");
+        const inputDir = path.join(tempDir("moldesk-companion-run-"), "input");
+        fs.mkdirSync(inputDir, { recursive: true });
+        try {
+            stageCompanionInputs({
+                jobFilePath,
+                refs: [{ id: "protein", sourcePath: "a.pdb" }, { id: "protein", sourcePath: "b.pdb" }],
+                inputDir,
+            });
+            expect.unreachable();
+        }
+        catch (error) {
+            expect(error.code).toBe("DUPLICATE_STAGED_INPUT");
+        }
+        expect(fs.existsSync(path.join(inputDir, "protein"))).toBe(false);
+    });
+    it("refuses to overwrite an existing staged destination", () => {
+        const jobDir = tempDir("moldesk-companion-job-");
+        const jobFilePath = path.join(jobDir, "job.json");
+        fs.writeFileSync(jobFilePath, "{}");
+        fs.writeFileSync(path.join(jobDir, "protein.pdb"), "content");
+        const inputDir = path.join(tempDir("moldesk-companion-run-"), "input");
+        fs.mkdirSync(path.join(inputDir, "protein"), { recursive: true });
+        fs.writeFileSync(path.join(inputDir, "protein", "protein.pdb"), "pre-existing");
+        try {
+            stageCompanionInputs({ jobFilePath, refs: [{ id: "protein", sourcePath: "protein.pdb" }], inputDir });
+            expect.unreachable();
+        }
+        catch (error) {
+            expect(error.code).toBe("STAGED_INPUT_DESTINATION_EXISTS");
+        }
+        expect(fs.readFileSync(path.join(inputDir, "protein", "protein.pdb"), "utf8")).toBe("pre-existing");
+    });
+    it("re-validates at staging time rather than trusting an earlier discovery-time check (TOCTOU: file replaced with an escaping symlink)", () => {
+        const jobDir = tempDir("moldesk-companion-job-");
+        const jobFilePath = path.join(jobDir, "job.json");
+        fs.writeFileSync(jobFilePath, "{}");
+        const refPath = path.join(jobDir, "protein.pdb");
+        fs.writeFileSync(refPath, "original content");
+        const inputDir = path.join(tempDir("moldesk-companion-run-"), "input");
+        fs.mkdirSync(inputDir, { recursive: true });
+        // Simulate an earlier "discovery" check (e.g. an adapter's own validateInput)
+        // that inspected the file when it was still a safe regular file.
+        expect(fs.existsSync(refPath)).toBe(true);
+        expect(fs.lstatSync(refPath).isFile()).toBe(true);
+        // Between discovery and staging, the file is replaced with a symlink escaping
+        // the allowed root.
+        const outsideDir = tempDir("moldesk-companion-outside-");
+        const secretPath = path.join(outsideDir, "secret.pdb");
+        fs.writeFileSync(secretPath, "secret");
+        fs.rmSync(refPath);
+        fs.symlinkSync(secretPath, refPath);
+        try {
+            stageCompanionInputs({ jobFilePath, refs: [{ id: "protein", sourcePath: "protein.pdb" }], inputDir });
+            expect.unreachable();
+        }
+        catch (error) {
+            expect(error.code).toBe("UNSAFE_COMPANION_INPUT_PATH");
+        }
+    });
+    it("stages multiple distinct companion inputs independently", () => {
+        const jobDir = tempDir("moldesk-companion-job-");
+        const jobFilePath = path.join(jobDir, "job.json");
+        fs.writeFileSync(jobFilePath, "{}");
+        fs.writeFileSync(path.join(jobDir, "protein.pdb"), "protein-bytes");
+        fs.writeFileSync(path.join(jobDir, "ligand.sdf"), "ligand-bytes");
+        const inputDir = path.join(tempDir("moldesk-companion-run-"), "input");
+        fs.mkdirSync(inputDir, { recursive: true });
+        const staged = stageCompanionInputs({
+            jobFilePath,
+            refs: [
+                { id: "protein", sourcePath: "protein.pdb" },
+                { id: "ligand", sourcePath: "ligand.sdf" },
+            ],
+            inputDir,
+        });
+        expect(staged.map((s) => s.id).sort()).toEqual(["ligand", "protein"]);
+        expect(fs.readFileSync(path.join(inputDir, "protein", "protein.pdb"), "utf8")).toBe("protein-bytes");
+        expect(fs.readFileSync(path.join(inputDir, "ligand", "ligand.sdf"), "utf8")).toBe("ligand-bytes");
+    });
+});

package/dist/filesystem/index.d.ts

@@ -0,0 +1,4 @@
+export { getMoldeskHome, getMoldeskPaths, modelInstallDir, modelVersionDir, pythonToolDir, runDir, uvToolDir } from "./paths.js";
+export type { MoldeskPaths } from "./paths.js";
+export { stageCompanionInputs } from "./companion-inputs.js";
+export type { CompanionInputRef, StageCompanionInputsParams, StagedCompanionInputPath } from "./companion-inputs.js";

package/dist/filesystem/index.js

@@ -0,0 +1,2 @@
+export { getMoldeskHome, getMoldeskPaths, modelInstallDir, modelVersionDir, pythonToolDir, runDir, uvToolDir } from "./paths.js";
+export { stageCompanionInputs } from "./companion-inputs.js";

package/dist/filesystem/paths.d.ts

@@ -0,0 +1,20 @@
+export interface MoldeskPaths {
+    home: string;
+    cache: string;
+    downloads: string;
+    objects: string;
+    models: string;
+    runs: string;
+    state: string;
+    locks: string;
+    tools: string;
+}
+/** Centralized home resolution. Honors MOLDESK_HOME for tests/advanced users. */
+export declare function getMoldeskHome(env?: NodeJS.ProcessEnv): string;
+/** Central path calculation. No other module should construct these paths by hand. */
+export declare function getMoldeskPaths(env?: NodeJS.ProcessEnv): MoldeskPaths;
+export declare function modelVersionDir(model: string, modelVersion: string, env?: NodeJS.ProcessEnv): string;
+export declare function modelInstallDir(model: string, modelVersion: string, runtimeFingerprint: string, env?: NodeJS.ProcessEnv): string;
+export declare function runDir(runId: string, env?: NodeJS.ProcessEnv): string;
+export declare function uvToolDir(version: string, env?: NodeJS.ProcessEnv): string;
+export declare function pythonToolDir(version: string, env?: NodeJS.ProcessEnv): string;

package/dist/filesystem/paths.js

@@ -0,0 +1,79 @@
+import os from "node:os";
+import path from "node:path";
+import { MoldeskError } from "@moldesk/registry";
+function defaultHome() {
+    // macOS/Linux default per spec §1.3. Windows out of v0.1 execution scope.
+    return path.join(os.homedir(), ".moldesk");
+}
+function unsafePath(message, details) {
+    throw new MoldeskError({
+        code: "UNSAFE_PATH",
+        message,
+        remediation: "Use a MoleculeDesk-owned directory and safe identifier values without path separators.",
+        details,
+    });
+}
+function safeSegment(value, label, pattern) {
+    if (!pattern.test(value) || value === "." || value === ".." || value.includes("\0")) {
+        return unsafePath(`Unsafe ${label}: ${JSON.stringify(value)}`, { label, value });
+    }
+    return value;
+}
+function safeModelName(value) {
+    return safeSegment(value, "model name", /^[a-z0-9]+(?:-[a-z0-9]+)*$/);
+}
+function safeVersion(value, label) {
+    return safeSegment(value, label, /^[A-Za-z0-9][A-Za-z0-9._+-]*$/);
+}
+function safeRuntimeFingerprint(value) {
+    return safeSegment(value, "runtime fingerprint", /^(?:python|docker)-[a-f0-9]{16,64}$/);
+}
+const RUN_ID_PATTERN = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}-[0-9]{2}-[0-9]{2}-[0-9]{3}Z-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+function safeRunId(value) {
+    return safeSegment(value, "run id", RUN_ID_PATTERN);
+}
+/** Centralized home resolution. Honors MOLDESK_HOME for tests/advanced users. */
+export function getMoldeskHome(env = process.env) {
+    const override = env["MOLDESK_HOME"];
+    if (override && override.trim().length > 0) {
+        const resolved = path.resolve(override.trim());
+        const filesystemRoot = path.parse(resolved).root;
+        if (resolved === filesystemRoot || resolved === path.resolve(os.homedir())) {
+            return unsafePath(`Refusing unsafe MOLDESK_HOME: ${resolved}`, { resolved });
+        }
+        return resolved;
+    }
+    return defaultHome();
+}
+/** Central path calculation. No other module should construct these paths by hand. */
+export function getMoldeskPaths(env = process.env) {
+    const home = getMoldeskHome(env);
+    const cache = path.join(home, "cache");
+    const state = path.join(home, "state");
+    return {
+        home,
+        cache,
+        downloads: path.join(cache, "downloads"),
+        objects: path.join(cache, "objects"),
+        models: path.join(home, "models"),
+        runs: path.join(home, "runs"),
+        state,
+        locks: path.join(state, "locks"),
+        tools: path.join(home, "tools"),
+    };
+}
+export function modelVersionDir(model, modelVersion, env) {
+    return path.join(getMoldeskPaths(env).models, safeModelName(model), safeVersion(modelVersion, "model version"));
+}
+export function modelInstallDir(model, modelVersion, runtimeFingerprint, env) {
+    return path.join(modelVersionDir(model, modelVersion, env), safeRuntimeFingerprint(runtimeFingerprint));
+}
+export function runDir(runId, env) {
+    return path.join(getMoldeskPaths(env).runs, safeRunId(runId));
+}
+export function uvToolDir(version, env) {
+    return path.join(getMoldeskPaths(env).tools, "uv", safeVersion(version, "uv version"));
+}
+export function pythonToolDir(version, env) {
+    return path.join(getMoldeskPaths(env).tools, "python", safeVersion(version, "Python version"));
+}

package/dist/filesystem/paths.test.d.ts

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

package/dist/filesystem/paths.test.js

@@ -0,0 +1,35 @@
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { MoldeskError } from "@moldesk/registry";
+import { getMoldeskHome, getMoldeskPaths, modelInstallDir, uvToolDir } from "./paths.js";
+describe("moldesk paths", () => {
+    it("honors MOLDESK_HOME override", () => {
+        const p = getMoldeskPaths({ MOLDESK_HOME: "/tmp/custom-home" });
+        expect(p.home).toBe(path.resolve("/tmp/custom-home"));
+        expect(p.downloads).toBe(path.join(p.home, "cache", "downloads"));
+        expect(p.locks).toBe(path.join(p.home, "state", "locks"));
+    });
+    it("defaults to ~/.moldesk", () => {
+        const env = {};
+        expect(getMoldeskHome(env)).toBe(path.join(os.homedir(), ".moldesk"));
+    });
+    it("nests one model version with multiple runtime fingerprints", () => {
+        const a = modelInstallDir("boltz", "2.2.1", "python-aaaaaaaaaaaaaaaa", { MOLDESK_HOME: "/tmp/h" });
+        const b = modelInstallDir("boltz", "2.2.1", "docker-bbbbbbbbbbbbbbbb", { MOLDESK_HOME: "/tmp/h" });
+        expect(a).toContain(path.join("models", "boltz", "2.2.1", "python-aaaaaaaaaaaaaaaa"));
+        expect(b).toContain(path.join("models", "boltz", "2.2.1", "docker-bbbbbbbbbbbbbbbb"));
+        expect(a).not.toBe(b);
+    });
+    it("rejects traversal and malformed installation path segments", () => {
+        const env = { MOLDESK_HOME: "/tmp/h" };
+        expect(() => modelInstallDir("../escape", "1.0.0", "python-aaaaaaaaaaaaaaaa", env)).toThrowError(MoldeskError);
+        expect(() => modelInstallDir("boltz", "../../escape", "python-aaaaaaaaaaaaaaaa", env)).toThrowError(MoldeskError);
+        expect(() => modelInstallDir("boltz", "1.0.0", "../../escape", env)).toThrowError(MoldeskError);
+        expect(() => uvToolDir("../../escape", env)).toThrowError(MoldeskError);
+    });
+    it("rejects filesystem root and the user home as MOLDESK_HOME", () => {
+        expect(() => getMoldeskHome({ MOLDESK_HOME: path.parse(path.resolve(path.sep)).root })).toThrowError(MoldeskError);
+        expect(() => getMoldeskHome({ MOLDESK_HOME: os.homedir() })).toThrowError(MoldeskError);
+    });
+});

package/dist/hardware/index.d.ts

@@ -7,3 +7,24 @@ export interface HardwareInfo {
     isAppleSilicon: boolean;
 }
 export declare function getHardwareInfo(): HardwareInfo;
+export interface DiskInfo {
+    availableBytes: number;
+    path: string;
+    /** True when the statfs probe failed/was unsupported — `availableBytes: 0` is a conservative placeholder, not a real reading. */
+    probeFailed?: boolean;
+    /** Captured error/reason when `probeFailed` is true. */
+    probeError?: string;
+}
+export type StatFsFn = (target: string) => Promise<{
+    availableBytes: number;
+} | null>;
+/** Default disk probe via `fs.statfs` (Node >= 19). Returns null when unavailable. */
+export declare const defaultStatFs: StatFsFn;
+/**
+ * Query free space at MOLDESK_HOME (or nearest existing parent).
+ * Never throws: on probe failure reports `availableBytes: 0` with
+ * `probeFailed: true` so callers can distinguish "genuinely 0 bytes free"
+ * (probeFailed absent) from "could not be determined" (probeFailed true) —
+ * the two must not be treated the same by compatibility evaluation.
+ */
+export declare function getDiskInfo(env?: NodeJS.ProcessEnv, statfs?: StatFsFn): Promise<DiskInfo>;

package/dist/hardware/index.js

@@ -1,4 +1,7 @@
 import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+import { getMoldeskHome } from "../filesystem/index.js";
 export function getHardwareInfo() {
     const cpus = os.cpus();
     const arch = os.arch();
@@ -12,3 +15,62 @@ export function getHardwareInfo() {
         isAppleSilicon: platform === "darwin" && arch === "arm64",
     };
 }
+function nearestExistingParent(start) {
+    let current = path.resolve(start);
+    for (;;) {
+        try {
+            if (fs.existsSync(current))
+                return current;
+        }
+        catch {
+            // fall through to parent walk
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return current;
+        current = parent;
+    }
+}
+/** Default disk probe via `fs.statfs` (Node >= 19). Returns null when unavailable. */
+export const defaultStatFs = async (target) => {
+    const statfs = fs.promises.statfs;
+    if (typeof statfs !== "function")
+        return null;
+    try {
+        const stats = await statfs(target);
+        const available = typeof stats.bavail === "number" && typeof stats.bsize === "number"
+            ? stats.bavail * stats.bsize
+            : Number.NaN;
+        if (!Number.isFinite(available) || available < 0)
+            return null;
+        return { availableBytes: Math.floor(available) };
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Query free space at MOLDESK_HOME (or nearest existing parent).
+ * Never throws: on probe failure reports `availableBytes: 0` with
+ * `probeFailed: true` so callers can distinguish "genuinely 0 bytes free"
+ * (probeFailed absent) from "could not be determined" (probeFailed true) —
+ * the two must not be treated the same by compatibility evaluation.
+ */
+export async function getDiskInfo(env = process.env, statfs = defaultStatFs) {
+    const home = getMoldeskHome(env);
+    const target = nearestExistingParent(home);
+    try {
+        const result = await statfs(target);
+        if (result)
+            return { availableBytes: result.availableBytes, path: target };
+        return { availableBytes: 0, path: target, probeFailed: true, probeError: "disk space probe unsupported or failed" };
+    }
+    catch (error) {
+        return {
+            availableBytes: 0,
+            path: target,
+            probeFailed: true,
+            probeError: error instanceof Error ? error.message : "disk space probe threw an unexpected error",
+        };
+    }
+}

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

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

package/dist/hardware/index.test.js

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { getDiskInfo } from "./index.js";
+describe("getDiskInfo — probeFailed vs genuine zero", () => {
+    it("does not set probeFailed on a genuine successful zero-byte reading", async () => {
+        const disk = await getDiskInfo({ MOLDESK_HOME: "/tmp" }, async () => ({ availableBytes: 0 }));
+        expect(disk.availableBytes).toBe(0);
+        expect(disk.probeFailed).toBeUndefined();
+        expect(disk.probeError).toBeUndefined();
+    });
+    it("sets probeFailed + probeError when statfs resolves null (unsupported)", async () => {
+        const disk = await getDiskInfo({ MOLDESK_HOME: "/tmp" }, async () => null);
+        expect(disk.probeFailed).toBe(true);
+        expect(disk.probeError).toBeTruthy();
+    });
+    it("sets probeFailed + probeError with the thrown message when statfs throws", async () => {
+        const disk = await getDiskInfo({ MOLDESK_HOME: "/tmp" }, async () => {
+            throw new Error("EACCES: permission denied");
+        });
+        expect(disk.probeFailed).toBe(true);
+        expect(disk.probeError).toBe("EACCES: permission denied");
+    });
+    it("reports a genuine positive reading without probeFailed", async () => {
+        const disk = await getDiskInfo({ MOLDESK_HOME: "/tmp" }, async () => ({ availableBytes: 5 * 1024 ** 3 }));
+        expect(disk.availableBytes).toBe(5 * 1024 ** 3);
+        expect(disk.probeFailed).toBeUndefined();
+    });
+});

package/dist/index.d.ts

@@ -1,14 +1,31 @@
 import { type HardwareInfo } from "./hardware/index.js";
 import { type PythonInfo } from "./python/index.js";
 import { type DockerInfo } from "./docker/index.js";
-export interface SystemReport {
+import { type DockerCapability, type DiskInfo, type NvidiaCapability, type NvidiaGpu, type SystemReport, type SystemReportDeps, type ToolCapability } from "./system.js";
+export interface LegacySystemReport {
     hardware: HardwareInfo;
     python: PythonInfo;
     docker: DockerInfo;
 }
-export declare function getSystemReport(): Promise<SystemReport>;
-export { getHardwareInfo } from "./hardware/index.js";
+/**
+ * Canonical system report (spec Step 2 shape). Re-exported through
+ * `@moldesk/core` for CLI + future consumers. Accepts `deps.dockerGpuAccess`
+ * so `install.ts` can inject a verified Tier-2 Docker GPU probe result.
+ */
+export declare function getSystemReport(deps?: SystemReportDeps): Promise<SystemReport>;
+export { getMoldeskHome, getMoldeskPaths, modelInstallDir, modelVersionDir, pythonToolDir, runDir, uvToolDir, stageCompanionInputs, } from "./filesystem/index.js";
+export type { MoldeskPaths, CompanionInputRef, StageCompanionInputsParams, StagedCompanionInputPath } from "./filesystem/index.js";
+export type { ExecuteRequest, ExecutionResult, MoldeskErrorData, PrepareRuntimeRequest, PreparedRuntime, RemoveRuntimeRequest, RuntimeCapability, RuntimeProvider, } from "./providers.js";
+export { MoldeskError } from "./providers.js";
+export { PythonRuntimeProvider } from "./providers/python.js";
+export { redactEnv } from "./redact.js";
+export { getHardwareInfo, getDiskInfo } from "./hardware/index.js";
 export { detectPython } from "./python/index.js";
-export { detectDocker } from "./docker/index.js";
+export { detectDocker, isImageCachedLocally, pullDockerImage, probeDockerGpuAccess, } from "./docker/index.js";
+export { detectNvidia } from "./nvidia/index.js";
+export { collectSystemReport } from "./system.js";
 export { runCommand } from "./process/index.js";
-export type { HardwareInfo, PythonInfo, DockerInfo };
+export type { RunOptions, RunResult } from "./process/index.js";
+export { cacheAsset, ensureManagedUv, managedUvDownloadBytes, materializeAsset, prepareDockerImage, preparePythonEnvironment, temporaryInstallDir, MANAGED_UV_VERSION, } from "./install/index.js";
+export type { AssetFetch, InstallCommandRunner, InstallProgress, PostInstallHookResult, PreparedPythonEnvironment, PythonInstallRequest, } from "./install/index.js";
+export type { DiskInfo, DockerCapability, DockerInfo, HardwareInfo, NvidiaCapability, NvidiaGpu, PythonInfo, SystemReport, SystemReportDeps, ToolCapability, };

package/dist/index.js

@@ -1,15 +1,20 @@
-import { getHardwareInfo } from "./hardware/index.js";
-import { detectPython } from "./python/index.js";
-import { detectDocker } from "./docker/index.js";
-export async function getSystemReport() {
-    const [python, docker] = await Promise.all([detectPython(), detectDocker()]);
-    return {
-        hardware: getHardwareInfo(),
-        python,
-        docker,
-    };
+import { collectSystemReport, } from "./system.js";
+/**
+ * Canonical system report (spec Step 2 shape). Re-exported through
+ * `@moldesk/core` for CLI + future consumers. Accepts `deps.dockerGpuAccess`
+ * so `install.ts` can inject a verified Tier-2 Docker GPU probe result.
+ */
+export async function getSystemReport(deps = {}) {
+    return collectSystemReport(deps);
 }
-export { getHardwareInfo } from "./hardware/index.js";
+export { getMoldeskHome, getMoldeskPaths, modelInstallDir, modelVersionDir, pythonToolDir, runDir, uvToolDir, stageCompanionInputs, } from "./filesystem/index.js";
+export { MoldeskError } from "./providers.js";
+export { PythonRuntimeProvider } from "./providers/python.js";
+export { redactEnv } from "./redact.js";
+export { getHardwareInfo, getDiskInfo } from "./hardware/index.js";
 export { detectPython } from "./python/index.js";
-export { detectDocker } from "./docker/index.js";
+export { detectDocker, isImageCachedLocally, pullDockerImage, probeDockerGpuAccess, } from "./docker/index.js";
+export { detectNvidia } from "./nvidia/index.js";
+export { collectSystemReport } from "./system.js";
 export { runCommand } from "./process/index.js";
+export { cacheAsset, ensureManagedUv, managedUvDownloadBytes, materializeAsset, prepareDockerImage, preparePythonEnvironment, temporaryInstallDir, MANAGED_UV_VERSION, } from "./install/index.js";