@moldesk/runtime 0.0.1 → 0.0.2

package/dist/python/index.d.ts

@@ -1,6 +1,17 @@
-export interface PythonInfo {
-    found: boolean;
+import type { CaptureFn } from "../process/index.js";
+export interface ToolCapability {
+    available: boolean;
     version?: string;
     path?: string;
+    error?: string;
 }
-export declare function detectPython(): Promise<PythonInfo>;
+/** Legacy alias kept for existing imports. */
+export type PythonInfo = ToolCapability & {
+    found?: boolean;
+};
+/**
+ * Detect the host Python interpreter for diagnostics only.
+ * Missing tools / timeouts / permission errors become capability
+ * results rather than crashes. Never required for managed runtimes.
+ */
+export declare function detectPython(capture?: CaptureFn, timeoutMs?: number): Promise<ToolCapability>;

package/dist/python/index.js

@@ -1,20 +1,38 @@
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-const execFileAsync = promisify(execFile);
-export async function detectPython() {
+const PROBE_TIMEOUT_MS = 10_000;
+function parseVersion(stdout) {
+    const cleaned = stdout.trim().replace(/^Python\s+/, "").split(/\s+/)[0];
+    return cleaned && cleaned.length > 0 ? cleaned : undefined;
+}
+/**
+ * Detect the host Python interpreter for diagnostics only.
+ * Missing tools / timeouts / permission errors become capability
+ * results rather than crashes. Never required for managed runtimes.
+ */
+export async function detectPython(capture, timeoutMs = PROBE_TIMEOUT_MS) {
+    if (!capture) {
+        const { defaultCapture } = await import("../process/index.js");
+        capture = defaultCapture;
+    }
     for (const cmd of ["python3", "python"]) {
-        try {
-            const { stdout } = await execFileAsync(cmd, ["--version"]);
-            const { stdout: pathOut } = await execFileAsync("which", [cmd]);
+        const versionResult = await capture(cmd, ["--version"], { timeoutMs });
+        if (versionResult.timedOut) {
             return {
-                found: true,
-                version: stdout.trim().replace(/^Python\s+/, ""),
-                path: pathOut.trim(),
+                available: false,
+                error: `${cmd} --version timed out after ${timeoutMs}ms`,
             };
         }
-        catch {
+        if (versionResult.code !== 0)
             continue;
+        // `python --version` may print to stderr on some interpreters.
+        const combined = `${versionResult.stdout}\n${versionResult.stderr}`.trim();
+        const version = parseVersion(combined);
+        let detectedPath;
+        const pathResult = await capture("which", [cmd], { timeoutMs });
+        if (pathResult.code === 0) {
+            const firstLine = pathResult.stdout.split("\n").map((l) => l.trim()).find(Boolean);
+            detectedPath = firstLine;
         }
+        return { available: true, version, path: detectedPath };
     }
-    return { found: false };
+    return { available: false, error: "no python3 or python interpreter on PATH" };
 }

package/dist/redact.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Redacts values whose keys look like secrets, plus any caller-declared
+ * sensitive keys. Used before persisting adapter-declared command env into
+ * a durable record (e.g. run.json) — never the full inherited environment.
+ */
+export declare function redactEnv(env: Record<string, string> | undefined, extraSensitiveKeys?: readonly string[]): Record<string, string>;

package/dist/redact.js

@@ -0,0 +1,16 @@
+const SECRET_KEY_PATTERN = /token|secret|password|key|credential|auth/i;
+const REDACTED = "[redacted]";
+/**
+ * Redacts values whose keys look like secrets, plus any caller-declared
+ * sensitive keys. Used before persisting adapter-declared command env into
+ * a durable record (e.g. run.json) — never the full inherited environment.
+ */
+export function redactEnv(env, extraSensitiveKeys = []) {
+    if (!env)
+        return {};
+    const sensitive = new Set(extraSensitiveKeys.map((key) => key.toLowerCase()));
+    return Object.fromEntries(Object.entries(env).map(([key, value]) => [
+        key,
+        SECRET_KEY_PATTERN.test(key) || sensitive.has(key.toLowerCase()) ? REDACTED : value,
+    ]));
+}

package/dist/redact.test.d.ts

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

package/dist/redact.test.js

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { redactEnv } from "./redact.js";
+describe("redactEnv", () => {
+    it("redacts values whose keys look like secrets", () => {
+        expect(redactEnv({ API_TOKEN: "abc123", DB_PASSWORD: "hunter2", HOME: "/home/user", PATH: "/usr/bin" })).toEqual({ API_TOKEN: "[redacted]", DB_PASSWORD: "[redacted]", HOME: "/home/user", PATH: "/usr/bin" });
+    });
+    it("redacts caller-declared sensitive keys regardless of name", () => {
+        expect(redactEnv({ MODEL_LICENSE_ID: "xyz" }, ["MODEL_LICENSE_ID"])).toEqual({ MODEL_LICENSE_ID: "[redacted]" });
+    });
+    it("returns an empty object for undefined input", () => {
+        expect(redactEnv(undefined)).toEqual({});
+    });
+    it("leaves non-matching keys untouched", () => {
+        expect(redactEnv({ OUTPUT_DIR: "/tmp/out" })).toEqual({ OUTPUT_DIR: "/tmp/out" });
+    });
+});

package/dist/system.d.ts

@@ -0,0 +1,39 @@
+import { type DiskInfo } from "./hardware/index.js";
+import type { StatFsFn } from "./hardware/index.js";
+import { type ToolCapability } from "./python/index.js";
+import { type DockerCapability } from "./docker/index.js";
+import { type NvidiaCapability, type NvidiaGpu } from "./nvidia/index.js";
+import type { CaptureFn } from "./process/index.js";
+export type { ToolCapability, DockerCapability, NvidiaCapability, NvidiaGpu, DiskInfo };
+export interface SystemReport {
+    capturedAt: string;
+    platform: "darwin" | "linux" | "win32" | "unknown";
+    arch: string;
+    cpu: {
+        model: string;
+        logicalCores: number;
+    };
+    memory: {
+        totalBytes: number;
+    };
+    disk: DiskInfo;
+    appleSilicon: boolean;
+    /** Host interpreter: diagnostic context only, never required for managed runtimes. */
+    hostPython: ToolCapability;
+    docker: DockerCapability;
+    nvidia: NvidiaCapability;
+}
+export interface SystemReportDeps {
+    capture?: CaptureFn;
+    statfs?: StatFsFn;
+    platform?: NodeJS.Platform | string;
+    arch?: string;
+    /** Tier-2 verified Docker GPU-access result to inject (install.ts only). */
+    dockerGpuAccess?: DockerCapability["gpuAccess"];
+}
+/**
+ * Build one normalized machine report. Cached only within a single CLI
+ * invocation by the caller; hardware may change between runs so this
+ * function never persists anything.
+ */
+export declare function collectSystemReport(deps?: SystemReportDeps, env?: NodeJS.ProcessEnv): Promise<SystemReport>;

package/dist/system.js

@@ -0,0 +1,42 @@
+import os from "node:os";
+import { getDiskInfo } from "./hardware/index.js";
+import { detectPython } from "./python/index.js";
+import { detectDocker } from "./docker/index.js";
+import { detectNvidia } from "./nvidia/index.js";
+function normalizePlatform(raw) {
+    if (raw === "darwin" || raw === "linux" || raw === "win32")
+        return raw;
+    return "unknown";
+}
+/**
+ * Build one normalized machine report. Cached only within a single CLI
+ * invocation by the caller; hardware may change between runs so this
+ * function never persists anything.
+ */
+export async function collectSystemReport(deps = {}, env = process.env) {
+    const rawPlatform = deps.platform ?? os.platform();
+    const platform = normalizePlatform(rawPlatform);
+    const arch = deps.arch ?? os.arch();
+    const cpus = os.cpus();
+    const [disk, hostPython, docker, nvidia] = await Promise.all([
+        getDiskInfo(env, deps.statfs),
+        detectPython(deps.capture),
+        detectDocker(deps.capture, { gpuAccess: deps.dockerGpuAccess }),
+        detectNvidia(deps.capture),
+    ]);
+    return {
+        capturedAt: new Date().toISOString(),
+        platform,
+        arch,
+        cpu: {
+            model: cpus[0]?.model ?? "unknown",
+            logicalCores: cpus.length,
+        },
+        memory: { totalBytes: os.totalmem() },
+        disk,
+        appleSilicon: platform === "darwin" && arch === "arm64",
+        hostPython,
+        docker,
+        nvidia,
+    };
+}

package/dist/system.test.d.ts

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

package/dist/system.test.js

@@ -0,0 +1,138 @@
+import { describe, expect, it } from "vitest";
+import { detectPython } from "./python/index.js";
+import { detectDocker } from "./docker/index.js";
+import { detectNvidia } from "./nvidia/index.js";
+import { getDiskInfo } from "./hardware/index.js";
+import { collectSystemReport } from "./system.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 };
+    };
+}
+describe("python probe", () => {
+    it("reports version + path when python3 exists", async () => {
+        const capture = stubCapture((cmd, args) => {
+            if (cmd === "python3" && args[0] === "--version")
+                return { code: 0, stdout: "Python 3.11.9\n" };
+            if (cmd === "which")
+                return { code: 0, stdout: "/opt/homebrew/bin/python3\n" };
+            return { code: 1 };
+        });
+        const result = await detectPython(capture);
+        expect(result).toMatchObject({ available: true, version: "3.11.9", path: "/opt/homebrew/bin/python3" });
+    });
+    it("degrades to unavailable when no interpreter on PATH", async () => {
+        const capture = stubCapture(() => ({ code: 127, stderr: "not found" }));
+        const result = await detectPython(capture);
+        expect(result.available).toBe(false);
+        expect(result.error).toBeDefined();
+    });
+    it("reports timeout instead of throwing", async () => {
+        const capture = stubCapture(() => ({ code: 0, timedOut: true }));
+        const result = await detectPython(capture);
+        expect(result.available).toBe(false);
+        expect(result.error).toMatch(/timed out/);
+    });
+});
+describe("docker probe", () => {
+    it("separates installed/running from gpu access", async () => {
+        const capture = stubCapture((cmd, args) => {
+            if (cmd === "docker" && args[0] === "--version")
+                return { code: 0, stdout: "Docker version 24.0.7, build abc\n" };
+            if (cmd === "docker" && args[0] === "info")
+                return { code: 0, stdout: "Server Version: 24\n" };
+            return { code: 1 };
+        });
+        const result = await detectDocker(capture);
+        expect(result).toMatchObject({ available: true, running: true, gpuAccess: "unknown" });
+    });
+    it("reports stopped daemon without crashing", async () => {
+        const capture = stubCapture((cmd, args) => {
+            if (args[0] === "--version")
+                return { code: 0, stdout: "Docker version 24.0.7\n" };
+            return { code: 1, stderr: "Cannot connect to the Docker daemon" };
+        });
+        const result = await detectDocker(capture);
+        expect(result).toMatchObject({ available: true, running: false });
+        expect(result.error).toMatch(/daemon not running/);
+    });
+    it("reports missing docker", async () => {
+        const capture = stubCapture(() => ({ code: 127, stderr: "command not found" }));
+        const result = await detectDocker(capture);
+        expect(result).toMatchObject({ available: false, running: false, gpuAccess: "unknown" });
+    });
+});
+describe("nvidia probe", () => {
+    it("parses CSV query output only", async () => {
+        const capture = stubCapture((cmd, args) => {
+            if (cmd === "nvidia-smi" && args.join(" ").includes("memory.total"))
+                return { code: 0, stdout: "0, NVIDIA A100, 81920\n1, NVIDIA A100, 81920\n" };
+            if (cmd === "nvidia-smi" && args.includes("-x"))
+                return { code: 0, stdout: "<nvidia_smi_log><cuda_version>12.4</cuda_version></nvidia_smi_log>\n" };
+            if (cmd === "nvidia-smi")
+                return { code: 0, stdout: "550.54.15\n" };
+            if (cmd === "nvcc")
+                return { code: 0, stdout: "Cuda compilation tools, release 12.4\n" };
+            return { code: 1 };
+        });
+        const result = await detectNvidia(capture);
+        expect(result.available).toBe(true);
+        expect(result.gpus).toHaveLength(2);
+        expect(result.gpus[0]?.totalVramBytes).toBe(81920 * 1024 * 1024);
+        expect(result.driverCudaVersion).toBe("12.4");
+        expect(result.cudaToolkitVersion).toBe("12.4");
+    });
+    it("treats missing nvidia-smi as unavailable", async () => {
+        const capture = stubCapture(() => ({ code: 127, stderr: "not found" }));
+        const result = await detectNvidia(capture);
+        expect(result).toMatchObject({ available: false, gpus: [] });
+    });
+    it("treats unknown/decorative output as unavailable, not a crash", async () => {
+        const capture = stubCapture(() => ({
+            code: 0,
+            stdout: "+-----+-------+\n| GPU | MEM |\n+-----+-------+\n",
+        }));
+        const result = await detectNvidia(capture);
+        expect(result.available).toBe(false);
+        expect(result.error).toMatch(/unrecognized nvidia-smi output/);
+    });
+});
+describe("disk probe", () => {
+    it("queries MOLDESK_HOME nearest parent", async () => {
+        const disk = await getDiskInfo({ MOLDESK_HOME: "/tmp/moldesk-test-home-no-such-dir-xyz/sub" }, async () => ({
+            availableBytes: 42 * 1024 ** 3,
+        }));
+        expect(disk.availableBytes).toBe(42 * 1024 ** 3);
+        expect(disk.path.length).toBeGreaterThan(0);
+    });
+    it("falls back to 0 bytes on probe failure, flagged as probeFailed (not a real zero)", async () => {
+        const disk = await getDiskInfo({ MOLDESK_HOME: "/tmp" }, async () => null);
+        expect(disk.availableBytes).toBe(0);
+        expect(disk.probeFailed).toBe(true);
+        expect(disk.probeError).toBeTruthy();
+    });
+});
+describe("collectSystemReport", () => {
+    it("assembles one report with injected results (no real GPU/Docker)", async () => {
+        const capture = stubCapture((cmd, args) => {
+            if (cmd === "python3")
+                return { code: 0, stdout: "Python 3.11.0\n" };
+            if (cmd === "which")
+                return { code: 0, stdout: "/usr/bin/python3\n" };
+            if (cmd === "docker")
+                return { code: 127, stderr: "no docker" };
+            if (cmd === "nvidia-smi")
+                return { code: 127, stderr: "no gpu" };
+            void args;
+            return { code: 1 };
+        });
+        const report = await collectSystemReport({ capture, statfs: async () => ({ availableBytes: 100 * 1024 ** 3 }) }, { MOLDESK_HOME: "/tmp/moldesk-report-test" });
+        expect(typeof report.capturedAt).toBe("string");
+        expect(report.hostPython.available).toBe(true);
+        expect(report.docker.available).toBe(false);
+        expect(report.nvidia.available).toBe(false);
+        expect(report.disk.availableBytes).toBe(100 * 1024 ** 3);
+        expect(["darwin", "linux", "win32", "unknown"]).toContain(report.platform);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldesk/runtime",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Hardware detection and Python/Docker/process execution for MoleculeDesk",
   "license": "MIT",
   "type": "module",
@@ -18,12 +18,17 @@
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "@moldesk/registry": "0.0.2"
+  },
   "devDependencies": {
     "typescript": "^5.6.3",
-    "@types/node": "^20.16.11"
+    "@types/node": "^20.16.11",
+    "vitest": "^3.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
 }