@slicervm/sdk 0.1.5 → 0.1.6

package/dist/index.d.cts

@@ -712,4 +712,70 @@ declare class SlicerClient {
     getInfo(): Promise<SlicerInfo>;
 }
 
-export { type AddressMapping, type AgentHealth, type BgDeleteResponse, type BgExecInfo, type BgExecRequest, type BgExecResponse, type BgKillOptions, type BgKillResponse, type BgLogOptions, type BgWaitExitResponse, type CreateSecretRequest, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, type FSEntry, type FSMkdirRequest, type FSWatchEvent, type FSWatchEventType, type FSWatchRequest, Forwarder, type ForwarderListener, type ForwarderOptions, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, type Secret, SecretExistsError, SecretsAPI, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, type UpdateSecretRequest, VM, VMBg, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, parseAddressMapping, resolveTransport };
+/**
+ * Browser-compatible shell adapter for Slicer VMs.
+ *
+ * Provides frame encode/decode helpers and a `SlicerShellSession` class that
+ * wires a standard browser WebSocket to an xterm.js Terminal instance using
+ * the Slicer binary shell protocol.
+ *
+ * This module intentionally avoids Node-only imports so it can be used in
+ * browser bundles.
+ */
+declare const FRAME_TYPE_DATA = 1;
+declare const FRAME_TYPE_WINDOW_SIZE = 2;
+declare const FRAME_TYPE_SHUTDOWN = 3;
+declare const FRAME_TYPE_HEARTBEAT = 4;
+declare const FRAME_TYPE_SESSION_CLOSE = 5;
+/** Encode a frame into the 5-byte-header binary protocol. */
+declare function encodeFrame(frameType: number, payload?: Uint8Array): Uint8Array;
+/** Parse a binary frame. Returns null if the data is malformed. */
+declare function parseFrame(data: ArrayBuffer): {
+    frameType: number;
+    payload: Uint8Array;
+} | null;
+interface ShellSessionOptions {
+    /** WebSocket URL for the shell endpoint (ws:// or wss://). */
+    url: string;
+    /** Heartbeat interval in ms. Default 30000. */
+    heartbeatIntervalMs?: number;
+    /** Called when connection state changes. */
+    onStateChange?: (state: 'connecting' | 'connected' | 'disconnected') => void;
+    /** Called on error. */
+    onError?: (error: string) => void;
+}
+/**
+ * Minimal xterm.js Terminal interface — only the methods SlicerShellSession
+ * actually calls. Avoids requiring @xterm/xterm as a dependency.
+ */
+interface XTermLike {
+    onData: (cb: (data: string) => void) => {
+        dispose: () => void;
+    };
+    write: (data: string) => void;
+    reset: () => void;
+    cols: number;
+    rows: number;
+}
+declare class SlicerShellSession {
+    private readonly terminal;
+    private readonly options;
+    private ws;
+    private heartbeatTimer;
+    private dataDisposable;
+    constructor(terminal: XTermLike, options: ShellSessionOptions);
+    /** True when the WebSocket is open and relaying. */
+    get connected(): boolean;
+    /** Open the WebSocket and begin relaying. */
+    connect(): void;
+    /** Send a graceful shutdown frame and close. */
+    disconnect(): void;
+    /** Send a window resize. Call this from FitAddon's onResize or a ResizeObserver. */
+    resize(cols: number, rows: number): void;
+    private sendResize;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private teardown;
+}
+
+export { type AddressMapping, type AgentHealth, type BgDeleteResponse, type BgExecInfo, type BgExecRequest, type BgExecResponse, type BgKillOptions, type BgKillResponse, type BgLogOptions, type BgWaitExitResponse, type CreateSecretRequest, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, FRAME_TYPE_DATA, FRAME_TYPE_HEARTBEAT, FRAME_TYPE_SESSION_CLOSE, FRAME_TYPE_SHUTDOWN, FRAME_TYPE_WINDOW_SIZE, type FSEntry, type FSMkdirRequest, type FSWatchEvent, type FSWatchEventType, type FSWatchRequest, Forwarder, type ForwarderListener, type ForwarderOptions, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, type Secret, SecretExistsError, SecretsAPI, type ShellSessionOptions, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, SlicerShellSession, type UpdateSecretRequest, VM, VMBg, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, type XTermLike, encodeFrame, parseAddressMapping, parseFrame, resolveTransport };

package/dist/index.d.ts

@@ -712,4 +712,70 @@ declare class SlicerClient {
     getInfo(): Promise<SlicerInfo>;
 }
 
-export { type AddressMapping, type AgentHealth, type BgDeleteResponse, type BgExecInfo, type BgExecRequest, type BgExecResponse, type BgKillOptions, type BgKillResponse, type BgLogOptions, type BgWaitExitResponse, type CreateSecretRequest, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, type FSEntry, type FSMkdirRequest, type FSWatchEvent, type FSWatchEventType, type FSWatchRequest, Forwarder, type ForwarderListener, type ForwarderOptions, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, type Secret, SecretExistsError, SecretsAPI, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, type UpdateSecretRequest, VM, VMBg, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, parseAddressMapping, resolveTransport };
+/**
+ * Browser-compatible shell adapter for Slicer VMs.
+ *
+ * Provides frame encode/decode helpers and a `SlicerShellSession` class that
+ * wires a standard browser WebSocket to an xterm.js Terminal instance using
+ * the Slicer binary shell protocol.
+ *
+ * This module intentionally avoids Node-only imports so it can be used in
+ * browser bundles.
+ */
+declare const FRAME_TYPE_DATA = 1;
+declare const FRAME_TYPE_WINDOW_SIZE = 2;
+declare const FRAME_TYPE_SHUTDOWN = 3;
+declare const FRAME_TYPE_HEARTBEAT = 4;
+declare const FRAME_TYPE_SESSION_CLOSE = 5;
+/** Encode a frame into the 5-byte-header binary protocol. */
+declare function encodeFrame(frameType: number, payload?: Uint8Array): Uint8Array;
+/** Parse a binary frame. Returns null if the data is malformed. */
+declare function parseFrame(data: ArrayBuffer): {
+    frameType: number;
+    payload: Uint8Array;
+} | null;
+interface ShellSessionOptions {
+    /** WebSocket URL for the shell endpoint (ws:// or wss://). */
+    url: string;
+    /** Heartbeat interval in ms. Default 30000. */
+    heartbeatIntervalMs?: number;
+    /** Called when connection state changes. */
+    onStateChange?: (state: 'connecting' | 'connected' | 'disconnected') => void;
+    /** Called on error. */
+    onError?: (error: string) => void;
+}
+/**
+ * Minimal xterm.js Terminal interface — only the methods SlicerShellSession
+ * actually calls. Avoids requiring @xterm/xterm as a dependency.
+ */
+interface XTermLike {
+    onData: (cb: (data: string) => void) => {
+        dispose: () => void;
+    };
+    write: (data: string) => void;
+    reset: () => void;
+    cols: number;
+    rows: number;
+}
+declare class SlicerShellSession {
+    private readonly terminal;
+    private readonly options;
+    private ws;
+    private heartbeatTimer;
+    private dataDisposable;
+    constructor(terminal: XTermLike, options: ShellSessionOptions);
+    /** True when the WebSocket is open and relaying. */
+    get connected(): boolean;
+    /** Open the WebSocket and begin relaying. */
+    connect(): void;
+    /** Send a graceful shutdown frame and close. */
+    disconnect(): void;
+    /** Send a window resize. Call this from FitAddon's onResize or a ResizeObserver. */
+    resize(cols: number, rows: number): void;
+    private sendResize;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private teardown;
+}
+
+export { type AddressMapping, type AgentHealth, type BgDeleteResponse, type BgExecInfo, type BgExecRequest, type BgExecResponse, type BgKillOptions, type BgKillResponse, type BgLogOptions, type BgWaitExitResponse, type CreateSecretRequest, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, FRAME_TYPE_DATA, FRAME_TYPE_HEARTBEAT, FRAME_TYPE_SESSION_CLOSE, FRAME_TYPE_SHUTDOWN, FRAME_TYPE_WINDOW_SIZE, type FSEntry, type FSMkdirRequest, type FSWatchEvent, type FSWatchEventType, type FSWatchRequest, Forwarder, type ForwarderListener, type ForwarderOptions, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, type Secret, SecretExistsError, SecretsAPI, type ShellSessionOptions, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, SlicerShellSession, type UpdateSecretRequest, VM, VMBg, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, type XTermLike, encodeFrame, parseAddressMapping, parseFrame, resolveTransport };

package/dist/index.js

@@ -5,7 +5,7 @@ import os from 'os';
 import path2 from 'path';
 import net, { createServer } from 'net';
 import fs from 'fs';
-import { createWebSocketStream, WebSocket } from 'ws';
+import { createWebSocketStream, WebSocket as WebSocket$1 } from 'ws';
 
 // src/types.ts
 var ExecStdioText = "text";
@@ -526,7 +526,7 @@ function openWebSocket(init, mapping) {
   if (init.transport.kind === "socket") {
     opts.agent = unixAgent(init.transport.socketPath);
   }
-  return new WebSocket(url, opts);
+  return new WebSocket$1(url, opts);
 }
 function wsURLForVM(transport, hostname) {
   if (transport.kind === "socket") {
@@ -965,8 +965,8 @@ var VMBg = class {
     q.set("cmd", req.command);
     for (const a of req.args ?? []) q.append("args", a);
     for (const e of req.env ?? []) q.append("env", e);
-    if (req.uid !== void 0 && req.uid !== 0) q.set("uid", String(req.uid));
-    if (req.gid !== void 0 && req.gid !== 0) q.set("gid", String(req.gid));
+    if (req.uid !== void 0) q.set("uid", String(req.uid));
+    if (req.gid !== void 0) q.set("gid", String(req.gid));
     if (req.shell) q.set("shell", req.shell);
     if (req.cwd) q.set("cwd", req.cwd);
     if (req.ringBytes !== void 0 && req.ringBytes > 0) {
@@ -1278,6 +1278,146 @@ var SlicerClient = class _SlicerClient {
   }
 };
 
-export { ExecStdioBase64, ExecStdioText, Forwarder, GiB, HostGroupsAPI, MiB, NonRootUser, SecretExistsError, SecretsAPI, SlicerAPIError, SlicerClient, VM, VMBg, VMFileSystem, VMsAPI, parseAddressMapping, resolveTransport };
+// src/shell.ts
+var FRAME_TYPE_DATA = 1;
+var FRAME_TYPE_WINDOW_SIZE = 2;
+var FRAME_TYPE_SHUTDOWN = 3;
+var FRAME_TYPE_HEARTBEAT = 4;
+var FRAME_TYPE_SESSION_CLOSE = 5;
+var HEADER_SIZE = 5;
+function encodeFrame(frameType, payload) {
+  const payloadLen = payload ? payload.byteLength : 0;
+  const buf = new Uint8Array(HEADER_SIZE + payloadLen);
+  const view = new DataView(buf.buffer);
+  view.setUint8(0, frameType);
+  view.setUint32(1, payloadLen, false);
+  if (payload) buf.set(payload, HEADER_SIZE);
+  return buf;
+}
+function parseFrame(data) {
+  if (data.byteLength < HEADER_SIZE) return null;
+  const view = new DataView(data);
+  const frameType = view.getUint8(0);
+  const payloadLen = view.getUint32(1, false);
+  if (data.byteLength < HEADER_SIZE + payloadLen) return null;
+  const payload = new Uint8Array(data, HEADER_SIZE, payloadLen);
+  return { frameType, payload };
+}
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+var SlicerShellSession = class {
+  constructor(terminal, options) {
+    this.terminal = terminal;
+    this.options = options;
+  }
+  terminal;
+  options;
+  ws = null;
+  heartbeatTimer = null;
+  dataDisposable = null;
+  /** True when the WebSocket is open and relaying. */
+  get connected() {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+  /** Open the WebSocket and begin relaying. */
+  connect() {
+    if (this.ws) return;
+    this.options.onStateChange?.("connecting");
+    const ws = new WebSocket(this.options.url);
+    ws.binaryType = "arraybuffer";
+    this.ws = ws;
+    ws.onopen = () => {
+      this.options.onStateChange?.("connected");
+      this.terminal.reset();
+      this.sendResize(this.terminal.cols, this.terminal.rows);
+      this.startHeartbeat();
+    };
+    ws.onmessage = (ev) => {
+      if (!(ev.data instanceof ArrayBuffer)) return;
+      const frame = parseFrame(ev.data);
+      if (!frame) return;
+      switch (frame.frameType) {
+        case FRAME_TYPE_DATA:
+          this.terminal.write(decoder.decode(frame.payload));
+          break;
+        case FRAME_TYPE_SHUTDOWN:
+        case FRAME_TYPE_SESSION_CLOSE:
+          this.teardown();
+          break;
+      }
+    };
+    ws.onclose = () => {
+      this.teardown();
+    };
+    ws.onerror = () => {
+      this.options.onError?.("WebSocket error");
+      this.teardown();
+    };
+    this.dataDisposable = this.terminal.onData((data) => {
+      if (!this.connected) return;
+      const payload = encoder.encode(data);
+      this.ws.send(encodeFrame(FRAME_TYPE_DATA, payload));
+    });
+  }
+  /** Send a graceful shutdown frame and close. */
+  disconnect() {
+    if (this.ws) {
+      try {
+        this.ws.send(encodeFrame(FRAME_TYPE_SHUTDOWN));
+      } catch {
+      }
+    }
+    this.teardown();
+  }
+  /** Send a window resize. Call this from FitAddon's onResize or a ResizeObserver. */
+  resize(cols, rows) {
+    if (!this.connected) return;
+    this.sendResize(cols, rows);
+  }
+  // --- internals -------------------------------------------------------------
+  sendResize(cols, rows) {
+    const payload = new Uint8Array(8);
+    const view = new DataView(payload.buffer);
+    view.setUint32(0, cols, false);
+    view.setUint32(4, rows, false);
+    this.ws.send(encodeFrame(FRAME_TYPE_WINDOW_SIZE, payload));
+  }
+  startHeartbeat() {
+    this.stopHeartbeat();
+    const intervalMs = this.options.heartbeatIntervalMs ?? 3e4;
+    this.heartbeatTimer = setInterval(() => {
+      if (!this.connected) return;
+      this.ws.send(encodeFrame(FRAME_TYPE_HEARTBEAT));
+    }, intervalMs);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  teardown() {
+    this.stopHeartbeat();
+    if (this.dataDisposable) {
+      this.dataDisposable.dispose();
+      this.dataDisposable = null;
+    }
+    if (this.ws) {
+      const ws = this.ws;
+      this.ws = null;
+      ws.onopen = null;
+      ws.onmessage = null;
+      ws.onclose = null;
+      ws.onerror = null;
+      try {
+        ws.close();
+      } catch {
+      }
+    }
+    this.options.onStateChange?.("disconnected");
+  }
+};
+
+export { ExecStdioBase64, ExecStdioText, FRAME_TYPE_DATA, FRAME_TYPE_HEARTBEAT, FRAME_TYPE_SESSION_CLOSE, FRAME_TYPE_SHUTDOWN, FRAME_TYPE_WINDOW_SIZE, Forwarder, GiB, HostGroupsAPI, MiB, NonRootUser, SecretExistsError, SecretsAPI, SlicerAPIError, SlicerClient, SlicerShellSession, VM, VMBg, VMFileSystem, VMsAPI, encodeFrame, parseAddressMapping, parseFrame, resolveTransport };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map