@moldesk/runtime 0.0.3 → 0.0.5

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

@@ -24,6 +24,16 @@ export interface StageCompanionInputsParams {
      * reference arbitrary filesystem locations outside where it itself lives. */
     allowedRoot?: string;
 }
+/**
+ * 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.
+ */
+export declare function isWithinRoot(root: string, target: string): boolean;
 /**
  * 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

package/dist/filesystem/companion-inputs.js

@@ -14,7 +14,7 @@ function companionError(code, message, remediation, details) {
  * across drives) path whenever `target` escapes `root`, regardless of any
  * shared string prefix.
  */
-function isWithinRoot(root, target) {
+export function isWithinRoot(root, target) {
     if (target === root)
         return true;
     const rel = path.relative(root, target);

package/dist/filesystem/index.d.ts

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

package/dist/filesystem/index.js

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

package/dist/filesystem/paths.d.ts

@@ -16,5 +16,7 @@ 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;
+/** Owned location for standalone (non-run) visualizations: `<cache>/visualizations/<id>`. */
+export declare function visualizationDir(id: 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

@@ -71,6 +71,10 @@ export function modelInstallDir(model, modelVersion, runtimeFingerprint, env) {
 export function runDir(runId, env) {
     return path.join(getMoldeskPaths(env).runs, safeRunId(runId));
 }
+/** Owned location for standalone (non-run) visualizations: `<cache>/visualizations/<id>`. */
+export function visualizationDir(id, env) {
+    return path.join(getMoldeskPaths(env).cache, "visualizations", safeSegment(id, "visualization id", /^[A-Za-z0-9][A-Za-z0-9-]{7,63}$/));
+}
 export function uvToolDir(version, env) {
     return path.join(getMoldeskPaths(env).tools, "uv", safeVersion(version, "uv version"));
 }

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export interface LegacySystemReport {
  * 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 { getMoldeskHome, getMoldeskPaths, modelInstallDir, modelVersionDir, pythonToolDir, runDir, uvToolDir, visualizationDir, isWithinRoot, 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";
@@ -25,6 +25,8 @@ export { detectDocker, isImageCachedLocally, pullDockerImage, probeDockerGpuAcce
 export { detectNvidia } from "./nvidia/index.js";
 export { collectSystemReport } from "./system.js";
 export { runCommand } from "./process/index.js";
+export { openInBrowser } from "./process/open.js";
+export type { OpenResult } from "./process/open.js";
 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";

package/dist/index.js

@@ -7,7 +7,7 @@ import { collectSystemReport, } from "./system.js";
 export async function getSystemReport(deps = {}) {
     return collectSystemReport(deps);
 }
-export { getMoldeskHome, getMoldeskPaths, modelInstallDir, modelVersionDir, pythonToolDir, runDir, uvToolDir, stageCompanionInputs, } from "./filesystem/index.js";
+export { getMoldeskHome, getMoldeskPaths, modelInstallDir, modelVersionDir, pythonToolDir, runDir, uvToolDir, visualizationDir, isWithinRoot, stageCompanionInputs, } from "./filesystem/index.js";
 export { MoldeskError } from "./providers.js";
 export { PythonRuntimeProvider } from "./providers/python.js";
 export { redactEnv } from "./redact.js";
@@ -17,4 +17,5 @@ export { detectDocker, isImageCachedLocally, pullDockerImage, probeDockerGpuAcce
 export { detectNvidia } from "./nvidia/index.js";
 export { collectSystemReport } from "./system.js";
 export { runCommand } from "./process/index.js";
+export { openInBrowser } from "./process/open.js";
 export { cacheAsset, ensureManagedUv, managedUvDownloadBytes, materializeAsset, prepareDockerImage, preparePythonEnvironment, temporaryInstallDir, MANAGED_UV_VERSION, } from "./install/index.js";

package/dist/process/open.d.ts

@@ -0,0 +1,14 @@
+import { type RunResult } from "./index.js";
+export interface OpenResult {
+    opened: boolean;
+    error?: string;
+}
+/**
+ * Opens a local file in the default browser. Structured executable + args, no shell,
+ * so paths with spaces, quotes, `$()`, backticks, Unicode, or a leading dash are inert:
+ * the path is made absolute first, so it can never be parsed as an option.
+ */
+export declare function openInBrowser(filePath: string, deps?: {
+    platform?: NodeJS.Platform;
+    run?: (command: string, args: string[]) => Promise<Pick<RunResult, "code" | "stderr">>;
+}): Promise<OpenResult>;

package/dist/process/open.js

@@ -0,0 +1,24 @@
+import path from "node:path";
+import { runCommand } from "./index.js";
+/**
+ * Opens a local file in the default browser. Structured executable + args, no shell,
+ * so paths with spaces, quotes, `$()`, backticks, Unicode, or a leading dash are inert:
+ * the path is made absolute first, so it can never be parsed as an option.
+ */
+export async function openInBrowser(filePath, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const executable = platform === "darwin" ? "open" : platform === "linux" ? "xdg-open" : undefined;
+    if (!executable)
+        return { opened: false, error: `Opening a browser is not supported on ${platform}.` };
+    const target = path.resolve(filePath);
+    const run = deps.run ?? ((command, args) => runCommand(command, args, { timeoutMs: 10_000 }));
+    try {
+        const result = await run(executable, [target]);
+        if (result.code === 0)
+            return { opened: true };
+        return { opened: false, error: result.stderr.trim() || `${executable} exited with code ${result.code}` };
+    }
+    catch (error) {
+        return { opened: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/process/open.test.d.ts

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

package/dist/process/open.test.js

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { openInBrowser } from "./open.js";
+describe("openInBrowser", () => {
+    it.each([
+        ["darwin", "open"],
+        ["linux", "xdg-open"],
+    ])("uses %s -> %s with the path as one argument", async (platform, exe) => {
+        const calls = [];
+        const hostile = "-evil $(touch /tmp/pwned) `x` 'q' \"d\" ü.html";
+        const result = await openInBrowser(hostile, {
+            platform,
+            run: async (c, a) => {
+                calls.push([c, a]);
+                return { code: 0, stderr: "" };
+            },
+        });
+        expect(result).toEqual({ opened: true });
+        expect(calls).toHaveLength(1);
+        expect(calls[0][0]).toBe(exe);
+        expect(calls[0][1]).toHaveLength(1);
+        expect(calls[0][1][0].startsWith("/")).toBe(true);
+        expect(calls[0][1][0].endsWith(hostile)).toBe(true);
+    });
+    it("reports failures instead of throwing", async () => {
+        expect((await openInBrowser("/a.html", { platform: "linux", run: async () => ({ code: 3, stderr: "no display\n" }) })).error).toBe("no display");
+        expect((await openInBrowser("/a.html", { platform: "linux", run: async () => { throw new Error("ENOENT"); } })).error).toBe("ENOENT");
+        expect((await openInBrowser("/a.html", { platform: "win32" })).opened).toBe(false);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldesk/runtime",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Hardware detection and Python/Docker/process execution for MoleculeDesk",
   "license": "MIT",
   "type": "module",
@@ -19,7 +19,7 @@
     "dist"
   ],
   "dependencies": {
-    "@moldesk/registry": "0.0.3"
+    "@moldesk/registry": "0.0.5"
   },
   "devDependencies": {
     "typescript": "^5.6.3",