@slicervm/sdk 0.1.2 → 0.1.3

package/dist/index.d.cts

@@ -143,6 +143,42 @@ interface FSMkdirRequest {
     recursive?: boolean;
     mode?: string;
 }
+type FSWatchEventType = 'create' | 'write' | 'remove' | 'rename' | 'chmod';
+interface FSWatchRequest {
+    /** Absolute paths inside the VM to watch. At least one is required. */
+    paths: string[];
+    /** Optional glob patterns to filter event paths (e.g. `["*.go", "bin/*"]`). */
+    patterns?: string[];
+    /**
+     * Restrict to a subset of event types. When omitted, all types are delivered.
+     */
+    events?: FSWatchEventType[];
+    /** UID used by the agent to resolve `~` in paths. Default: 0 (root). */
+    uid?: number;
+    /** Watch directories recursively. */
+    recursive?: boolean;
+    /** Stop the stream after the first matching event. */
+    oneShot?: boolean;
+    /** Coalesce events arriving within this window. Go-duration string e.g. `"100ms"`. */
+    debounce?: string;
+    /** Server-side wall-clock cap on the stream. Go-duration string e.g. `"5m"`. */
+    timeout?: string;
+    /** Stop after delivering this many events. */
+    maxEvents?: number;
+    /** Forwarded as the SSE `Last-Event-ID` header for cross-connection resume. */
+    lastEventId?: string;
+}
+interface FSWatchEvent {
+    /** Monotonic per-stream ID (from the SSE `id:` line). */
+    id: number;
+    type: FSWatchEventType | string;
+    path: string;
+    /** RFC3339Nano string (when present). */
+    timestamp: string;
+    size: number;
+    isDir: boolean;
+    message?: string;
+}
 interface ShutdownRequest {
     action?: 'shutdown' | 'reboot';
 }
@@ -271,7 +307,7 @@ declare class TransportClient {
     /** Raw-bytes request (for binary cp endpoints). */
     requestRaw(method: string, reqPath: string, body?: Buffer, contentType?: string): Promise<Buffer>;
     /** Streaming request producing a Node Readable of the response body. */
-    requestStreamRaw(method: string, reqPath: string, body?: Buffer | Readable, contentType?: string): Promise<IncomingMessage>;
+    requestStreamRaw(method: string, reqPath: string, body?: Buffer | Readable, contentType?: string, extraHeaders?: Record<string, string>): Promise<IncomingMessage>;
     /** Yields decoded JSON frames from an NDJSON response (one JSON object per line). */
     requestNDJSON<Frame = unknown>(method: string, reqPath: string, body?: Buffer | Readable): AsyncGenerator<Frame, void, void>;
 }
@@ -387,6 +423,22 @@ declare class VMFileSystem {
     }): Promise<void>;
     /** Upload a tar archive, expanded into the VM at `path`. */
     tarTo(path: string, tar: Buffer | Readable): Promise<void>;
+    /**
+     * Open a Server-Sent Events stream of filesystem events from the VM.
+     * Yields one `FSWatchEvent` per agent-side event. The stream stays open
+     * until the supplied request's `timeout` / `maxEvents` is hit, the daemon
+     * tears it down, or the caller breaks out of the loop.
+     *
+     * Heartbeat SSE comments and named `event:` lines are silently dropped.
+     *
+     * Example:
+     * ```ts
+     * for await (const e of vm.fs.watch({ paths: ['/tmp'], recursive: true })) {
+     *   console.log(e.type, e.path);
+     * }
+     * ```
+     */
+    watch(req: FSWatchRequest): AsyncGenerator<FSWatchEvent, void, void>;
     /** Download `path` from the VM as a tar archive. */
     tarFrom(path: string): Promise<Buffer>;
 }
@@ -523,4 +575,4 @@ declare class SlicerClient {
     getInfo(): Promise<SlicerInfo>;
 }
 
-export { type AddressMapping, type AgentHealth, 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, 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, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, parseAddressMapping, resolveTransport };
+export { type AddressMapping, type AgentHealth, 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, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, parseAddressMapping, resolveTransport };

package/dist/index.d.ts

@@ -143,6 +143,42 @@ interface FSMkdirRequest {
     recursive?: boolean;
     mode?: string;
 }
+type FSWatchEventType = 'create' | 'write' | 'remove' | 'rename' | 'chmod';
+interface FSWatchRequest {
+    /** Absolute paths inside the VM to watch. At least one is required. */
+    paths: string[];
+    /** Optional glob patterns to filter event paths (e.g. `["*.go", "bin/*"]`). */
+    patterns?: string[];
+    /**
+     * Restrict to a subset of event types. When omitted, all types are delivered.
+     */
+    events?: FSWatchEventType[];
+    /** UID used by the agent to resolve `~` in paths. Default: 0 (root). */
+    uid?: number;
+    /** Watch directories recursively. */
+    recursive?: boolean;
+    /** Stop the stream after the first matching event. */
+    oneShot?: boolean;
+    /** Coalesce events arriving within this window. Go-duration string e.g. `"100ms"`. */
+    debounce?: string;
+    /** Server-side wall-clock cap on the stream. Go-duration string e.g. `"5m"`. */
+    timeout?: string;
+    /** Stop after delivering this many events. */
+    maxEvents?: number;
+    /** Forwarded as the SSE `Last-Event-ID` header for cross-connection resume. */
+    lastEventId?: string;
+}
+interface FSWatchEvent {
+    /** Monotonic per-stream ID (from the SSE `id:` line). */
+    id: number;
+    type: FSWatchEventType | string;
+    path: string;
+    /** RFC3339Nano string (when present). */
+    timestamp: string;
+    size: number;
+    isDir: boolean;
+    message?: string;
+}
 interface ShutdownRequest {
     action?: 'shutdown' | 'reboot';
 }
@@ -271,7 +307,7 @@ declare class TransportClient {
     /** Raw-bytes request (for binary cp endpoints). */
     requestRaw(method: string, reqPath: string, body?: Buffer, contentType?: string): Promise<Buffer>;
     /** Streaming request producing a Node Readable of the response body. */
-    requestStreamRaw(method: string, reqPath: string, body?: Buffer | Readable, contentType?: string): Promise<IncomingMessage>;
+    requestStreamRaw(method: string, reqPath: string, body?: Buffer | Readable, contentType?: string, extraHeaders?: Record<string, string>): Promise<IncomingMessage>;
     /** Yields decoded JSON frames from an NDJSON response (one JSON object per line). */
     requestNDJSON<Frame = unknown>(method: string, reqPath: string, body?: Buffer | Readable): AsyncGenerator<Frame, void, void>;
 }
@@ -387,6 +423,22 @@ declare class VMFileSystem {
     }): Promise<void>;
     /** Upload a tar archive, expanded into the VM at `path`. */
     tarTo(path: string, tar: Buffer | Readable): Promise<void>;
+    /**
+     * Open a Server-Sent Events stream of filesystem events from the VM.
+     * Yields one `FSWatchEvent` per agent-side event. The stream stays open
+     * until the supplied request's `timeout` / `maxEvents` is hit, the daemon
+     * tears it down, or the caller breaks out of the loop.
+     *
+     * Heartbeat SSE comments and named `event:` lines are silently dropped.
+     *
+     * Example:
+     * ```ts
+     * for await (const e of vm.fs.watch({ paths: ['/tmp'], recursive: true })) {
+     *   console.log(e.type, e.path);
+     * }
+     * ```
+     */
+    watch(req: FSWatchRequest): AsyncGenerator<FSWatchEvent, void, void>;
     /** Download `path` from the VM as a tar archive. */
     tarFrom(path: string): Promise<Buffer>;
 }
@@ -523,4 +575,4 @@ declare class SlicerClient {
     getInfo(): Promise<SlicerInfo>;
 }
 
-export { type AddressMapping, type AgentHealth, 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, 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, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, parseAddressMapping, resolveTransport };
+export { type AddressMapping, type AgentHealth, 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, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, parseAddressMapping, resolveTransport };

package/dist/index.js

@@ -150,9 +150,9 @@ var TransportClient = class {
     });
   }
   /** Streaming request producing a Node Readable of the response body. */
-  requestStreamRaw(method, reqPath, body, contentType = "application/octet-stream") {
+  requestStreamRaw(method, reqPath, body, contentType = "application/octet-stream", extraHeaders = {}) {
     return new Promise((resolve, reject) => {
-      const headers = {};
+      const headers = { ...extraHeaders };
       if (body instanceof Buffer) {
         headers["Content-Type"] = contentType;
         headers["Content-Length"] = String(body.length);
@@ -639,6 +639,85 @@ var VMFileSystem = class {
     );
     for await (const _ of res) void _;
   }
+  /**
+   * Open a Server-Sent Events stream of filesystem events from the VM.
+   * Yields one `FSWatchEvent` per agent-side event. The stream stays open
+   * until the supplied request's `timeout` / `maxEvents` is hit, the daemon
+   * tears it down, or the caller breaks out of the loop.
+   *
+   * Heartbeat SSE comments and named `event:` lines are silently dropped.
+   *
+   * Example:
+   * ```ts
+   * for await (const e of vm.fs.watch({ paths: ['/tmp'], recursive: true })) {
+   *   console.log(e.type, e.path);
+   * }
+   * ```
+   */
+  async *watch(req) {
+    if (!req.paths || req.paths.length === 0) {
+      throw new Error("vm.fs.watch: paths is required");
+    }
+    const q = new URLSearchParams();
+    for (const p of req.paths) if (p) q.append("paths", p);
+    for (const p of req.patterns ?? []) if (p) q.append("patterns", p);
+    for (const e of req.events ?? []) if (e) q.append("events", e);
+    if (req.uid !== void 0 && req.uid !== 0) q.set("uid", String(req.uid));
+    if (req.recursive) q.set("recursive", "true");
+    if (req.oneShot) q.set("one_shot", "true");
+    if (req.debounce) q.set("debounce", req.debounce);
+    if (req.timeout) q.set("timeout", req.timeout);
+    if (req.maxEvents !== void 0 && req.maxEvents > 0) {
+      q.set("max_events", String(req.maxEvents));
+    }
+    const extraHeaders = { Accept: "text/event-stream" };
+    if (req.lastEventId) extraHeaders["Last-Event-ID"] = req.lastEventId;
+    const res = await this.transport.requestStreamRaw(
+      "GET",
+      `/vm/${encodeURIComponent(this.hostname)}/fs/watch?${q.toString()}`,
+      void 0,
+      void 0,
+      extraHeaders
+    );
+    res.setEncoding("utf8");
+    let buffer = "";
+    let dataLines = [];
+    let pendingId = 0;
+    for await (const chunk of res) {
+      buffer += chunk;
+      let nl;
+      while ((nl = buffer.indexOf("\n")) >= 0) {
+        const raw = buffer.slice(0, nl);
+        buffer = buffer.slice(nl + 1);
+        const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+        if (line === "") {
+          if (dataLines.length > 0) {
+            const payload = dataLines.join("\n");
+            dataLines = [];
+            try {
+              const parsed = JSON.parse(payload);
+              const evt = {
+                id: typeof parsed.id === "number" && parsed.id !== 0 ? parsed.id : pendingId,
+                type: parsed.type ?? "",
+                path: parsed.path ?? "",
+                timestamp: parsed.timestamp ?? "",
+                size: parsed.size ?? 0,
+                isDir: parsed.isDir ?? false,
+                ...parsed.message !== void 0 && { message: parsed.message }
+              };
+              yield evt;
+            } catch {
+            }
+          }
+        } else if (line.startsWith(":")) ; else if (line.startsWith("data:")) {
+          dataLines.push(line.slice(5).replace(/^ /, ""));
+        } else if (line.startsWith("id:")) {
+          const v = parseInt(line.slice(3).trim(), 10);
+          if (!Number.isNaN(v)) pendingId = v;
+        }
+      }
+    }
+  }
   /** Download `path` from the VM as a tar archive. */
   async tarFrom(path3) {
     const q = new URLSearchParams({ path: path3, mode: "tar" });